docs(skills): fix MCP method references and dedupe shared guidance (#452)

* docs(skills): fix MCP method references and dedupe shared guidance

Review pass over the three issue-workflow skill commands:

- Add frontmatter (description + argument-hint) to all three so they
  surface properly in the slash-command picker.
- plan-issues: issue_read's default `get` method does not return
  comments — call `get_comments` separately for triage comments.
- address-review: get_review_comments now returns threads with
  isResolved/isOutdated flags; skip resolved/outdated threads instead
  of re-addressing them. Qualify get_check_runs as a pull_request_read
  method.
- Replace verbatim duplication of guidance promoted to AGENTS.md in
  #444 (model-selection table, CI/coverage triage principles, GitHub
  MCP heredoc note) with pointers, so the skills can't drift from the
  canonical copy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* chore(mcp): expose mise as a project MCP server

Add a project-scoped .mcp.json that runs `./bin/mise mcp`, exposing
mise tasks, tools, env, and config to AI assistants over stdio. The
server provides the run_task tool plus mise://tasks, mise://tools,
mise://env, and mise://config resources.

Pre-approve it via enabledMcpjsonServers in .claude/settings.json so
web/remote sessions trust it without a manual approval prompt.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* Revert "chore(mcp): expose mise as a project MCP server"

The mise MCP server is redundant in this environment: `mise … --json`
(tasks ls, ls, config ls, env) already returns the same structured data
the mise:// resources expose, via the already-allowlisted CLI. run_task
duplicates the existing `./bin/mise run` allowlist and loses the
log-file grep workflow the test/analyze tasks provide. MCP's real edge
is reaching systems the shell can't (GitHub API, browser, DBs) — not
wrapping a local CLI that already speaks JSON.

This reverts commit 4506fea.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* docs(agents): note mise --json for structured introspection

Most mise introspection commands (tasks ls, ls, config ls, env) support
--json. Prefer it over scraping the human-readable text when parsing
output programmatically.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* chore(mise): auto-activate sandboxed + dev envs on Claude Code Web

Add .miserc.toml that detects CLAUDE_CODE_REMOTE=true and selects the
`sandboxed` and `dev` envs automatically, so plain `./bin/mise` (e.g.
the session-start hook) gets the right config without anyone passing
MISE_ENV by hand. Off the sandbox both entries render empty → no-op.

- sandboxed: existing git-transport fix (libgit2/gix off) now applies
  on web automatically, and Node is pinned to the image-baked
  /opt/node22 (path: backend) to skip a redundant download. The
  version-metadata host is blocked by the sandbox proxy, but the four
  pinned tools resolve via their own backends, so this is an
  optimisation rather than a fix.
- dev: watchexec/buf/api-linter become available without MISE_ENV=dev,
  and sandboxed's libgit2=off is what lets the github-backend api-linter
  install in the sandbox.

Note in AGENTS.md that MISE_ENV=dev must NOT be set on web (it overrides
.miserc.toml and drops the sandbox env); it's still required locally/CI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* chore(mise): rename sandboxed env to claude-code-web

Rename mise.sandboxed.toml → mise.claude-code-web.toml and update the
.miserc.toml selector + AGENTS.md note to match. The env name now states
exactly what it targets (the Claude Code on Web sandbox) and aligns with
the convention used in sibling repos. Behaviour is unchanged: git mv
preserves history, and the env still auto-activates via CLAUDE_CODE_REMOTE
alongside dev.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* docs(mise): warn against setting MISE_ENV in the web environment config

An explicit MISE_ENV overrides .miserc.toml, so a leftover
MISE_ENV=dev,sandboxed at the environment level would shadow this file
and — after the sandboxed→claude-code-web rename — silently load nothing
for the missing env. Document the footgun next to the selector.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* refactor(mise): hoist the CLAUDE_CODE_REMOTE check in .miserc.toml

The two env entries gated on the same condition. Compute it once into a
Tera `on_web` variable and emit both env names together, so off-sandbox
resolves to a clean `env = []` instead of two empty-string elements.
Behaviour is unchanged (verified: in-sandbox loads claude-code-web+dev
with node pinned and libgit2 off; off-sandbox stays base-only).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

* refactor(mise): omit the env key entirely off-sandbox

Wrap the whole `env = [...]` line in the CLAUDE_CODE_REMOTE conditional
so off-sandbox the key is absent rather than an empty list. On web it
renders the two env names; elsewhere .miserc.toml is just comments.
Verified unchanged activation on both paths.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016osYfpqBmMA5DZ82au86Cd

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: richardthe3rd

.claude/commands/address-review.md

@@ -1,3 +1,8 @@
+---
+description: Triage review comments on PRs and spawn fixup agents for actionable findings
+argument-hint: "[branch ...] (omit to triage all watched PRs)"
+---
+
 # Address Review Findings
 
 Triage review comments on one or more PRs and spawn fixup agents for actionable findings.
@@ -11,8 +16,8 @@ Or just: `/address-review` to triage all open PRs being watched in this session.
 
 For each branch / PR:
 
-1. Fetch review comments via `mcp__github__pull_request_read` (method: `get_review_comments`).
-2. Check current CI status (`get_check_runs`) before evaluating any comment.
+1. Fetch review threads via `mcp__github__pull_request_read` (method: `get_review_comments`). Each thread carries `isResolved` / `isOutdated` flags — skip threads already resolved or outdated; they need no action.
+2. Check current CI status via `mcp__github__pull_request_read` (method: `get_check_runs`) before evaluating any comment.
 3. Triage each comment:
    - **Fix** — correct finding, confined to the PR's allowed files, clear how to resolve
    - **Skip** — contradicted by passing CI, factually wrong, out of scope, or pure style preference
@@ -23,11 +28,11 @@ For each branch / PR:
 
 ## Triage principles
 
-- **CI is ground truth.** If tests and analyzer pass, a "this won't compile" comment is wrong — skip it.
-- **Verify type hierarchy claims.** Automated reviewers sometimes get subtype relationships wrong; check the language/SDK docs before acting.
-- **Internal implementation files don't need barrel exports.** Files only meant to be imported via conditional imports or as private implementation details should not be added to public barrels.
-- **Coverage warnings are informational** unless the `codecov/patch` check itself fails (not just the comment).
-- **Pure refactors inherit prior coverage.** Moved code that was untested before is not a new gap.
+The shared triage facts live in AGENTS.md — consult them before evaluating any comment:
+- **CI and Coverage** — CI is ground truth; coverage warnings are informational unless `codecov/patch` itself fails; pure refactors inherit prior coverage.
+- **Dart / Flutter Type Facts** and **Proto / AIP Design Facts** — verify subtype/annotation claims; internal conditional-import stubs don't belong in barrel exports.
+
+Automated reviewers are frequently wrong about type hierarchies and "won't compile" claims when CI is green. When in doubt, trust the analyzer over the comment.
 
 ## Fixup agent constraints
 

.claude/commands/plan-issues.md

@@ -1,3 +1,8 @@
+---
+description: Spawn parallel planning agents for one or more GitHub issues
+argument-hint: "<issue-number> [issue-number ...]"
+---
+
 # Plan Issues
 
 Spawn parallel planning agents for one or more GitHub issue numbers.
@@ -8,7 +13,7 @@ Usage: `/plan-issues #270 #324` or `/plan-issues 270 324 355`
 
 For each issue number provided:
 
-1. Read the issue from GitHub (`mcp__github__issue_read`) to get the title, body, and any triage comments.
+1. Read the issue from GitHub: `mcp__github__issue_read` (method: `get`) for the title and body, then (method: `get_comments`) for any triage comments — `get` alone does not return comments.
 2. Explore the affected files to understand the current code.
 3. Produce a plan in the exact contract format below.
 
@@ -38,11 +43,7 @@ Done signal: (what "done" looks like)
 
 ## Model selection guide
 
-| Use haiku for | Use sonnet for |
-|---|---|
-| Single-file mechanical changes | Multi-file architectural changes |
-| Tests following an established pattern | Nullable/sentinel patterns, type system changes |
-| ≤2 files with a grep-based done signal | Cascading updates across 6+ files |
+See the model selection table in AGENTS.md ("Parallel Work with Subagents → Model Selection"). In short: **haiku** for single-file mechanical changes and pattern-following tests; **sonnet** for multi-file or architectural changes, nullable/sentinel patterns, and type-system work.
 
 ---
 

.claude/commands/ship-issues.md

@@ -1,3 +1,8 @@
+---
+description: Full plan → implement → review → PR → watch cycle for GitHub issues
+argument-hint: "<issue-number> [issue-number ...]"
+---
+
 # Ship Issues
 
 Full plan → implement → review → fix → PR → watch cycle for one or more GitHub issues.
@@ -49,4 +54,4 @@ The session ends when all PRs are green and have no unresolved review threads.
 - Implementation agents use `isolation: "worktree"` — this creates worktrees inside the repo at `.claude/worktrees/`, which is required for commit signing in the managed environment.
 - Fix branches target `main` directly. The session branch (`claude/session-*`) is for session-level changes (AGENTS.md updates, etc.).
 - Always run `./bin/mise run` commands, never raw `flutter` — see AGENTS.md for the full command reference.
-- MCP tool parameters take plain strings — do not use `$(cat <<'EOF'...)` heredoc syntax in `body` fields; it will appear literally in the PR description.
+- MCP tool parameters take plain strings — no `$(cat <<'EOF'...)` heredoc syntax in `body` fields (see AGENTS.md → "GitHub MCP Notes").

.miserc.toml

@@ -0,0 +1,16 @@
+# Loaded before any mise.<env>.toml; its `env` key selects which env configs
+# apply. Tera here only sees OS-level context (env vars, cwd), which is enough
+# to detect the Claude Code on web sandbox via CLAUDE_CODE_REMOTE and activate
+# the right envs automatically (no need to pass MISE_ENV by hand):
+#   - claude-code-web: git-transport fix + Node pinned to the baked /opt/node22
+#   - dev:             developer tooling (watchexec, buf, api-linter) so agents
+#                      can run build/proto/e2e tasks without MISE_ENV=dev
+# `human` is intentionally NOT selected — those tools are for local machines.
+# Off the sandbox the condition is false and the `env` key is omitted entirely.
+#
+# NOTE: an explicit MISE_ENV environment variable overrides this file entirely.
+# Do NOT also set MISE_ENV in the Claude Code Web environment config — it would
+# shadow this file (and silently load nothing for any renamed/removed env).
+{% if env.CLAUDE_CODE_REMOTE | default(value='') == 'true' %}
+env = ["claude-code-web", "dev"]
+{% endif %}

AGENTS.md

@@ -88,6 +88,15 @@ The app uses a layered architecture:
 MISE_ENV=dev ./bin/mise tasks ls      # All tasks including build/serve
 ```
 
+Add `--json` when you need to parse the output rather than read it — most introspection commands support it, so prefer it over scraping the human-readable text:
+
+```bash
+./bin/mise tasks ls --json            # Task name, description, source, depends
+./bin/mise ls --json                  # Installed tools + versions/paths
+./bin/mise config ls --json           # Config files and their tools
+./bin/mise env --json                 # Resolved environment variables
+```
+
 ### Common Tasks
 
 | Task | Command | Notes |
@@ -115,6 +124,8 @@ MISE_ENV=dev ./bin/mise tasks ls      # All tasks including build/serve
 
 **Rule**: Building or running the app → always use `MISE_ENV=dev`.
 
+> **On Claude Code Web** (`CLAUDE_CODE_REMOTE=true`), `.miserc.toml` auto-selects the `claude-code-web` (`mise.claude-code-web.toml`) and `dev` envs, so plain `./bin/mise` already exposes the dev tasks (and pins Node to the baked `/opt/node22` + applies the git-transport fix). Do **not** prefix `MISE_ENV=dev` there — an explicit `MISE_ENV` overrides `.miserc.toml` and drops the web env. Locally and in CI, `MISE_ENV=dev` is still required.
+
 ### CI → Mise Mapping
 
 | CI Command | Mise Equivalent |

mise.claude-code-web.toml

@@ -0,0 +1,30 @@
+# Claude Code Web Environment Configuration
+#
+# IMPORTANT: Only needed for the Claude Code on Web sandbox.
+# Desktop Claude Code and local development do NOT need these settings.
+#
+# Auto-activated via .miserc.toml, which detects CLAUDE_CODE_REMOTE=true and
+# selects this env — so a plain `./bin/mise install` (e.g. the session-start
+# hook) picks it up with no MISE_ENV needed.
+#
+# An explicit MISE_ENV overrides .miserc.toml, so to combine with developer
+# tools yourself include this env: MISE_ENV=claude-code-web,dev.
+# Multiple environments can be specified with the last taking precedence for
+# conflicting values; settings from this file are merged with the others.
+#
+# Why these settings exist:
+# - The web sandbox restricts git operations
+# - libgit2 and gix cause "Failed to configure the transport" errors
+# - Disabling them allows mise to use alternative git methods
+
+[settings]
+# Disable libgit2 and gix to prevent Flutter installation errors in the web sandbox
+libgit2 = false
+gix = false
+
+[tools]
+# Reuse the Node runtime baked into the web-sandbox image instead of downloading
+# a fresh copy at session start. The base config pins node = "22"; here we point
+# at /opt/node22 (a path: backend, so no version metadata is fetched). Only
+# applies when this env is active, i.e. on Claude Code Web — local/CI keep "22".
+node = "path:/opt/node22"