fix(cargo): symlink project CARGO_HOME/bin to ~/.cargo/bin, add PATH

The _setup-cargo-home task was symlinking to the mise install dir,
which contains relative multicall symlinks that break when rustup
is missing from that directory. Instead:

- Symlink project-local CARGO_HOME/bin/<tool> to ~/.cargo/bin/<tool>
- Add ~/.cargo/bin to PATH in cargo.yml env so rustup is findable
- Document the three-directory structure in AGENTS.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pythoninthegrass

AGENTS.md

@@ -72,7 +72,15 @@ See [Tauri Architecture](docs/tauri-architecture.md) for full details.
 
 ### Rust Toolchain (mise + rustup)
 
-mise manages the Rust version (via `.tool-versions`) but delegates to rustup under the hood. The mise install directory (`~/.local/share/mise/installs/rust/<version>/`) contains symlinks like `cargo -> rustup` — these are rustup multicall symlinks that require the `rustup` binary to be resolvable. The `cargo:_setup-cargo-home` task in `taskfiles/cargo.yml` creates `$CARGO_HOME/bin` symlinks pointing directly at `$CARGO_HOME/bin/rustup` (the real binary) rather than chaining through the mise install dir, which would break if the relative `rustup` target is missing.
+Three directories are involved — do NOT cross-link them:
+
+| Directory | Purpose | Managed by |
+|-----------|---------|------------|
+| `~/.cargo/bin/` | Real rustup binary + multicall symlinks (`cargo -> rustup`) | rustup |
+| `~/.local/share/mise/installs/rust/<version>/` | Relative multicall symlinks (`cargo -> rustup`) + rustup copy | mise |
+| `$CARGO_HOME/bin/` (project-local `.cache/cargo/bin/`) | Symlinks to `~/.cargo/bin/<tool>` | `cargo:_setup-cargo-home` task |
+
+`cargo.yml` adds `~/.cargo/bin` to PATH so rustup tools are always findable. The `_setup-cargo-home` task symlinks project-local `CARGO_HOME/bin/` to `~/.cargo/bin/` — never to the mise install dir, which has its own internal symlink structure.
 
 ## Queue and Shuffle Behavior
 

taskfiles/cargo.yml

@@ -3,6 +3,9 @@ version: "3.0"
 set: ['e', 'u', 'pipefail']
 shopt: ['globstar']
 
+env:
+  PATH: "{{.HOME}}/.cargo/bin:{{.PATH}}"
+
 tasks:
   _setup-cargo-home:
     internal: true
@@ -11,13 +14,13 @@ tasks:
       - |
         cargo_bin="$CARGO_HOME/bin"
         mkdir -p "$cargo_bin"
-        rustup_bin="$cargo_bin/rustup"
-        if [[ ! -x "$rustup_bin" ]]; then
-          echo "error: rustup not found at $rustup_bin" >&2
-          exit 1
-        fi
+        src="${HOME}/.cargo/bin"
         for tool in cargo cargo-clippy cargo-fmt rustc rustdoc rustfmt; do
-          ln -sf "$rustup_bin" "$cargo_bin/$tool"
+          if [[ ! -x "$src/$tool" ]]; then
+            echo "error: $src/$tool not found" >&2
+            exit 1
+          fi
+          ln -sf "$src/$tool" "$cargo_bin/$tool"
         done
     status:
       - test -L "$CARGO_HOME/bin/cargo" && test -e "$CARGO_HOME/bin/cargo"