v0.1.0 chore: modernize GPUI template and starter UX

.github/dependabot.yml.liquid

@@ -0,0 +1,18 @@
+{% raw %}
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+{% endraw %}

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ permissions:
 # Cancel a still-running CI for a branch when a newer commit is pushed (faster feedback,
 # fewer minutes — the generated project's first git-gpui build is slow).
 concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
@@ -55,19 +55,19 @@ jobs:
       - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
         with:
           workspaces: ${{ runner.temp }}/gen/deck-ci
-      # No --locked: the generated Cargo.lock's root entry is renamed at generate time, so
-      # cargo refreshes just that on first build (the git-gpui deps stay pinned).
+      # Cargo.lock is a processed template file, so the generated root entry already
+      # matches the generated crate name and every command can enforce reproducibility.
       - name: Build, lint, and test the generated project
         working-directory: ${{ runner.temp }}/gen/deck-ci
         run: |
-          cargo build
-          cargo build --features tray
-          cargo clippy --all-targets -- -D warnings
-          cargo clippy --all-targets --features tray -- -D warnings
-          cargo clippy --all-targets --features overlay -- -D warnings
-          cargo clippy --all-targets --features tray,overlay -- -D warnings
-          cargo test
-          cargo test --features overlay
+          cargo build --locked
+          cargo build --locked --features tray
+          cargo clippy --locked --all-targets -- -D warnings
+          cargo clippy --locked --all-targets --features tray -- -D warnings
+          cargo clippy --locked --all-targets --features overlay -- -D warnings
+          cargo clippy --locked --all-targets --features tray,overlay -- -D warnings
+          cargo test --locked
+          cargo test --locked --features overlay
 
   linux:
     runs-on: ubuntu-latest
@@ -102,13 +102,14 @@ jobs:
         working-directory: ${{ runner.temp }}/gen/deck-ci
         run: |
           cargo fmt --all --check
-          cargo build
-          cargo build --features tray
-          cargo clippy --all-targets -- -D warnings
-          cargo clippy --all-targets --features tray -- -D warnings
-          cargo clippy --all-targets --features overlay -- -D warnings
-          cargo test
-          cargo test --features overlay
+          cargo build --locked
+          cargo build --locked --features tray
+          cargo clippy --locked --all-targets -- -D warnings
+          cargo clippy --locked --all-targets --features tray -- -D warnings
+          cargo clippy --locked --all-targets --features overlay -- -D warnings
+          cargo clippy --locked --all-targets --features tray,overlay -- -D warnings
+          cargo test --locked
+          cargo test --locked --features overlay
 
   # Supply-chain gate (advisories / bans / sources / licenses) via cargo-deny, run against
   # the GENERATED project (the raw template Cargo.toml has tokens and won't parse). REQUIRED:

.github/workflows/ci.yml.liquid

@@ -0,0 +1,73 @@
+{% raw %}
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+      - name: Build, lint, and test
+        run: |
+          cargo build --locked
+          cargo build --locked --features tray
+          cargo clippy --locked --all-targets -- -D warnings
+          cargo clippy --locked --all-targets --features tray -- -D warnings
+          cargo clippy --locked --all-targets --features overlay -- -D warnings
+          cargo clippy --locked --all-targets --features tray,overlay -- -D warnings
+          cargo test --locked
+          cargo test --locked --features overlay
+
+  linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential pkg-config \
+            libxcb1-dev libxkbcommon-dev libxkbcommon-x11-dev \
+            libwayland-dev libvulkan-dev \
+            libfontconfig1-dev libfreetype6-dev libssl-dev \
+            libgtk-3-dev libayatana-appindicator3-dev libxdo-dev
+      - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+      - name: Format-check, build, lint, and test
+        run: |
+          cargo fmt --all --check
+          cargo build --locked
+          cargo build --locked --features tray
+          cargo clippy --locked --all-targets -- -D warnings
+          cargo clippy --locked --all-targets --features tray -- -D warnings
+          cargo clippy --locked --all-targets --features overlay -- -D warnings
+          cargo clippy --locked --all-targets --features tray,overlay -- -D warnings
+          cargo test --locked
+          cargo test --locked --features overlay
+
+  cargo-deny:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: taiki-e/install-action@7a79fe8c3a13344501c80d99cae481c1c9085912 # v2.81.10
+        with:
+          tool: cargo-deny
+      - run: cargo deny check advisories bans sources licenses
+{% endraw %}

AGENTS.md

@@ -29,15 +29,18 @@ GPUI stack is pinned in `Cargo.lock`; the toolchain is pinned in
 ## This repo is a cargo-generate template — don't break it
 
 Deck ships via `cargo generate gh:hellno/deck`. The files in `cargo-generate.toml`'s
-`include` list (`Cargo.toml`, `Cargo.lock`, `src/main.rs`, `src/settings.rs`,
-`src/overlay/mod.rs`, `scripts/make-app-icon.py`, `LICENSE`) hold `{{ }}` Liquid tokens,
-so **the raw repo does not `cargo run` / `cargo build`** — render it first.
+`include` list hold Liquid tokens, so **the raw repo does not `cargo run` /
+`cargo build`** — render it first. The `.liquid` files are generated-project
+overrides for README, agent guidance, recipes, and CI; cargo-generate strips the
+suffix and lets them replace the maintainer-facing files in the rendered app.
 
 - Verify template changes with **`just check-template`** (renders a project, then clippy +
   test). `just run` / `just ci` only work *inside a generated fork*.
 - Renaming a new literal? Add its file to `include` **and** add the `{{ }}` token — a literal
   in a non-included file ships as "deck" to every fork.
-- **Never** put a literal `{{` or `{%` in an included file (Liquid will try to parse it).
+- In a normal included file, every `{{` / `{%` must be intentional Liquid. In a
+  `.liquid` override, wrap syntax owned by another tool (Just/GitHub Actions) in
+  `{% raw %}` / `{% endraw %}`.
 - CI renders a throwaway project and builds THAT (`.github/workflows/ci.yml`).
 
 ## The loop (verify and self-correct without a CI round-trip)

AGENTS.md.liquid

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Guidance for coding agents working in `{{project-name}}`. `CLAUDE.md` contains
+the same rules. Rationale for the lint and CI policy lives in
+`docs/AGENTIC-ENGINEERING.md`.
+
+## Project shape
+
+This is a single Rust crate generated from the Deck GPUI starter. It targets
+macOS and Linux, with optional `tray` and `overlay` features. The git GPUI stack
+is pinned in `Cargo.lock`, and `rust-toolchain.toml` matches Zed's toolchain.
+
+- `src/main.rs` opens the window and wires menus, shortcuts, and features.
+- `src/shell.rs` is the root view and routing/state owner.
+- `src/command_palette.rs` owns commands and fuzzy-match tests.
+- `src/welcome.rs` is starter UI intended to be replaced.
+- `src/settings.rs` and `src/settings_view.rs` own persisted preferences.
+- `src/theme.rs` owns dark/light palettes and accents.
+- `src/tray.rs` and `src/overlay/` are feature-gated platform surfaces.
+
+## Working loop
+
+- Use `cargo check` for fast type checking and `just run` to launch.
+- Use `just fix` for machine-applicable clippy fixes plus formatting.
+- Run `just ci` before declaring a change done. It checks formatting, clippy
+  with `-D warnings` on all four feature combinations, and tests.
+- For UI changes, use `just screenshot` on macOS and inspect the actual image.
+
+## Definition of done
+
+1. `cargo fmt --all --check` is clean.
+2. Clippy is green for default, `tray`, `overlay`, and `tray,overlay`.
+3. Default and overlay tests pass.
+4. Dependency changes are intentional, reviewed, and reflected in `Cargo.lock`.
+
+## Code constraints
+
+- No `todo!()` or `dbg!()`; both are denied.
+- Never ignore a `Result`. Propagate it or handle it deliberately.
+- `unsafe_code` is denied. A necessary escape hatch needs a scoped allow and a
+  reviewed `// SAFETY:` explanation.
+- `.expect()` is acceptable for genuinely infallible GPUI handles; prefer
+  `Result` and `?` elsewhere.
+- Keep I/O and network work off the UI thread. Update memory and notify first,
+  then persist on a background executor or at a coarse commit boundary.
+- Keep volatile state in its own `Entity<T>` so notifications repaint the
+  smallest useful subtree.
+- Use `uniform_list` or `list` for large collections and filter in memory.
+
+## Dependencies
+
+Refresh the dependency lockfile with `just bump-gpui`, then run `just ci` and a
+runtime smoke test. The script restores the previous lockfile when an update
+does not build. Do not hand-edit git SHAs in `Cargo.lock`; see
+`docs/UPGRADING.md` for known-green revision overrides.

CLAUDE.md

@@ -29,15 +29,18 @@ GPUI stack is pinned in `Cargo.lock`; the toolchain is pinned in
 ## This repo is a cargo-generate template — don't break it
 
 Deck ships via `cargo generate gh:hellno/deck`. The files in `cargo-generate.toml`'s
-`include` list (`Cargo.toml`, `Cargo.lock`, `src/main.rs`, `src/settings.rs`,
-`src/overlay/mod.rs`, `scripts/make-app-icon.py`, `LICENSE`) hold `{{ }}` Liquid tokens,
-so **the raw repo does not `cargo run` / `cargo build`** — render it first.
+`include` list hold Liquid tokens, so **the raw repo does not `cargo run` /
+`cargo build`** — render it first. The `.liquid` files are generated-project
+overrides for README, agent guidance, recipes, and CI; cargo-generate strips the
+suffix and lets them replace the maintainer-facing files in the rendered app.
 
 - Verify template changes with **`just check-template`** (renders a project, then clippy +
   test). `just run` / `just ci` only work *inside a generated fork*.
 - Renaming a new literal? Add its file to `include` **and** add the `{{ }}` token — a literal
   in a non-included file ships as "deck" to every fork.
-- **Never** put a literal `{{` or `{%` in an included file (Liquid will try to parse it).
+- In a normal included file, every `{{` / `{%` must be intentional Liquid. In a
+  `.liquid` override, wrap syntax owned by another tool (Just/GitHub Actions) in
+  `{% raw %}` / `{% endraw %}`.
 - CI renders a throwaway project and builds THAT (`.github/workflows/ci.yml`).
 
 ## The loop (verify and self-correct without a CI round-trip)

CLAUDE.md.liquid

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Guidance for coding agents working in `{{project-name}}`. `CLAUDE.md` contains
+the same rules. Rationale for the lint and CI policy lives in
+`docs/AGENTIC-ENGINEERING.md`.
+
+## Project shape
+
+This is a single Rust crate generated from the Deck GPUI starter. It targets
+macOS and Linux, with optional `tray` and `overlay` features. The git GPUI stack
+is pinned in `Cargo.lock`, and `rust-toolchain.toml` matches Zed's toolchain.
+
+- `src/main.rs` opens the window and wires menus, shortcuts, and features.
+- `src/shell.rs` is the root view and routing/state owner.
+- `src/command_palette.rs` owns commands and fuzzy-match tests.
+- `src/welcome.rs` is starter UI intended to be replaced.
+- `src/settings.rs` and `src/settings_view.rs` own persisted preferences.
+- `src/theme.rs` owns dark/light palettes and accents.
+- `src/tray.rs` and `src/overlay/` are feature-gated platform surfaces.
+
+## Working loop
+
+- Use `cargo check` for fast type checking and `just run` to launch.
+- Use `just fix` for machine-applicable clippy fixes plus formatting.
+- Run `just ci` before declaring a change done. It checks formatting, clippy
+  with `-D warnings` on all four feature combinations, and tests.
+- For UI changes, use `just screenshot` on macOS and inspect the actual image.
+
+## Definition of done
+
+1. `cargo fmt --all --check` is clean.
+2. Clippy is green for default, `tray`, `overlay`, and `tray,overlay`.
+3. Default and overlay tests pass.
+4. Dependency changes are intentional, reviewed, and reflected in `Cargo.lock`.
+
+## Code constraints
+
+- No `todo!()` or `dbg!()`; both are denied.
+- Never ignore a `Result`. Propagate it or handle it deliberately.
+- `unsafe_code` is denied. A necessary escape hatch needs a scoped allow and a
+  reviewed `// SAFETY:` explanation.
+- `.expect()` is acceptable for genuinely infallible GPUI handles; prefer
+  `Result` and `?` elsewhere.
+- Keep I/O and network work off the UI thread. Update memory and notify first,
+  then persist on a background executor or at a coarse commit boundary.
+- Keep volatile state in its own `Entity<T>` so notifications repaint the
+  smallest useful subtree.
+- Use `uniform_list` or `list` for large collections and filter in memory.
+
+## Dependencies
+
+Refresh the dependency lockfile with `just bump-gpui`, then run `just ci` and a
+runtime smoke test. The script restores the previous lockfile when an update
+does not build. Do not hand-edit git SHAs in `Cargo.lock`; see
+`docs/UPGRADING.md` for known-green revision overrides.

CONTRIBUTING.md

@@ -67,11 +67,11 @@ is pinned to exact commits in `Cargo.lock`. **Never hand-edit those pins.** Bump
 them only with:
 
 ```bash
-just bump-gpui   # cargo update on the four crates + rebuild
+just bump-gpui   # stage a full lockfile refresh, rebuild, then install it atomically
 ```
 
-then commit the updated `Cargo.lock` (and `rust-toolchain.toml` if the build
-needed a newer toolchain). Full procedure and the crates.io fallback channel:
+then run `just ci` and commit the updated `Cargo.lock` (and `rust-toolchain.toml`
+if the build needed a newer toolchain). Full procedure and the crates.io fallback channel:
 [`docs/UPGRADING.md`](docs/UPGRADING.md).
 
 ## Submitting a PR