From 553e83e9f94722b422c88adf720120714fc17a27 Mon Sep 17 00:00:00 2001
From: ikma <ikma@ricon.family>
Date: Sat, 18 Jul 2026 15:42:30 -0400
Subject: [PATCH] feat: support Zed review task fields

---
 .mise/tasks/zed/keymap/bind-snippet  |  14 +++
 .mise/tasks/zed/keymap/check-snippet |  13 +++
 .mise/tasks/zed/tasks/upsert         | 137 +++++++++++++++++++++++----
 README.md                            |  48 ++++++----
 README.tsx                           |  28 ++++--
 test/zed/keymap.bats                 | 117 +++++++++++++++++++++++
 test/zed/tasks.bats                  | 123 ++++++++++++++++++++++++
 7 files changed, 437 insertions(+), 43 deletions(-)
 create mode 100755 .mise/tasks/zed/keymap/bind-snippet
 create mode 100755 .mise/tasks/zed/keymap/check-snippet

diff --git a/.mise/tasks/zed/keymap/bind-snippet b/.mise/tasks/zed/keymap/bind-snippet
new file mode 100755
index 0000000..5e095a7
--- /dev/null
+++ b/.mise/tasks/zed/keymap/bind-snippet
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+#MISE description="Bind a Zed key to insert an inline snippet"
+#MISE dir="{{config_root}}"
+#USAGE flag "--keystroke <keystroke>" required=#true help="Zed key binding, for example cmd-k i"
+#USAGE flag "--snippet <snippet>" required=#true help="Inline Zed snippet text"
+#USAGE flag "--context <context>" default="Editor" help="Zed keymap context"
+#USAGE flag "--force" default=#false help="Replace an existing different binding"
+#USAGE example "mise run zed:keymap:bind-snippet --context 'Editor && extension == md' --keystroke 'cmd-k i' --snippet '<!-- ! \"@ikma ${1:feedback}\" | mise comment -->$0'" header="Bind a Markdown snippet"
+set -euo pipefail
+
+source "$MISE_CONFIG_ROOT/lib/zed/keymap.sh"
+
+binding_json="$(jq -n --arg snippet "$usage_snippet" '["editor::InsertSnippet", {snippet: $snippet}]')"
+zed_keymap_upsert_binding_json "$usage_context" "$usage_keystroke" "$binding_json" "$usage_force"
diff --git a/.mise/tasks/zed/keymap/check-snippet b/.mise/tasks/zed/keymap/check-snippet
new file mode 100755
index 0000000..dc6c8b9
--- /dev/null
+++ b/.mise/tasks/zed/keymap/check-snippet
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#MISE description="Check whether a Zed snippet key binding can be installed"
+#MISE dir="{{config_root}}"
+#USAGE flag "--keystroke <keystroke>" required=#true help="Zed key binding, for example cmd-k i"
+#USAGE flag "--snippet <snippet>" required=#true help="Inline Zed snippet text"
+#USAGE flag "--context <context>" default="Editor" help="Zed keymap context"
+#USAGE example "mise run zed:keymap:check-snippet --context 'Editor && extension == md' --keystroke 'cmd-k i' --snippet '<!-- ! \"@ikma ${1:feedback}\" | mise comment -->$0'" header="Check a Markdown snippet binding"
+set -euo pipefail
+
+source "$MISE_CONFIG_ROOT/lib/zed/keymap.sh"
+
+binding_json="$(jq -n --arg snippet "$usage_snippet" '["editor::InsertSnippet", {snippet: $snippet}]')"
+zed_keymap_check_binding_json "$usage_context" "$usage_keystroke" "$binding_json"
diff --git a/.mise/tasks/zed/tasks/upsert b/.mise/tasks/zed/tasks/upsert
index 5d4180b..9ff1d5e 100755
--- a/.mise/tasks/zed/tasks/upsert
+++ b/.mise/tasks/zed/tasks/upsert
@@ -4,30 +4,131 @@
 #USAGE flag "--label <label>" required=#true help="Task label"
 #USAGE flag "--command <command>" required=#true help="Command to run"
 #USAGE flag "--arg <arg>" default="" var=#true help="Command argument (repeatable)"
-#USAGE flag "--save <save>" default="" help="Zed save policy, for example current"
-#USAGE flag "--hide <hide>" default="" help="Zed hide policy, for example on_success"
-#USAGE example "mise run zed:tasks:upsert --label 'comments: dispatch current file' --command comments --arg dispatch --arg '$ZED_FILE' --save current --hide on_success" header="Upsert a current-file task"
+#USAGE flag "--save <save>" default="" help="Zed save policy: all, current, or none"
+#USAGE flag "--reveal <reveal>" default="" help="Zed reveal policy: always, no_focus, or never"
+#USAGE flag "--hide <hide>" default="" help="Zed hide policy: never, always, or on_success"
+#USAGE flag "--shell-program <shell_program>" default="" help="Explicit Zed task shell program"
+#USAGE flag "--shell-arg <shell_arg>" default="" var=#true help="Shell argument (repeatable; requires --shell-program)"
+#USAGE flag "--env <env>" default="" var=#true help="Task environment entry as name=value (repeatable)"
+#USAGE example "mise run zed:tasks:upsert --label 'comments: dispatch current file' --command comments --arg dispatch --arg '$ZED_FILE' --save current --reveal never --hide on_success" header="Upsert a current-file task"
+#USAGE example "mise run zed:tasks:upsert --label review --command comments --shell-program /bin/zsh --shell-arg=-f --env COMMENT_CHAT_AS=or" header="Set an explicit shell and environment"
 set -euo pipefail
 
 source "$MISE_CONFIG_ROOT/lib/zed/tasks.sh"
 
+usage_values() {
+  local raw="$1"
+  [ -n "$raw" ] || return 0
+  printf '%s' "$raw" | xargs printf '%s\n'
+}
+
+json_array() {
+  if [ "$#" -eq 0 ]; then
+    printf '[]\n'
+  else
+    printf '%s\n' "$@" | jq -R . | jq -s .
+  fi
+}
+
+validate_optional_enum() {
+  local field="$1"
+  local value="$2"
+  shift 2
+
+  [ -n "$value" ] || return 0
+
+  local allowed
+  for allowed in "$@"; do
+    [ "$value" != "$allowed" ] || return 0
+  done
+
+  printf 'ctl zed tasks upsert: invalid %s value: %s\n' "$field" "$value" >&2
+  return 1
+}
+
+save="${usage_save:-}"
+reveal="${usage_reveal:-}"
+hide="${usage_hide:-}"
+shell_program="${usage_shell_program:-}"
+
+validate_optional_enum save "$save" all current none
+validate_optional_enum reveal "$reveal" always no_focus never
+validate_optional_enum hide "$hide" never always on_success
+
 args=()
-if [ -n "${usage_arg:-}" ]; then
-  while IFS= read -r arg; do
-    [ -z "$arg" ] && continue
-    args+=("$arg")
-  done < <(printf '%s' "$usage_arg" | xargs printf '%s\n')
+while IFS= read -r value; do
+  [ -n "$value" ] || continue
+  args+=("$value")
+done < <(usage_values "${usage_arg:-}")
+args_json="$(json_array ${args[@]+"${args[@]}"})"
+
+shell_args=()
+while IFS= read -r value; do
+  [ -n "$value" ] || continue
+  shell_args+=("$value")
+done < <(usage_values "${usage_shell_arg:-}")
+
+if [ "${#shell_args[@]}" -gt 0 ] && [ -z "$shell_program" ]; then
+  echo "ctl zed tasks upsert: --shell-arg requires --shell-program" >&2
+  exit 1
+fi
+
+shell_json='null'
+if [ -n "$shell_program" ]; then
+  if [ "${#shell_args[@]}" -gt 0 ]; then
+    shell_args_json="$(json_array ${shell_args[@]+"${shell_args[@]}"})"
+    shell_json="$(
+      jq -n \
+        --arg program "$shell_program" \
+        --argjson args "$shell_args_json" \
+        '{with_arguments: {program: $program, args: $args}}'
+    )"
+  else
+    shell_json="$(jq -n --arg program "$shell_program" '{program: $program}')"
+  fi
 fi
 
-args_json=$(printf '%s\n' ${args[@]+"${args[@]}"} | jq -R . | jq -s .)
-task_json=$(jq -n \
-  --arg label "$usage_label" \
-  --arg command "$usage_command" \
-  --argjson args "$args_json" \
-  --arg save "${usage_save:-}" \
-  --arg hide "${usage_hide:-}" \
-  '{label: $label, command: $command, args: $args}
-   + (if $save == "" then {} else {save: $save} end)
-   + (if $hide == "" then {} else {hide: $hide} end)')
+env_json='{}'
+while IFS= read -r entry; do
+  [ -n "$entry" ] || continue
+
+  case "$entry" in
+    *=*) ;;
+    *)
+      printf 'ctl zed tasks upsert: invalid --env entry (expected name=value): %s\n' "$entry" >&2
+      exit 1
+      ;;
+  esac
+
+  name="${entry%%=*}"
+  value="${entry#*=}"
+  if ! [[ "$name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    printf 'ctl zed tasks upsert: invalid environment name: %s\n' "$name" >&2
+    exit 1
+  fi
+  if jq -e --arg name "$name" 'has($name)' <<<"$env_json" >/dev/null; then
+    printf 'ctl zed tasks upsert: duplicate environment name: %s\n' "$name" >&2
+    exit 1
+  fi
+  env_json="$(jq --arg name "$name" --arg value "$value" '. + {($name): $value}' <<<"$env_json")"
+done < <(usage_values "${usage_env:-}")
+
+task_json="$(
+  jq -n \
+    --arg label "$usage_label" \
+    --arg command "$usage_command" \
+    --argjson args "$args_json" \
+    --arg save "$save" \
+    --arg reveal "$reveal" \
+    --arg hide "$hide" \
+    --argjson shell "$shell_json" \
+    --argjson env "$env_json" \
+    '{label: $label, command: $command, args: $args}
+     + (if $save == "" then {} else {save: $save} end)
+     + (if $reveal == "" then {} else {reveal: $reveal} end)
+     + (if $hide == "" then {} else {hide: $hide} end)
+     + (if $shell == null then {} else {shell: $shell} end)
+     + (if ($env | length) == 0 then {} else {env: $env} end)'
+)"
 
 zed_tasks_upsert_json "$task_json"
diff --git a/README.md b/README.md
index 4b174ca..28e1582 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 Boring JSON surgery for tools that should not each own it.
 
 ![shape: mise + BATS](https://img.shields.io/badge/shape-mise%20%2B%20BATS-4EAA25?style=flat&logo=gnubash&logoColor=white)
-[![tests: 23](https://img.shields.io/badge/tests-23-brightgreen?style=flat)](test/)
+[![tests: 34](https://img.shields.io/badge/tests-34-brightgreen?style=flat)](test/)
 ![lints: 9](https://img.shields.io/badge/lints-9-blue?style=flat)
 ![README: TSX](https://img.shields.io/badge/README-TSX-f472b6?style=flat)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat)](LICENSE)
@@ -18,7 +18,7 @@ Boring JSON surgery for tools that should not each own it.
 
 ## What this is
 
-`ctl` is a shiv-installable CLI for app and editor integrations that need a small, reusable command surface. The first version manages project-local Zed tasks in `.zed/tasks.json`.
+`ctl` is a shiv-installable CLI for app and editor integrations that need a small, reusable command surface. Its first namespace manages Zed task and keymap JSON.
 
 The immediate extraction target is `comments integrations zed`: it should not own generic Zed JSON upsert logic forever. `ctl zed tasks ...` gives that logic one home so other tools can reuse it.
 
@@ -46,13 +46,17 @@ ctl zed tasks upsert \
   --arg dispatch \
   --arg '$ZED_FILE' \
   --save current \
-  --hide on_success
+  --reveal never \
+  --hide on_success \
+  --shell-program /bin/zsh \
+  --shell-arg=-f \
+  --env COMMENT_CHAT_AS=or
 
 # Remove tasks with a matching label.
 ctl zed tasks remove --label "comments: dispatch current file"
 ```
 
-All commands target the caller directory's `.zed/tasks.json`. Existing tasks are preserved. Upsert replaces tasks with the same `label` and appends when the label is new. Invalid JSON or a non-array tasks file fails without clobbering the file.
+All commands target the caller directory's `.zed/tasks.json`. Existing tasks are preserved. Upsert replaces tasks with the same `label` and appends when the label is new. Optional reveal, shell, and environment fields are emitted only when the caller supplies them. Invalid values, invalid JSON, or a non-array tasks file fail without clobbering the file.
 
 ## Zed keymap
 
@@ -69,6 +73,10 @@ ctl zed keymap bind-task   --keystroke cmd-shift-d   --task "comments: dispatch
 # Check/bind rerun with fresh Zed context.
 ctl zed keymap check-rerun --keystroke cmd-shift-r
 ctl zed keymap bind-rerun   --keystroke cmd-shift-r   --reevaluate-context
+
+# Check/bind a concrete inline snippet action.
+ctl zed keymap check-snippet   --context 'Editor && extension == md'   --keystroke 'cmd-k i'   --snippet '<!-- ! "@ikma ${1:feedback}" | mise comment -->$0'
+ctl zed keymap bind-snippet   --context 'Editor && extension == md'   --keystroke 'cmd-k i'   --snippet '<!-- ! "@ikma ${1:feedback}" | mise comment -->$0'
 ```
 
 Keymap commands target Zed's global `keymap.json`. Existing bindings are preserved. If a requested keystroke already has a different binding in the target context, `ctl` fails without clobbering it unless `--force` is passed.
@@ -87,6 +95,8 @@ mise run zed:keymap:check-task --keystroke cmd-shift-d --task example
 mise run zed:keymap:bind-task --keystroke cmd-shift-d --task example
 mise run zed:keymap:check-rerun --keystroke cmd-shift-r
 mise run zed:keymap:bind-rerun --keystroke cmd-shift-r
+mise run zed:keymap:check-snippet --context Editor --keystroke 'cmd-k i' --snippet 'Hello ${1:there}$0'
+mise run zed:keymap:bind-snippet --context Editor --keystroke 'cmd-k i' --snippet 'Hello ${1:there}$0'
 ```
 
 ## Project-local path resolution
@@ -95,19 +105,21 @@ When installed by shiv, the shim exports `CTL_CALLER_PWD` before running the tas
 
 ## Tasks
 
-| Task                              | Description                                            |
-| --------------------------------- | ------------------------------------------------------ |
-| `mise run doctor`                 | Check local development setup                          |
-| `mise run test`                   | Run BATS tests                                         |
-| `mise run zed:keymap:bind-rerun`  | Bind a Zed key to rerun the last task                  |
-| `mise run zed:keymap:bind-task`   | Bind a Zed key to spawn a named task                   |
-| `mise run zed:keymap:check-rerun` | Check whether a Zed rerun key binding can be installed |
-| `mise run zed:keymap:check-task`  | Check whether a Zed task key binding can be installed  |
-| `mise run zed:keymap:path`        | Print the global Zed keymap.json path                  |
-| `mise run zed:tasks:list`         | Print project-local Zed tasks as JSON                  |
-| `mise run zed:tasks:path`         | Print the project-local Zed tasks.json path            |
-| `mise run zed:tasks:remove`       | Remove a project-local Zed task by label               |
-| `mise run zed:tasks:upsert`       | Insert or replace a project-local Zed task by label    |
+| Task                                | Description                                              |
+| ----------------------------------- | -------------------------------------------------------- |
+| `mise run doctor`                   | Check local development setup                            |
+| `mise run test`                     | Run BATS tests                                           |
+| `mise run zed:keymap:bind-rerun`    | Bind a Zed key to rerun the last task                    |
+| `mise run zed:keymap:bind-snippet`  | Bind a Zed key to insert an inline snippet               |
+| `mise run zed:keymap:bind-task`     | Bind a Zed key to spawn a named task                     |
+| `mise run zed:keymap:check-rerun`   | Check whether a Zed rerun key binding can be installed   |
+| `mise run zed:keymap:check-snippet` | Check whether a Zed snippet key binding can be installed |
+| `mise run zed:keymap:check-task`    | Check whether a Zed task key binding can be installed    |
+| `mise run zed:keymap:path`          | Print the global Zed keymap.json path                    |
+| `mise run zed:tasks:list`           | Print project-local Zed tasks as JSON                    |
+| `mise run zed:tasks:path`           | Print the project-local Zed tasks.json path              |
+| `mise run zed:tasks:remove`         | Remove a project-local Zed task by label                 |
+| `mise run zed:tasks:upsert`         | Insert or replace a project-local Zed task by label      |
 
 ## Repo inventory
 
@@ -152,7 +164,7 @@ readme build --check
 git diff --check
 ```
 
-The suite currently has **23 tests** and **11 public tasks**. CI runs on **ubuntu-latest + macos-latest**.
+The suite currently has **34 tests** and **13 public tasks**. CI runs on **ubuntu-latest + macos-latest**.
 
 <div align="center">
 
diff --git a/README.tsx b/README.tsx
index 14cab21..517fbdb 100644
--- a/README.tsx
+++ b/README.tsx
@@ -164,9 +164,7 @@ const readme = (
     <Section title="What this is">
       <Paragraph>
         <Code>ctl</Code>
-        {" is a shiv-installable CLI for app and editor integrations that need a small, reusable command surface. The first version manages project-local Zed tasks in "}
-        <Code>.zed/tasks.json</Code>
-        {"."}
+        {" is a shiv-installable CLI for app and editor integrations that need a small, reusable command surface. Its first namespace manages Zed task and keymap JSON."}
       </Paragraph>
 
       <Paragraph>
@@ -200,7 +198,11 @@ ctl zed tasks upsert \\
   --arg dispatch \\
   --arg '$ZED_FILE' \\
   --save current \\
-  --hide on_success
+  --reveal never \\
+  --hide on_success \\
+  --shell-program /bin/zsh \\
+  --shell-arg=-f \\
+  --env COMMENT_CHAT_AS=or
 
 # Remove tasks with a matching label.
 ctl zed tasks remove --label "comments: dispatch current file"`}</CodeBlock>
@@ -210,7 +212,7 @@ ctl zed tasks remove --label "comments: dispatch current file"`}</CodeBlock>
         <Code>.zed/tasks.json</Code>
         {". Existing tasks are preserved. Upsert replaces tasks with the same "}
         <Code>label</Code>
-        {" and appends when the label is new. Invalid JSON or a non-array tasks file fails without clobbering the file."}
+        {" and appends when the label is new. Optional reveal, shell, and environment fields are emitted only when the caller supplies them. Invalid values, invalid JSON, or a non-array tasks file fail without clobbering the file."}
       </Paragraph>
     </Section>
 
@@ -232,7 +234,17 @@ ctl zed keymap bind-task \
 ctl zed keymap check-rerun --keystroke cmd-shift-r
 ctl zed keymap bind-rerun \
   --keystroke cmd-shift-r \
-  --reevaluate-context`}</CodeBlock>
+  --reevaluate-context
+
+# Check/bind a concrete inline snippet action.
+ctl zed keymap check-snippet \
+  --context 'Editor && extension == md' \
+  --keystroke 'cmd-k i' \
+  --snippet '<!-- ! "@ikma \${1:feedback}" | mise comment -->$0'
+ctl zed keymap bind-snippet \
+  --context 'Editor && extension == md' \
+  --keystroke 'cmd-k i' \
+  --snippet '<!-- ! "@ikma \${1:feedback}" | mise comment -->$0'`}</CodeBlock>
 
       <Paragraph>
         {"Keymap commands target Zed's global "}
@@ -258,7 +270,9 @@ mise run zed:keymap:path
 mise run zed:keymap:check-task --keystroke cmd-shift-d --task example
 mise run zed:keymap:bind-task --keystroke cmd-shift-d --task example
 mise run zed:keymap:check-rerun --keystroke cmd-shift-r
-mise run zed:keymap:bind-rerun --keystroke cmd-shift-r`}</CodeBlock>
+mise run zed:keymap:bind-rerun --keystroke cmd-shift-r
+mise run zed:keymap:check-snippet --context Editor --keystroke 'cmd-k i' --snippet 'Hello \${1:there}$0'
+mise run zed:keymap:bind-snippet --context Editor --keystroke 'cmd-k i' --snippet 'Hello \${1:there}$0'`}</CodeBlock>
     </Section>
 
     <Section title="Project-local path resolution">
diff --git a/test/zed/keymap.bats b/test/zed/keymap.bats
index 71cabd7..4f2babc 100644
--- a/test/zed/keymap.bats
+++ b/test/zed/keymap.bats
@@ -191,3 +191,120 @@ JSON
     --keystroke cmd-shift-r
   [ "$status" -eq 0 ]
 }
+
+@test "zed:keymap:bind-snippet adds an inline snippet and preserves other contexts" {
+  mkdir -p "$BATS_TEST_TMPDIR/zed-config"
+  cat > "$BATS_TEST_TMPDIR/zed-config/keymap.json" <<'JSON'
+[
+  {
+    "context": "Workspace",
+    "bindings": {
+      "cmd-shift-d": ["task::Spawn", {"task_name": "comments: dispatch current file"}]
+    }
+  }
+]
+JSON
+
+  snippet='<!-- ! "@ikma ${1:feedback}" | mise comment -->$0'
+  ZED_CONFIG_HOME="$BATS_TEST_TMPDIR/zed-config" run ctl zed:keymap:bind-snippet \
+    --context 'Editor && extension == md' \
+    --keystroke 'cmd-k i' \
+    --snippet "$snippet"
+  [ "$status" -eq 0 ]
+
+  keymap="$BATS_TEST_TMPDIR/zed-config/keymap.json"
+  [ "$(jq 'length' "$keymap")" = "2" ]
+  [ "$(jq -r '.[0].bindings["cmd-shift-d"][0]' "$keymap")" = "task::Spawn" ]
+  [ "$(jq -r '.[1].context' "$keymap")" = "Editor && extension == md" ]
+  [ "$(jq -r '.[1].bindings["cmd-k i"][0]' "$keymap")" = "editor::InsertSnippet" ]
+  [ "$(jq -r '.[1].bindings["cmd-k i"][1].snippet' "$keymap")" = "$snippet" ]
+}
+
+@test "zed:keymap:check-snippet accepts an identical binding without writing" {
+  mkdir -p "$BATS_TEST_TMPDIR/zed-config"
+  cat > "$BATS_TEST_TMPDIR/zed-config/keymap.json" <<'JSON'
+[
+  {
+    "context": "Editor && extension == md",
+    "bindings": {
+      "cmd-k i": ["editor::InsertSnippet", {"snippet": "<!-- ! review -->$0"}]
+    }
+  }
+]
+JSON
+  before="$(cat "$BATS_TEST_TMPDIR/zed-config/keymap.json")"
+
+  ZED_CONFIG_HOME="$BATS_TEST_TMPDIR/zed-config" run ctl zed:keymap:check-snippet \
+    --context 'Editor && extension == md' \
+    --keystroke 'cmd-k i' \
+    --snippet '<!-- ! review -->$0'
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"is available"* ]]
+  [ "$(cat "$BATS_TEST_TMPDIR/zed-config/keymap.json")" = "$before" ]
+}
+
+@test "zed:keymap:check-snippet rejects a conflicting binding without writing" {
+  mkdir -p "$BATS_TEST_TMPDIR/zed-config"
+  cat > "$BATS_TEST_TMPDIR/zed-config/keymap.json" <<'JSON'
+[
+  {
+    "context": "Editor && extension == md",
+    "bindings": {
+      "cmd-k i": "editor::Format"
+    }
+  }
+]
+JSON
+  before="$(cat "$BATS_TEST_TMPDIR/zed-config/keymap.json")"
+
+  ZED_CONFIG_HOME="$BATS_TEST_TMPDIR/zed-config" run ctl zed:keymap:check-snippet \
+    --context 'Editor && extension == md' \
+    --keystroke 'cmd-k i' \
+    --snippet '<!-- ! review -->$0'
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"already exists with a different value"* ]]
+  [ "$(cat "$BATS_TEST_TMPDIR/zed-config/keymap.json")" = "$before" ]
+}
+
+@test "zed:keymap:bind-snippet requires force to replace a conflicting binding" {
+  mkdir -p "$BATS_TEST_TMPDIR/zed-config"
+  cat > "$BATS_TEST_TMPDIR/zed-config/keymap.json" <<'JSON'
+[
+  {
+    "context": "Editor && extension == md",
+    "bindings": {
+      "cmd-k i": "editor::Format"
+    }
+  }
+]
+JSON
+
+  ZED_CONFIG_HOME="$BATS_TEST_TMPDIR/zed-config" run ctl zed:keymap:bind-snippet \
+    --context 'Editor && extension == md' \
+    --keystroke 'cmd-k i' \
+    --snippet '<!-- ! review -->$0'
+  [ "$status" -ne 0 ]
+  [ "$(jq -r '.[0].bindings["cmd-k i"]' "$BATS_TEST_TMPDIR/zed-config/keymap.json")" = "editor::Format" ]
+
+  ZED_CONFIG_HOME="$BATS_TEST_TMPDIR/zed-config" run ctl zed:keymap:bind-snippet \
+    --context 'Editor && extension == md' \
+    --keystroke 'cmd-k i' \
+    --snippet '<!-- ! review -->$0' \
+    --force
+  [ "$status" -eq 0 ]
+  [ "$(jq -r '.[0].bindings["cmd-k i"][0]' "$BATS_TEST_TMPDIR/zed-config/keymap.json")" = "editor::InsertSnippet" ]
+}
+
+@test "zed:keymap:bind-snippet is idempotent" {
+  snippet='<!-- ! "@ikma ${1:feedback}" | mise comment -->$0'
+  for _ in 1 2; do
+    ZED_CONFIG_HOME="$BATS_TEST_TMPDIR/zed-config" ctl zed:keymap:bind-snippet \
+      --context 'Editor && extension == md' \
+      --keystroke 'cmd-k i' \
+      --snippet "$snippet" >/dev/null
+  done
+
+  keymap="$BATS_TEST_TMPDIR/zed-config/keymap.json"
+  [ "$(jq 'length' "$keymap")" = "1" ]
+  [ "$(jq '.[0].bindings | keys | length' "$keymap")" = "1" ]
+}
diff --git a/test/zed/tasks.bats b/test/zed/tasks.bats
index 586f599..f2e613c 100644
--- a/test/zed/tasks.bats
+++ b/test/zed/tasks.bats
@@ -152,6 +152,129 @@ JSON
   [ "$(cat "$BATS_TEST_TMPDIR/.zed/tasks.json")" = '{"label":"not an array"}' ]
 }
 
+@test "zed:tasks:upsert emits optional reveal shell and environment fields" {
+  CTL_CALLER_PWD="$BATS_TEST_TMPDIR" run ctl zed:tasks:upsert \
+    --label "comments: dispatch current file" \
+    --command comments \
+    --arg dispatch \
+    --arg '$ZED_FILE' \
+    --save current \
+    --reveal never \
+    --hide on_success \
+    --shell-program /bin/zsh \
+    --shell-arg=-f \
+    --shell-arg=-l \
+    --env COMMENT_CHAT_AS=or \
+    --env 'GREETING=hello world'
+  [ "$status" -eq 0 ]
+
+  tasks="$BATS_TEST_TMPDIR/.zed/tasks.json"
+  jq -e '.[0] == {
+    "label": "comments: dispatch current file",
+    "command": "comments",
+    "args": ["dispatch", "$ZED_FILE"],
+    "save": "current",
+    "reveal": "never",
+    "hide": "on_success",
+    "shell": {"with_arguments": {"program": "/bin/zsh", "args": ["-f", "-l"]}},
+    "env": {"COMMENT_CHAT_AS": "or", "GREETING": "hello world"}
+  }' "$tasks"
+}
+
+@test "zed:tasks:upsert uses simple shell form and omits unused fields" {
+  CTL_CALLER_PWD="$BATS_TEST_TMPDIR" run ctl zed:tasks:upsert \
+    --label simple \
+    --command true \
+    --shell-program /bin/sh
+  [ "$status" -eq 0 ]
+
+  tasks="$BATS_TEST_TMPDIR/.zed/tasks.json"
+  [ "$(jq -r '.[0].shell.program' "$tasks")" = "/bin/sh" ]
+  [ "$(jq '.[0].args | length' "$tasks")" = "0" ]
+  [ "$(jq '.[0] | has("reveal")' "$tasks")" = "false" ]
+  [ "$(jq '.[0] | has("env")' "$tasks")" = "false" ]
+}
+
+@test "zed:tasks:upsert validates task policy enums before writing" {
+  for specification in 'save=sometimes' 'reveal=on_success' 'hide=no_focus'; do
+    field="${specification%%=*}"
+    value="${specification#*=}"
+    caller="$BATS_TEST_TMPDIR/$field"
+    mkdir -p "$caller"
+
+    run env CTL_CALLER_PWD="$caller" \
+      mise -C "$REPO_DIR" run -q zed:tasks:upsert \
+      --label invalid \
+      --command true \
+      "--$field" "$value"
+
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"invalid $field value: $value"* ]]
+    [ ! -e "$caller/.zed/tasks.json" ]
+  done
+}
+
+@test "zed:tasks:upsert requires a shell program before shell arguments" {
+  CTL_CALLER_PWD="$BATS_TEST_TMPDIR" run ctl zed:tasks:upsert \
+    --label invalid \
+    --command true \
+    --shell-arg=-f
+
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"--shell-arg requires --shell-program"* ]]
+  [ ! -e "$BATS_TEST_TMPDIR/.zed/tasks.json" ]
+}
+
+@test "zed:tasks:upsert validates environment entries before writing" {
+  for entry in 'MISSING_EQUALS' 'BAD-NAME=value'; do
+    caller="$BATS_TEST_TMPDIR/$(printf '%s' "$entry" | tr '=-' '__')"
+    mkdir -p "$caller"
+
+    CTL_CALLER_PWD="$caller" run ctl zed:tasks:upsert \
+      --label invalid \
+      --command true \
+      --env "$entry"
+
+    [ "$status" -ne 0 ]
+    [ ! -e "$caller/.zed/tasks.json" ]
+  done
+
+  caller="$BATS_TEST_TMPDIR/duplicate"
+  mkdir -p "$caller"
+  CTL_CALLER_PWD="$caller" run ctl zed:tasks:upsert \
+    --label invalid \
+    --command true \
+    --env NAME=one \
+    --env NAME=two
+
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"duplicate environment name: NAME"* ]]
+  [ ! -e "$caller/.zed/tasks.json" ]
+}
+
+@test "zed:tasks:upsert replaces the whole environment for a matching label" {
+  mkdir -p "$BATS_TEST_TMPDIR/.zed"
+  cat > "$BATS_TEST_TMPDIR/.zed/tasks.json" <<'JSON'
+[
+  {
+    "label": "review",
+    "command": "old",
+    "env": {"OLD": "value"}
+  }
+]
+JSON
+
+  CTL_CALLER_PWD="$BATS_TEST_TMPDIR" run ctl zed:tasks:upsert \
+    --label review \
+    --command comments \
+    --env NEW=value
+  [ "$status" -eq 0 ]
+
+  tasks="$BATS_TEST_TMPDIR/.zed/tasks.json"
+  [ "$(jq -r '.[0].env.NEW' "$tasks")" = "value" ]
+  [ "$(jq '.[0].env | has("OLD")' "$tasks")" = "false" ]
+}
+
 @test "doctor reports optional pre-commit hook state" {
   run ctl doctor
   [ "$status" -eq 0 ]