diff --git a/Cargo.lock b/Cargo.lock
index a147ba5..7483b99 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -629,6 +629,7 @@ dependencies = [
  "tabular",
  "tempfile",
  "textwrap",
+ "thiserror 2.0.18",
  "tokio",
  "tokio-stream",
  "tokio-util",
diff --git a/Cargo.toml b/Cargo.toml
index ad08719..fa7e45f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,7 +13,7 @@ categories = ["command-line-utilities"]
 [features]
 default = ["self-update", "sync"]
 self-update = ["dep:self_update"]
-sync = ["dep:cooklang-sync-client", "dep:uuid", "dep:tokio-util", "dep:base64", "dep:libsqlite3-sys"]
+sync = ["dep:cooklang-sync-client", "dep:uuid", "dep:tokio-util", "dep:base64", "dep:libsqlite3-sys", "dep:thiserror"]
 
 [lib]
 name = "cookcli"
@@ -66,6 +66,7 @@ textwrap = { version = "0.16", features = ["terminal_size"] }
 tokio = { version = "1", features = ["full"] }
 tokio-stream = { version = "0.1", features = ["sync"] }
 tokio-util = { version = "0.7", optional = true }
+thiserror = { version = "2", optional = true }
 toml = "0.9.5"
 tower = { version = "0.5", features = ["util"] }
 tower-http = { version = "0.5", features = ["fs", "trace", "cors", "normalize-path"] }
diff --git a/docs/superpowers/plans/2026-05-15-shopping-list-pantry-flags.md b/docs/superpowers/plans/2026-05-15-shopping-list-pantry-flags.md
new file mode 100644
index 0000000..15d837c
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-15-shopping-list-pantry-flags.md
@@ -0,0 +1,272 @@
+# Shopping List Pantry Flags Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add `--pantry <path>` and `--ignore-pantry` flags to the `cook shopping-list` command so users can specify a custom pantry file or skip pantry subtraction entirely.
+
+**Architecture:** Two new clap arguments on `ShoppingListArgs`. Pantry resolution becomes `if args.ignore_pantry { None } else { args.pantry.or_else(|| ctx.pantry()) }`. The existing parse/subtract logic is otherwise unchanged.
+
+**Tech Stack:** Rust, clap 4 (derive API), `camino::Utf8PathBuf`, `cooklang::pantry::parse_lenient`.
+
+**Note on testing:** Per `CLAUDE.md`, this project has no automated test suite. Verification is manual using `cargo run` against the `seed/` recipes, which include a `seed/config/pantry.conf`.
+
+---
+
+## File Structure
+
+Only one source file is modified:
+
+- Modify: `src/shopping_list.rs` — add two `ShoppingListArgs` fields and rewrite the pantry-loading block to honor them.
+
+No new files. No changes to other modules: `Context::pantry()` (`src/main.rs:104`) is still used as the auto-discovery fallback, and `list.subtract_pantry(...)` at `src/shopping_list.rs:264-267` is unchanged.
+
+---
+
+### Task 1: Add `--pantry` and `--ignore-pantry` args and wire them into pantry resolution
+
+**Files:**
+- Modify: `src/shopping_list.rs:98-104` (add new args next to existing `--aisle` / `--ignore-references`)
+- Modify: `src/shopping_list.rs:198-233` (rewrite pantry loading block)
+
+- [ ] **Step 1: Add the two new clap fields to `ShoppingListArgs`**
+
+In `src/shopping_list.rs`, locate this block (around lines 98-104):
+
+```rust
+    /// Load aisle conf file
+    #[arg(short, long)]
+    aisle: Option<Utf8PathBuf>,
+
+    /// Don't expand referenced recipes
+    #[arg(short, long)]
+    ignore_references: bool,
+```
+
+Replace it with:
+
+```rust
+    /// Load aisle conf file
+    #[arg(short, long)]
+    aisle: Option<Utf8PathBuf>,
+
+    /// Load pantry conf file
+    #[arg(long)]
+    pantry: Option<Utf8PathBuf>,
+
+    /// Don't expand referenced recipes
+    #[arg(short, long)]
+    ignore_references: bool,
+
+    /// Don't subtract pantry items from the shopping list
+    #[arg(long)]
+    ignore_pantry: bool,
+```
+
+Notes:
+- `--pantry` is intentionally long-only. A short `-p` would collide with the existing `-p` / `--plain` flag.
+- `--ignore-pantry` mirrors the naming of the existing `--ignore-references` flag.
+
+- [ ] **Step 2: Rewrite the pantry loading block to honor the new flags**
+
+In `src/shopping_list.rs`, locate this block (lines 198-233):
+
+```rust
+    // Load pantry configuration if available
+    let pantry_path = ctx.pantry();
+    let pantry = if let Some(path) = &pantry_path {
+        match std::fs::read_to_string(path) {
+            Ok(content) => {
+                tracing::debug!("Loading pantry from: {}", path);
+                let result = cooklang::pantry::parse_lenient(&content);
+
+                // Check if there are any warnings to display
+                if result.report().has_warnings() {
+                    for warning in result.report().warnings() {
+                        warn!("Pantry configuration warning: {}", warning);
+                    }
+                }
+
+                let mut pantry_conf = result.output().cloned();
+                if let Some(ref mut pantry) = pantry_conf {
+                    pantry.rebuild_index();
+                    tracing::debug!(
+                        "Pantry loaded successfully with {} sections",
+                        pantry.sections.len()
+                    );
+                } else {
+                    tracing::warn!("Failed to parse pantry file");
+                }
+                pantry_conf
+            }
+            Err(e) => {
+                warn!("Failed to read pantry file: {}", e);
+                None
+            }
+        }
+    } else {
+        tracing::debug!("No pantry file found");
+        None
+    };
+```
+
+Replace it with:
+
+```rust
+    // Resolve pantry path: --ignore-pantry skips entirely; otherwise prefer
+    // --pantry, falling back to ctx.pantry() auto-discovery.
+    let pantry_path = if args.ignore_pantry {
+        tracing::debug!("Pantry ignored via --ignore-pantry");
+        None
+    } else {
+        args.pantry.clone().or_else(|| ctx.pantry())
+    };
+
+    let pantry = if let Some(path) = &pantry_path {
+        match std::fs::read_to_string(path) {
+            Ok(content) => {
+                tracing::debug!("Loading pantry from: {}", path);
+                let result = cooklang::pantry::parse_lenient(&content);
+
+                // Check if there are any warnings to display
+                if result.report().has_warnings() {
+                    for warning in result.report().warnings() {
+                        warn!("Pantry configuration warning: {}", warning);
+                    }
+                }
+
+                let mut pantry_conf = result.output().cloned();
+                if let Some(ref mut pantry) = pantry_conf {
+                    pantry.rebuild_index();
+                    tracing::debug!(
+                        "Pantry loaded successfully with {} sections",
+                        pantry.sections.len()
+                    );
+                } else {
+                    tracing::warn!("Failed to parse pantry file");
+                }
+                pantry_conf
+            }
+            Err(e) => {
+                warn!("Failed to read pantry file: {}", e);
+                None
+            }
+        }
+    } else {
+        tracing::debug!("No pantry file found");
+        None
+    };
+```
+
+The only changes are:
+1. The initial `pantry_path` binding now branches on `args.ignore_pantry`.
+2. When not ignoring, `args.pantry.clone()` is preferred over `ctx.pantry()`. `.clone()` is required because `args` is consumed later by `args.output`, `args.ingredients_only`, etc.
+
+The rest of the function (subtract call at the previous line ~264, output formatting) is unchanged.
+
+- [ ] **Step 3: Run formatting and linting**
+
+```bash
+cargo fmt
+cargo clippy --all-targets -- -D warnings
+```
+
+Expected: both succeed with no output / no warnings.
+
+- [ ] **Step 4: Run the build**
+
+```bash
+cargo build
+```
+
+Expected: clean build, no warnings.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/shopping_list.rs
+git commit -m "feat(shopping-list): add --pantry and --ignore-pantry flags"
+```
+
+---
+
+### Task 2: Manual verification against seed recipes
+
+**Files:** (no source changes — manual exercise only)
+- Read: `seed/config/pantry.conf` (contains `butter`, `milk`, `eggs`, `flour`, etc.)
+- Read: `seed/Breakfast/Easy Pancakes.cook` (uses some of the pantry ingredients)
+
+- [ ] **Step 1: Baseline — confirm default behavior still subtracts pantry**
+
+```bash
+cargo run --quiet -- shopping-list --base-path ./seed "Breakfast/Easy Pancakes.cook"
+```
+
+Expected: a categorized shopping list. Ingredients also present in `seed/config/pantry.conf` with non-zero quantity (e.g. `flour`, `milk`, `eggs`, `butter`) should be absent or reduced in the output. Note which ingredients appear / are reduced — you'll compare against the next runs.
+
+- [ ] **Step 2: `--ignore-pantry` produces the unfiltered list**
+
+```bash
+cargo run --quiet -- shopping-list --base-path ./seed --ignore-pantry "Breakfast/Easy Pancakes.cook"
+```
+
+Expected: same recipe, but the ingredients suppressed in Step 1 (e.g. `flour`, `milk`, `eggs`, `butter`) now appear at their full recipe quantities. Confirm at least one ingredient that was missing in Step 1 is present here.
+
+- [ ] **Step 3: `--pantry <path>` uses the custom file**
+
+Create a minimal temporary pantry file that subtracts only one ingredient:
+
+```bash
+cat > /tmp/test-pantry.conf <<'EOF'
+[pantry]
+flour = { quantity = "1%kg" }
+EOF
+```
+
+Then run:
+
+```bash
+cargo run --quiet -- shopping-list --base-path ./seed --pantry /tmp/test-pantry.conf "Breakfast/Easy Pancakes.cook"
+```
+
+Expected: `flour` is reduced/removed (per the custom pantry), but `milk`, `eggs`, and `butter` (which are in `seed/config/pantry.conf` but NOT in the custom file) now appear at full recipe quantities. This confirms `--pantry` overrides auto-discovery.
+
+Clean up: `rm /tmp/test-pantry.conf`
+
+- [ ] **Step 4: `--ignore-pantry` wins over `--pantry`**
+
+```bash
+cargo run --quiet -- shopping-list --base-path ./seed --ignore-pantry --pantry /does/not/exist.conf "Breakfast/Easy Pancakes.cook"
+```
+
+Expected: succeeds with no error (does not attempt to open `/does/not/exist.conf`) and produces the same unfiltered list as Step 2.
+
+- [ ] **Step 5: Help text reflects the new flags**
+
+```bash
+cargo run --quiet -- shopping-list --help
+```
+
+Expected: output includes lines for `--pantry <PANTRY>` ("Load pantry conf file") and `--ignore-pantry` ("Don't subtract pantry items from the shopping list").
+
+- [ ] **Step 6: Confirm no commit is needed**
+
+```bash
+git status
+```
+
+Expected: working tree clean (Task 1 already committed; this task is verification only). If anything was modified, investigate before continuing.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Spec goal 1: add `--pantry <path>` arg → Task 1 Step 1.
+- Spec goal 2: add `--ignore-pantry` flag → Task 1 Step 1.
+- Spec resolution logic (ignore wins; else `args.pantry.or_else(ctx.pantry())`) → Task 1 Step 2.
+- Spec interaction matrix row "ignore wins over `--pantry`" → Task 2 Step 4.
+- Spec testing section bullets 1–4 → Task 2 Steps 1–4.
+
+**Placeholder scan:** No TBDs, no "add appropriate X", no "similar to task N". All code shown in full.
+
+**Type consistency:** Both new args use `Option<Utf8PathBuf>` / `bool`, matching the existing `aisle` and `ignore_references` fields on the same struct. The resolution expression `args.pantry.clone().or_else(|| ctx.pantry())` returns `Option<Utf8PathBuf>`, which is what the rest of the existing block already expects.
diff --git a/docs/superpowers/plans/2026-05-15-static-site-build.md b/docs/superpowers/plans/2026-05-15-static-site-build.md
new file mode 100644
index 0000000..f7b202a
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-15-static-site-build.md
@@ -0,0 +1,1774 @@
+# Static Site Build Command Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `cook build` CLI command that renders the recipe collection as a self-contained static HTML site, reusing the existing server templates.
+
+**Architecture:** New top-level module `src/build/` orchestrates a single-pass render. We add a `static_mode: bool` flag to existing Askama template structs and gate dynamic UI in template files behind it. Recipe/menu rendering logic is first extracted from `src/server/ui.rs` handlers into `src/server/builders.rs` so both the server and the static build use the same code path. The build writes HTML files mirroring the source tree, copies embedded static assets and recipe images, and generates a JSON search index plus a small client-side `search.js`.
+
+**Tech Stack:** Rust, Askama (templates), `cooklang_find` (recipe tree), `RustEmbed` (static asset embedding), `tempfile`/`assert_cmd` (tests).
+
+**Spec:** `docs/superpowers/specs/2026-05-15-static-site-build-design.md`
+
+---
+
+## File Structure
+
+**New files (Rust):**
+- `src/build/mod.rs` — `BuildArgs`, `run(ctx, args)`, orchestrator
+- `src/build/renderer.rs` — render functions for index/directory/recipe/menu pages
+- `src/build/writer.rs` — file writes, static asset copying, image copying
+- `src/build/links.rs` — relative `prefix` computation per page
+- `src/build/index.rs` — search index generation
+- `src/server/builders.rs` — extracted template-builder functions (used by both server and build)
+- `tests/build.rs` — integration smoke tests
+
+**New file (static asset):**
+- `static/js/search.js` — client-side search using `search-index.json`
+
+**Modified files:**
+- `src/args.rs` — add `Build` command variant
+- `src/main.rs` — add `build` module + dispatch + base_path handling for build command
+- `src/server/mod.rs` — wire `builders` module
+- `src/server/templates.rs` — add `static_mode: bool` to all relevant template structs
+- `src/server/ui.rs` — call new builders, pass `static_mode: false`
+- `templates/base.html` — gate dynamic nav, switch search JS source
+- `templates/recipes.html` — gate shopping-list & menu buttons; append `.html` to links
+- `templates/recipe.html` — gate edit/shopping-list/pantry/scaling; append `.html`
+- `templates/menu.html` — gate edit/shopping-list; append `.html`
+- `Cargo.toml` — none expected; reuse existing deps
+
+---
+
+## Task 1: CLI skeleton (`cook build` stub)
+
+**Files:**
+- Create: `src/build/mod.rs`
+- Modify: `src/args.rs`, `src/main.rs`
+- Test: `tests/build.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/build.rs`:
+
+```rust
+use assert_cmd::Command;
+
+#[test]
+fn build_command_help_works() {
+    let mut cmd = Command::cargo_bin("cook").unwrap();
+    cmd.args(["build", "--help"]).assert().success();
+}
+```
+
+- [ ] **Step 2: Run test, verify it fails**
+
+Run: `cargo test --test build build_command_help_works`
+Expected: FAIL with unrecognized subcommand `build`.
+
+- [ ] **Step 3: Add stub module `src/build/mod.rs`**
+
+```rust
+use crate::Context;
+use anyhow::Result;
+use camino::Utf8PathBuf;
+use clap::Args;
+
+#[derive(Debug, Args)]
+pub struct BuildArgs {
+    /// Output directory for the generated static site
+    ///
+    /// Defaults to ./_site if not specified. The directory is created if
+    /// missing. Existing files in the directory are overwritten as needed
+    /// but not wiped wholesale.
+    #[arg(value_hint = clap::ValueHint::DirPath)]
+    pub output_dir: Option<Utf8PathBuf>,
+
+    /// Root directory containing your recipe files
+    #[arg(long, value_hint = clap::ValueHint::DirPath)]
+    pub base_path: Option<Utf8PathBuf>,
+
+    /// Absolute URL prefix for hosting under a subpath (e.g. /recipes/)
+    ///
+    /// When set, internal links use this absolute prefix instead of
+    /// page-relative paths. Useful when you know the deployed subpath.
+    #[arg(long)]
+    pub base_url: Option<String>,
+}
+
+impl BuildArgs {
+    pub fn get_base_path(&self) -> Option<Utf8PathBuf> {
+        self.base_path.clone()
+    }
+}
+
+pub fn run(_ctx: &Context, _args: BuildArgs) -> Result<()> {
+    println!("cook build: not yet implemented");
+    Ok(())
+}
+```
+
+- [ ] **Step 4: Wire into `src/args.rs`**
+
+Add `build` to the imports at top:
+
+```rust
+use crate::{build, doctor, import, lsp, pantry, recipe, report, search, seed, server, shopping_list};
+```
+
+Add the command variant in the `Command` enum (after `Server`):
+
+```rust
+/// Generate a self-contained static website from your recipe collection
+///
+/// Renders your recipes as static HTML files browsable on any static-file
+/// host or directly from disk via file://. Excludes dynamic features
+/// (shopping list, pantry, editing).
+///
+/// Examples:
+///   cook build                         # Build to ./_site
+///   cook build out                     # Build to ./out
+///   cook build --base-path ~/recipes   # Use specific source directory
+///   cook build --base-url /recipes/    # Absolute URL prefix for subpath hosting
+#[command(
+    long_about = "Generate a static HTML website from your recipe collection"
+)]
+Build(build::BuildArgs),
+```
+
+- [ ] **Step 5: Wire into `src/main.rs`**
+
+Add module declaration near the other `mod` lines:
+
+```rust
+mod build;
+```
+
+Add match arm in `main()`:
+
+```rust
+Command::Build(args) => build::run(&ctx, args),
+```
+
+Add the `Build` case in `configure_context()` so its `--base-path` flag is honored:
+
+```rust
+Command::Build(ref build_args) => build_args
+    .get_base_path()
+    .unwrap_or_else(|| Utf8PathBuf::from(".")),
+```
+
+- [ ] **Step 6: Run test, verify it passes**
+
+Run: `cargo test --test build build_command_help_works`
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): add cook build command skeleton"
+```
+
+---
+
+## Task 2: Output directory resolution and basic invocation
+
+**Files:**
+- Modify: `src/build/mod.rs`
+- Test: `tests/build.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/build.rs`:
+
+```rust
+use std::path::PathBuf;
+use tempfile::TempDir;
+
+fn seed_dir() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("seed")
+}
+
+#[test]
+fn build_creates_output_dir() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    let mut cmd = Command::cargo_bin("cook").unwrap();
+    cmd.args([
+        "build",
+        out.to_str().unwrap(),
+        "--base-path",
+        seed.to_str().unwrap(),
+    ])
+    .assert()
+    .success();
+
+    assert!(out.is_dir(), "output dir should exist after build");
+}
+```
+
+- [ ] **Step 2: Run test, verify it fails**
+
+Run: `cargo test --test build build_creates_output_dir`
+Expected: FAIL — output dir not created (stub just prints).
+
+- [ ] **Step 3: Implement output directory creation in `src/build/mod.rs`**
+
+Replace `run`:
+
+```rust
+use crate::util::resolve_to_absolute_path;
+use crate::Context;
+use anyhow::{bail, Context as _, Result};
+use camino::Utf8PathBuf;
+use clap::Args;
+
+#[derive(Debug, Args)]
+pub struct BuildArgs {
+    /// Output directory for the generated static site
+    #[arg(value_hint = clap::ValueHint::DirPath)]
+    pub output_dir: Option<Utf8PathBuf>,
+
+    /// Root directory containing your recipe files
+    #[arg(long, value_hint = clap::ValueHint::DirPath)]
+    pub base_path: Option<Utf8PathBuf>,
+
+    /// Absolute URL prefix for hosting under a subpath (e.g. /recipes/)
+    #[arg(long)]
+    pub base_url: Option<String>,
+}
+
+impl BuildArgs {
+    pub fn get_base_path(&self) -> Option<Utf8PathBuf> {
+        self.base_path.clone()
+    }
+}
+
+pub fn run(ctx: &Context, args: BuildArgs) -> Result<()> {
+    let source = resolve_to_absolute_path(ctx.base_path())?;
+    if !source.is_dir() {
+        bail!("Source base path is not a directory: {source}");
+    }
+
+    let output = args
+        .output_dir
+        .clone()
+        .unwrap_or_else(|| Utf8PathBuf::from("_site"));
+    let output = resolve_to_absolute_path(&output)?;
+
+    std::fs::create_dir_all(&output)
+        .with_context(|| format!("Failed to create output directory: {output}"))?;
+
+    tracing::info!("Building static site from {source} into {output}");
+    println!("Building static site from {source} into {output}");
+    Ok(())
+}
+```
+
+- [ ] **Step 4: Run test, verify it passes**
+
+Run: `cargo test --test build`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): resolve source and output paths"
+```
+
+---
+
+## Task 3: Add `static_mode` field to template structs
+
+**Files:**
+- Modify: `src/server/templates.rs`
+- Modify: `src/server/ui.rs`
+
+- [ ] **Step 1: Add `static_mode` to template structs**
+
+In `src/server/templates.rs`, add `pub static_mode: bool` as the last field of these structs:
+- `ErrorTemplate`
+- `RecipesTemplate`
+- `RecipeTemplate`
+- `MenuTemplate`
+
+(Skip `ShoppingListTemplate`, `PreferencesTemplate`, `PantryTemplate`, `EditTemplate`, `NewTemplate` — never rendered in static mode.)
+
+Example for `RecipesTemplate`:
+
+```rust
+#[derive(Template)]
+#[template(path = "recipes.html")]
+pub struct RecipesTemplate {
+    pub active: String,
+    pub current_name: String,
+    pub breadcrumbs: Vec<Breadcrumb>,
+    pub items: Vec<RecipeItem>,
+    pub todays_menu: Option<TodaysMenu>,
+    pub tr: Tr,
+    pub prefix: String,
+    pub static_mode: bool,
+}
+```
+
+- [ ] **Step 2: Pass `static_mode: false` from every server handler**
+
+In `src/server/ui.rs`, find each construction of `RecipesTemplate`, `RecipeTemplate`, `MenuTemplate`, and `ErrorTemplate` (in `error_page`). Add `static_mode: false,` to each struct literal.
+
+Use `grep` to find every occurrence:
+```bash
+grep -n "RecipesTemplate\|RecipeTemplate\|MenuTemplate\|ErrorTemplate" src/server/ui.rs src/server/handlers/*.rs src/server/mod.rs
+```
+
+For each match, append `static_mode: false,` to the field list. Do not miss any — askama will fail to compile if `static_mode` is referenced in templates and missing from struct literals.
+
+- [ ] **Step 3: Run `cargo build` to verify compilation**
+
+Run: `cargo build`
+Expected: compiles cleanly. If any struct literal is missing `static_mode`, the compiler points at the line.
+
+- [ ] **Step 4: Run existing tests**
+
+Run: `cargo test`
+Expected: all existing tests pass (no behavior change yet).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "refactor(server): add static_mode field to template structs"
+```
+
+---
+
+## Task 4: Gate dynamic UI in `templates/base.html`
+
+**Files:**
+- Modify: `templates/base.html`
+
+- [ ] **Step 1: Gate dynamic nav links**
+
+In `templates/base.html`, wrap each of these elements in `{% if !static_mode %} ... {% endif %}`:
+
+1. The shopping-list nav link (the `<a href="{{ prefix }}/shopping-list" ...>` block, lines ~777-779).
+2. The pantry nav link (`<a href="{{ prefix }}/pantry" ...>`, lines ~780-782).
+3. The preferences nav link (`<a href="{{ prefix }}/preferences" ...>`, lines ~784-786).
+4. The mobile overflow dropdown's preferences link inside `#more-dropdown` (lines ~808-810).
+
+Each looks like:
+```html
+{% if !static_mode %}
+<a href="{{ prefix }}/shopping-list" ...>...</a>
+{% endif %}
+```
+
+- [ ] **Step 2: Conditional search JS source**
+
+Find the inline search script (around line 877 with `fetch(\`{{ prefix }}/api/search?q=...\`)`).
+
+Wrap the entire `<script>` block that defines the search behavior (from `const searchInput = document.getElementById('search-input');` through the closing `</script>` containing the `document.addEventListener('click', ...)` block) in:
+
+```html
+{% if !static_mode %}
+<script>
+  // ... existing dynamic search script unchanged ...
+</script>
+{% else %}
+<script src="{{ prefix }}/static/js/search.js"></script>
+{% endif %}
+```
+
+Keep the `translations` object (which is currently at the top of that script block) inside the `!static_mode` branch — search.js for static mode will hardcode strings.
+
+- [ ] **Step 3: Verify template compiles**
+
+Run: `cargo build`
+Expected: compiles cleanly. Askama validates template syntax at compile time.
+
+- [ ] **Step 4: Run existing tests**
+
+Run: `cargo test`
+Expected: PASS (server still passes `static_mode: false`, so nothing changes at runtime).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(templates): gate dynamic nav and search behind static_mode"
+```
+
+---
+
+## Task 5: Gate dynamic UI in remaining templates
+
+**Files:**
+- Modify: `templates/recipes.html`
+- Modify: `templates/recipe.html`
+- Modify: `templates/menu.html`
+
+For each file:
+
+- [ ] **Step 1: Search for elements that mutate state or call dynamic APIs**
+
+Run for each file:
+```bash
+grep -n "/api/\|shopping-list\|pantry\|/edit\|/new\|scale-input\|reload\|onclick" templates/recipes.html
+grep -n "/api/\|shopping-list\|pantry\|/edit\|/new\|scale-input\|reload\|onclick" templates/recipe.html
+grep -n "/api/\|shopping-list\|pantry\|/edit\|/new\|scale-input\|reload\|onclick" templates/menu.html
+```
+
+- [ ] **Step 2: Wrap each dynamic-only block in `{% if !static_mode %} ... {% endif %}`**
+
+Specifically gate:
+
+In `templates/recipes.html`:
+- "Add menu to shopping list" buttons and links to `/shopping-list`.
+- Any link to `/edit/...` or `/new`.
+
+In `templates/recipe.html`:
+- Edit button / link to `/edit/...`
+- "Add to shopping list" button(s) and any `/api/shopping_list*` form submission targets.
+- "In pantry" badges / pantry-related elements.
+- Scale input control (the entire scaling form/UI block).
+- Any `<script>` block that calls `/api/shopping_list*` or `/api/pantry*`.
+
+In `templates/menu.html`:
+- Edit / shopping-list / pantry actions, same as recipe.html.
+
+Leave intact: ingredient/cookware/timer badges, recipe metadata, sections/steps, the cooking-mode JSON script (which is read-only), images.
+
+- [ ] **Step 3: Verify template compiles**
+
+Run: `cargo build`
+Expected: cleanly compiles.
+
+- [ ] **Step 4: Run existing tests**
+
+Run: `cargo test`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(templates): gate dynamic actions in recipe/menu/recipes templates"
+```
+
+---
+
+## Task 6: Append `.html` to internal links when `static_mode`
+
+**Files:**
+- Modify: `templates/base.html`
+- Modify: `templates/recipes.html`
+- Modify: `templates/recipe.html`
+- Modify: `templates/menu.html`
+
+The server uses URLs like `{{ prefix }}/recipe/{{ path }}`. The static site needs the same but with `.html` appended. We do this with an inline conditional next to each href.
+
+- [ ] **Step 1: Find every relevant href**
+
+Run:
+```bash
+grep -n 'href="{{ prefix }}/recipe/\|href="{{ prefix }}/directory/\|href="{{ prefix }}/menu/' templates/*.html
+```
+
+- [ ] **Step 2: Add `.html` suffix conditionally**
+
+For each match, change:
+```html
+href="{{ prefix }}/recipe/{{ item.path }}"
+```
+to:
+```html
+href="{{ prefix }}/recipe/{{ item.path }}{% if static_mode %}.html{% endif %}"
+```
+
+Do the same for `/directory/...` and `/menu/...` href patterns.
+
+Also handle the root navigation: `href="{{ prefix }}/"` in base.html. In static mode the root is `index.html` — the existing trailing-slash form works on web servers but not under `file://`. Change to:
+```html
+href="{{ prefix }}/{% if static_mode %}index.html{% endif %}"
+```
+
+For breadcrumbs that link to a directory path (e.g. `href="{{ prefix }}/directory/{{ crumb.path }}"`), apply the same `.html` suffix rule.
+
+- [ ] **Step 3: Verify template compiles**
+
+Run: `cargo build`
+Expected: cleanly compiles.
+
+- [ ] **Step 4: Run existing tests**
+
+Run: `cargo test`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(templates): append .html to internal links in static_mode"
+```
+
+---
+
+## Task 7: Extract template builders from `src/server/ui.rs`
+
+The goal is to share recipe / menu / recipes template construction between the server handler and the static-site renderer without copy-pasting.
+
+**Files:**
+- Create: `src/server/builders.rs`
+- Modify: `src/server/mod.rs`
+- Modify: `src/server/ui.rs`
+
+- [ ] **Step 1: Create `src/server/builders.rs` with extracted functions**
+
+Move (don't copy) the template-construction body of each handler in `src/server/ui.rs` into new functions:
+
+```rust
+use crate::server::templates::*;
+use anyhow::Result;
+use camino::{Utf8Path, Utf8PathBuf};
+use unic_langid::LanguageIdentifier;
+
+pub struct RecipesBuildInput<'a> {
+    pub base_path: &'a Utf8Path,
+    pub url_prefix: &'a str,
+    pub sub_path: Option<&'a str>,
+    pub lang: LanguageIdentifier,
+    pub static_mode: bool,
+}
+
+/// Build a RecipesTemplate for either the root or a subdirectory.
+pub fn build_recipes_template(input: RecipesBuildInput<'_>) -> Result<RecipesTemplate> {
+    // ... move the body of `recipes_handler` here, returning RecipesTemplate instead of Response ...
+}
+
+pub struct RecipeBuildInput<'a> {
+    pub base_path: &'a Utf8Path,
+    pub url_prefix: &'a str,
+    pub recipe_path: &'a str,
+    pub aisle_path: Option<&'a Utf8PathBuf>,
+    pub scale: f64,
+    pub lang: LanguageIdentifier,
+    pub static_mode: bool,
+}
+
+pub enum RecipeBuildOutput {
+    Recipe(RecipeTemplate),
+    Menu(MenuTemplate),
+}
+
+/// Build a RecipeTemplate or MenuTemplate for the given recipe path.
+pub fn build_recipe_template(input: RecipeBuildInput<'_>) -> Result<RecipeBuildOutput> {
+    // ... move the body of `recipe_page` (excluding axum response handling) here ...
+}
+```
+
+The functions return template structs (`Result<RecipesTemplate>` etc.) rather than `axum::Response`. Move the parsing, image-path resolution, ingredient grouping, and section building. Set `static_mode` from the input.
+
+- [ ] **Step 2: Register `builders` module**
+
+In `src/server/mod.rs`, add:
+```rust
+pub mod builders;
+```
+
+- [ ] **Step 3: Update `src/server/ui.rs` handlers to use builders**
+
+Each handler becomes a thin wrapper:
+
+```rust
+async fn recipes_handler(
+    state: Arc<AppState>,
+    path: Option<String>,
+    lang: LanguageIdentifier,
+) -> axum::response::Response {
+    let input = crate::server::builders::RecipesBuildInput {
+        base_path: &state.base_path,
+        url_prefix: &state.url_prefix,
+        sub_path: path.as_deref(),
+        lang: lang.clone(),
+        static_mode: false,
+    };
+    match crate::server::builders::build_recipes_template(input) {
+        Ok(template) => template.into_response(),
+        Err(e) => error_page(lang, &state.url_prefix, &e),
+    }
+}
+```
+
+Apply equivalent rewrites for `recipe_page` (handling both `RecipeBuildOutput::Recipe` and `Menu`), and remove now-unused helpers from `ui.rs` (`count_recipes_tree`, `get_image_path`, etc.) by moving them into `builders.rs` if still needed.
+
+- [ ] **Step 4: Verify everything compiles**
+
+Run: `cargo build`
+Expected: clean build.
+
+- [ ] **Step 5: Run existing tests**
+
+Run: `cargo test`
+Expected: PASS. Server behavior unchanged.
+
+- [ ] **Step 6: Manual smoke test**
+
+Run:
+```bash
+cargo run -- server ./seed &
+SERVER_PID=$!
+sleep 2
+curl -sf http://127.0.0.1:9080/ > /dev/null && echo "root OK"
+curl -sf http://127.0.0.1:9080/recipe/Breakfast/Easy%20Pancakes > /dev/null && echo "recipe OK"
+kill $SERVER_PID
+```
+Expected: both "root OK" and "recipe OK" print.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add -A
+git commit -m "refactor(server): extract template builders for reuse"
+```
+
+---
+
+## Task 8: Implement relative-prefix helper
+
+**Files:**
+- Create: `src/build/links.rs`
+- Modify: `src/build/mod.rs`
+- Test: inline `#[cfg(test)]` module in `src/build/links.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/build/links.rs`:
+
+```rust
+use camino::Utf8Path;
+
+/// Given an output file path like "index.html" or "recipe/Breakfast/Pancakes.html",
+/// return the relative prefix that resolves from that file back to the output root.
+/// Examples:
+///   "index.html"                            -> "."
+///   "directory/Breakfast.html"              -> ".."
+///   "recipe/Breakfast/Pancakes.html"        -> "../.."
+///   "menu/Sunday/Brunch.html"               -> "../.."
+pub fn relative_prefix(output_relpath: &Utf8Path) -> String {
+    let depth = output_relpath
+        .components()
+        .count()
+        .saturating_sub(1); // last component is the filename
+    if depth == 0 {
+        ".".to_string()
+    } else {
+        std::iter::repeat("..")
+            .take(depth)
+            .collect::<Vec<_>>()
+            .join("/")
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn root_index() {
+        assert_eq!(relative_prefix(Utf8Path::new("index.html")), ".");
+    }
+
+    #[test]
+    fn one_level_deep() {
+        assert_eq!(relative_prefix(Utf8Path::new("directory/Breakfast.html")), "..");
+    }
+
+    #[test]
+    fn two_levels_deep() {
+        assert_eq!(relative_prefix(Utf8Path::new("recipe/Breakfast/Pancakes.html")), "../..");
+    }
+
+    #[test]
+    fn three_levels_deep() {
+        assert_eq!(relative_prefix(Utf8Path::new("recipe/A/B/C.html")), "../../..");
+    }
+}
+```
+
+- [ ] **Step 2: Register module in `src/build/mod.rs`**
+
+Add at the top:
+```rust
+mod links;
+```
+
+- [ ] **Step 3: Run tests, verify they pass**
+
+Run: `cargo test --lib build::links`
+Expected: PASS for all four tests.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): add relative-prefix helper"
+```
+
+---
+
+## Task 9: Implement file writer module
+
+**Files:**
+- Create: `src/build/writer.rs`
+- Modify: `src/build/mod.rs`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `src/build/writer.rs`:
+
+```rust
+use anyhow::{Context, Result};
+use camino::Utf8Path;
+use std::fs;
+
+/// Write `contents` to `output_root/relpath`, creating parent directories.
+pub fn write_html(output_root: &Utf8Path, relpath: &Utf8Path, contents: &str) -> Result<()> {
+    let dest = output_root.join(relpath);
+    if let Some(parent) = dest.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("Failed to create parent dir: {parent}"))?;
+    }
+    fs::write(&dest, contents).with_context(|| format!("Failed to write: {dest}"))?;
+    Ok(())
+}
+
+/// Copy `bytes` to `output_root/relpath`, creating parent directories.
+pub fn write_bytes(output_root: &Utf8Path, relpath: &Utf8Path, bytes: &[u8]) -> Result<()> {
+    let dest = output_root.join(relpath);
+    if let Some(parent) = dest.parent() {
+        fs::create_dir_all(parent)
+            .with_context(|| format!("Failed to create parent dir: {parent}"))?;
+    }
+    fs::write(&dest, bytes).with_context(|| format!("Failed to write: {dest}"))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn write_html_creates_nested_dirs() {
+        let tmp = TempDir::new().unwrap();
+        let root = camino::Utf8Path::from_path(tmp.path()).unwrap();
+        let rel = Utf8Path::new("a/b/c.html");
+        write_html(root, rel, "<html></html>").unwrap();
+        let contents = std::fs::read_to_string(root.join(rel)).unwrap();
+        assert_eq!(contents, "<html></html>");
+    }
+}
+```
+
+- [ ] **Step 2: Register module in `src/build/mod.rs`**
+
+Add:
+```rust
+mod writer;
+```
+
+- [ ] **Step 3: Run test**
+
+Run: `cargo test --lib build::writer`
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): add output writer with nested dir support"
+```
+
+---
+
+## Task 10: Copy embedded static assets
+
+**Files:**
+- Modify: `src/build/writer.rs`
+- Modify: `src/build/mod.rs`
+
+Note: The server's `StaticFiles` rust-embed is declared as `struct StaticFiles` in `src/server/mod.rs`. We need access to it. Make it `pub` so build can use it.
+
+- [ ] **Step 1: Make `StaticFiles` pub in `src/server/mod.rs`**
+
+Find:
+```rust
+#[derive(RustEmbed)]
+#[folder = "static/"]
+struct StaticFiles;
+```
+
+Change to:
+```rust
+#[derive(RustEmbed)]
+#[folder = "static/"]
+pub struct StaticFiles;
+```
+
+- [ ] **Step 2: Add `copy_static_assets` to `src/build/writer.rs`**
+
+Append:
+
+```rust
+use rust_embed::RustEmbed;
+
+/// Copy every file in the rust-embed `StaticFiles` to `output_root/static/<path>`.
+pub fn copy_static_assets(output_root: &Utf8Path) -> Result<usize> {
+    let mut count = 0;
+    for path in crate::server::StaticFiles::iter() {
+        let rel = Utf8Path::new("static").join(path.as_ref());
+        let file = crate::server::StaticFiles::get(path.as_ref())
+            .with_context(|| format!("Embedded file vanished: {path}"))?;
+        write_bytes(output_root, &rel, &file.data)?;
+        count += 1;
+    }
+    Ok(count)
+}
+```
+
+- [ ] **Step 3: Write test**
+
+Append to the `#[cfg(test)] mod tests` block in `src/build/writer.rs`:
+
+```rust
+#[test]
+fn copy_static_assets_writes_known_file() {
+    let tmp = TempDir::new().unwrap();
+    let root = camino::Utf8Path::from_path(tmp.path()).unwrap();
+    let count = copy_static_assets(root).unwrap();
+    assert!(count > 0, "should copy at least one static asset");
+    assert!(root.join("static/css/output.css").is_file());
+}
+```
+
+- [ ] **Step 4: Run test**
+
+Run: `cargo test --lib build::writer::tests::copy_static_assets_writes_known_file`
+Expected: PASS. (Prerequisite: `make css` was run at some point so `static/css/output.css` exists. CI runs this. Locally run `make css` first if it fails.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): copy embedded static assets to output"
+```
+
+---
+
+## Task 11: Render index and directory pages
+
+**Files:**
+- Create: `src/build/renderer.rs`
+- Modify: `src/build/mod.rs`
+
+- [ ] **Step 1: Create `src/build/renderer.rs`**
+
+```rust
+use crate::build::links::relative_prefix;
+use crate::build::writer::write_html;
+use crate::server::builders::{build_recipes_template, RecipesBuildInput};
+use anyhow::Result;
+use askama::Template;
+use camino::{Utf8Path, Utf8PathBuf};
+use unic_langid::LanguageIdentifier;
+
+/// Render the root index page (recipes listing).
+pub fn render_index(
+    source: &Utf8Path,
+    output: &Utf8Path,
+    base_url: Option<&str>,
+    lang: &LanguageIdentifier,
+) -> Result<()> {
+    let relpath = Utf8PathBuf::from("index.html");
+    let prefix = compute_prefix(base_url, &relpath);
+    let template = build_recipes_template(RecipesBuildInput {
+        base_path: source,
+        url_prefix: &prefix,
+        sub_path: None,
+        lang: lang.clone(),
+        static_mode: true,
+    })?;
+    let html = template.render()?;
+    write_html(output, &relpath, &html)
+}
+
+/// Render one directory listing page.
+pub fn render_directory(
+    source: &Utf8Path,
+    output: &Utf8Path,
+    sub_path: &str,
+    base_url: Option<&str>,
+    lang: &LanguageIdentifier,
+) -> Result<()> {
+    let relpath = Utf8PathBuf::from(format!("directory/{sub_path}.html"));
+    let prefix = compute_prefix(base_url, &relpath);
+    let template = build_recipes_template(RecipesBuildInput {
+        base_path: source,
+        url_prefix: &prefix,
+        sub_path: Some(sub_path),
+        lang: lang.clone(),
+        static_mode: true,
+    })?;
+    let html = template.render()?;
+    write_html(output, &relpath, &html)
+}
+
+fn compute_prefix(base_url: Option<&str>, relpath: &Utf8Path) -> String {
+    match base_url {
+        Some(b) => b.trim_end_matches('/').to_string(),
+        None => relative_prefix(relpath),
+    }
+}
+```
+
+- [ ] **Step 2: Register module**
+
+In `src/build/mod.rs`:
+```rust
+mod renderer;
+```
+
+- [ ] **Step 3: Walk tree in `run()` and render listings**
+
+In `src/build/mod.rs`, replace the body of `run()`:
+
+```rust
+pub fn run(ctx: &Context, args: BuildArgs) -> Result<()> {
+    let source = resolve_to_absolute_path(ctx.base_path())?;
+    if !source.is_dir() {
+        bail!("Source base path is not a directory: {source}");
+    }
+
+    let output = args
+        .output_dir
+        .clone()
+        .unwrap_or_else(|| Utf8PathBuf::from("_site"));
+    let output = resolve_to_absolute_path(&output)?;
+    std::fs::create_dir_all(&output)
+        .with_context(|| format!("Failed to create output directory: {output}"))?;
+
+    println!("Building static site from {source} into {output}");
+
+    let lang: unic_langid::LanguageIdentifier = "en-US".parse().unwrap();
+    let base_url = args.base_url.as_deref();
+
+    renderer::render_index(&source, &output, base_url, &lang)?;
+
+    let tree = cooklang_find::build_tree(&source)?;
+    walk_directories(&tree, &source, &output, base_url, &lang, String::new())?;
+
+    let asset_count = writer::copy_static_assets(&output)?;
+    println!("Wrote index, directories, and {asset_count} static assets");
+    Ok(())
+}
+
+fn walk_directories(
+    tree: &cooklang_find::RecipeTree,
+    source: &camino::Utf8Path,
+    output: &camino::Utf8Path,
+    base_url: Option<&str>,
+    lang: &unic_langid::LanguageIdentifier,
+    prefix_path: String,
+) -> Result<()> {
+    for (name, child) in &tree.children {
+        if child.children.is_empty() {
+            continue; // it's a recipe file, handled in next task
+        }
+        let sub = if prefix_path.is_empty() {
+            name.to_string()
+        } else {
+            format!("{prefix_path}/{name}")
+        };
+        renderer::render_directory(source, output, &sub, base_url, lang)?;
+        walk_directories(child, source, output, base_url, lang, sub)?;
+    }
+    Ok(())
+}
+```
+
+- [ ] **Step 4: Write integration test**
+
+Append to `tests/build.rs`:
+
+```rust
+#[test]
+fn build_writes_index_and_static_assets() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    Command::cargo_bin("cook")
+        .unwrap()
+        .args([
+            "build",
+            out.to_str().unwrap(),
+            "--base-path",
+            seed.to_str().unwrap(),
+        ])
+        .assert()
+        .success();
+
+    assert!(out.join("index.html").is_file(), "index.html should exist");
+    assert!(out.join("static/css/output.css").is_file(), "css should exist");
+
+    let index = std::fs::read_to_string(out.join("index.html")).unwrap();
+    assert!(!index.contains("/api/search"), "static index should not reference api search");
+    assert!(!index.contains("Add to shopping list"), "no shopping list UI");
+}
+```
+
+- [ ] **Step 5: Run test**
+
+Run: `cargo test --test build build_writes_index_and_static_assets`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): render index and directory listings"
+```
+
+---
+
+## Task 12: Render recipe and menu pages
+
+**Files:**
+- Modify: `src/build/renderer.rs`
+- Modify: `src/build/mod.rs`
+
+- [ ] **Step 1: Add render functions for recipes and menus**
+
+Append to `src/build/renderer.rs`:
+
+```rust
+use crate::server::builders::{build_recipe_template, RecipeBuildInput, RecipeBuildOutput};
+
+/// Render a single recipe (or menu) page.
+///
+/// Both `recipe/<path>.html` and `menu/<path>.html` sit at the same depth in
+/// the output tree, so the page-relative `prefix` is identical regardless of
+/// which one we end up writing. We render once and pick the destination path
+/// based on whether the entry turned out to be a menu.
+pub fn render_recipe(
+    source: &Utf8Path,
+    output: &Utf8Path,
+    recipe_relpath: &str,
+    aisle_path: Option<&Utf8PathBuf>,
+    base_url: Option<&str>,
+    lang: &LanguageIdentifier,
+) -> Result<()> {
+    let trimmed = recipe_relpath.trim_end_matches(".cook");
+    let provisional = Utf8PathBuf::from(format!("recipe/{trimmed}.html"));
+    let prefix = compute_prefix(base_url, &provisional);
+
+    let kind = build_recipe_template(RecipeBuildInput {
+        base_path: source,
+        url_prefix: &prefix,
+        recipe_path: recipe_relpath,
+        aisle_path,
+        scale: 1.0,
+        lang: lang.clone(),
+        static_mode: true,
+    })?;
+
+    match kind {
+        RecipeBuildOutput::Recipe(t) => {
+            let html = t.render()?;
+            write_html(output, &provisional, &html)
+        }
+        RecipeBuildOutput::Menu(t) => {
+            let menu_relpath = Utf8PathBuf::from(format!("menu/{trimmed}.html"));
+            let html = t.render()?;
+            write_html(output, &menu_relpath, &html)
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Walk all `.cook` files in `run()`**
+
+In `src/build/mod.rs`, add a recipe-walk helper and call it from `run()` (after `walk_directories` but before asset copy):
+
+```rust
+fn walk_recipes(
+    tree: &cooklang_find::RecipeTree,
+    source: &camino::Utf8Path,
+    output: &camino::Utf8Path,
+    aisle_path: Option<&camino::Utf8PathBuf>,
+    base_url: Option<&str>,
+    lang: &unic_langid::LanguageIdentifier,
+    prefix_path: String,
+) -> Result<usize> {
+    let mut count = 0;
+    for (name, child) in &tree.children {
+        let sub = if prefix_path.is_empty() {
+            name.to_string()
+        } else {
+            format!("{prefix_path}/{name}")
+        };
+
+        if child.children.is_empty() {
+            // Recipe file
+            if let Err(e) = renderer::render_recipe(source, output, &sub, aisle_path, base_url, lang) {
+                tracing::warn!("Skipping recipe {sub}: {e:#}");
+                continue;
+            }
+            count += 1;
+        } else {
+            count += walk_recipes(child, source, output, aisle_path, base_url, lang, sub)?;
+        }
+    }
+    Ok(count)
+}
+```
+
+In `run()`, after the `walk_directories(...)` call:
+
+```rust
+let aisle = ctx.aisle();
+let recipe_count = walk_recipes(&tree, &source, &output, aisle.as_ref(), base_url, &lang, String::new())?;
+```
+
+Update the summary `println!` to include `{recipe_count}`.
+
+- [ ] **Step 3: Write integration test**
+
+Append to `tests/build.rs`:
+
+```rust
+#[test]
+fn build_writes_recipe_pages() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    Command::cargo_bin("cook")
+        .unwrap()
+        .args([
+            "build",
+            out.to_str().unwrap(),
+            "--base-path",
+            seed.to_str().unwrap(),
+        ])
+        .assert()
+        .success();
+
+    // The seed contains "Easy Pancakes.cook" under Breakfast.
+    let pancakes = out.join("recipe/Breakfast/Easy Pancakes.html");
+    assert!(pancakes.is_file(), "pancakes html should exist at {pancakes:?}");
+
+    let html = std::fs::read_to_string(&pancakes).unwrap();
+    assert!(html.contains("Pancakes"), "title should be present");
+    assert!(!html.contains("/api/shopping_list"), "no shopping-list api references");
+}
+```
+
+(If the seed directory doesn't contain that exact filename, run `ls seed/Breakfast/` first and adjust to the actual filename present.)
+
+- [ ] **Step 4: Run tests**
+
+Run: `cargo test --test build`
+Expected: PASS for all build tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): render recipe and menu pages"
+```
+
+---
+
+## Task 13: Copy recipe images
+
+**Files:**
+- Modify: `src/build/writer.rs`
+- Modify: `src/build/mod.rs`
+
+Recipe images live alongside `.cook` files (e.g. `Pancakes.jpg` next to `Pancakes.cook`). The server serves them via `/api/static/<path>`. We copy them into `_site/api/static/<same-path>` so the template-generated URLs continue to resolve.
+
+- [ ] **Step 1: Add image copy function**
+
+Append to `src/build/writer.rs`:
+
+```rust
+/// Copy a single source file into `output_root/api/static/<relpath>`.
+pub fn copy_image(output_root: &Utf8Path, source_root: &Utf8Path, abs_image: &Utf8Path) -> Result<()> {
+    let rel = abs_image
+        .strip_prefix(source_root)
+        .with_context(|| format!("Image {abs_image} not under source {source_root}"))?;
+    let dest = output_root.join("api/static").join(rel);
+    if let Some(parent) = dest.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    fs::copy(abs_image, &dest)
+        .with_context(|| format!("Failed to copy {abs_image} → {dest}"))?;
+    Ok(())
+}
+```
+
+- [ ] **Step 2: Discover and copy images during the recipe walk**
+
+In `src/build/mod.rs`, the recipe walk has access to each recipe entry. Modify `walk_recipes` so that after rendering a recipe, it also discovers and copies image files.
+
+Use the recipe-find API's `title_image()` (which the renderer already uses) plus a manual scan for step images. Simpler approach for v1: walk the source directory for any file with an image extension and copy it:
+
+Add a helper `copy_all_images(source, output)`:
+
+```rust
+fn copy_all_images(source: &camino::Utf8Path, output: &camino::Utf8Path) -> Result<usize> {
+    let mut count = 0;
+    for entry in walkdir_utf8(source)? {
+        let path = entry;
+        if path.is_file() {
+            match path.extension().map(|e| e.to_ascii_lowercase()).as_deref() {
+                Some("jpg" | "jpeg" | "png" | "gif" | "webp" | "avif") => {
+                    writer::copy_image(output, source, &path)?;
+                    count += 1;
+                }
+                _ => {}
+            }
+        }
+    }
+    Ok(count)
+}
+```
+
+The project already uses `camino` and standard library. Implement `walkdir_utf8` inline using `std::fs::read_dir` recursively (no new dependency):
+
+```rust
+fn walkdir_utf8(root: &camino::Utf8Path) -> Result<Vec<camino::Utf8PathBuf>> {
+    let mut out = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        for entry in std::fs::read_dir(&dir)? {
+            let entry = entry?;
+            let path = camino::Utf8PathBuf::try_from(entry.path())
+                .map_err(|e| anyhow::anyhow!("Non-UTF-8 path: {e}"))?;
+            if path.is_dir() {
+                // Skip hidden + output-like dirs at the source root
+                if let Some(name) = path.file_name() {
+                    if name.starts_with('.') {
+                        continue;
+                    }
+                }
+                stack.push(path);
+            } else {
+                out.push(path);
+            }
+        }
+    }
+    Ok(out)
+}
+```
+
+Call from `run()`:
+
+```rust
+let image_count = copy_all_images(&source, &output)?;
+println!("Wrote {recipe_count} recipes, {image_count} images, {asset_count} static assets");
+```
+
+- [ ] **Step 3: Integration test**
+
+Append to `tests/build.rs` (assuming the seed has at least one image):
+
+```rust
+#[test]
+fn build_copies_images_when_present() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    Command::cargo_bin("cook")
+        .unwrap()
+        .args([
+            "build",
+            out.to_str().unwrap(),
+            "--base-path",
+            seed.to_str().unwrap(),
+        ])
+        .assert()
+        .success();
+
+    // At minimum, no panic. If the seed has images, api/static exists.
+    let images_dir = out.join("api/static");
+    if images_dir.is_dir() {
+        let entries: Vec<_> = std::fs::read_dir(&images_dir).unwrap().collect();
+        assert!(!entries.is_empty(), "api/static is empty");
+    }
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cargo test --test build`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): copy recipe images to output"
+```
+
+---
+
+## Task 14: Generate search index JSON
+
+**Files:**
+- Create: `src/build/index.rs`
+- Modify: `src/build/mod.rs`
+
+- [ ] **Step 1: Write search index module**
+
+Create `src/build/index.rs`:
+
+```rust
+use anyhow::Result;
+use camino::Utf8Path;
+use serde::Serialize;
+
+#[derive(Serialize)]
+pub struct SearchEntry {
+    pub title: String,
+    pub path: String,        // e.g. "recipe/Breakfast/Pancakes.html"
+    pub tags: Vec<String>,
+    pub ingredients: Vec<String>,
+}
+
+/// Build a flat list of search entries by walking the recipe tree.
+pub fn build_search_index(
+    source: &Utf8Path,
+    tree: &cooklang_find::RecipeTree,
+) -> Result<Vec<SearchEntry>> {
+    let mut out = Vec::new();
+    collect(source, tree, String::new(), &mut out);
+    Ok(out)
+}
+
+fn collect(
+    source: &Utf8Path,
+    tree: &cooklang_find::RecipeTree,
+    prefix: String,
+    out: &mut Vec<SearchEntry>,
+) {
+    for (name, child) in &tree.children {
+        let sub = if prefix.is_empty() {
+            name.to_string()
+        } else {
+            format!("{prefix}/{name}")
+        };
+        if child.children.is_empty() {
+            if let Some(ref recipe) = child.recipe {
+                let url_path = if recipe.is_menu() {
+                    format!("menu/{sub}.html")
+                } else {
+                    format!("recipe/{sub}.html")
+                };
+                let tags = recipe.tags();
+                // Best-effort ingredient extraction; failures degrade silently.
+                let ingredients = match crate::util::parse_recipe_from_entry(recipe, 1.0) {
+                    Ok(parsed) => parsed
+                        .group_ingredients(crate::util::PARSER.converter())
+                        .into_iter()
+                        .map(|e| e.ingredient.display_name().to_string())
+                        .collect(),
+                    Err(_) => Vec::new(),
+                };
+                out.push(SearchEntry {
+                    title: name.clone(),
+                    path: url_path,
+                    tags,
+                    ingredients,
+                });
+            }
+        } else {
+            collect(source, child, sub, out);
+        }
+    }
+    let _ = source; // currently unused; reserved for future use
+}
+```
+
+- [ ] **Step 2: Register module and write index in `run()`**
+
+In `src/build/mod.rs`:
+
+```rust
+mod index;
+```
+
+After the recipe walk in `run()`:
+
+```rust
+let entries = index::build_search_index(&source, &tree)?;
+let json = serde_json::to_string(&entries)?;
+writer::write_bytes(&output, camino::Utf8Path::new("static/search-index.json"), json.as_bytes())?;
+```
+
+- [ ] **Step 3: Integration test**
+
+Append to `tests/build.rs`:
+
+```rust
+#[test]
+fn build_writes_search_index() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    Command::cargo_bin("cook")
+        .unwrap()
+        .args([
+            "build",
+            out.to_str().unwrap(),
+            "--base-path",
+            seed.to_str().unwrap(),
+        ])
+        .assert()
+        .success();
+
+    let idx = out.join("static/search-index.json");
+    assert!(idx.is_file(), "search-index.json should exist");
+
+    let json: serde_json::Value =
+        serde_json::from_reader(std::fs::File::open(&idx).unwrap()).unwrap();
+    let arr = json.as_array().expect("index is array");
+    assert!(!arr.is_empty(), "index should not be empty for seed");
+
+    let first = &arr[0];
+    assert!(first.get("title").is_some());
+    assert!(first.get("path").is_some());
+    assert!(first.get("tags").is_some());
+    assert!(first.get("ingredients").is_some());
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cargo test --test build`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): generate client-side search index JSON"
+```
+
+---
+
+## Task 15: Add client-side search script
+
+**Files:**
+- Create: `static/js/search.js`
+
+- [ ] **Step 1: Write `static/js/search.js`**
+
+This script is loaded by `base.html` when `static_mode` is true. It fetches `search-index.json`, filters as the user types, and renders results into the existing `#search-results` element. It also rewires keyboard navigation to mirror the dynamic version.
+
+```javascript
+(function () {
+  var prefix = window.__PREFIX__ || ".";
+  var input = document.getElementById("search-input");
+  var results = document.getElementById("search-results");
+  if (!input || !results) return;
+
+  var index = null;
+  var selectedIndex = -1;
+
+  function loadIndex() {
+    if (index !== null) return Promise.resolve(index);
+    return fetch(prefix + "/static/search-index.json")
+      .then(function (r) { return r.json(); })
+      .then(function (data) {
+        index = data;
+        return data;
+      })
+      .catch(function (e) {
+        console.error("search-index load failed", e);
+        index = [];
+        return index;
+      });
+  }
+
+  function score(entry, q) {
+    var ql = q.toLowerCase();
+    if (entry.title.toLowerCase().indexOf(ql) !== -1) return 3;
+    if (entry.tags.some(function (t) { return t.toLowerCase().indexOf(ql) !== -1; })) return 2;
+    if (entry.ingredients.some(function (i) { return i.toLowerCase().indexOf(ql) !== -1; })) return 1;
+    return 0;
+  }
+
+  function render(matches) {
+    if (matches.length === 0) {
+      results.innerHTML = '<div class="p-4 text-gray-500 text-center">No recipes found</div>';
+    } else {
+      results.innerHTML = matches.map(function (m) {
+        var href = prefix + "/" + m.path;
+        return '<a href="' + href + '" class="search-result block px-4 py-3 hover:bg-gradient-to-r hover:from-purple-50 hover:to-pink-50 transition-colors border-b border-gray-100 last:border-b-0">' +
+          '<div class="font-medium text-gray-800">' + escapeHtml(m.title) + '</div>' +
+          '</a>';
+      }).join("");
+    }
+    results.classList.remove("hidden");
+  }
+
+  function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  }
+
+  function updateSearchSelection() {
+    var items = results.querySelectorAll("a");
+    items.forEach(function (item, i) {
+      if (i === selectedIndex) {
+        item.classList.add("search-selected");
+        item.scrollIntoView({ block: "nearest" });
+      } else {
+        item.classList.remove("search-selected");
+      }
+    });
+  }
+
+  var timeout;
+  input.addEventListener("input", function () {
+    clearTimeout(timeout);
+    var q = this.value.trim();
+    selectedIndex = -1;
+    if (q.length < 2) {
+      results.classList.add("hidden");
+      return;
+    }
+    timeout = setTimeout(function () {
+      loadIndex().then(function (idx) {
+        var matches = idx
+          .map(function (e) { return { e: e, s: score(e, q) }; })
+          .filter(function (x) { return x.s > 0; })
+          .sort(function (a, b) { return b.s - a.s; })
+          .slice(0, 20)
+          .map(function (x) { return x.e; });
+        render(matches);
+      });
+    }, 150);
+  });
+
+  input.addEventListener("keydown", function (e) {
+    var items = results.querySelectorAll("a");
+    if (items.length === 0 || results.classList.contains("hidden")) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      selectedIndex = Math.min(selectedIndex + 1, items.length - 1);
+      updateSearchSelection();
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      selectedIndex = Math.max(selectedIndex - 1, -1);
+      updateSearchSelection();
+    } else if (e.key === "Enter") {
+      if (selectedIndex >= 0 && selectedIndex < items.length) {
+        e.preventDefault();
+        items[selectedIndex].click();
+      }
+    }
+  });
+
+  document.addEventListener("click", function (e) {
+    if (!input.contains(e.target) && !results.contains(e.target)) {
+      results.classList.add("hidden");
+      selectedIndex = -1;
+    }
+  });
+})();
+```
+
+- [ ] **Step 2: Verify it lands in the embedded assets**
+
+Run:
+```bash
+cargo build
+```
+
+`RustEmbed` rebuilds the embed automatically when files in `static/` change.
+
+- [ ] **Step 3: Integration test that search.js is in output**
+
+Extend the existing `build_writes_index_and_static_assets` test (or add a new one):
+
+```rust
+#[test]
+fn build_writes_search_js() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    Command::cargo_bin("cook")
+        .unwrap()
+        .args([
+            "build",
+            out.to_str().unwrap(),
+            "--base-path",
+            seed.to_str().unwrap(),
+        ])
+        .assert()
+        .success();
+
+    assert!(out.join("static/js/search.js").is_file(), "search.js should exist");
+}
+```
+
+- [ ] **Step 4: Run tests**
+
+Run: `cargo test --test build`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "feat(build): add client-side search script"
+```
+
+---
+
+## Task 16: Verify static mode strips dynamic UI strings
+
+A safety-net test that proves the gating in templates is correctly disabled in static mode.
+
+**Files:**
+- Modify: `tests/build.rs`
+
+- [ ] **Step 1: Write assertion**
+
+Append to `tests/build.rs`:
+
+```rust
+#[test]
+fn static_output_omits_dynamic_ui() {
+    let tmp = TempDir::new().unwrap();
+    let out = tmp.path().join("_site");
+    let seed = seed_dir();
+
+    Command::cargo_bin("cook")
+        .unwrap()
+        .args([
+            "build",
+            out.to_str().unwrap(),
+            "--base-path",
+            seed.to_str().unwrap(),
+        ])
+        .assert()
+        .success();
+
+    let index = std::fs::read_to_string(out.join("index.html")).unwrap();
+
+    // Nav links to dynamic-only pages should be gone.
+    assert!(!index.contains("/shopping-list\""), "shopping-list nav present");
+    assert!(!index.contains("/pantry\""), "pantry nav present");
+    assert!(!index.contains("/preferences\""), "preferences nav present");
+
+    // The dynamic search fetch should be gone; the static search.js link should be present.
+    assert!(!index.contains("/api/search"), "api search reference remains");
+    assert!(index.contains("/static/js/search.js"), "static search.js missing");
+}
+```
+
+- [ ] **Step 2: Run test**
+
+Run: `cargo test --test build static_output_omits_dynamic_ui`
+Expected: PASS. If any assertion fails, return to Task 4/5/6 and find the un-gated element.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add -A
+git commit -m "test(build): verify static output omits dynamic UI"
+```
+
+---
+
+## Task 17: Manual verification
+
+Not a code task, but documents the manual smoke test for verification-before-completion.
+
+- [ ] **Step 1: Run a clean build against `./seed`**
+
+```bash
+cargo run -- build --base-path ./seed /tmp/cook-static
+```
+
+Expected output (counts will vary):
+```
+Building static site from /…/seed into /tmp/cook-static
+Wrote N recipes, N images, N static assets
+```
+
+- [ ] **Step 2: Browse via local web server**
+
+```bash
+python3 -m http.server -d /tmp/cook-static 8765
+```
+
+Open `http://localhost:8765/` in a browser. Confirm:
+- Recipe listing renders
+- Clicking a recipe loads its page
+- Search box filters as you type
+- No "Shopping List", "Pantry", or "Edit" controls visible
+- Images render (if seed contains any)
+
+- [ ] **Step 3: Browse via `file://`**
+
+```bash
+open /tmp/cook-static/index.html
+```
+
+Confirm: links navigate correctly within the static site, no broken relative paths.
+
+- [ ] **Step 4: Verify formatting and lint**
+
+```bash
+cargo fmt
+cargo clippy -- -D warnings
+cargo test
+```
+
+All three must pass with no warnings.
+
+- [ ] **Step 5: Final commit if any formatting changes were applied**
+
+```bash
+git add -A
+git commit -m "chore: fmt"  # only if needed
+```
+
+---
+
+## Self-Review
+
+This plan was reviewed against the spec at `docs/superpowers/specs/2026-05-15-static-site-build-design.md`. Spec coverage:
+
+- CLI `cook build [OUTPUT_DIR] [--base-path] [--base-url]` — Task 1, 2, 11.
+- Output layout (`index.html`, `directory/<path>.html`, `recipe/<path>.html`, `menu/<path>.html`, `static/`, `api/static/`) — Tasks 11, 12, 13, 10.
+- Module `src/build/` (renderer, writer, links, index) — Tasks 8, 9, 10, 11, 12, 14.
+- Reuse Askama templates via `static_mode` flag — Tasks 3, 4, 5, 6.
+- Refactor shared builders out of `ui.rs` — Task 7.
+- Search index + `search.js` — Tasks 14, 15.
+- Recipe images copied — Task 13.
+- Relative URL prefix per page; `--base-url` override — Tasks 8, 11.
+- Lenient parsing (warn + skip on bad recipes) — Task 12 (`walk_recipes` warns and continues).
+- Smoke tests + manual verification — Tasks 11, 12, 13, 14, 15, 16, 17.
+
+No placeholders, TBDs, or "implement later" steps remain. Method signatures (`render_index`, `render_directory`, `render_recipe`, `build_recipes_template`, `build_recipe_template`, `relative_prefix`, `write_html`, `copy_static_assets`, `copy_image`) are referenced consistently across tasks.
diff --git a/docs/superpowers/plans/2026-05-16-device-code-auth.md b/docs/superpowers/plans/2026-05-16-device-code-auth.md
new file mode 100644
index 0000000..f217932
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-16-device-code-auth.md
@@ -0,0 +1,2186 @@
+# Device-Code Authentication Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace CookCLI's browser-popup login (broken in Docker per [#290](https://github.com/cooklang/cookcli/issues/290)) with the OAuth 2.0 Device Authorization Grant (RFC 8628), shared by the web UI and a new `cook login` / `cook logout` CLI.
+
+**Architecture:** Two phases across two repos. Phase 1 adds new endpoints to `cook.md` (Rails): `POST /oauth/device/code`, `POST /oauth/device/token`, and a `/device` web page (GET form, POST confirm, POST approve, POST deny). State lives in Redis with 15-minute TTL. Phase 2 adds a shared Rust `device_flow` module to CookCLI, replaces the broken browser-popup flow in the web handler, and adds `cook login` / `cook logout` CLI commands. JWT issuance, session storage, and sync remain unchanged downstream.
+
+**Tech Stack:**
+- cook.md: Rails 8, RSpec, RuboCop, `redis` gem (`$redis` global), `rack-attack`, `jwt` gem (via `Token` module).
+- CookCLI: Rust, Axum, Askama templates, `reqwest`, `tokio`, `tokio_util::sync::CancellationToken`, `serde_json`, `anyhow`. Existing `sync` cargo feature continues to gate everything.
+
+**Spec:** `docs/superpowers/specs/2026-05-16-device-code-auth-design.md`
+
+---
+
+## File Structure
+
+### Phase 1 — cook.md (`/Users/alexeydubovskoy/Cooklang/cook.md/web`)
+
+**New files:**
+- `lib/device_flow.rb` — Redis I/O, code generation, state transitions. One module with class-level helpers.
+- `app/controllers/oauth/device_controller.rb` — `POST /oauth/device/code`, `POST /oauth/device/token`. Inherits `ActionController::API` (no CSRF, no Warden).
+- `app/controllers/device_controller.rb` — `GET /device`, `POST /device`, `POST /device/approve`, `POST /device/deny`. Inherits `ApplicationController` (Warden web strategy, CSRF on).
+- `app/views/device/show.html.erb` — user_code entry form.
+- `app/views/device/confirm.html.erb` — approve/deny page.
+- `app/views/device/approved.html.erb` — success page.
+- `app/views/device/denied.html.erb` — denial confirmation.
+- `app/views/device/expired.html.erb` — code expired / invalid.
+- `spec/lib/device_flow_spec.rb` — unit specs for `DeviceFlow`.
+- `spec/requests/oauth/device_spec.rb` — request specs for `/oauth/device/*`.
+- `spec/requests/device_spec.rb` — request specs for the web page.
+
+**Modified:**
+- `config/routes.rb` — add 6 new routes.
+- `config/initializers/rack_attack.rb` — add 3 throttles.
+
+### Phase 2 — CookCLI (`/Users/alexeydubovskoy/Cooklang/CookCLI`)
+
+**New files:**
+- `src/server/sync/device_flow.rs` — `request_device_code()`, `poll_for_token()`, types, errors.
+- `src/login.rs` — `cook login` command.
+- `src/logout.rs` — `cook logout` command.
+
+**Modified:**
+- `src/server/sync/mod.rs` — re-export `device_flow`.
+- `src/server/mod.rs` — replace `login_in_progress: AtomicBool` with `pending_device_flow: Mutex<Option<DeviceFlowState>>` in `AppState`; add `/api/sync/cancel_login` route.
+- `src/server/handlers/sync.rs` — delete browser-popup helpers; rewrite `sync_login`; extend `LoginResponse`; extend `SyncStatusResponse`; add `sync_cancel_login`.
+- `templates/preferences.html` — replace login button JS with the device-code card; status polling reads `pending_login`.
+- `src/args.rs` — add `Login(LoginArgs)` and `Logout(LogoutArgs)` variants.
+- `src/main.rs` — add match arms.
+- `Cargo.toml` — no changes (`open`, `uuid`, `tokio-util`, `reqwest` all already present).
+
+---
+
+# Phase 1 — cook.md (Rails)
+
+Work directory: `/Users/alexeydubovskoy/Cooklang/cook.md/web`. All RSpec / RuboCop commands must be run from there.
+
+### Task 1: Rack::Attack throttles
+
+**Files:**
+- Modify: `config/initializers/rack_attack.rb`
+
+- [ ] **Step 1: Read the existing throttles**
+
+Run: `cat config/initializers/rack_attack.rb`
+
+Note the existing pattern (e.g. `auth/code_request/ip` block). New throttles will mirror it.
+
+- [ ] **Step 2: Add three new throttles**
+
+Append to `config/initializers/rack_attack.rb` (inside the `Rack::Attack` configuration block, near the other `throttle` calls):
+
+```ruby
+# Device-code issuance: cap creation rate per IP.
+throttle("oauth/device/code/ip", limit: 10, period: 1.minute) do |req|
+  if req.path == "/oauth/device/code" && req.post?
+    Rack::Attack.real_ip(req)
+  end
+end
+
+# Device-code token polling: hard cap per IP. Per-device_code slow_down is
+# enforced inside the controller against last_polled_at.
+throttle("oauth/device/token/ip", limit: 60, period: 1.minute) do |req|
+  if req.path == "/oauth/device/token" && req.post?
+    Rack::Attack.real_ip(req)
+  end
+end
+
+# /device form submissions: prevent user_code brute-force per session/IP.
+throttle("device/submit/ip", limit: 10, period: 15.minutes) do |req|
+  if req.path == "/device" && req.post?
+    Rack::Attack.real_ip(req)
+  end
+end
+```
+
+- [ ] **Step 3: Verify Rails boots**
+
+Run: `bundle exec rails runner "puts 'ok'"`
+Expected: `ok` on stdout, no exceptions.
+
+- [ ] **Step 4: Run rubocop on the file**
+
+Run: `bundle exec rubocop config/initializers/rack_attack.rb`
+Expected: no offenses. Fix any styling complaints inline.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add config/initializers/rack_attack.rb
+git commit -m "feat(device-flow): add rate limits for device-code endpoints"
+```
+
+---
+
+### Task 2: `DeviceFlow` lib module — TDD
+
+The `DeviceFlow` module owns code generation, Redis I/O, and state transitions. Independently testable from any controller.
+
+**Files:**
+- Create: `lib/device_flow.rb`
+- Create: `spec/lib/device_flow_spec.rb`
+
+- [ ] **Step 1: Write the failing spec**
+
+Create `spec/lib/device_flow_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe DeviceFlow do
+  before { $redis.flushdb }
+
+  describe ".create!" do
+    it "returns a fresh device_code + user_code" do
+      result = described_class.create!(client_name: "CookCLI test")
+      expect(result.device_code).to be_a(String).and have_attributes(length: be > 20)
+      expect(result.user_code).to match(/\A[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{4}-[23456789ABCDEFGHJKLMNPQRSTUVWXYZ]{4}\z/)
+      expect(result.expires_in).to eq(DeviceFlow::EXPIRES_IN)
+      expect(result.interval).to eq(DeviceFlow::DEFAULT_INTERVAL)
+    end
+
+    it "persists state as pending with the supplied client_name" do
+      result = described_class.create!(client_name: "CookCLI 0.30 (linux/docker)")
+      record = described_class.find_by_device_code(result.device_code)
+      expect(record).to include("status" => "pending", "client_name" => "CookCLI 0.30 (linux/docker)")
+    end
+
+    it "truncates client_name to 80 chars" do
+      result = described_class.create!(client_name: "X" * 200)
+      record = described_class.find_by_device_code(result.device_code)
+      expect(record["client_name"].length).to eq(80)
+    end
+
+    it "sets a 15-minute TTL on both keys" do
+      result = described_class.create!(client_name: "x")
+      device_hash = Digest::SHA256.hexdigest(result.device_code)
+      user_code = result.user_code.delete("-")
+      expect($redis.ttl("device_code:#{device_hash}")).to be_between(890, 901)
+      expect($redis.ttl("user_code:#{user_code}")).to be_between(890, 901)
+    end
+  end
+
+  describe ".find_by_user_code" do
+    it "is hyphen- and case-tolerant" do
+      result = described_class.create!(client_name: "x")
+      expect(described_class.find_by_user_code(result.user_code)["status"]).to eq("pending")
+      expect(described_class.find_by_user_code(result.user_code.delete("-"))["status"]).to eq("pending")
+      expect(described_class.find_by_user_code(result.user_code.downcase)["status"]).to eq("pending")
+    end
+
+    it "returns nil for an unknown code" do
+      expect(described_class.find_by_user_code("AAAA-BBBB")).to be_nil
+    end
+  end
+
+  describe ".approve!" do
+    it "transitions pending → approved, records user_id, deletes user_code index" do
+      result = described_class.create!(client_name: "x")
+      described_class.approve!(user_code: result.user_code, user_id: 42)
+      record = described_class.find_by_device_code(result.device_code)
+      expect(record).to include("status" => "approved", "user_id" => 42)
+      expect($redis.get("user_code:#{result.user_code.delete('-')}")).to be_nil
+    end
+
+    it "returns false for an unknown user_code" do
+      expect(described_class.approve!(user_code: "AAAA-BBBB", user_id: 1)).to be(false)
+    end
+  end
+
+  describe ".deny!" do
+    it "transitions pending → denied" do
+      result = described_class.create!(client_name: "x")
+      described_class.deny!(user_code: result.user_code)
+      record = described_class.find_by_device_code(result.device_code)
+      expect(record["status"]).to eq("denied")
+    end
+  end
+
+  describe ".poll" do
+    let(:created) { described_class.create!(client_name: "x") }
+
+    it "returns [:pending, nil] before approval" do
+      status, payload = described_class.poll(device_code: created.device_code)
+      expect(status).to eq(:pending)
+      expect(payload).to be_nil
+    end
+
+    it "returns [:slow_down, nil] when polled within interval" do
+      described_class.poll(device_code: created.device_code)
+      status, _ = described_class.poll(device_code: created.device_code)
+      expect(status).to eq(:slow_down)
+    end
+
+    it "returns [:approved, {user_id}] after approval and then consumes the code" do
+      described_class.approve!(user_code: created.user_code, user_id: 7)
+      status, payload = described_class.poll(device_code: created.device_code)
+      expect(status).to eq(:approved)
+      expect(payload).to eq(user_id: 7)
+      # Subsequent poll: code is consumed
+      status2, _ = described_class.poll(device_code: created.device_code)
+      expect(status2).to eq(:expired)
+    end
+
+    it "returns [:denied, nil] after deny" do
+      described_class.deny!(user_code: created.user_code)
+      status, _ = described_class.poll(device_code: created.device_code)
+      expect(status).to eq(:denied)
+    end
+
+    it "returns [:expired, nil] for an unknown device_code" do
+      status, _ = described_class.poll(device_code: "bogus")
+      expect(status).to eq(:expired)
+    end
+  end
+end
+```
+
+- [ ] **Step 2: Run spec to verify it fails**
+
+Run: `bundle exec rspec spec/lib/device_flow_spec.rb`
+Expected: All examples error with `uninitialized constant DeviceFlow` (file not yet created).
+
+- [ ] **Step 3: Implement the module**
+
+Create `lib/device_flow.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "digest"
+require "securerandom"
+
+module DeviceFlow
+  EXPIRES_IN = 900  # 15 minutes (seconds)
+  DEFAULT_INTERVAL = 5
+  SLOW_DOWN_BUMP = 5
+  USER_CODE_ALPHABET = "23456789ABCDEFGHJKLMNPQRSTUVWXYZ".freeze
+  USER_CODE_LEN = 8
+  CLIENT_NAME_MAX = 80
+
+  Created = Struct.new(:device_code, :user_code, :expires_in, :interval, keyword_init: true)
+
+  def self.create!(client_name:)
+    device_code = SecureRandom.urlsafe_base64(32)
+    user_code = generate_user_code
+    hash = Digest::SHA256.hexdigest(device_code)
+    safe_name = (client_name || "Unknown client").to_s[0, CLIENT_NAME_MAX]
+
+    record = {
+      "user_code" => user_code,
+      "client_name" => safe_name,
+      "status" => "pending",
+      "user_id" => nil,
+      "last_polled_at" => nil
+    }
+
+    $redis.set("device_code:#{hash}", record.to_json, ex: EXPIRES_IN)
+    $redis.set("user_code:#{user_code}", hash, ex: EXPIRES_IN)
+
+    Created.new(
+      device_code: device_code,
+      user_code: format_user_code(user_code),
+      expires_in: EXPIRES_IN,
+      interval: DEFAULT_INTERVAL
+    )
+  end
+
+  def self.find_by_device_code(device_code)
+    hash = Digest::SHA256.hexdigest(device_code)
+    raw = $redis.get("device_code:#{hash}")
+    raw && JSON.parse(raw)
+  end
+
+  def self.find_by_user_code(user_code)
+    normalized = normalize_user_code(user_code)
+    hash = $redis.get("user_code:#{normalized}")
+    return nil unless hash
+
+    raw = $redis.get("device_code:#{hash}")
+    raw && JSON.parse(raw)
+  end
+
+  def self.approve!(user_code:, user_id:)
+    update_state(user_code: user_code, status: "approved", user_id: user_id)
+  end
+
+  def self.deny!(user_code:)
+    update_state(user_code: user_code, status: "denied", user_id: nil)
+  end
+
+  # Returns [status_symbol, payload_or_nil].
+  # status_symbol ∈ [:pending, :slow_down, :approved, :denied, :expired]
+  # On :approved, payload is { user_id: Integer }. The Redis entry is deleted
+  # on the same call (single-use).
+  def self.poll(device_code:)
+    hash = Digest::SHA256.hexdigest(device_code)
+    raw = $redis.get("device_code:#{hash}")
+    return [:expired, nil] unless raw
+
+    record = JSON.parse(raw)
+    now = Time.now.to_i
+
+    case record["status"]
+    when "approved"
+      payload = { user_id: record["user_id"] }
+      $redis.del("device_code:#{hash}")
+      [:approved, payload]
+    when "denied"
+      [:denied, nil]
+    else
+      # pending
+      last = record["last_polled_at"]
+      if last && (now - last) < DEFAULT_INTERVAL
+        [:slow_down, nil]
+      else
+        record["last_polled_at"] = now
+        ttl = $redis.ttl("device_code:#{hash}")
+        $redis.set("device_code:#{hash}", record.to_json, ex: ttl.positive? ? ttl : EXPIRES_IN)
+        [:pending, nil]
+      end
+    end
+  end
+
+  def self.normalize_user_code(code)
+    code.to_s.upcase.delete("-")
+  end
+
+  class << self
+    private
+
+    def generate_user_code
+      Array.new(USER_CODE_LEN) { USER_CODE_ALPHABET[SecureRandom.random_number(USER_CODE_ALPHABET.length)] }.join
+    end
+
+    def format_user_code(raw)
+      "#{raw[0, 4]}-#{raw[4, 4]}"
+    end
+
+    def update_state(user_code:, status:, user_id:)
+      normalized = normalize_user_code(user_code)
+      hash = $redis.get("user_code:#{normalized}")
+      return false unless hash
+
+      raw = $redis.get("device_code:#{hash}")
+      return false unless raw
+
+      record = JSON.parse(raw)
+      record["status"] = status
+      record["user_id"] = user_id if user_id
+
+      ttl = $redis.ttl("device_code:#{hash}")
+      $redis.set("device_code:#{hash}", record.to_json, ex: ttl.positive? ? ttl : EXPIRES_IN)
+      $redis.del("user_code:#{normalized}")
+      true
+    end
+  end
+end
+```
+
+- [ ] **Step 4: Run spec to verify it passes**
+
+Run: `bundle exec rspec spec/lib/device_flow_spec.rb`
+Expected: all examples pass.
+
+- [ ] **Step 5: RuboCop**
+
+Run: `bundle exec rubocop lib/device_flow.rb spec/lib/device_flow_spec.rb`
+Expected: no offenses. Fix inline if any.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/device_flow.rb spec/lib/device_flow_spec.rb
+git commit -m "feat(device-flow): add DeviceFlow lib module with Redis state"
+```
+
+---
+
+### Task 3: `POST /oauth/device/code` endpoint — TDD
+
+**Files:**
+- Create: `app/controllers/oauth/device_controller.rb`
+- Create: `spec/requests/oauth/device_spec.rb`
+- Modify: `config/routes.rb`
+
+- [ ] **Step 1: Write the failing request spec for `/oauth/device/code`**
+
+Create `spec/requests/oauth/device_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe "Oauth::Device", type: :request do
+  before { $redis.flushdb }
+
+  describe "POST /oauth/device/code" do
+    it "returns 200 with a complete RFC 8628 response body" do
+      post "/oauth/device/code", params: { client_name: "CookCLI 0.30 (linux)" }, as: :json
+      expect(response).to have_http_status(:ok)
+      body = response.parsed_body
+      expect(body["device_code"]).to be_a(String)
+      expect(body["user_code"]).to match(/\A[A-Z0-9]{4}-[A-Z0-9]{4}\z/)
+      expect(body["verification_uri"]).to end_with("/device")
+      expect(body["verification_uri_complete"]).to include("user_code=#{body['user_code']}")
+      expect(body["expires_in"]).to eq(900)
+      expect(body["interval"]).to eq(5)
+    end
+
+    it "accepts a missing client_name and uses a default" do
+      post "/oauth/device/code", as: :json
+      expect(response).to have_http_status(:ok)
+    end
+  end
+end
+```
+
+- [ ] **Step 2: Run spec to verify it fails**
+
+Run: `bundle exec rspec spec/requests/oauth/device_spec.rb`
+Expected: routing error / 404 — route does not exist yet.
+
+- [ ] **Step 3: Add the route**
+
+Modify `config/routes.rb`. Find the `namespace :auth do ... end` block (around line 114). Immediately *after* that block (before `resource :profile`), add:
+
+```ruby
+namespace :oauth do
+  post "device/code", to: "device#code"
+  post "device/token", to: "device#token"
+end
+```
+
+- [ ] **Step 4: Implement the controller**
+
+Create `app/controllers/oauth/device_controller.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module Oauth
+  class DeviceController < ActionController::API
+    def code
+      result = DeviceFlow.create!(client_name: params[:client_name])
+      verification_uri = url_for(controller: "/device", action: "show", only_path: false)
+      verification_uri_complete = url_for(
+        controller: "/device", action: "show", only_path: false,
+        user_code: result.user_code
+      )
+
+      render json: {
+        device_code: result.device_code,
+        user_code: result.user_code,
+        verification_uri: verification_uri,
+        verification_uri_complete: verification_uri_complete,
+        expires_in: result.expires_in,
+        interval: result.interval
+      }
+    end
+
+    def token
+      # Placeholder — implemented in Task 4.
+      head :not_implemented
+    end
+  end
+end
+```
+
+> Note: `url_for(controller: "/device", action: "show", ...)` resolves to the top-level `device#show` route added in Task 5. Until that route exists Rails will raise. The next step adds a stub route so this controller compiles end-to-end immediately; Task 5 replaces the stub with the real view-rendering action.
+
+- [ ] **Step 5: Add a placeholder `/device` route so URL generation works**
+
+Modify `config/routes.rb`. Anywhere outside the `namespace :auth` and `namespace :oauth` blocks, add:
+
+```ruby
+get "/device", to: "device#show", as: :device
+```
+
+You also need a stub controller so route loading doesn't error during Task 3 specs. Create `app/controllers/device_controller.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+class DeviceController < ApplicationController
+  def show
+    render plain: "stub", status: :ok
+  end
+end
+```
+
+(Task 5 replaces both action and view with the real ones.)
+
+- [ ] **Step 6: Run spec to verify it passes**
+
+Run: `bundle exec rspec spec/requests/oauth/device_spec.rb`
+Expected: both examples pass.
+
+- [ ] **Step 7: RuboCop**
+
+Run: `bundle exec rubocop app/controllers/oauth/device_controller.rb app/controllers/device_controller.rb spec/requests/oauth/device_spec.rb config/routes.rb`
+Expected: no offenses.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app/controllers/oauth/device_controller.rb app/controllers/device_controller.rb \
+        spec/requests/oauth/device_spec.rb config/routes.rb
+git commit -m "feat(device-flow): add POST /oauth/device/code endpoint"
+```
+
+---
+
+### Task 4: `POST /oauth/device/token` endpoint — TDD
+
+Implements the full RFC 8628 token-polling state machine.
+
+**Files:**
+- Modify: `app/controllers/oauth/device_controller.rb`
+- Modify: `spec/requests/oauth/device_spec.rb`
+
+- [ ] **Step 1: Extend the spec**
+
+Append inside `RSpec.describe "Oauth::Device", type: :request do` in `spec/requests/oauth/device_spec.rb`:
+
+```ruby
+  describe "POST /oauth/device/token" do
+    let(:created) { DeviceFlow.create!(client_name: "x") }
+    let(:grant) { "urn:ietf:params:oauth:grant-type:device_code" }
+    let(:user) { User.create!(email: "alice@example.com") }
+
+    def poll(device_code:, grant_type: grant)
+      post "/oauth/device/token", params: { device_code: device_code, grant_type: grant_type }, as: :json
+    end
+
+    it "returns 400 authorization_pending while still pending" do
+      poll(device_code: created.device_code)
+      expect(response).to have_http_status(:bad_request)
+      expect(response.parsed_body["error"]).to eq("authorization_pending")
+    end
+
+    it "returns 400 slow_down on rapid re-poll" do
+      poll(device_code: created.device_code)
+      poll(device_code: created.device_code)
+      expect(response).to have_http_status(:bad_request)
+      expect(response.parsed_body["error"]).to eq("slow_down")
+    end
+
+    it "returns 200 with a JWT on approval, then 400 expired_token on replay" do
+      DeviceFlow.approve!(user_code: created.user_code, user_id: user.id)
+      poll(device_code: created.device_code)
+      expect(response).to have_http_status(:ok)
+      body = response.parsed_body
+      expect(body["token"]).to be_a(String)
+      expect(body["token_type"]).to eq("Bearer")
+      decoded = Token.decode(body["token"])
+      expect(decoded["uid"]).to eq(user.id)
+      expect(decoded["email"]).to eq(user.email)
+
+      # Replay
+      poll(device_code: created.device_code)
+      expect(response).to have_http_status(:bad_request)
+      expect(response.parsed_body["error"]).to eq("expired_token")
+    end
+
+    it "returns 400 access_denied after deny" do
+      DeviceFlow.deny!(user_code: created.user_code)
+      poll(device_code: created.device_code)
+      expect(response).to have_http_status(:bad_request)
+      expect(response.parsed_body["error"]).to eq("access_denied")
+    end
+
+    it "returns 400 expired_token for an unknown device_code" do
+      poll(device_code: "bogus")
+      expect(response).to have_http_status(:bad_request)
+      expect(response.parsed_body["error"]).to eq("expired_token")
+    end
+
+    it "returns 400 invalid_grant on wrong grant_type" do
+      poll(device_code: created.device_code, grant_type: "wrong")
+      expect(response).to have_http_status(:bad_request)
+      expect(response.parsed_body["error"]).to eq("invalid_grant")
+    end
+  end
+```
+
+- [ ] **Step 2: Run spec to verify it fails**
+
+Run: `bundle exec rspec spec/requests/oauth/device_spec.rb`
+Expected: the `token` examples fail (the action returns 501).
+
+- [ ] **Step 3: Implement `token` action**
+
+Replace the `token` method in `app/controllers/oauth/device_controller.rb` with:
+
+```ruby
+    DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+
+    def token
+      if params[:grant_type] != DEVICE_CODE_GRANT
+        return render(json: { error: "invalid_grant" }, status: :bad_request)
+      end
+
+      status, payload = DeviceFlow.poll(device_code: params[:device_code].to_s)
+
+      case status
+      when :pending
+        render json: { error: "authorization_pending" }, status: :bad_request
+      when :slow_down
+        render json: { error: "slow_down" }, status: :bad_request
+      when :denied
+        render json: { error: "access_denied" }, status: :bad_request
+      when :expired
+        render json: { error: "expired_token" }, status: :bad_request
+      when :approved
+        user = User.find_by(id: payload[:user_id])
+        if user.nil?
+          render json: { error: "access_denied" }, status: :bad_request
+        else
+          jwt = Token.encode(uid: user.id, email: user.email)
+          render json: { token: jwt, token_type: "Bearer" }
+        end
+      end
+    end
+```
+
+- [ ] **Step 4: Run spec to verify it passes**
+
+Run: `bundle exec rspec spec/requests/oauth/device_spec.rb`
+Expected: all examples pass.
+
+- [ ] **Step 5: RuboCop**
+
+Run: `bundle exec rubocop app/controllers/oauth/device_controller.rb spec/requests/oauth/device_spec.rb`
+Expected: no offenses.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/controllers/oauth/device_controller.rb spec/requests/oauth/device_spec.rb
+git commit -m "feat(device-flow): implement POST /oauth/device/token state machine"
+```
+
+---
+
+### Task 5: `GET /device` form & `POST /device` confirm — TDD
+
+**Files:**
+- Modify: `config/routes.rb`
+- Modify: `app/controllers/device_controller.rb`
+- Create: `app/views/device/show.html.erb`
+- Create: `app/views/device/confirm.html.erb`
+- Create: `spec/requests/device_spec.rb`
+
+- [ ] **Step 1: Write the failing request spec**
+
+Create `spec/requests/device_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe "Device", type: :request do
+  before { $redis.flushdb }
+
+  let(:user) { User.create!(email: "alice@example.com") }
+
+  def sign_in_as(u)
+    # Mirror the test helper used elsewhere for Warden web strategy login.
+    # If a helper like `login_as` exists in spec/support, use that instead.
+    post "/auth/desktop/code", params: { email: u.email }
+    # In tests, SessionCode for test@cook.md returns 424242; for other emails
+    # the code is generated. Inject directly via SessionCode if necessary.
+    code = $redis.get("code:#{u.email}")
+    post "/auth/desktop/code/verify_code", params: { email: u.email, code: code }
+  end
+
+  describe "GET /device" do
+    context "when signed out" do
+      it "redirects to sign-in, preserving user_code via session" do
+        get "/device", params: { user_code: "ABCD-EFGH" }
+        expect(response).to redirect_to(sign_in_path)
+      end
+    end
+
+    context "when signed in" do
+      before { sign_in_as(user) }
+
+      it "renders the form" do
+        get "/device"
+        expect(response).to have_http_status(:ok)
+        expect(response.body).to include("Enter the code shown by CookCLI")
+      end
+
+      it "pre-fills the input from ?user_code=" do
+        get "/device", params: { user_code: "WDJB-MJHT" }
+        expect(response.body).to include('value="WDJB-MJHT"')
+      end
+    end
+  end
+
+  describe "POST /device" do
+    before { sign_in_as(user) }
+
+    it "renders the confirm page for a known user_code" do
+      created = DeviceFlow.create!(client_name: "CookCLI test")
+      post "/device", params: { user_code: created.user_code }
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to include("CookCLI test")
+      expect(response.body).to include(user.email)
+      expect(response.body).to include("Approve")
+      expect(response.body).to include("Deny")
+    end
+
+    it "renders the expired view for an unknown user_code" do
+      post "/device", params: { user_code: "ZZZZ-ZZZZ" }
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to include("expired or invalid")
+    end
+  end
+end
+```
+
+> Note: the `sign_in_as` helper above depends on the email-code flow already wired in the app. If `spec/support` provides a faster login helper (e.g. via Warden test mode), prefer it. Look in `spec/rails_helper.rb` and `spec/support/`. Adjust as needed but keep the assertions identical.
+
+- [ ] **Step 2: Run spec to verify it fails**
+
+Run: `bundle exec rspec spec/requests/device_spec.rb`
+Expected: examples fail (controller still returns the "stub" string; views don't exist).
+
+- [ ] **Step 3: Replace the stub route + add the new ones**
+
+In `config/routes.rb`, replace the line added in Task 3:
+
+```ruby
+get "/device", to: "device#show", as: :device
+```
+
+with:
+
+```ruby
+get  "/device", to: "device#show", as: :device
+post "/device", to: "device#confirm"
+post "/device/approve", to: "device#approve", as: :device_approve
+post "/device/deny",    to: "device#deny",    as: :device_deny
+```
+
+- [ ] **Step 4: Implement the controller actions**
+
+Replace `app/controllers/device_controller.rb` with:
+
+```ruby
+# frozen_string_literal: true
+
+class DeviceController < ApplicationController
+  before_action :authenticate!
+
+  # GET /device
+  def show
+    @user_code = params[:user_code].to_s.upcase
+  end
+
+  # POST /device — looks up the user_code and renders approve/deny page.
+  def confirm
+    @user_code = params[:user_code].to_s
+    @record = DeviceFlow.find_by_user_code(@user_code)
+    if @record.nil? || @record["status"] != "pending"
+      render :expired
+    else
+      @client_name = @record["client_name"]
+      @email = current_user.email
+      render :confirm
+    end
+  end
+
+  # POST /device/approve
+  def approve
+    if DeviceFlow.approve!(user_code: params[:user_code].to_s, user_id: current_user.id)
+      render :approved
+    else
+      render :expired
+    end
+  end
+
+  # POST /device/deny
+  def deny
+    if DeviceFlow.deny!(user_code: params[:user_code].to_s)
+      render :denied
+    else
+      render :expired
+    end
+  end
+end
+```
+
+> The `authenticate!` before-action (defined in `ApplicationController`) redirects to `sign_in_path` for signed-out users. Devise/Warden flash-based return-URL preservation is already handled by the existing sign-in flow.
+
+> If the existing sign-in flow does **not** auto-return to `/device` after login, the spec's first `it` block ("redirects to sign-in") will pass but the subsequent user journey requires the user to navigate back manually with `?user_code=`. That's an acceptable v1 trade-off and matches RFC 8628; document it in the implementation plan completion notes.
+
+- [ ] **Step 5: Implement the views**
+
+Create `app/views/device/show.html.erb`:
+
+```erb
+<% content_for :title, "Enter Device Code" %>
+<div class="flex flex-col h-screen">
+  <div class="flex-1 bg-neutral-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
+    <div class="sm:mx-auto sm:w-full sm:max-w-md">
+      <h2 class="mt-6 text-center text-3xl font-semibold text-cook-text">
+        Enter the code shown by CookCLI
+      </h2>
+      <p class="mt-2 text-center text-sm text-cook-text/60">
+        Signed in as <%= current_user.email %>.
+      </p>
+    </div>
+
+    <div class="mt-8 sm:mx-auto sm:w-full sm:max-w-md">
+      <div class="bg-white py-8 px-4 shadow-sm border border-cook-text/10 sm:rounded-lg sm:px-10">
+        <%= form_with url: device_path, method: :post, data: { turbo: false }, local: true do |f| %>
+          <%= f.label :user_code, "One-time code", class: "block text-sm font-medium text-cook-text" %>
+          <%= f.text_field :user_code,
+                value: @user_code,
+                autofocus: true,
+                required: true,
+                pattern: "[A-Za-z0-9-]{8,9}",
+                class: "mt-1 block w-full px-3 py-2 border border-cook-text/20 rounded-md uppercase tracking-widest text-center text-xl" %>
+          <%= f.submit "Continue", class: "mt-4 w-full inline-flex justify-center py-2 px-4 border rounded-md bg-cook-text text-white" %>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+Create `app/views/device/confirm.html.erb`:
+
+```erb
+<% content_for :title, "Approve CookCLI" %>
+<div class="flex flex-col h-screen">
+  <div class="flex-1 bg-neutral-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
+    <div class="sm:mx-auto sm:w-full sm:max-w-md">
+      <h2 class="mt-6 text-center text-3xl font-semibold text-cook-text">
+        Authorize this device?
+      </h2>
+      <p class="mt-2 text-center text-sm text-cook-text/70">
+        <strong><%= @client_name %></strong> wants to access your
+        CookCloud account as <strong><%= @email %></strong>.
+      </p>
+    </div>
+
+    <div class="mt-8 sm:mx-auto sm:w-full sm:max-w-md">
+      <div class="bg-white py-8 px-4 shadow-sm border border-cook-text/10 sm:rounded-lg sm:px-10 flex gap-3">
+        <%= form_with url: device_approve_path, method: :post, data: { turbo: false }, local: true, class: "flex-1" do |f| %>
+          <%= f.hidden_field :user_code, value: @user_code %>
+          <%= f.submit "Approve", class: "w-full py-2 px-4 rounded-md bg-cook-text text-white" %>
+        <% end %>
+        <%= form_with url: device_deny_path, method: :post, data: { turbo: false }, local: true, class: "flex-1" do |f| %>
+          <%= f.hidden_field :user_code, value: @user_code %>
+          <%= f.submit "Deny", class: "w-full py-2 px-4 rounded-md border border-red-300 text-red-600" %>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+- [ ] **Step 6: Run spec to verify it passes**
+
+Run: `bundle exec rspec spec/requests/device_spec.rb`
+Expected: all `GET /device` and `POST /device` examples pass.
+
+- [ ] **Step 7: RuboCop**
+
+Run: `bundle exec rubocop app/controllers/device_controller.rb spec/requests/device_spec.rb`
+Expected: no offenses.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add config/routes.rb app/controllers/device_controller.rb \
+        app/views/device/show.html.erb app/views/device/confirm.html.erb \
+        spec/requests/device_spec.rb
+git commit -m "feat(device-flow): add /device form and confirmation page"
+```
+
+---
+
+### Task 6: `POST /device/approve` & `/device/deny` end-to-end — TDD
+
+Adds remaining specs covering the action endpoints and creates the result views. The controller actions were already added in Task 5.
+
+**Files:**
+- Modify: `spec/requests/device_spec.rb`
+- Create: `app/views/device/approved.html.erb`
+- Create: `app/views/device/denied.html.erb`
+- Create: `app/views/device/expired.html.erb`
+
+- [ ] **Step 1: Append specs**
+
+Append inside `RSpec.describe "Device", type: :request do` in `spec/requests/device_spec.rb`:
+
+```ruby
+  describe "POST /device/approve" do
+    before { sign_in_as(user) }
+
+    it "marks the device approved and renders the approved view" do
+      created = DeviceFlow.create!(client_name: "x")
+      post "/device/approve", params: { user_code: created.user_code }
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to include("All done")
+      expect(DeviceFlow.find_by_device_code(created.device_code)["status"]).to eq("approved")
+    end
+
+    it "renders expired for an unknown user_code" do
+      post "/device/approve", params: { user_code: "ZZZZ-ZZZZ" }
+      expect(response.body).to include("expired or invalid")
+    end
+  end
+
+  describe "POST /device/deny" do
+    before { sign_in_as(user) }
+
+    it "marks the device denied and renders the denied view" do
+      created = DeviceFlow.create!(client_name: "x")
+      post "/device/deny", params: { user_code: created.user_code }
+      expect(response).to have_http_status(:ok)
+      expect(response.body).to include("Authorization denied")
+      expect(DeviceFlow.find_by_device_code(created.device_code)["status"]).to eq("denied")
+    end
+  end
+```
+
+- [ ] **Step 2: Run spec to verify it fails**
+
+Run: `bundle exec rspec spec/requests/device_spec.rb`
+Expected: examples fail with `ActionView::MissingTemplate` for `approved`, `denied`, `expired`.
+
+- [ ] **Step 3: Create the three result views**
+
+Create `app/views/device/approved.html.erb`:
+
+```erb
+<% content_for :title, "Authorized" %>
+<div class="flex flex-col h-screen">
+  <div class="flex-1 bg-neutral-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
+    <div class="sm:mx-auto sm:w-full sm:max-w-md text-center">
+      <h2 class="mt-6 text-3xl font-semibold text-cook-text">All done</h2>
+      <p class="mt-2 text-cook-text/70">You can close this tab and return to CookCLI.</p>
+    </div>
+  </div>
+</div>
+```
+
+Create `app/views/device/denied.html.erb`:
+
+```erb
+<% content_for :title, "Authorization Denied" %>
+<div class="flex flex-col h-screen">
+  <div class="flex-1 bg-neutral-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
+    <div class="sm:mx-auto sm:w-full sm:max-w-md text-center">
+      <h2 class="mt-6 text-3xl font-semibold text-cook-text">Authorization denied</h2>
+      <p class="mt-2 text-cook-text/70">CookCLI will not be granted access.</p>
+    </div>
+  </div>
+</div>
+```
+
+Create `app/views/device/expired.html.erb`:
+
+```erb
+<% content_for :title, "Code Expired" %>
+<div class="flex flex-col h-screen">
+  <div class="flex-1 bg-neutral-50 flex flex-col justify-center py-12 sm:px-6 lg:px-8">
+    <div class="sm:mx-auto sm:w-full sm:max-w-md text-center">
+      <h2 class="mt-6 text-3xl font-semibold text-cook-text">Code expired or invalid</h2>
+      <p class="mt-2 text-cook-text/70">Go back to CookCLI and start a new sign-in.</p>
+      <p class="mt-6"><%= link_to "Try again", device_path, class: "underline" %></p>
+    </div>
+  </div>
+</div>
+```
+
+- [ ] **Step 4: Run full Phase-1 specs**
+
+Run: `bundle exec rspec spec/lib/device_flow_spec.rb spec/requests/oauth/device_spec.rb spec/requests/device_spec.rb`
+Expected: all examples pass.
+
+- [ ] **Step 5: RuboCop on the touched files**
+
+Run: `bundle exec rubocop spec/requests/device_spec.rb app/views/device/`
+Expected: no offenses.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add spec/requests/device_spec.rb \
+        app/views/device/approved.html.erb \
+        app/views/device/denied.html.erb \
+        app/views/device/expired.html.erb
+git commit -m "feat(device-flow): add approve/deny actions and result views"
+```
+
+---
+
+### Task 7: Phase-1 verification
+
+- [ ] **Step 1: Run full suite**
+
+Run: `bundle exec rspec`
+Expected: no new failures; all Phase-1 device-flow specs pass. If any unrelated specs fail in CI but not locally, document and proceed — do not modify them.
+
+- [ ] **Step 2: Run full RuboCop**
+
+Run: `bundle exec rubocop`
+Expected: no offenses (or no *new* offenses vs main if the repo has a baseline file).
+
+- [ ] **Step 3: Manual smoke test**
+
+Start the dev server. In one terminal:
+```
+bundle exec rails server
+```
+
+In another, exercise the API:
+```
+# 1. Request a code
+curl -sS -X POST http://localhost:3000/oauth/device/code \
+     -H 'Content-Type: application/json' \
+     -d '{"client_name":"smoke test"}' | tee /tmp/device.json
+
+# 2. Poll — expect authorization_pending
+curl -sS -X POST http://localhost:3000/oauth/device/token \
+     -H 'Content-Type: application/json' \
+     -d "{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code\",\"device_code\":\"$(jq -r .device_code /tmp/device.json)\"}"
+
+# 3. In a browser, go to http://localhost:3000/device, sign in if needed,
+#    enter the user_code, approve.
+
+# 4. Poll again — expect 200 with token
+```
+
+Confirm the returned JWT decodes (`Token.decode` in `rails console`).
+
+- [ ] **Step 4: Final Phase-1 commit (if anything changed)**
+
+If `rubocop --auto-correct` or any cleanup was needed, commit it now with `chore(device-flow): tidy Phase-1`.
+
+---
+
+# Phase 2 — CookCLI (Rust)
+
+Work directory: `/Users/alexeydubovskoy/Cooklang/CookCLI`. Run `cargo` commands from there.
+
+> **Note:** the project has no Rust test harness today (per `CONTRIBUTING.md`). Each task verifies via `cargo build --features sync`, `cargo fmt`, `cargo clippy --features sync -- -D warnings`, and explicit manual steps. Do not introduce a test framework as part of this plan.
+
+> **Note:** Phase 2 assumes Phase 1 is deployed (or running locally). For local end-to-end testing, set `COOK_ENDPOINT=http://localhost:3000` before running CookCLI.
+
+### Task 8: New `device_flow.rs` shared module
+
+**Files:**
+- Create: `src/server/sync/device_flow.rs`
+- Modify: `src/server/sync/mod.rs`
+
+- [ ] **Step 1: Read existing sync module structure**
+
+Run: `cat src/server/sync/mod.rs | head -30`
+
+Identify the existing `pub use` lines and where to add a new one.
+
+- [ ] **Step 2: Create the device_flow module**
+
+Create `src/server/sync/device_flow.rs`:
+
+```rust
+use std::time::{Duration, Instant};
+
+use anyhow::Context;
+use serde::{Deserialize, Serialize};
+use tokio_util::sync::CancellationToken;
+
+use super::endpoints;
+
+const GRANT_TYPE: &str = "urn:ietf:params:oauth:grant-type:device_code";
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct DeviceCodeResponse {
+    pub device_code: String,
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in: u64,
+    pub interval: u64,
+}
+
+#[derive(Debug, Serialize)]
+struct DeviceCodeRequest<'a> {
+    client_name: &'a str,
+}
+
+#[derive(Debug, Serialize)]
+struct TokenRequest<'a> {
+    grant_type: &'a str,
+    device_code: &'a str,
+}
+
+#[derive(Debug, Deserialize)]
+struct TokenSuccess {
+    token: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct TokenError {
+    error: String,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum DeviceFlowError {
+    #[error("user denied authorization")]
+    AccessDenied,
+    #[error("device code expired")]
+    Expired,
+    #[error("flow cancelled")]
+    Cancelled,
+    #[error("network error: {0}")]
+    Network(#[from] reqwest::Error),
+    #[error("bad response from cook.md: {0}")]
+    BadResponse(String),
+}
+
+pub async fn request_device_code(
+    client: &reqwest::Client,
+    client_name: &str,
+) -> anyhow::Result<DeviceCodeResponse> {
+    let url = format!("{}/oauth/device/code", endpoints::base_url());
+    let resp = client
+        .post(&url)
+        .json(&DeviceCodeRequest { client_name })
+        .send()
+        .await
+        .context("calling /oauth/device/code")?;
+
+    if !resp.status().is_success() {
+        let status = resp.status();
+        let body = resp.text().await.unwrap_or_default();
+        anyhow::bail!("device code request failed: HTTP {status}: {body}");
+    }
+
+    resp.json::<DeviceCodeResponse>()
+        .await
+        .context("parsing device code response")
+}
+
+/// Polls /oauth/device/token until approved, denied, expired, or cancelled.
+/// Respects `slow_down` (bumps interval by 5 s) and the `expires_at` deadline.
+pub async fn poll_for_token(
+    client: &reqwest::Client,
+    device_code: &str,
+    mut interval: Duration,
+    expires_at: Instant,
+    cancel: CancellationToken,
+) -> Result<String, DeviceFlowError> {
+    let url = format!("{}/oauth/device/token", endpoints::base_url());
+
+    loop {
+        if Instant::now() >= expires_at {
+            return Err(DeviceFlowError::Expired);
+        }
+
+        tokio::select! {
+            _ = cancel.cancelled() => return Err(DeviceFlowError::Cancelled),
+            _ = tokio::time::sleep(interval) => {}
+        }
+
+        let resp = client
+            .post(&url)
+            .json(&TokenRequest { grant_type: GRANT_TYPE, device_code })
+            .send()
+            .await?;
+
+        let status = resp.status();
+
+        if status.is_success() {
+            let body: TokenSuccess = resp.json().await.map_err(DeviceFlowError::Network)?;
+            return Ok(body.token);
+        }
+
+        // 400 → parse {"error": "..."} per RFC 8628
+        let body: TokenError = resp
+            .json()
+            .await
+            .map_err(|e| DeviceFlowError::BadResponse(format!("unparseable error body: {e}")))?;
+
+        match body.error.as_str() {
+            "authorization_pending" => continue,
+            "slow_down" => {
+                interval += Duration::from_secs(5);
+            }
+            "access_denied" => return Err(DeviceFlowError::AccessDenied),
+            "expired_token" => return Err(DeviceFlowError::Expired),
+            other => {
+                return Err(DeviceFlowError::BadResponse(format!(
+                    "unexpected error code: {other}"
+                )))
+            }
+        }
+    }
+}
+
+/// Builds the client_name string sent to cook.md. Includes OS and a
+/// best-effort label ("docker" / "cli" / hostname).
+pub fn client_name(suffix: &str) -> String {
+    format!(
+        "CookCLI {} ({}/{})",
+        env!("CARGO_PKG_VERSION"),
+        std::env::consts::OS,
+        suffix
+    )
+}
+
+/// Returns "docker" if /.dockerenv exists, else "server".
+pub fn server_host_label() -> &'static str {
+    if std::path::Path::new("/.dockerenv").exists() {
+        "docker"
+    } else {
+        "server"
+    }
+}
+```
+
+- [ ] **Step 3: Re-export from `sync/mod.rs`**
+
+In `src/server/sync/mod.rs`, find the existing module declarations (likely a block of `pub mod ...` or `mod ...`). Add:
+
+```rust
+pub mod device_flow;
+```
+
+Add this alongside the other `mod` lines, keeping them grouped.
+
+- [ ] **Step 4: Confirm `thiserror` is available**
+
+Run: `grep '^thiserror' Cargo.toml`
+
+Expected: a dependency line. If missing, add `thiserror = "2"` to `[dependencies]`. (Most Rust projects already have it; the existing `cooklang-sync-client` likely transitively brings it.)
+
+If `thiserror` is *not* a direct dependency, **either** add it or change `DeviceFlowError` to use a manual `impl std::error::Error`. Adding the dep is simpler and ~zero binary cost.
+
+- [ ] **Step 5: Build with the sync feature**
+
+Run: `cargo build --features sync`
+Expected: clean build. Fix any compile errors.
+
+- [ ] **Step 6: Lint**
+
+Run: `cargo fmt --check && cargo clippy --features sync -- -D warnings`
+Expected: no output, exit 0.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/server/sync/device_flow.rs src/server/sync/mod.rs Cargo.toml Cargo.lock
+git commit -m "feat(sync): add device_flow module for OAuth device-code login"
+```
+
+---
+
+### Task 9: Update `AppState` — replace `login_in_progress` with `pending_device_flow`
+
+**Files:**
+- Modify: `src/server/mod.rs`
+
+- [ ] **Step 1: Read the relevant block**
+
+Run: `sed -n '355,400p' src/server/mod.rs`
+
+Locate the `AppState` struct definition.
+
+- [ ] **Step 2: Replace the `login_in_progress` field**
+
+In `src/server/mod.rs`, find the field:
+
+```rust
+    #[cfg(feature = "sync")]
+    pub login_in_progress: Arc<AtomicBool>,
+```
+
+Replace it with:
+
+```rust
+    #[cfg(feature = "sync")]
+    pub pending_device_flow: Arc<tokio::sync::Mutex<Option<sync::PendingDeviceFlow>>>,
+```
+
+- [ ] **Step 3: Add the `PendingDeviceFlow` type to the sync module**
+
+In `src/server/sync/mod.rs`, add:
+
+```rust
+use tokio_util::sync::CancellationToken;
+
+#[derive(Clone)]
+pub struct PendingDeviceFlow {
+    pub device_code: String,
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_at: std::time::Instant,
+    pub interval: std::time::Duration,
+    pub cancel: CancellationToken,
+}
+```
+
+- [ ] **Step 4: Update `build_state` initialization**
+
+In `src/server/mod.rs`, find the `build_state` function and locate where `login_in_progress` is initialized:
+
+```rust
+        #[cfg(feature = "sync")]
+        login_in_progress: Arc::new(AtomicBool::new(false)),
+```
+
+Replace with:
+
+```rust
+        #[cfg(feature = "sync")]
+        pending_device_flow: Arc::new(tokio::sync::Mutex::new(None)),
+```
+
+- [ ] **Step 5: Remove the now-unused `AtomicBool` import if it isn't used elsewhere**
+
+Run: `grep -n AtomicBool src/server/mod.rs`
+
+If `AtomicBool` is only referenced by the line above (now deleted), remove its `use` line. Otherwise leave it.
+
+- [ ] **Step 6: Build**
+
+Run: `cargo build --features sync`
+Expected: build will fail with errors in `src/server/handlers/sync.rs` (still references `login_in_progress`). That's expected — Task 10 rewrites that file.
+
+To unblock the build for this isolated commit, temporarily comment out (or `todo!()`) the `login_in_progress` references in `handlers/sync.rs`. **Do not delete them yet** — Task 10 deletes the entire helper graph.
+
+Actually simplest: keep the handler unchanged in this task and do Steps 1-5 together with Task 10 as a single commit. Skip ahead and combine — see Task 10.
+
+- [ ] **Step 7: Combine with Task 10**
+
+This task's commit is folded into Task 10 (which rewrites the handler). Do not commit yet.
+
+---
+
+### Task 10: Rewrite `handlers/sync.rs` for device-code flow
+
+**Files:**
+- Modify: `src/server/handlers/sync.rs`
+- Modify: `src/server/mod.rs` (apply Task 9's changes here too)
+
+This is the largest single change in Phase 2. It rewrites `sync_login`, deletes the browser-popup helpers, extends `LoginResponse` and `SyncStatusResponse`, and adds `sync_cancel_login`.
+
+- [ ] **Step 1: Apply Task 9 changes**
+
+If not already done, apply Task 9 Steps 2-5 now.
+
+- [ ] **Step 2: Rewrite `src/server/handlers/sync.rs`**
+
+Replace the **entire file** with:
+
+```rust
+use crate::server::sync::{self, device_flow, PendingDeviceFlow, SyncSession};
+use crate::server::AppState;
+use axum::{extract::State, http::StatusCode, Json};
+use serde::Serialize;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio_util::sync::CancellationToken;
+
+#[derive(Serialize)]
+pub struct PendingLogin {
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in_secs: u64,
+}
+
+#[derive(Serialize)]
+pub struct SyncStatusResponse {
+    pub logged_in: bool,
+    pub email: Option<String>,
+    pub syncing: bool,
+    pub pending_login: Option<PendingLogin>,
+}
+
+pub async fn sync_status(State(state): State<Arc<AppState>>) -> Json<SyncStatusResponse> {
+    let (logged_in, email, syncing) = state.sync_status().await;
+
+    let pending_login = {
+        let guard = state.pending_device_flow.lock().await;
+        guard.as_ref().map(|p| PendingLogin {
+            user_code: p.user_code.clone(),
+            verification_uri: p.verification_uri.clone(),
+            verification_uri_complete: p.verification_uri_complete.clone(),
+            expires_in_secs: p
+                .expires_at
+                .saturating_duration_since(Instant::now())
+                .as_secs(),
+        })
+    };
+
+    Json(SyncStatusResponse {
+        logged_in,
+        email,
+        syncing,
+        pending_login,
+    })
+}
+
+#[derive(Serialize)]
+pub struct LoginResponse {
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in: u64,
+}
+
+pub async fn sync_login(
+    State(state): State<Arc<AppState>>,
+) -> Result<Json<LoginResponse>, (StatusCode, Json<serde_json::Value>)> {
+    // Already logged in?
+    if state.sync_session.lock().unwrap().is_some() {
+        return Err((
+            StatusCode::BAD_REQUEST,
+            Json(serde_json::json!({ "error": "Already logged in" })),
+        ));
+    }
+
+    // Already a flow in progress?
+    {
+        let guard = state.pending_device_flow.lock().await;
+        if guard.is_some() {
+            return Err((
+                StatusCode::CONFLICT,
+                Json(serde_json::json!({ "error": "Login already in progress" })),
+            ));
+        }
+    }
+
+    let client = reqwest::Client::new();
+    let name = device_flow::client_name(device_flow::server_host_label());
+    let dc = device_flow::request_device_code(&client, &name)
+        .await
+        .map_err(|e| {
+            (
+                StatusCode::BAD_GATEWAY,
+                Json(serde_json::json!({ "error": format!("cook.md unreachable: {e}") })),
+            )
+        })?;
+
+    let cancel = CancellationToken::new();
+    let expires_at = Instant::now() + Duration::from_secs(dc.expires_in);
+    let interval = Duration::from_secs(dc.interval);
+
+    let pending = PendingDeviceFlow {
+        device_code: dc.device_code.clone(),
+        user_code: dc.user_code.clone(),
+        verification_uri: dc.verification_uri.clone(),
+        verification_uri_complete: dc.verification_uri_complete.clone(),
+        expires_at,
+        interval,
+        cancel: cancel.clone(),
+    };
+
+    *state.pending_device_flow.lock().await = Some(pending);
+
+    let state_clone = state.clone();
+    let device_code = dc.device_code.clone();
+    tokio::spawn(async move {
+        let result = device_flow::poll_for_token(
+            &client,
+            &device_code,
+            interval,
+            expires_at,
+            cancel,
+        )
+        .await;
+
+        // Clear pending flow regardless of outcome
+        *state_clone.pending_device_flow.lock().await = None;
+
+        match result {
+            Ok(jwt) => {
+                match SyncSession::from_jwt(jwt) {
+                    Ok(session) => {
+                        if let Err(e) = session.save(&state_clone.session_path) {
+                            tracing::error!("Failed to save session: {e}");
+                            return;
+                        }
+                        *state_clone.sync_session.lock().unwrap() = Some(session.clone());
+
+                        match sync::sync_db_path() {
+                            Ok(db_path) => match sync::start_sync(
+                                &session,
+                                state_clone.base_path.to_string(),
+                                db_path,
+                            ) {
+                                Ok(handle) => {
+                                    *state_clone.sync_handle.lock().await = Some(handle);
+                                    tracing::info!("Sync started after login");
+                                }
+                                Err(e) => tracing::warn!("Failed to start sync after login: {e}"),
+                            },
+                            Err(e) => tracing::error!("Failed to resolve sync db path: {e}"),
+                        }
+                    }
+                    Err(e) => tracing::error!("Failed to build SyncSession from JWT: {e}"),
+                }
+            }
+            Err(device_flow::DeviceFlowError::Cancelled) => {
+                tracing::info!("Login cancelled by user");
+            }
+            Err(e) => tracing::error!("Login failed: {e}"),
+        }
+    });
+
+    Ok(Json(LoginResponse {
+        user_code: dc.user_code,
+        verification_uri: dc.verification_uri,
+        verification_uri_complete: dc.verification_uri_complete,
+        expires_in: dc.expires_in,
+    }))
+}
+
+pub async fn sync_cancel_login(
+    State(state): State<Arc<AppState>>,
+) -> Json<serde_json::Value> {
+    let mut guard = state.pending_device_flow.lock().await;
+    if let Some(p) = guard.take() {
+        p.cancel.cancel();
+        Json(serde_json::json!({ "cancelled": true }))
+    } else {
+        Json(serde_json::json!({ "cancelled": false }))
+    }
+}
+
+pub async fn sync_logout(
+    State(state): State<Arc<AppState>>,
+) -> Result<Json<serde_json::Value>, (StatusCode, Json<serde_json::Value>)> {
+    // Stop sync task
+    if let Some(handle) = state.sync_handle.lock().await.take() {
+        handle.stop().await;
+    }
+
+    // Clear session
+    *state.sync_session.lock().unwrap() = None;
+    if let Err(e) = SyncSession::delete(&state.session_path) {
+        tracing::warn!("Failed to delete session file: {e}");
+    }
+
+    Ok(Json(serde_json::json!({ "ok": true })))
+}
+```
+
+- [ ] **Step 3: Register the new route**
+
+In `src/server/mod.rs`, find the existing `#[cfg(feature = "sync")]` route block (around lines 461-465):
+
+```rust
+#[cfg(feature = "sync")]
+let router = router
+    .route("/api/sync/status", get(handlers::sync_status))
+    .route("/api/sync/login", post(handlers::sync_login))
+    .route("/api/sync/logout", post(handlers::sync_logout));
+```
+
+Change it to:
+
+```rust
+#[cfg(feature = "sync")]
+let router = router
+    .route("/api/sync/status", get(handlers::sync_status))
+    .route("/api/sync/login", post(handlers::sync_login))
+    .route("/api/sync/cancel_login", post(handlers::sync_cancel_login))
+    .route("/api/sync/logout", post(handlers::sync_logout));
+```
+
+- [ ] **Step 4: Export `sync_cancel_login` from handlers module**
+
+Run: `grep -n 'pub use.*sync' src/server/handlers/mod.rs`
+
+If the module re-exports via `pub use sync::*` you're done. Otherwise add `pub use sync::sync_cancel_login;` (or the appropriate explicit export) to match the existing pattern for `sync_login`, `sync_status`, `sync_logout`.
+
+- [ ] **Step 5: Build**
+
+Run: `cargo build --features sync`
+Expected: clean build.
+
+- [ ] **Step 6: Lint**
+
+Run: `cargo fmt && cargo clippy --features sync -- -D warnings`
+Expected: no warnings.
+
+- [ ] **Step 7: Smoke test against a Phase-1 server**
+
+In one terminal, run cook.md locally on port 3000 (Phase 1).
+
+In another:
+```
+COOK_ENDPOINT=http://localhost:3000 cargo run --features sync -- server ./seed
+```
+
+In a browser at `http://localhost:9080/preferences`, click "Login to CookCloud". The button currently still triggers the *old* JS (templates/preferences.html is not yet updated). Verify in the network tab that `POST /api/sync/login` returns a body containing `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in`. (The page won't render the new UI yet — that's Task 11.)
+
+Cancel via:
+```
+curl -X POST http://localhost:9080/api/sync/cancel_login
+```
+
+Verify `GET /api/sync/status` no longer returns `pending_login`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/server/handlers/sync.rs src/server/mod.rs src/server/sync/mod.rs
+git commit -m "feat(sync): replace browser-popup login with device-code flow"
+```
+
+---
+
+### Task 11: Update `preferences.html` for device-code UI
+
+**Files:**
+- Modify: `templates/preferences.html`
+
+- [ ] **Step 1: Read the current login section**
+
+Run: `sed -n '40,80p' templates/preferences.html`
+Run: `sed -n '155,225p' templates/preferences.html`
+
+Note the existing markup for the Login button and the `syncLogin()` JS function. They will both be replaced.
+
+- [ ] **Step 2: Replace the Login button markup**
+
+Find the block containing `<button id="sync-login-btn">` (typically inside `{% if not sync_logged_in %}` around lines 60-72). Replace it with:
+
+```html
+<div id="sync-login-section">
+  <button id="sync-login-btn"
+          onclick="syncLogin()"
+          class="px-4 py-2 rounded-md bg-cook-text text-white">
+    Login to CookCloud
+  </button>
+  <p id="sync-login-message" class="text-sm text-cook-text/60 mt-2"></p>
+</div>
+
+<div id="sync-login-card" class="hidden mt-4 border border-cook-text/10 rounded-lg p-6 bg-white">
+  <h3 class="text-lg font-semibold">Sign in to CookCloud</h3>
+  <ol class="mt-3 space-y-2 text-sm">
+    <li>1. Open <a id="sync-login-link" href="#" target="_blank" rel="noopener" class="underline">cook.md/device</a> in any browser.</li>
+    <li>2. Enter this code:</li>
+  </ol>
+  <div class="mt-3 flex items-center gap-2">
+    <code id="sync-login-code" class="text-2xl tracking-widest bg-neutral-100 px-4 py-2 rounded">----  ----</code>
+    <button id="sync-login-copy" type="button" class="px-3 py-1 border rounded text-sm">Copy</button>
+  </div>
+  <p id="sync-login-expires" class="mt-3 text-sm text-cook-text/60"></p>
+  <div class="mt-4 flex gap-2">
+    <a id="sync-login-open" href="#" target="_blank" rel="noopener" class="px-4 py-2 rounded bg-cook-text text-white">Open cook.md/device</a>
+    <button id="sync-login-cancel" type="button" class="px-4 py-2 rounded border">Cancel</button>
+  </div>
+</div>
+```
+
+- [ ] **Step 3: Replace the `syncLogin()` JS**
+
+Find the `{% if sync_enabled %} ... async function syncLogin() ...` block (around lines 161-213). Replace from `async function syncLogin()` through the closing brace before `async function syncLogout()` with:
+
+```html
+let pollHandle = null;
+let countdownHandle = null;
+
+function renderPending(p) {
+  document.getElementById('sync-login-section').classList.add('hidden');
+  const card = document.getElementById('sync-login-card');
+  card.classList.remove('hidden');
+  document.getElementById('sync-login-code').textContent = p.user_code;
+  document.getElementById('sync-login-link').href = p.verification_uri;
+  document.getElementById('sync-login-link').textContent = p.verification_uri;
+  document.getElementById('sync-login-open').href = p.verification_uri_complete;
+
+  if (countdownHandle) clearInterval(countdownHandle);
+  let remaining = p.expires_in_secs ?? p.expires_in;
+  const expEl = document.getElementById('sync-login-expires');
+  const tick = () => {
+    if (remaining <= 0) {
+      expEl.textContent = 'Code expired.';
+      stopPolling();
+      resetLoginUi('Code expired — try again.');
+      return;
+    }
+    const m = Math.floor(remaining / 60);
+    const s = String(remaining % 60).padStart(2, '0');
+    expEl.textContent = `Expires in ${m}:${s}`;
+    remaining--;
+  };
+  tick();
+  countdownHandle = setInterval(tick, 1000);
+}
+
+function stopPolling() {
+  if (pollHandle) { clearInterval(pollHandle); pollHandle = null; }
+  if (countdownHandle) { clearInterval(countdownHandle); countdownHandle = null; }
+}
+
+function resetLoginUi(msg) {
+  document.getElementById('sync-login-card').classList.add('hidden');
+  document.getElementById('sync-login-section').classList.remove('hidden');
+  document.getElementById('sync-login-message').textContent = msg || '';
+}
+
+async function syncLogin() {
+  const btn = document.getElementById('sync-login-btn');
+  const msg = document.getElementById('sync-login-message');
+  try {
+    btn.disabled = true;
+    msg.textContent = 'Requesting code...';
+    const resp = await fetch('{{ prefix }}/api/sync/login', { method: 'POST' });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      btn.disabled = false;
+      msg.textContent = err.error || 'Login failed.';
+      return;
+    }
+    const body = await resp.json();
+    renderPending({ ...body, expires_in_secs: body.expires_in });
+
+    pollHandle = setInterval(async () => {
+      const status = await fetch('{{ prefix }}/api/sync/status').then(r => r.json());
+      if (status.logged_in) {
+        stopPolling();
+        window.location.reload();
+      } else if (!status.pending_login) {
+        stopPolling();
+        resetLoginUi('Login was cancelled or expired.');
+      }
+    }, 2000);
+  } catch (e) {
+    btn.disabled = false;
+    msg.textContent = 'Failed to start login: ' + e.message;
+  }
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  const copyBtn = document.getElementById('sync-login-copy');
+  if (copyBtn) {
+    copyBtn.addEventListener('click', async () => {
+      const code = document.getElementById('sync-login-code').textContent;
+      await navigator.clipboard.writeText(code.replace(/\s+/g, ''));
+      copyBtn.textContent = 'Copied!';
+      setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
+    });
+  }
+  const cancelBtn = document.getElementById('sync-login-cancel');
+  if (cancelBtn) {
+    cancelBtn.addEventListener('click', async () => {
+      stopPolling();
+      await fetch('{{ prefix }}/api/sync/cancel_login', { method: 'POST' });
+      resetLoginUi('Login cancelled.');
+    });
+  }
+
+  // Resume on page load if a flow is in progress server-side.
+  fetch('{{ prefix }}/api/sync/status').then(r => r.json()).then(status => {
+    if (!status.logged_in && status.pending_login) {
+      renderPending(status.pending_login);
+      pollHandle = setInterval(async () => {
+        const s = await fetch('{{ prefix }}/api/sync/status').then(r => r.json());
+        if (s.logged_in) { stopPolling(); window.location.reload(); }
+        else if (!s.pending_login) { stopPolling(); resetLoginUi('Login was cancelled or expired.'); }
+      }, 2000);
+    }
+  });
+});
+```
+
+- [ ] **Step 4: Rebuild CSS**
+
+Run: `make css` (or `npm run build-css`)
+Expected: `static/css/output.css` regenerated with no errors.
+
+- [ ] **Step 5: Manual UI smoke test**
+
+Run cook.md locally on port 3000 (Phase 1 deployed). Then:
+
+```
+COOK_ENDPOINT=http://localhost:3000 cargo run --features sync -- server ./seed
+```
+
+In a browser at `http://localhost:9080/preferences`:
+1. Click "Login to CookCloud". The login card appears with a code like `WDJB-MJHT` and an "Open cook.md/device" button.
+2. Click "Open cook.md/device" → a new tab opens at `http://localhost:3000/device?user_code=WDJB-MJHT`. Sign in (email-code flow). The form pre-fills the code. Click "Continue", then "Approve".
+3. Switch back to the CookCLI tab. Within ~2 s the page reloads and now shows the signed-in state.
+4. Re-test the "Cancel" button. Re-test page-reload-mid-flow (refresh after clicking Login; the card should reappear with the same code).
+
+If anything looks off visually, fix inline.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add templates/preferences.html static/css/output.css
+git commit -m "feat(sync): replace login button JS with device-code card"
+```
+
+---
+
+### Task 12: `cook login` CLI command
+
+**Files:**
+- Create: `src/login.rs`
+- Modify: `src/args.rs`
+- Modify: `src/main.rs`
+
+- [ ] **Step 1: Read the seed command pattern**
+
+Run: `sed -n '1,40p' src/seed.rs`
+Run: `grep -n 'Seed' src/args.rs src/main.rs`
+
+Match the existing pattern.
+
+- [ ] **Step 2: Create `src/login.rs`**
+
+```rust
+use std::time::{Duration, Instant};
+
+use anyhow::Result;
+use clap::Parser;
+use tokio_util::sync::CancellationToken;
+
+use crate::server::sync::{self, device_flow, SyncSession};
+use crate::Context;
+
+#[derive(Debug, Parser)]
+pub struct LoginArgs {}
+
+pub fn run(_ctx: &Context, _args: LoginArgs) -> Result<()> {
+    let runtime = tokio::runtime::Runtime::new()?;
+    runtime.block_on(run_async())
+}
+
+async fn run_async() -> Result<()> {
+    use std::io::{BufRead, Write};
+
+    let session_path = crate::global_file_path("session.json")
+        .unwrap_or_else(|_| std::path::PathBuf::from(".cook-session.json"));
+
+    if SyncSession::load(&session_path).ok().flatten().is_some() {
+        println!("Already logged in. Run `cook logout` first if you want to switch accounts.");
+        return Ok(());
+    }
+
+    let client = reqwest::Client::new();
+    let name = device_flow::client_name("cli");
+    let dc = device_flow::request_device_code(&client, &name).await?;
+
+    println!();
+    println!("First open {} in any browser and enter this code:", dc.verification_uri);
+    println!();
+    println!("    {}", dc.user_code);
+    println!();
+    println!("(Press Enter to open it automatically, or Ctrl-C to abort.)");
+
+    // Drain a line; ignore errors (e.g. piped stdin).
+    let stdin = std::io::stdin();
+    let _ = stdin.lock().lines().next();
+
+    // Try to open the verification_uri_complete; failure is non-fatal.
+    if let Err(e) = open::that(&dc.verification_uri_complete) {
+        eprintln!("Couldn't open browser automatically: {e}");
+        eprintln!("Please visit the URL above manually.");
+    }
+
+    print!("Waiting for authorization");
+    std::io::stdout().flush().ok();
+
+    let cancel = CancellationToken::new();
+    let cancel_for_signal = cancel.clone();
+    tokio::spawn(async move {
+        let _ = tokio::signal::ctrl_c().await;
+        cancel_for_signal.cancel();
+    });
+
+    let expires_at = Instant::now() + Duration::from_secs(dc.expires_in);
+    let interval = Duration::from_secs(dc.interval);
+
+    let dot_handle = {
+        let cancel = cancel.clone();
+        tokio::spawn(async move {
+            loop {
+                tokio::select! {
+                    _ = cancel.cancelled() => return,
+                    _ = tokio::time::sleep(Duration::from_secs(1)) => {
+                        print!(".");
+                        let _ = std::io::stdout().flush();
+                    }
+                }
+            }
+        })
+    };
+
+    let jwt = match device_flow::poll_for_token(&client, &dc.device_code, interval, expires_at, cancel.clone()).await {
+        Ok(jwt) => jwt,
+        Err(device_flow::DeviceFlowError::AccessDenied) => {
+            cancel.cancel();
+            dot_handle.abort();
+            anyhow::bail!("Authorization denied.");
+        }
+        Err(device_flow::DeviceFlowError::Expired) => {
+            cancel.cancel();
+            dot_handle.abort();
+            anyhow::bail!("Code expired — try `cook login` again.");
+        }
+        Err(device_flow::DeviceFlowError::Cancelled) => {
+            dot_handle.abort();
+            anyhow::bail!("Cancelled.");
+        }
+        Err(e) => {
+            cancel.cancel();
+            dot_handle.abort();
+            anyhow::bail!("Login failed: {e}");
+        }
+    };
+
+    cancel.cancel();
+    dot_handle.abort();
+    println!();
+
+    let session = SyncSession::from_jwt(jwt)?;
+    session.save(&session_path)?;
+
+    let email = session.email().unwrap_or_else(|| "<unknown>".to_string());
+    println!("✓ Logged in as {email}");
+    println!();
+    println!("Note: if `cook server` is running, restart it to pick up the new session.");
+
+    let _ = sync::sync_db_path(); // touch / verify
+
+    Ok(())
+}
+```
+
+> **Note on `SyncSession::email()`:** if the existing API doesn't expose `email()` directly, use whatever public accessor returns the email (likely a `pub email: String` field or a method on the struct — check `src/server/sync/session.rs`). Adjust the call site to match.
+
+- [ ] **Step 3: Add the variant to `args.rs`**
+
+In `src/args.rs`, find the `Command` enum. Add:
+
+```rust
+/// Sign in to CookCloud.
+#[cfg(feature = "sync")]
+Login(crate::login::LoginArgs),
+```
+
+- [ ] **Step 4: Wire the dispatch in `main.rs`**
+
+In `src/main.rs`, find the `match command { ... }` block. Add:
+
+```rust
+#[cfg(feature = "sync")]
+Command::Login(args) => login::run(&ctx, args),
+```
+
+Also add the module declaration near the top:
+
+```rust
+#[cfg(feature = "sync")]
+mod login;
+```
+
+- [ ] **Step 5: Build**
+
+Run: `cargo build --features sync`
+Expected: clean build.
+
+- [ ] **Step 6: Lint**
+
+Run: `cargo fmt && cargo clippy --features sync -- -D warnings`
+
+- [ ] **Step 7: Manual smoke test**
+
+With Phase 1 running locally:
+
+```
+COOK_ENDPOINT=http://localhost:3000 cargo run --features sync -- login
+```
+
+Press Enter when prompted. Browser opens to cook.md/device. Sign in, enter code, approve. Terminal shows "✓ Logged in as ...". Then:
+
+```
+ls -la ~/.config/cook/session.json   # or platform-equivalent
+```
+
+File exists with mode `-rw-------`.
+
+Test the failure paths:
+- Run `cook login`, then Ctrl-C → exits with "Cancelled."
+- Run `cook login`, enter the code on web but click "Deny" → exits with "Authorization denied."
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/login.rs src/args.rs src/main.rs
+git commit -m "feat(sync): add `cook login` CLI command"
+```
+
+---
+
+### Task 13: `cook logout` CLI command
+
+**Files:**
+- Create: `src/logout.rs`
+- Modify: `src/args.rs`
+- Modify: `src/main.rs`
+
+- [ ] **Step 1: Create `src/logout.rs`**
+
+```rust
+use anyhow::Result;
+use clap::Parser;
+
+use crate::server::sync::SyncSession;
+use crate::Context;
+
+#[derive(Debug, Parser)]
+pub struct LogoutArgs {}
+
+pub fn run(_ctx: &Context, _args: LogoutArgs) -> Result<()> {
+    let session_path = crate::global_file_path("session.json")
+        .unwrap_or_else(|_| std::path::PathBuf::from(".cook-session.json"));
+
+    match SyncSession::load(&session_path) {
+        Ok(Some(_)) => {
+            SyncSession::delete(&session_path)?;
+            println!("Logged out.");
+        }
+        _ => {
+            println!("Not logged in.");
+        }
+    }
+    Ok(())
+}
+```
+
+- [ ] **Step 2: Add the variant to `args.rs`**
+
+```rust
+/// Sign out of CookCloud.
+#[cfg(feature = "sync")]
+Logout(crate::logout::LogoutArgs),
+```
+
+- [ ] **Step 3: Wire dispatch in `main.rs`**
+
+```rust
+#[cfg(feature = "sync")]
+mod logout;
+```
+
+```rust
+#[cfg(feature = "sync")]
+Command::Logout(args) => logout::run(&ctx, args),
+```
+
+- [ ] **Step 4: Build & lint**
+
+Run: `cargo build --features sync && cargo fmt && cargo clippy --features sync -- -D warnings`
+
+- [ ] **Step 5: Manual smoke test**
+
+After running `cook login` in Task 12:
+
+```
+cargo run --features sync -- logout
+ls -la ~/.config/cook/session.json   # should not exist
+cargo run --features sync -- logout   # second invocation
+```
+
+Expected output, in order: `Logged out.`, then `Not logged in.`
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/logout.rs src/args.rs src/main.rs
+git commit -m "feat(sync): add `cook logout` CLI command"
+```
+
+---
+
+### Task 14: Final Phase-2 verification
+
+- [ ] **Step 1: Full build + lint + format**
+
+Run: `cargo build --features sync && cargo fmt --check && cargo clippy --features sync -- -D warnings && cargo test --features sync`
+Expected: clean across the board. (`cargo test` may report `0 passed` — the codebase has no Rust tests yet. That's fine.)
+
+- [ ] **Step 2: Build the non-sync variant**
+
+Run: `cargo build --no-default-features --features self-update`
+Expected: clean — confirms no accidental references to sync types from non-feature-gated code.
+
+- [ ] **Step 3: Full manual test matrix**
+
+For each row, complete the device-code flow end-to-end and confirm the session file is written.
+
+| Environment | Command | Browser? |
+|---|---|---|
+| Native macOS | `cook login` | Default browser opens. |
+| Native macOS, no browser auto-open | `cook login`, press Ctrl-C immediately after seeing the code | Cancels cleanly. |
+| Inside Docker (`docker run -it cookcli login`) | `cook login` | Auto-open fails gracefully; user pastes URL into host browser. |
+| SSH session, no display | `cook login` | Auto-open fails gracefully; user copies URL. |
+| Web UI native | Browser → preferences → Login | New tab to cook.md; flow completes; preferences reloads. |
+| Web UI in Docker (port-mapped 9080) | Browser → preferences → Login | Card shows code; user opens cook.md/device on host; flow completes. |
+
+For each: also verify `cook logout` removes the session.
+
+- [ ] **Step 4: Confirm the original issue is fixed**
+
+Reproduce the issue from #290 if possible:
+
+```yaml
+services:
+  cookcli:
+    image: <local build tagged for test>
+    ports: ["9080:9080"]
+    volumes: ["./recipes:/recipes"]
+```
+
+Run `docker compose up`. Open `http://localhost:9080/preferences`. Click Login. Verify no `ERROR Failed to open browser` log line appears, and the device-code card renders.
+
+- [ ] **Step 5: Squash-merge or PR**
+
+Open the PR linking to issue #290 and the design spec. PR description should call out:
+- Removed: server-side `open::that` for auth flow, local TCP listener / CSRF callback.
+- Added: device-code flow shared by web UI and CLI; `cook login` / `cook logout`.
+- Behaviour change: server-side login never spawns a host browser.
+
+---
+
+## Self-Review (already performed during plan-writing)
+
+**1. Spec coverage:** every section of the spec maps to one or more tasks above:
+- §"cook.md side" → Tasks 1-7
+- §"CookCLI" device_flow module → Task 8
+- AppState changes → Task 9 (folded into Task 10)
+- handler rewrite → Task 10
+- preferences.html → Task 11
+- `cook login` → Task 12
+- `cook logout` → Task 13
+- "Files deleted" inventory verified inside Task 10 (rewrites the file wholesale).
+- Security section: rate limits in Task 1; SHA-256 hashing in Task 2; CSRF tokens via Rails defaults in Task 5; single-use enforcement covered by Task 2 spec and Task 4 spec.
+- Testing section: RSpec specs in Tasks 2-6; manual matrix in Task 14.
+
+**2. Placeholder scan:** no "TBD", "TODO", "fill in details" present. The note about `SyncSession::email()` in Task 12 is an *adapt-to-existing-API* instruction with a clear fallback (use whatever the public accessor is), not a placeholder.
+
+**3. Type consistency:** `PendingDeviceFlow`, `DeviceCodeResponse`, `LoginResponse`, `PendingLogin`, `SyncStatusResponse`, `DeviceFlowError` — names used consistently across Tasks 8, 9, 10, 11. `device_flow::client_name()` / `server_host_label()` / `request_device_code()` / `poll_for_token()` signatures match between definition (Task 8) and call sites (Tasks 10, 12). `DeviceFlow.create!` / `find_by_user_code` / `approve!` / `deny!` / `poll` signatures match between Task 2 spec, Task 2 impl, and call sites in Tasks 4-6.
diff --git a/docs/superpowers/specs/2026-05-15-shopping-list-pantry-flags-design.md b/docs/superpowers/specs/2026-05-15-shopping-list-pantry-flags-design.md
new file mode 100644
index 0000000..5fc7e8a
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-15-shopping-list-pantry-flags-design.md
@@ -0,0 +1,77 @@
+# Shopping List Pantry Flags — Design
+
+## Background
+
+The `cook shopping-list` CLI command already loads a pantry file via `Context::pantry()` (`src/main.rs:104`) and subtracts pantry quantities from the generated shopping list (`src/shopping_list.rs:264-267`). However, two ergonomic gaps remain compared to the aisle handling and compared to the web server:
+
+1. No way to specify a custom pantry file path on the command line. The aisle flag (`--aisle <path>`) supports this; pantry does not.
+2. No way to disable pantry subtraction. If a user wants the full unfiltered shopping list, they must move or delete their pantry file.
+
+This spec closes both gaps.
+
+## Goals
+
+- Add `--pantry <path>` argument to `cook shopping-list`, mirroring the existing `--aisle <path>`.
+- Add `--ignore-pantry` boolean flag that completely skips pantry loading and subtraction.
+
+## Non-Goals
+
+- No changes to pantry parsing, subtraction logic, or the underlying `cooklang::pantry` API.
+- No changes to the web server pantry handling.
+- No changes to the `pantry` subcommand or other commands.
+
+## Design
+
+### CLI Surface
+
+Add two fields to `ShoppingListArgs` in `src/shopping_list.rs`:
+
+```rust
+/// Load pantry conf file
+#[arg(long)]
+pantry: Option<Utf8PathBuf>,
+
+/// Don't subtract pantry items from the shopping list
+#[arg(long)]
+ignore_pantry: bool,
+```
+
+Notes:
+- `--pantry` is long-only (no short flag) to avoid colliding with `-p` / `--plain`.
+- `--ignore-pantry` follows the naming pattern of the existing `--ignore-references` flag.
+
+### Resolution Logic
+
+Replace the current pantry loading block (`src/shopping_list.rs:198-233`) with logic that mirrors the aisle resolution pattern at `src/shopping_list.rs:168-175`:
+
+1. If `args.ignore_pantry` is `true`: skip loading entirely. `pantry` is `None`. No file I/O occurs.
+2. Otherwise, resolve the path as `args.pantry.or_else(|| ctx.pantry())`.
+3. If a path is resolved, load and parse as today (parse_lenient, surface warnings, rebuild index).
+4. If no path is resolved, behave as today (no pantry, no subtraction).
+
+The existing subtraction call at `src/shopping_list.rs:264-267` is unchanged — it already short-circuits when `pantry` is `None`.
+
+### Interaction Matrix
+
+| `--ignore-pantry` | `--pantry <path>` | `ctx.pantry()` resolves | Behavior                                  |
+| ----------------- | ----------------- | ----------------------- | ----------------------------------------- |
+| true              | (any)             | (any)                   | No load, no subtraction                   |
+| false             | Some(path)        | (any)                   | Load from `path`, subtract                |
+| false             | None              | Some(auto)              | Load from auto path, subtract (unchanged) |
+| false             | None              | None                    | No load, no subtraction (unchanged)       |
+
+When both `--ignore-pantry` and `--pantry` are passed, `--ignore-pantry` wins. The provided path is not opened. This matches the user's stated intent ("skip pantry items") and avoids surprising failures from a bad path that the user explicitly asked to ignore.
+
+## Testing
+
+Manual verification using `cook seed` fixtures:
+
+1. Default behavior unchanged: `cook shopping-list <recipe>` still subtracts auto-discovered pantry.
+2. Custom path: create a pantry file at a non-default location, run `cook shopping-list --pantry <path> <recipe>`, verify subtraction uses the custom file.
+3. Skip flag: with an auto-discoverable pantry file present, run `cook shopping-list --ignore-pantry <recipe>` and verify no items are subtracted.
+4. Skip flag dominates: run `cook shopping-list --ignore-pantry --pantry /nonexistent/path <recipe>` and verify it succeeds with no subtraction (does not error on the bad path).
+
+## Out of Scope / Future Work
+
+- Documentation update in `docs/shopping-list.md` to mention the new flags.
+- Mirroring the web server's reporting of which items were filtered out (the web UI shows pantry-subtracted items separately; the CLI does not).
diff --git a/docs/superpowers/specs/2026-05-15-static-site-build-design.md b/docs/superpowers/specs/2026-05-15-static-site-build-design.md
new file mode 100644
index 0000000..ba80ad0
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-15-static-site-build-design.md
@@ -0,0 +1,177 @@
+# Static Site Build Command — Design
+
+## Summary
+
+A new top-level CLI command `cook build` that generates a self-contained static website from a Cooklang recipe collection. The output mirrors the existing web server UI (directory browsing, recipe pages, menus, search) but omits all dynamic, user-state features (shopping list, pantry, edit/new, preferences, sync, reload, scaling).
+
+The static site can be hosted on any static-file host (GitHub Pages, Netlify, S3, etc.) or browsed directly from disk via `file://`.
+
+## Goals
+
+- Render the recipe collection as static HTML browsable without a server.
+- Maximize reuse of the existing Askama templates and rendering code; do not duplicate the recipe rendering pipeline.
+- Self-contained output: the chosen output directory is uploadable as-is.
+- Works on `file://` and arbitrary host subpaths.
+
+## Non-goals (v1)
+
+- Recipe scaling in the static output. Quantities render as written.
+- Shopping list, pantry, edit, new, preferences, sync, reload.
+- Incremental / watch-mode builds.
+- Themes or template customization.
+- Pretty (extensionless) URLs.
+
+## CLI
+
+```
+cook build [OUTPUT_DIR]
+  [--base-path <DIR>]        # source recipes, defaults to current working dir / Context base_path
+  [--base-url <PREFIX>]      # absolute URL prefix (e.g. /recipes/) for subpath hosting
+```
+
+- `OUTPUT_DIR` defaults to `./_site`.
+- The output directory is created if missing. Existing contents are **not** wiped; the build writes files over existing ones. (User controls cleanup.)
+- Aliases: none in v1.
+
+## Output Layout
+
+```
+_site/
+  index.html                          # root recipe listing
+  directory/<path>.html               # one per non-empty subdirectory
+  recipe/<path>.html                  # one per .cook file
+  menu/<path>.html                    # one per menu
+  static/
+    css/output.css
+    js/search.js
+    search-index.json
+    (other embedded static assets)
+  api/static/<recipe-image-path>      # recipe images, mirrors source layout
+```
+
+`recipe/<path>.html` keeps the URL scheme close to the running server (`/recipe/...`), which means the existing `prefix`-based URL helpers in templates continue to work with a per-page relative prefix.
+
+## Architecture
+
+### New module: `src/build/`
+
+Mirrors the layout of `src/server/`:
+
+- `mod.rs` — `BuildArgs` (clap), `run(ctx, args) -> Result<()>`, top-level orchestrator.
+- `renderer.rs` — wraps existing Askama template structs (`RecipesTemplate`, `RecipeTemplate`, `MenuTemplate`, etc.) with `static_mode: true` and computed per-page `prefix`.
+- `writer.rs` — handles directory creation, file writes, copying embedded static assets, copying recipe images.
+- `index.rs` — walks the recipe tree to build `search-index.json`.
+- `links.rs` — computes per-page relative `prefix` strings; helper to map an output path to its `../`-walking root prefix.
+
+### Template changes
+
+Add `static_mode: bool` to every Askama template struct in `src/server/templates.rs`. Default remains `false`; the server continues to pass `false`, the build command passes `true`.
+
+In templates (`templates/*.html`):
+- Gate the following behind `{% if !static_mode %}`:
+  - Shopping-list nav link, add-to-shopping-list buttons, "in pantry" badges
+  - Edit / New / Delete controls
+  - Preferences nav link
+  - Sync UI (login/logout/status)
+  - Reload button
+  - Recipe scaling input
+- Search box stays visible. Its JS handler points to `static/search.js` (client-side filter over `search-index.json`) in static mode, or `/api/search` in server mode.
+- URL helpers that produce `/recipe/<path>` etc. honor `static_mode` by appending `.html`.
+
+### Link strategy
+
+Existing templates already generate URLs using a `prefix` value. The build renderer computes `prefix` per page so all internal links are relative and work on `file://` and any host subpath:
+
+- `_site/index.html` → `prefix = "."`
+- `_site/directory/Breakfast.html` → `prefix = ".."`
+- `_site/recipe/Breakfast/Pancakes.html` → `prefix = "../.."`
+
+When `--base-url` is provided, the build uses it as an absolute prefix instead of computing relative paths. This is useful for known subpath hosting (e.g. `/recipes/`).
+
+### Search
+
+Build-time generation of `static/search-index.json`. Each entry:
+
+```json
+{
+  "title": "Pancakes",
+  "path": "recipe/Breakfast/Pancakes.html",
+  "tags": ["breakfast", "quick"],
+  "ingredients": ["flour", "milk", "egg"]
+}
+```
+
+A small `static/js/search.js` (new, shipped alongside other embedded static assets) reads the JSON, filters as the user types, and renders results into the existing search dropdown markup. No external libraries.
+
+### Assets
+
+- Embedded static assets (CSS, JS, images under `static/`) are written verbatim to `_site/static/`. Uses the existing `RustEmbed` `StaticFiles` source.
+- Recipe images are discovered the same way the server does (matched by stem alongside `.cook` files). They are copied into `_site/api/static/<same-relative-path>` so the templates' existing image URL logic continues to resolve correctly when given the per-page `prefix`.
+
+## Data Flow (Build Pipeline)
+
+A single pass:
+
+1. **Resolve paths**: `source = args.base_path || ctx.base_path`, `output = args.output_dir || "./_site"`. Make `output` absolute. Create if missing. Bail if `source` is not a directory.
+2. **Build recipe tree**: `cooklang_find::build_tree(source)`.
+3. **Build search index** by walking the tree.
+4. **Render pages**:
+   - `index.html` from the root tree.
+   - One `directory/<path>.html` per non-empty subdirectory.
+   - One `recipe/<path>.html` per `.cook` file.
+   - One `menu/<path>.html` per menu file.
+5. **Copy assets**:
+   - Embedded `StaticFiles` → `_site/static/`.
+   - Discovered recipe images → `_site/api/static/<path>`.
+   - Write `search-index.json` and `search.js` to `_site/static/`.
+6. **Print summary**: counts of pages and assets written, output path.
+
+## Error Handling
+
+- Fatal (return `Err`, exit non-zero):
+  - Source directory does not exist or is a file.
+  - Output directory cannot be created or written to.
+  - Failure to write a critical static asset.
+- Non-fatal (log via `tracing::warn!`, skip, continue):
+  - A `.cook` file fails to parse.
+  - A menu fails to resolve.
+  - An image referenced by a recipe is missing.
+
+Matches the server's lenient philosophy: one bad recipe should not break the whole build.
+
+## Testing
+
+### Automated (`cargo test`)
+
+A smoke test that runs `cook build` against `./seed` recipes into a `tempfile::TempDir`:
+
+- Assert these files exist: `index.html`, at least one `recipe/*.html`, `static/css/output.css`, `static/js/search.js`, `static/search-index.json`.
+- Parse one recipe HTML and assert it contains the recipe title.
+- Assert no dynamic-mode strings appear (e.g., "Add to shopping list", "Edit recipe").
+- Parse `search-index.json` and assert it has entries with the expected schema.
+
+### Manual
+
+Documented as part of the command's help text or CLAUDE.md:
+
+```bash
+cook build ./seed _site
+python3 -m http.server -d _site 8000
+# browse http://localhost:8000
+
+# or directly via file://
+open _site/index.html
+```
+
+### Regression safety
+
+The existing Playwright suite covers the dynamic server. The `static_mode` flag defaults to `false`, so the server's behavior is unchanged.
+
+## Open Questions / Future Work
+
+- Theme/customization: deferred. v1 ships with the existing Tailwind look.
+- Watch / incremental builds: deferred. Users can rerun `cook build`.
+- Pretty URLs: deferred. `.html` extensions are universal.
+- Pre-rendered scaling variants: deferred. Scaling is dropped in v1 entirely.
+- Sitemap/RSS feed: deferred.
+- Adding a download link to source `.cook` file from each recipe page: deferred.
diff --git a/docs/superpowers/specs/2026-05-16-device-code-auth-design.md b/docs/superpowers/specs/2026-05-16-device-code-auth-design.md
new file mode 100644
index 0000000..c252dda
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-16-device-code-auth-design.md
@@ -0,0 +1,342 @@
+# Device-Code Authentication for CookCloud Sync — Design
+
+## Summary
+
+Replace CookCLI's current browser-popup login flow with the OAuth 2.0 Device Authorization Grant (RFC 8628). The new flow works in any environment — native desktop, Docker, SSH, behind a reverse proxy — because CookCLI never needs to open a browser on the host where it runs. The existing "Login to CookCloud" button in the web UI is fixed, and a new `cook login` / `cook logout` CLI command is added. CookCLI and `cook.md` share one device-code flow; the CookCLI web handler and CLI command share one Rust implementation.
+
+## Motivation
+
+[Issue #290](https://github.com/cooklang/cookcli/issues/290): users running CookCLI in Docker cannot sign in. The current flow fails twice over:
+
+1. The server calls `open::that(login_url)` — there is no browser inside the container, so the call errors with `No such file or directory`.
+2. Even with a browser, the OAuth callback URL is `http://localhost:RANDOM_PORT` bound to the *container's* loopback — unreachable from the host browser.
+
+`cook.md` further restricts callback URLs to `http://localhost` / `http://127.0.0.1` (`DesktopAuthCallback#safe_callback_url?`), so loosening port/host alone is not enough. A different flow is required.
+
+## Goals
+
+- "Login to CookCloud" works in Docker, SSH, native, and reverse-proxy deployments.
+- Headless CLI login via `cook login` for environments with no web UI at all.
+- Single shared mechanism between web UI and CLI; single shared Rust module.
+- Standards-based: OAuth 2.0 Device Authorization Grant (RFC 8628).
+- JWT issuance, session storage, refresh, and sync remain unchanged downstream.
+
+## Non-goals (v1)
+
+- Revoking active JWTs. They remain 100-day, stateless, as today.
+- Scoped tokens / per-app permissions. CookCLI continues to get full account access.
+- QR code rendering in the web UI. `verification_uri_complete` is returned, so a QR can be bolted on later trivially.
+- Registered-clients allow-list on `cook.md`. `client_name` is free-text, HTML-escaped, with a length cap.
+- File-watcher in `cook server` to pick up newly-written `session.json`. CLI login still requires a server restart, as today.
+
+## End-to-end Flow
+
+```
+┌──────────────┐                       ┌──────────────┐                 ┌────────────┐
+│ User browser │                       │   CookCLI    │                 │  cook.md   │
+│  (any device)│                       │  (server/CLI)│                 │            │
+└──────┬───────┘                       └──────┬───────┘                 └─────┬──────┘
+       │  click Login / run `cook login`      │                               │
+       │ ────────────────────────────────────▶│                               │
+       │                                      │  POST /oauth/device/code      │
+       │                                      │   {client_name}               │
+       │                                      │ ─────────────────────────────▶│
+       │                                      │  {device_code, user_code,     │
+       │                                      │   verification_uri,           │
+       │                                      │   verification_uri_complete,  │
+       │                                      │   expires_in:900, interval:5} │
+       │                                      │ ◀─────────────────────────────│
+       │  show user_code + verification_uri   │                               │
+       │ ◀────────────────────────────────────│                               │
+       │                                      │  POST /oauth/device/token     │
+       │                                      │   (loop every `interval`s)    │
+       │                                      │ ─────────────────────────────▶│
+       │                                      │  400 authorization_pending    │
+       │                                      │ ◀─────────────────────────────│
+       │  user opens verification_uri in any browser, signs in if needed,    │
+       │  enters user_code, sees "CookCLI on linux/docker — Approve?"        │
+       │  ──────────────────────────────────────────────────────────────────▶│
+       │                                      │  POST /oauth/device/token     │
+       │                                      │ ─────────────────────────────▶│
+       │                                      │  200 {token: <JWT>}           │
+       │                                      │ ◀─────────────────────────────│
+       │                                      │  save session.json,           │
+       │                                      │  start sync                   │
+```
+
+---
+
+## cook.md (Rails)
+
+### Storage
+
+Redis, matching the existing `SessionCode` pattern. Two keys per flow, both TTL 15 min:
+
+- `device_code:{sha256(device_code)}` → JSON `{user_code, client_name, status, user_id?, last_polled_at}`
+- `user_code:{user_code}` → `{device_code_hash}`  *(reverse lookup; deleted on approve/deny so user codes are single-use)*
+
+State values: `pending`, `approved`, `denied`. Expiry is implicit via Redis TTL (no `expired` state needed).
+
+### Codes
+
+- **`user_code`**: 8 characters, format `XXXX-XXXX`, alphabet `23456789ABCDEFGHJKLMNPQRSTUVWXYZ` (excludes `0/O/1/I/L`). ≈10¹² combinations.
+- **`device_code`**: 32 random bytes, base64url-encoded. Hashed with SHA-256 before storage; plain returned to client once.
+
+### Endpoints
+
+| Route | Auth | Purpose |
+|---|---|---|
+| `POST /oauth/device/code` | none | Issue a `device_code` + `user_code`. Body: `{client_name}` (optional). Rate-limit 10/min/IP. |
+| `POST /oauth/device/token` | none | Poll. Body: `{device_code, grant_type:"urn:ietf:params:oauth:grant-type:device_code"}`. Returns `200 {token}` or `400 {error}` per RFC 8628. |
+| `GET /device` | required (redirects to existing `/auth/desktop/code` sign-in, return URL preserved) | Form to enter `user_code`. Pre-fills from `?user_code=` query param. |
+| `POST /device/approve` | required | Marks the matched device code approved; sets `user_id` to current user. |
+| `POST /device/deny` | required | Marks denied. |
+
+### Token endpoint responses (RFC 8628 contract)
+
+- `200 {"token": "<JWT>", "token_type": "Bearer"}` — approved. Redis entry deleted after this response, so subsequent polls fail with `expired_token`.
+- `400 {"error": "authorization_pending"}` — still waiting.
+- `400 {"error": "slow_down"}` — polled faster than `interval`; client must bump interval by 5s.
+- `400 {"error": "access_denied"}` — user denied.
+- `400 {"error": "expired_token"}` — Redis key absent (TTL elapsed or unknown device_code).
+- `400 {"error": "invalid_grant"}` — wrong `grant_type`.
+
+### `/device` page UX
+
+1. Open `https://cook.md/device`. If not signed in → existing `/auth/desktop/code` email-code flow runs, then returns to `/device` with the original `?user_code=` preserved.
+2. Form: single input. Auto-uppercases, accepts both `WDJBMJHT` and `WDJB-MJHT`. Hyphen stripped before lookup.
+3. After submit: page renders `"CookCLI 0.30 (linux/docker) wants to access your CookCloud account as alice@example.com"` with **Approve** / **Deny** buttons (CSRF-protected `POST`).
+4. After Approve: "All done — return to CookCLI" page. After Deny: "Authorization denied" page.
+
+`client_name` is free-text from the client, HTML-escaped, max 80 chars. We accept the small phishing risk this entails (an attacker-supplied `"GitHub login"` string) because the surrounding page makes it clear *this is CookCloud authorizing CookCLI*. Mitigation via a registered-clients allow-list is deferred.
+
+### JWT minting
+
+Unchanged. On approve, the controller calls the existing `Token.encode(uid: user.id, email: user.email)`. 100-day expiry, same JWT secret, same shape. Existing token-refresh code (`/api/sessions/renew`) keeps working as-is.
+
+### Rate limiting
+
+Using whatever rack-attack-style middleware the repo conventionally uses:
+
+- `POST /oauth/device/code`: 10/min/IP.
+- `POST /oauth/device/token`: per-`device_code` `slow_down` enforcement (compares now vs `last_polled_at`), plus a global 60/min/IP hard cap.
+- `POST /device` (user code submission): 10 per 15 min per session.
+
+Failed user-code lookups return the same response as expired codes ("Code expired or invalid") so the form does not leak enumeration signal.
+
+### Files added (cook.md)
+
+- `app/controllers/oauth/device_controller.rb` — `/oauth/device/code`, `/oauth/device/token`
+- `app/controllers/device_controller.rb` — `GET /device`, `POST /device/approve`, `POST /device/deny`
+- `app/views/devices/show.html.erb`, `approve.html.erb`, `success.html.erb`, `denied.html.erb`, `expired.html.erb`
+- `lib/device_flow.rb` — `DeviceFlow.create!`, `.find_by_user_code`, `.poll`, `.approve!`, `.deny!` (Redis I/O, encoding/decoding, state transitions)
+- `spec/requests/oauth/device_spec.rb`, `spec/requests/device_spec.rb`
+- `config/routes.rb` — five new routes
+
+No new DB migration. No new Warden strategy (existing email-code sign-in is reused for the `/device` page).
+
+---
+
+## CookCLI (Rust)
+
+### New shared module: `src/server/sync/device_flow.rs`
+
+Used by both the HTTP handler (`POST /api/sync/login`) and the new `cook login` CLI command.
+
+```rust
+pub struct DeviceCodeResponse {
+    pub device_code: String,               // server-side only
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in: u64,
+    pub interval: u64,
+}
+
+pub async fn request_device_code(client_name: &str) -> Result<DeviceCodeResponse>;
+
+/// Polls /oauth/device/token at `interval`, respects `slow_down`, surfaces
+/// denial/expiry. Returns the JWT on success.
+pub async fn poll_for_token(
+    device_code: &str,
+    interval: Duration,
+    expires_at: Instant,
+    cancel: CancellationToken,
+) -> Result<String, DeviceFlowError>;
+
+pub enum DeviceFlowError {
+    AccessDenied,
+    Expired,
+    Cancelled,
+    Network(reqwest::Error),
+    BadResponse(String),
+}
+```
+
+`client_name` is built as `format!("CookCLI {} ({}/{})", VERSION, OS, host_label)` where `host_label` is `"docker"` if `/.dockerenv` exists, `"cli"` for the CLI command, else the machine hostname. Best-effort; harmless if wrong.
+
+### HTTP handler changes (`src/server/handlers/sync.rs`)
+
+```
+POST /api/sync/login
+   1. Reject if already logged in or if a flow is already in progress.
+   2. Call request_device_code(client_name).
+   3. Store {device_code, expires_at, user_code, verification_uri,
+            verification_uri_complete} in AppState::pending_device_flow
+      (Mutex<Option<DeviceFlowState>>).
+   4. Spawn a background tokio task that calls poll_for_token. On success →
+      save session.json, start sync.
+   5. Return {user_code, verification_uri, verification_uri_complete,
+            expires_in} to the browser.
+
+GET /api/sync/status
+   Existing body PLUS, when a flow is pending:
+     {pending_login: {user_code, verification_uri,
+                      verification_uri_complete, expires_at}}.
+   This lets the preferences page survive a reload mid-flow.
+
+POST /api/sync/cancel_login   (new)
+   Aborts the in-flight device flow via CancellationToken, clears state.
+```
+
+### Web UI (`templates/preferences.html`)
+
+The Login button now opens an in-page card. No browser is spawned by the server.
+
+```
+┌──────────────────────────────────────────────┐
+│  Sign in to CookCloud                        │
+│                                              │
+│  1. Open  https://cook.md/device  ↗          │
+│  2. Enter this code:                         │
+│                                              │
+│         ┌──────────────────────┐             │
+│         │     WDJB - MJHT      │  [Copy]     │
+│         └──────────────────────┘             │
+│                                              │
+│  Expires in 14:58                            │
+│                                              │
+│  [Open cook.md/device]   [Cancel]            │
+└──────────────────────────────────────────────┘
+```
+
+- "Open cook.md/device" is a plain `<a target="_blank" href="{verification_uri_complete}">` — the user's own browser handles it.
+- "Copy" button: `navigator.clipboard.writeText(user_code)`.
+- JS polls `/api/sync/status` every 2s (same cadence as today). On `logged_in: true` → page reload. On code expiry → "Code expired — try again" + re-enable button.
+
+`verification_uri_complete` includes `user_code` in the URL for click-through convenience. RFC 8628 explicitly supports this. The URL is only ever shown to the signed-in user inside their own browser, so the phishing-resistance trade-off is acceptable.
+
+### CLI: `cook login`
+
+New `src/login.rs`. Reuses the same `device_flow` module.
+
+```
+$ cook login
+First open https://cook.md/device in any browser and enter this code:
+
+    WDJB-MJHT
+
+(Press Enter to open it automatically in your default browser, or Ctrl-C to abort.)
+
+Waiting for authorization... ⠋
+✓ Logged in as alice@example.com
+```
+
+Behaviour:
+
+1. `client_name = "CookCLI <ver> (<os>/cli)"`.
+2. On Enter, calls `open::that(verification_uri_complete)`. If that fails (Docker exec, SSH), prints "Couldn't open browser automatically — please visit the URL above manually" and keeps waiting. **Browser-open failure is no longer fatal**, unlike today.
+3. Spinner while polling; respects `interval` and `slow_down`.
+4. On success: writes `~/.config/cook/session.json` exactly like the web flow.
+5. On expiry / denial / Ctrl-C: clear error message, non-zero exit code, no half-written session file.
+
+### CLI: `cook logout`
+
+New `src/logout.rs`.
+
+- Deletes `~/.config/cook/session.json`.
+- No network call. JWT revocation is out of scope (cook.md JWTs are stateless; adding revocation would require new infrastructure).
+- If no session exists: prints `"Not logged in."`, exits 0.
+
+### Interaction with a running `cook server`
+
+If `cook serve` is running while `cook login` writes a new `session.json`, the server does not pick it up until restart — same as today's behaviour. `cook login --help` notes this. A file-watcher in the server is a future improvement.
+
+### Files changed (CookCLI)
+
+**Added:**
+
+- `src/server/sync/device_flow.rs`
+- `src/login.rs`
+- `src/logout.rs`
+
+**Modified:**
+
+- `src/server/handlers/sync.rs` — replace `browser_login_flow` & helpers; extend `LoginResponse`; add `cancel_login`.
+- `src/server/mod.rs` (or wherever `AppState` lives) — add `pending_device_flow: Mutex<Option<DeviceFlowState>>`. Remove `login_in_progress: AtomicBool`.
+- `src/args.rs`, `src/main.rs` — wire `Login(LoginArgs)` and `Logout(LogoutArgs)` Command variants.
+- `templates/preferences.html` — replace login-button JS with the device-code card.
+
+**Deleted:**
+
+- In `src/server/handlers/sync.rs`: `browser_login_flow`, `wait_for_callback`, `handle_get_callback`, `extract_token`, `cors_origin`.
+
+**Cargo.toml:**
+
+- `open = "5.3"` stays (CLI `cook login` uses it; `cook server --open` already does too).
+- `uuid` usage in `sync.rs` goes away (was only for CSRF state), but the crate likely stays for other reasons — verify before removing.
+
+---
+
+## Security
+
+| Risk | Mitigation |
+|---|---|
+| **User-code brute force** | 8 chars × 32-char alphabet ≈ 10¹² combos; rate limit `POST /device` to 10/15 min/session. Failed lookups indistinguishable from expired codes. |
+| **Device-code leakage** | Hashed (SHA-256) in Redis. Plain value only on the wire (TLS) and in CookCLI process memory. Never logged. |
+| **Replay** | Device code deleted from Redis after first successful `/token` returns the JWT; reverse user_code index deleted on approve/deny. |
+| **Phishing via `client_name`** | HTML-escaped, capped at 80 chars. Surrounding page makes ownership clear ("CookCloud → CookCLI"). 15-min TTL bounds the window. |
+| **CSRF on approve/deny** | Standard Rails authenticity tokens on `POST /device/approve` and `/device/deny`. |
+| **Polling abuse** | `slow_down` per `device_code` (bumps interval by 5s); 60/min/IP hard cap on `/oauth/device/token`. |
+| **Session file on disk** | Existing `0o600` permissions in `SyncSession::save()` — unchanged. |
+| **Token in logs** | No `tracing::*` call takes `device_code` or JWT as a field. Code review item. |
+| **TLS** | Production uses `https://cook.md`; `COOK_ENDPOINT` env override allows http for dev. Document the risk of plaintext in non-dev. |
+| **Cross-process collision** | CookCLI server uses `Mutex<Option<DeviceFlowState>>` to allow one in-flight flow; CLI is a separate process with its own state — each gets an independent `device_code`. |
+
+---
+
+## Testing
+
+**cook.md (RSpec, real Redis in CI):**
+
+- `Oauth::DeviceController#code`: issues unique codes; IP rate limit enforced.
+- `Oauth::DeviceController#token`: full state machine — pending → approved → token issued and Redis key deleted; pending → denied → `access_denied`; expired/unknown → `expired_token`; rapid poll → `slow_down`; wrong `grant_type` → `invalid_grant`.
+- `DeviceController`: unauthenticated GET redirects to sign-in with `user_code` preserved; case-insensitive and hyphen-tolerant user_code lookup; approve/deny update Redis correctly; one-shot enforcement of user_code.
+
+**CookCLI:** the repo has no Rust test harness today (per `CONTRIBUTING.md`). This design does not introduce one. Instead, the implementation plan will include a manual test matrix:
+
+- Web UI on native macOS / Linux / Docker / behind a reverse proxy.
+- `cook login` on macOS / Linux / SSH session / `docker exec`.
+- Cancellation paths: Ctrl-C, "Cancel" button, browser tab closed mid-flow.
+- Expired-code path (let the 15 min run out).
+- Denial path.
+- Already-logged-in idempotency.
+
+---
+
+## Rollout
+
+1. Ship cook.md changes. Endpoints go live as soon as the deploy lands.
+2. Verify with a local CookCLI build pointed at staging via `COOK_ENDPOINT`.
+3. Ship CookCLI release. Older CookCLI binaries continue working against the legacy `/auth/desktops?callback=...` flow.
+4. After a deprecation window long enough for the fleet to update (target: ~6 months, tied to release cadence), remove the legacy `/auth/desktops` callback redirect on cook.md. The `Auth::DesktopsController` file goes away; `DesktopAuthCallback` concern can be deleted.
+
+## Open questions
+
+None at design time. All items raised during brainstorming were resolved:
+
+- `client_name` is free text (no registered-clients list in v1).
+- Device codes are single-use (consumed by the first successful `/token` poll).
+- `verification_uri_complete` is included and the web UI links to it.
+- The `open` crate stays in CookCLI for `cook login` (graceful-failure) and `cook server --open`.
+- No feature flag on the cook.md side — the new endpoints ship live.
diff --git a/src/args.rs b/src/args.rs
index bdf3f21..d34e429 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -233,6 +233,29 @@ pub enum Command {
     )]
     Lsp(lsp::LspArgs),
 
+    /// Sign in to CookCloud
+    ///
+    /// Initiates the OAuth 2.0 Device Authorization Grant flow:
+    /// displays a code, opens your browser to the verification page,
+    /// and polls until you approve the request.
+    ///
+    /// Examples:
+    ///   cook login                      # Start the device-code login flow
+    #[cfg(feature = "sync")]
+    #[command(long_about = "Sign in to CookCloud via the OAuth 2.0 device-code flow")]
+    Login(crate::login::LoginArgs),
+
+    /// Sign out of CookCloud
+    ///
+    /// Removes the stored session file. The `cook server` instance, if running,
+    /// will pick up the change on its next status check or restart.
+    ///
+    /// Examples:
+    ///   cook logout
+    #[cfg(feature = "sync")]
+    #[command(long_about = "Sign out of CookCloud and delete the local session file")]
+    Logout(crate::logout::LogoutArgs),
+
     /// Update CookCLI to the latest version
     ///
     /// Checks for new releases on GitHub and automatically downloads and
diff --git a/src/lib.rs b/src/lib.rs
index c13d423..234f99a 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -6,6 +6,10 @@ use camino::{Utf8Path, Utf8PathBuf};
 pub mod build;
 pub mod doctor;
 pub mod import;
+#[cfg(feature = "sync")]
+pub mod login;
+#[cfg(feature = "sync")]
+pub mod logout;
 pub mod lsp;
 pub mod pantry;
 pub mod recipe;
diff --git a/src/login.rs b/src/login.rs
new file mode 100644
index 0000000..3625852
--- /dev/null
+++ b/src/login.rs
@@ -0,0 +1,137 @@
+use std::time::{Duration, Instant};
+
+use anyhow::Result;
+use clap::Args;
+use tokio_util::sync::CancellationToken;
+
+use crate::server::sync::{device_flow, SyncSession};
+use crate::Context;
+
+#[derive(Debug, Args)]
+pub struct LoginArgs {}
+
+pub fn run(_ctx: &Context, _args: LoginArgs) -> Result<()> {
+    let runtime = tokio::runtime::Runtime::new()?;
+    runtime.block_on(run_async())
+}
+
+async fn run_async() -> Result<()> {
+    use std::io::{BufRead, Write};
+
+    let session_path = crate::global_file_path("session.json")
+        .map(std::path::PathBuf::from)
+        .unwrap_or_else(|_| std::path::PathBuf::from(".cook-session.json"));
+
+    if SyncSession::load(&session_path).ok().flatten().is_some() {
+        println!("Already logged in. Run `cook logout` first if you want to switch accounts.");
+        return Ok(());
+    }
+
+    let client = reqwest::Client::new();
+    let name = device_flow::client_name("cli");
+    let dc = device_flow::request_device_code(&client, &name).await?;
+
+    println!();
+    println!(
+        "First open {} in any browser and enter this code:",
+        dc.verification_uri
+    );
+    println!();
+    println!("    {}", dc.user_code);
+    println!();
+    println!("(Press Enter to open it automatically, or Ctrl-C to abort.)");
+
+    let cancel = CancellationToken::new();
+    let cancel_for_signal = cancel.clone();
+    tokio::spawn(async move {
+        let _ = tokio::signal::ctrl_c().await;
+        cancel_for_signal.cancel();
+    });
+
+    let stdin_task = tokio::task::spawn_blocking(|| {
+        let stdin = std::io::stdin();
+        let _ = stdin.lock().lines().next();
+    });
+
+    tokio::select! {
+        _ = stdin_task => {}
+        _ = cancel.cancelled() => {
+            println!();
+            anyhow::bail!("Cancelled.");
+        }
+    }
+
+    if let Err(e) = open::that(&dc.verification_uri_complete) {
+        eprintln!("Couldn't open browser automatically: {e}");
+        eprintln!("Please visit the URL above manually.");
+    }
+
+    print!("Waiting for authorization");
+    std::io::stdout().flush().ok();
+
+    let expires_at = Instant::now() + Duration::from_secs(dc.expires_in);
+    let interval = Duration::from_secs(dc.interval);
+
+    let dot_handle = {
+        let cancel = cancel.clone();
+        tokio::spawn(async move {
+            loop {
+                tokio::select! {
+                    _ = cancel.cancelled() => return,
+                    _ = tokio::time::sleep(Duration::from_secs(1)) => {
+                        print!(".");
+                        let _ = std::io::stdout().flush();
+                    }
+                }
+            }
+        })
+    };
+
+    let jwt = match device_flow::poll_for_token(
+        &client,
+        &dc.device_code,
+        interval,
+        expires_at,
+        cancel.clone(),
+    )
+    .await
+    {
+        Ok(jwt) => jwt,
+        Err(device_flow::DeviceFlowError::AccessDenied) => {
+            cancel.cancel();
+            dot_handle.abort();
+            anyhow::bail!("Authorization denied.");
+        }
+        Err(device_flow::DeviceFlowError::Expired) => {
+            cancel.cancel();
+            dot_handle.abort();
+            anyhow::bail!("Code expired - try `cook login` again.");
+        }
+        Err(device_flow::DeviceFlowError::Cancelled) => {
+            dot_handle.abort();
+            anyhow::bail!("Cancelled.");
+        }
+        Err(e) => {
+            cancel.cancel();
+            dot_handle.abort();
+            anyhow::bail!("Login failed: {e}");
+        }
+    };
+
+    cancel.cancel();
+    dot_handle.abort();
+    println!();
+
+    let session = SyncSession::from_jwt(jwt)?;
+    session.save(&session_path)?;
+
+    let email = session
+        .email
+        .clone()
+        .unwrap_or_else(|| "<unknown>".to_string());
+    println!("Logged in as {email}");
+    println!();
+    println!("Note: if `cook server` is running, restart it to pick up the new session.");
+
+    Ok(())
+}
diff --git a/src/logout.rs b/src/logout.rs
new file mode 100644
index 0000000..ee11ffb
--- /dev/null
+++ b/src/logout.rs
@@ -0,0 +1,25 @@
+use anyhow::Result;
+use clap::Args;
+
+use crate::server::sync::SyncSession;
+use crate::Context;
+
+#[derive(Debug, Args)]
+pub struct LogoutArgs {}
+
+pub fn run(_ctx: &Context, _args: LogoutArgs) -> Result<()> {
+    let session_path = crate::global_file_path("session.json")
+        .map(std::path::PathBuf::from)
+        .unwrap_or_else(|_| std::path::PathBuf::from(".cook-session.json"));
+
+    match SyncSession::load(&session_path) {
+        Ok(Some(_)) => {
+            SyncSession::delete(&session_path)?;
+            println!("Logged out.");
+        }
+        _ => {
+            println!("Not logged in.");
+        }
+    }
+    Ok(())
+}
diff --git a/src/main.rs b/src/main.rs
index b10b724..7b837b5 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -38,6 +38,10 @@ use clap::Parser;
 mod build;
 mod doctor;
 mod import;
+#[cfg(feature = "sync")]
+mod login;
+#[cfg(feature = "sync")]
+mod logout;
 mod lsp;
 mod pantry;
 mod recipe;
@@ -77,6 +81,10 @@ pub fn main() -> Result<()> {
         Command::Doctor(args) => doctor::run(&ctx, args),
         Command::Pantry(args) => pantry::run(&ctx, args),
         Command::Lsp(args) => lsp::run(&ctx, args),
+        #[cfg(feature = "sync")]
+        Command::Login(args) => login::run(&ctx, args),
+        #[cfg(feature = "sync")]
+        Command::Logout(args) => logout::run(&ctx, args),
         #[cfg(feature = "self-update")]
         Command::Update(args) => update::run(args),
     }
diff --git a/src/server/handlers/mod.rs b/src/server/handlers/mod.rs
index f328b17..dc48d71 100644
--- a/src/server/handlers/mod.rs
+++ b/src/server/handlers/mod.rs
@@ -22,4 +22,4 @@ pub use shopping_list::{
 pub use shopping_list_events::shopping_list_events;
 pub use stats::stats;
 #[cfg(feature = "sync")]
-pub use sync::{sync_login, sync_logout, sync_status};
+pub use sync::{sync_cancel_login, sync_login, sync_logout, sync_status};
diff --git a/src/server/handlers/sync.rs b/src/server/handlers/sync.rs
index e62cd3c..eca5b8d 100644
--- a/src/server/handlers/sync.rs
+++ b/src/server/handlers/sync.rs
@@ -1,12 +1,17 @@
-use crate::server::sync::{self, SyncSession};
+use crate::server::sync::{self, device_flow, PendingDeviceFlow, SyncSession};
 use crate::server::AppState;
 use axum::{extract::State, http::StatusCode, Json};
 use serde::Serialize;
 use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio_util::sync::CancellationToken;
 
-/// CORS origin for the OAuth callback server.
-fn cors_origin() -> String {
-    sync::endpoints::base_url()
+#[derive(Serialize)]
+pub struct PendingLogin {
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in_secs: u64,
 }
 
 #[derive(Serialize)]
@@ -14,28 +19,44 @@ pub struct SyncStatusResponse {
     pub logged_in: bool,
     pub email: Option<String>,
     pub syncing: bool,
+    pub pending_login: Option<PendingLogin>,
 }
 
 pub async fn sync_status(State(state): State<Arc<AppState>>) -> Json<SyncStatusResponse> {
     let (logged_in, email, syncing) = state.sync_status().await;
+
+    let pending_login = {
+        let guard = state.pending_device_flow.lock().await;
+        guard.as_ref().map(|p| PendingLogin {
+            user_code: p.user_code.clone(),
+            verification_uri: p.verification_uri.clone(),
+            verification_uri_complete: p.verification_uri_complete.clone(),
+            expires_in_secs: p
+                .expires_at
+                .saturating_duration_since(Instant::now())
+                .as_secs(),
+        })
+    };
+
     Json(SyncStatusResponse {
         logged_in,
         email,
         syncing,
+        pending_login,
     })
 }
 
 #[derive(Serialize)]
 pub struct LoginResponse {
-    pub login_url: String,
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in_secs: u64,
 }
 
 pub async fn sync_login(
     State(state): State<Arc<AppState>>,
 ) -> Result<Json<LoginResponse>, (StatusCode, Json<serde_json::Value>)> {
-    use std::sync::atomic::Ordering;
-
-    // Already logged in?
     if state.sync_session.lock().unwrap().is_some() {
         return Err((
             StatusCode::BAD_REQUEST,
@@ -43,240 +64,108 @@ pub async fn sync_login(
         ));
     }
 
-    // Prevent concurrent login attempts
-    if state
-        .login_in_progress
-        .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
-        .is_err()
-    {
+    let mut pending_guard = state.pending_device_flow.lock().await;
+    if pending_guard.is_some() {
         return Err((
             StatusCode::CONFLICT,
             Json(serde_json::json!({ "error": "Login already in progress" })),
         ));
     }
 
-    let state_clone = state.clone();
+    let client = reqwest::Client::new();
+    let name = device_flow::client_name(device_flow::server_host_label());
+    let dc = device_flow::request_device_code(&client, &name)
+        .await
+        .map_err(|e| {
+            (
+                StatusCode::BAD_GATEWAY,
+                Json(serde_json::json!({ "error": format!("cook.md unreachable: {e}") })),
+            )
+        })?;
+
+    let cancel = CancellationToken::new();
+    let expires_at = Instant::now() + Duration::from_secs(dc.expires_in);
+    let interval = Duration::from_secs(dc.interval);
+
+    *pending_guard = Some(PendingDeviceFlow {
+        user_code: dc.user_code.clone(),
+        verification_uri: dc.verification_uri.clone(),
+        verification_uri_complete: dc.verification_uri_complete.clone(),
+        expires_at,
+        cancel: cancel.clone(),
+    });
+    drop(pending_guard);
 
-    // Spawn login flow in background (it blocks waiting for callback)
+    let state_clone = state.clone();
+    let device_code = dc.device_code.clone();
     tokio::spawn(async move {
-        match browser_login_flow(&state_clone).await {
-            Ok(()) => tracing::info!("Login completed successfully"),
+        let result =
+            device_flow::poll_for_token(&client, &device_code, interval, expires_at, cancel).await;
+
+        *state_clone.pending_device_flow.lock().await = None;
+
+        match result {
+            Ok(jwt) => match SyncSession::from_jwt(jwt) {
+                Ok(session) => {
+                    if let Err(e) = session.save(&state_clone.session_path) {
+                        tracing::error!("Failed to save session: {e}");
+                        return;
+                    }
+                    *state_clone.sync_session.lock().unwrap() = Some(session.clone());
+
+                    match sync::sync_db_path() {
+                        Ok(db_path) => match sync::start_sync(
+                            &session,
+                            state_clone.base_path.to_string(),
+                            db_path,
+                        ) {
+                            Ok(handle) => {
+                                *state_clone.sync_handle.lock().await = Some(handle);
+                                tracing::info!("Sync started after login");
+                            }
+                            Err(e) => tracing::warn!("Failed to start sync after login: {e}"),
+                        },
+                        Err(e) => tracing::error!("Failed to resolve sync db path: {e}"),
+                    }
+                }
+                Err(e) => tracing::error!("Failed to build SyncSession from JWT: {e}"),
+            },
+            Err(device_flow::DeviceFlowError::Cancelled) => {
+                tracing::info!("Login cancelled by user");
+            }
             Err(e) => tracing::error!("Login failed: {e}"),
         }
-        state_clone.login_in_progress.store(false, Ordering::SeqCst);
     });
 
-    // Return the base URL so the frontend knows login was initiated
-    let base_url = sync::endpoints::base_url();
     Ok(Json(LoginResponse {
-        login_url: format!("{base_url}/auth/desktops"),
+        user_code: dc.user_code,
+        verification_uri: dc.verification_uri,
+        verification_uri_complete: dc.verification_uri_complete,
+        expires_in_secs: dc.expires_in,
     }))
 }
 
-async fn browser_login_flow(state: &Arc<AppState>) -> anyhow::Result<()> {
-    use tokio::net::TcpListener;
-
-    // Bind to random port
-    let listener = TcpListener::bind("127.0.0.1:0").await?;
-    let port = listener.local_addr()?.port();
-
-    // CSRF state
-    let csrf_state = uuid::Uuid::new_v4().to_string();
-
-    // Build login URL
-    let callback_url = format!("http://localhost:{port}/auth/callback");
-    let encoded_callback = urlencoding::encode(&callback_url);
-    let base_url = sync::endpoints::base_url();
-    let login_url =
-        format!("{base_url}/auth/desktops?callback={encoded_callback}&state={csrf_state}");
-
-    tracing::info!("Opening browser for CookCloud login");
-    if let Err(e) = open::that(&login_url) {
-        tracing::error!("Failed to open browser: {e}");
-        return Err(e.into());
-    }
-
-    // Wait for callback (5 min timeout)
-    let result = tokio::time::timeout(
-        std::time::Duration::from_secs(300),
-        wait_for_callback(&listener, &csrf_state),
-    )
-    .await;
-
-    let jwt = match result {
-        Ok(Ok(token)) => token,
-        Ok(Err(e)) => return Err(e),
-        Err(_) => anyhow::bail!("Login timed out after 5 minutes"),
-    };
-
-    // Create and save session
-    let session = SyncSession::from_jwt(jwt)?;
-    session.save(&state.session_path)?;
-
-    // Update state
-    *state.sync_session.lock().unwrap() = Some(session.clone());
-
-    // Start sync
-    let db_path = sync::sync_db_path()?;
-
-    match sync::start_sync(&session, state.base_path.to_string(), db_path) {
-        Ok(handle) => {
-            *state.sync_handle.lock().await = Some(handle);
-            tracing::info!("Sync started after login");
-        }
-        Err(e) => tracing::warn!("Failed to start sync after login: {e}"),
-    }
-
-    Ok(())
-}
-
-async fn wait_for_callback(
-    listener: &tokio::net::TcpListener,
-    expected_state: &str,
-) -> anyhow::Result<String> {
-    use tokio::io::{AsyncReadExt, AsyncWriteExt};
-
-    let (mut socket, _) = listener.accept().await?;
-    let mut buffer = [0u8; 4096];
-    let n = socket.read(&mut buffer).await?;
-    let request = String::from_utf8_lossy(&buffer[..n]);
-
-    // Handle CORS preflight
-    if request.starts_with("OPTIONS ") {
-        let origin = cors_origin();
-        let cors_response = format!(
-            "HTTP/1.1 200 OK\r\n\
-            Access-Control-Allow-Origin: {origin}\r\n\
-            Access-Control-Allow-Methods: GET, OPTIONS\r\n\
-            Access-Control-Allow-Headers: x-csrf-token, x-turbo-request-id\r\n\
-            Access-Control-Max-Age: 86400\r\n\
-            Content-Length: 0\r\n\r\n"
-        );
-        socket.write_all(cors_response.as_bytes()).await?;
-
-        // Try same connection, then new connection
-        let mut buffer = [0u8; 4096];
-        match tokio::time::timeout(std::time::Duration::from_secs(5), socket.read(&mut buffer))
-            .await
-        {
-            Ok(Ok(n)) if n > 0 => {
-                let req = String::from_utf8_lossy(&buffer[..n]).to_string();
-                handle_get_callback(&mut socket, &req, expected_state).await
-            }
-            _ => {
-                // Use a 30s timeout so the user gets feedback sooner than the outer 5-min deadline
-                let (mut new_socket, _) =
-                    tokio::time::timeout(std::time::Duration::from_secs(30), listener.accept())
-                        .await
-                        .map_err(|_| {
-                            anyhow::anyhow!(
-                                "Timed out waiting for login callback. Please try again."
-                            )
-                        })??;
-                let mut buffer = [0u8; 4096];
-                let n = new_socket.read(&mut buffer).await?;
-                let req = String::from_utf8_lossy(&buffer[..n]).to_string();
-                handle_get_callback(&mut new_socket, &req, expected_state).await
-            }
-        }
+pub async fn sync_cancel_login(State(state): State<Arc<AppState>>) -> Json<serde_json::Value> {
+    let mut guard = state.pending_device_flow.lock().await;
+    if let Some(p) = guard.take() {
+        p.cancel.cancel();
+        Json(serde_json::json!({ "cancelled": true }))
     } else {
-        // Regular GET
-        handle_get_callback(&mut socket, &request, expected_state).await
-    }
-}
-
-async fn handle_get_callback(
-    socket: &mut tokio::net::TcpStream,
-    request: &str,
-    expected_state: &str,
-) -> anyhow::Result<String> {
-    use tokio::io::AsyncWriteExt;
-
-    let origin = cors_origin();
-    if let Some(token) = extract_token(request, expected_state) {
-        let response = format!(
-            "HTTP/1.1 200 OK\r\n\
-            Content-Type: text/html; charset=utf-8\r\n\
-            Access-Control-Allow-Origin: {origin}\r\n\r\n\
-            <!DOCTYPE html><html><head><title>Login Complete</title>\
-            <style>\
-            body{{font-family:system-ui;display:flex;align-items:center;\
-            justify-content:center;min-height:100vh;margin:0;background:#f5f5f5}}\
-            .c{{text-align:center;background:white;padding:2rem 3rem;\
-            border-radius:8px;box-shadow:0 2px 10px rgba(0,0,0,.1)}}\
-            .ok{{width:64px;height:64px;margin:0 auto 1rem;background:#4CAF50;\
-            border-radius:50%;display:flex;align-items:center;\
-            justify-content:center;font-size:32px;color:white}}\
-            </style></head><body><div class=\"c\"><div class=\"ok\">&#10003;</div>\
-            <h1>All Done!</h1>\
-            <p>You can close this tab and return to CookCLI.</p></div>\
-            <script>setTimeout(()=>{{if(window.opener)window.close()}},2000)</script>\
-            </body></html>"
-        );
-        socket.write_all(response.as_bytes()).await?;
-        Ok(token)
-    } else {
-        let response = format!(
-            "HTTP/1.1 400 Bad Request\r\n\
-            Content-Type: text/html; charset=utf-8\r\n\
-            Access-Control-Allow-Origin: {origin}\r\n\r\n\
-            <!DOCTYPE html><html><head><title>Login Failed</title>\
-            <style>\
-            body{{font-family:system-ui;display:flex;align-items:center;\
-            justify-content:center;min-height:100vh;margin:0;background:#f5f5f5}}\
-            .c{{text-align:center;background:white;padding:2rem 3rem;\
-            border-radius:8px;box-shadow:0 2px 10px rgba(0,0,0,.1)}}\
-            .err{{width:64px;height:64px;margin:0 auto 1rem;background:#f44336;\
-            border-radius:50%;display:flex;align-items:center;\
-            justify-content:center;font-size:32px;color:white}}\
-            </style></head><body><div class=\"c\"><div class=\"err\">&#10005;</div>\
-            <h1>Login Failed</h1>\
-            <p>Please close this tab and try again.</p></div>\
-            </body></html>"
-        );
-        socket.write_all(response.as_bytes()).await?;
-        anyhow::bail!("Failed to extract token from callback")
-    }
-}
-
-fn extract_token(request: &str, expected_state: &str) -> Option<String> {
-    let first_line = request.lines().next()?;
-    if !first_line.starts_with("GET ") {
-        return None;
-    }
-    let path = first_line.split(' ').nth(1)?;
-
-    // Use url crate for robust query string parsing (handles %26-encoded values, etc.)
-    let full_url = format!("http://localhost{path}");
-    let parsed = url::Url::parse(&full_url).ok()?;
-
-    let mut token = None;
-    let mut state = None;
-
-    for (key, value) in parsed.query_pairs() {
-        match key.as_ref() {
-            "token" => token = Some(value.into_owned()),
-            "state" => state = Some(value.into_owned()),
-            _ => {}
-        }
-    }
-
-    if state.as_deref() == Some(expected_state) {
-        token
-    } else {
-        None
+        Json(serde_json::json!({ "cancelled": false }))
     }
 }
 
 pub async fn sync_logout(
     State(state): State<Arc<AppState>>,
 ) -> Result<Json<serde_json::Value>, (StatusCode, Json<serde_json::Value>)> {
-    // Stop sync task
+    if let Some(p) = state.pending_device_flow.lock().await.take() {
+        p.cancel.cancel();
+    }
+
     if let Some(handle) = state.sync_handle.lock().await.take() {
         handle.stop().await;
     }
 
-    // Clear session
     *state.sync_session.lock().unwrap() = None;
     if let Err(e) = SyncSession::delete(&state.session_path) {
         tracing::warn!("Failed to delete session file: {e}");
diff --git a/src/server/mod.rs b/src/server/mod.rs
index e2f6cf2..8b3361c 100644
--- a/src/server/mod.rs
+++ b/src/server/mod.rs
@@ -42,8 +42,6 @@ use camino::Utf8PathBuf;
 use clap::Args;
 use rust_embed::RustEmbed;
 #[cfg(feature = "sync")]
-use std::sync::atomic::AtomicBool;
-#[cfg(feature = "sync")]
 use std::sync::Mutex;
 use std::{net::IpAddr, net::SocketAddr, sync::Arc};
 use tower_http::{cors::CorsLayer, services::ServeDir};
@@ -318,7 +316,7 @@ fn build_state(ctx: Context, args: ServerArgs) -> Result<Arc<AppState>> {
         #[cfg(feature = "sync")]
         sync_handle: Arc::new(tokio::sync::Mutex::new(None)),
         #[cfg(feature = "sync")]
-        login_in_progress: Arc::new(AtomicBool::new(false)),
+        pending_device_flow: Arc::new(tokio::sync::Mutex::new(None)),
         #[cfg(feature = "sync")]
         session_path,
         #[cfg(feature = "sync")]
@@ -372,7 +370,7 @@ pub struct AppState {
     #[cfg(feature = "sync")]
     pub sync_handle: Arc<tokio::sync::Mutex<Option<sync::SyncHandle>>>,
     #[cfg(feature = "sync")]
-    pub login_in_progress: Arc<AtomicBool>,
+    pub pending_device_flow: Arc<tokio::sync::Mutex<Option<sync::PendingDeviceFlow>>>,
     #[cfg(feature = "sync")]
     pub session_path: std::path::PathBuf,
     #[cfg(feature = "sync")]
@@ -462,6 +460,7 @@ fn api(_state: &AppState) -> Result<Router<Arc<AppState>>> {
     let router = router
         .route("/sync/status", get(handlers::sync_status))
         .route("/sync/login", post(handlers::sync_login))
+        .route("/sync/cancel_login", post(handlers::sync_cancel_login))
         .route("/sync/logout", post(handlers::sync_logout));
 
     Ok(router)
diff --git a/src/server/sync/device_flow.rs b/src/server/sync/device_flow.rs
new file mode 100644
index 0000000..1243d3a
--- /dev/null
+++ b/src/server/sync/device_flow.rs
@@ -0,0 +1,154 @@
+use std::time::{Duration, Instant};
+
+use serde::{Deserialize, Serialize};
+use tokio_util::sync::CancellationToken;
+
+use super::endpoints;
+
+const GRANT_TYPE: &str = "urn:ietf:params:oauth:grant-type:device_code";
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct DeviceCodeResponse {
+    pub device_code: String,
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_in: u64,
+    pub interval: u64,
+}
+
+#[derive(Debug, Serialize)]
+struct DeviceCodeRequest<'a> {
+    client_name: &'a str,
+}
+
+#[derive(Debug, Serialize)]
+struct TokenRequest<'a> {
+    grant_type: &'a str,
+    device_code: &'a str,
+}
+
+#[derive(Debug, Deserialize)]
+struct TokenSuccess {
+    access_token: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct TokenError {
+    error: String,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum DeviceFlowError {
+    #[error("user denied authorization")]
+    AccessDenied,
+    #[error("device code expired")]
+    Expired,
+    #[error("flow cancelled")]
+    Cancelled,
+    #[error("network error: {0}")]
+    Network(#[from] reqwest::Error),
+    #[error("bad response from cook.md: {0}")]
+    BadResponse(String),
+}
+
+pub async fn request_device_code(
+    client: &reqwest::Client,
+    client_name: &str,
+) -> Result<DeviceCodeResponse, DeviceFlowError> {
+    let url = format!("{}/oauth/device/code", endpoints::base_url());
+    let resp = client
+        .post(&url)
+        .json(&DeviceCodeRequest { client_name })
+        .send()
+        .await?;
+
+    if !resp.status().is_success() {
+        let status = resp.status();
+        let body = resp.text().await.unwrap_or_default();
+        return Err(DeviceFlowError::BadResponse(format!(
+            "device code request failed: HTTP {status}: {body}"
+        )));
+    }
+
+    resp.json::<DeviceCodeResponse>().await.map_err(Into::into)
+}
+
+/// Polls /oauth/device/token until approved, denied, expired, or cancelled.
+/// Respects `slow_down` (bumps interval by 5 s) and the `expires_at` deadline.
+pub async fn poll_for_token(
+    client: &reqwest::Client,
+    device_code: &str,
+    mut interval: Duration,
+    expires_at: Instant,
+    cancel: CancellationToken,
+) -> Result<String, DeviceFlowError> {
+    let url = format!("{}/oauth/device/token", endpoints::base_url());
+
+    loop {
+        if Instant::now() >= expires_at {
+            return Err(DeviceFlowError::Expired);
+        }
+
+        tokio::select! {
+            _ = cancel.cancelled() => return Err(DeviceFlowError::Cancelled),
+            _ = tokio::time::sleep(interval) => {}
+        }
+
+        let resp = client
+            .post(&url)
+            .json(&TokenRequest {
+                grant_type: GRANT_TYPE,
+                device_code,
+            })
+            .send()
+            .await?;
+
+        let status = resp.status();
+
+        if status.is_success() {
+            let body: TokenSuccess = resp.json().await.map_err(DeviceFlowError::Network)?;
+            return Ok(body.access_token);
+        }
+
+        // 400 → parse {"error": "..."} per RFC 8628
+        let body: TokenError = resp
+            .json()
+            .await
+            .map_err(|e| DeviceFlowError::BadResponse(format!("unparseable error body: {e}")))?;
+
+        match body.error.as_str() {
+            "authorization_pending" => continue,
+            "slow_down" => {
+                interval += Duration::from_secs(5);
+            }
+            "access_denied" => return Err(DeviceFlowError::AccessDenied),
+            "expired_token" => return Err(DeviceFlowError::Expired),
+            other => {
+                return Err(DeviceFlowError::BadResponse(format!(
+                    "unexpected error code: {other}"
+                )))
+            }
+        }
+    }
+}
+
+/// Builds the client_name string sent to cook.md. Includes OS and a
+/// best-effort label ("docker" / "cli" / hostname).
+pub fn client_name(suffix: &str) -> String {
+    format!(
+        "CookCLI {} ({}/{})",
+        env!("CARGO_PKG_VERSION"),
+        std::env::consts::OS,
+        suffix
+    )
+}
+
+/// Returns "docker" if /.dockerenv exists, else "server".
+pub fn server_host_label() -> &'static str {
+    if std::path::Path::new("/.dockerenv").exists() {
+        "docker"
+    } else {
+        "server"
+    }
+}
diff --git a/src/server/sync/mod.rs b/src/server/sync/mod.rs
index a84f17c..9884f7f 100644
--- a/src/server/sync/mod.rs
+++ b/src/server/sync/mod.rs
@@ -1,5 +1,6 @@
 use camino::Utf8PathBuf;
 
+pub mod device_flow;
 pub mod endpoints;
 pub mod runner;
 pub mod session;
@@ -7,6 +8,17 @@ pub mod session;
 pub use runner::{start_sync, SyncHandle};
 pub use session::SyncSession;
 
+use tokio_util::sync::CancellationToken;
+
+#[derive(Clone)]
+pub struct PendingDeviceFlow {
+    pub user_code: String,
+    pub verification_uri: String,
+    pub verification_uri_complete: String,
+    pub expires_at: std::time::Instant,
+    pub cancel: CancellationToken,
+}
+
 /// Resolve the sync database file path.
 /// Returns an error if the global config directory cannot be determined.
 pub fn sync_db_path() -> anyhow::Result<String> {
diff --git a/templates/preferences.html b/templates/preferences.html
index 51e928d..88db9b4 100644
--- a/templates/preferences.html
+++ b/templates/preferences.html
@@ -62,13 +62,30 @@ <h2 class="text-lg font-semibold mb-3">CookCloud Sync</h2>
                     </button>
                 </div>
                 {% else %}
-                <div class="flex items-center justify-between">
+                <div id="sync-login-section" class="flex items-center justify-between">
                     <p class="text-sm text-gray-600" id="sync-login-message">Sync your recipes across devices with CookCloud.</p>
                     <button id="sync-login-btn" onclick="syncLogin()"
                             class="px-4 py-2 rounded-lg font-medium transition-all duration-200 border-2 bg-orange-700 text-white border-orange-800 hover:bg-orange-800">
                         Login to CookCloud
                     </button>
                 </div>
+
+                <div id="sync-login-card" class="hidden mt-4 border border-gray-200 rounded-lg p-6 bg-white">
+                    <h3 class="text-lg font-semibold mb-2">Sign in to CookCloud</h3>
+                    <ol class="mt-3 space-y-2 text-sm text-gray-700">
+                        <li>1. Open <a id="sync-login-link" href="#" target="_blank" rel="noopener" class="underline text-orange-700 hover:text-orange-800">cook.md/device</a> in any browser.</li>
+                        <li>2. Enter this code:</li>
+                    </ol>
+                    <div class="mt-3 flex items-center gap-2">
+                        <span id="sync-login-code" class="text-2xl tracking-widest bg-gray-100 px-4 py-2 rounded font-mono">----  ----</span>
+                        <button id="sync-login-copy" type="button" class="px-3 py-1 border border-gray-300 rounded text-sm hover:bg-gray-50">Copy</button>
+                    </div>
+                    <p id="sync-login-expires" class="mt-3 text-sm text-gray-600"></p>
+                    <div class="mt-4 flex gap-2">
+                        <a id="sync-login-open" href="#" target="_blank" rel="noopener" class="px-4 py-2 rounded-lg font-medium bg-orange-700 text-white border-2 border-orange-800 hover:bg-orange-800">Open cook.md/device</a>
+                        <button id="sync-login-cancel" type="button" class="px-4 py-2 rounded-lg font-medium border-2 border-gray-300 text-gray-700 hover:bg-gray-50">Cancel</button>
+                    </div>
+                </div>
                 {% endif %}
             </div>
         </div>
@@ -159,59 +176,120 @@ <h2 class="text-lg font-semibold mb-3">Documentation & Resources</h2>
     }
 
     {% if sync_enabled %}
+    let pollHandle = null;
+    let countdownHandle = null;
+
+    function renderPending(p) {
+      document.getElementById('sync-login-section').classList.add('hidden');
+      const card = document.getElementById('sync-login-card');
+      card.classList.remove('hidden');
+      document.getElementById('sync-login-code').textContent = p.user_code;
+      document.getElementById('sync-login-link').href = p.verification_uri;
+      document.getElementById('sync-login-link').textContent = p.verification_uri;
+      document.getElementById('sync-login-open').href = p.verification_uri_complete;
+
+      if (countdownHandle) clearInterval(countdownHandle);
+      const deadline = Date.now() + p.expires_in_secs * 1000;
+      const expEl = document.getElementById('sync-login-expires');
+      const tick = () => {
+        const remaining = Math.max(0, Math.round((deadline - Date.now()) / 1000));
+        if (remaining <= 0) {
+          expEl.textContent = 'Code expired.';
+          stopPolling();
+          resetLoginUi('Code expired — try again.');
+          return;
+        }
+        const m = Math.floor(remaining / 60);
+        const s = String(remaining % 60).padStart(2, '0');
+        expEl.textContent = `Expires in ${m}:${s}`;
+      };
+      tick();
+      countdownHandle = setInterval(tick, 1000);
+    }
+
+    function stopPolling() {
+      if (pollHandle) { clearInterval(pollHandle); pollHandle = null; }
+      if (countdownHandle) { clearInterval(countdownHandle); countdownHandle = null; }
+    }
+
+    function startPolling() {
+      stopPolling();
+      pollHandle = setInterval(async () => {
+        const status = await fetch('{{ prefix }}/api/sync/status').then(r => r.json()).catch(() => null);
+        if (!status) return; // network blip — keep polling
+        if (status.logged_in) {
+          stopPolling();
+          window.location.reload();
+        } else if (!status.pending_login) {
+          stopPolling();
+          resetLoginUi('Login was cancelled or expired.');
+        }
+      }, 2000);
+    }
+
+    function resetLoginUi(msg) {
+      document.getElementById('sync-login-card').classList.add('hidden');
+      document.getElementById('sync-login-section').classList.remove('hidden');
+      const btn = document.getElementById('sync-login-btn');
+      if (btn) btn.disabled = false;
+      document.getElementById('sync-login-message').textContent = msg || '';
+    }
+
     async function syncLogin() {
-        const btn = document.getElementById('sync-login-btn');
-        const msg = document.getElementById('sync-login-message');
-        try {
-            btn.disabled = true;
-            btn.textContent = 'Opening browser...';
-            btn.classList.add('opacity-50', 'cursor-not-allowed');
-            msg.textContent = 'Complete login in your browser.';
-
-            const resp = await fetch('{{ prefix }}/api/sync/login', { method: 'POST' });
-            if (!resp.ok) {
-                const err = await resp.json();
-                btn.disabled = false;
-                btn.textContent = 'Login to CookCloud';
-                btn.classList.remove('opacity-50', 'cursor-not-allowed');
-                msg.textContent = err.error || 'Login failed. Please try again.';
-                return;
-            }
-
-            btn.textContent = 'Waiting for login...';
-
-            // Poll for login completion
-            const pollInterval = setInterval(async () => {
-                const status = await fetch('{{ prefix }}/api/sync/status').then(r => r.json());
-                if (status.logged_in) {
-                    clearInterval(pollInterval);
-                    window.removeEventListener('beforeunload', cleanupPolling);
-                    window.location.reload();
-                }
-            }, 2000);
-            // Stop polling after 5 minutes and show timeout message
-            const timeoutId = setTimeout(() => {
-                clearInterval(pollInterval);
-                window.removeEventListener('beforeunload', cleanupPolling);
-                btn.disabled = false;
-                btn.textContent = 'Login to CookCloud';
-                btn.classList.remove('opacity-50', 'cursor-not-allowed');
-                msg.textContent = 'Login timed out. Please try again.';
-            }, 300000);
-            // Clean up timers if user navigates away
-            function cleanupPolling() {
-                clearInterval(pollInterval);
-                clearTimeout(timeoutId);
-            }
-            window.addEventListener('beforeunload', cleanupPolling);
-        } catch (e) {
-            btn.disabled = false;
-            btn.textContent = 'Login to CookCloud';
-            btn.classList.remove('opacity-50', 'cursor-not-allowed');
-            msg.textContent = 'Failed to start login: ' + e.message;
+      const btn = document.getElementById('sync-login-btn');
+      const msg = document.getElementById('sync-login-message');
+      try {
+        btn.disabled = true;
+        msg.textContent = 'Requesting code...';
+        const resp = await fetch('{{ prefix }}/api/sync/login', { method: 'POST' });
+        if (!resp.ok) {
+          const err = await resp.json().catch(() => ({}));
+          btn.disabled = false;
+          msg.textContent = err.error || 'Login failed.';
+          return;
         }
+        const body = await resp.json();
+        renderPending(body);
+
+        startPolling();
+      } catch (e) {
+        btn.disabled = false;
+        msg.textContent = 'Failed to start login: ' + e.message;
+      }
     }
 
+    document.addEventListener('DOMContentLoaded', () => {
+      const copyBtn = document.getElementById('sync-login-copy');
+      if (copyBtn) {
+        copyBtn.addEventListener('click', async () => {
+          const code = document.getElementById('sync-login-code').textContent;
+          try {
+            await navigator.clipboard.writeText(code.replace(/\s+/g, ''));
+            copyBtn.textContent = 'Copied!';
+          } catch (e) {
+            copyBtn.textContent = 'Copy failed';
+          }
+          setTimeout(() => { copyBtn.textContent = 'Copy'; }, 1500);
+        });
+      }
+      const cancelBtn = document.getElementById('sync-login-cancel');
+      if (cancelBtn) {
+        cancelBtn.addEventListener('click', async () => {
+          stopPolling();
+          await fetch('{{ prefix }}/api/sync/cancel_login', { method: 'POST' });
+          resetLoginUi('Login cancelled.');
+        });
+      }
+
+      // Resume on page load if a flow is in progress server-side.
+      fetch('{{ prefix }}/api/sync/status').then(r => r.json()).then(status => {
+        if (!status.logged_in && status.pending_login) {
+          renderPending(status.pending_login);
+          startPolling();
+        }
+      });
+    });
+
     async function syncLogout() {
         try {
             await fetch('{{ prefix }}/api/sync/logout', { method: 'POST' });
diff --git a/tests/snapshots/snapshot_test__help_output.snap b/tests/snapshots/snapshot_test__help_output.snap
index fb0972a..f345797 100644
--- a/tests/snapshots/snapshot_test__help_output.snap
+++ b/tests/snapshots/snapshot_test__help_output.snap
@@ -19,6 +19,8 @@ Commands:
   doctor         Analyze your recipe collection for issues and improvements
   pantry         Manage and analyze your pantry inventory
   lsp            Start the Cooklang Language Server Protocol (LSP) server
+  login          Sign in to CookCloud
+  logout         Sign out of CookCloud
   update         Update CookCLI to the latest version
   help           Print this message or the help of the given subcommand(s)