Update to Freckle

{
  "description": "Freckle setup — install and authenticate the `freckle` CLI, which is how the plugin talks to Freckle. Use when `freckle` is not found on PATH or the `freckle` found on PATH is the wrong version, `freckle auth status` fails, the CLI isn't signed in, or the user wants to configure Freckle. Signs the user in for new users.",
  "included_files": [],
  "name": "setup",
  "skill_md_contents": "---\nname: setup\ndescription: Freckle setup — install and authenticate the `freckle` CLI, which is how the plugin talks to Freckle. Use when `freckle` is not found on PATH or the `freckle` found on PATH is the wrong version, `freckle auth status` fails, the CLI isn't signed in, or the user wants to configure Freckle. Signs the user in for new users.\nallowed-tools: Bash, Read, Edit, Write\n---\n\n# Freckle setup\n\nSkills reach Freckle through the **`freckle` CLI**. **`freckle auth`** runs a device flow once\nand stores the credential on disk; the CLI re-reads it on every command, so `freckle auth status`\nsucceeding is the whole proof.\n\n## 1. Check current state\n\nRun this and read the printed **exit code and output**, not any status string:\n\n```bash\nfreckle auth status; echo \"exit_code=$?\"\n```\n\n- **exit_code=0** and the output shows a signed-in identity → the CLI is authenticated.\n  Also confirm it isn't an old install shadowing the bundled launcher, which an\n  auth check alone can't tell you — compare the resolved version against the\n  release this plugin pins in `bin/cli-version` (two levels up from this skill's\n  directory):\n\n  ```bash\n  # Prints e.g. `freckle v1.0.0`; compare the semver part.\n  freckle --version\n  # The pin is a full release tag like cli-v1.0.0-r299-3b81ee5; extract its semver.\n  sed -e 's/^cli-v//' -e 's/-r.*//' \"<THIS_SKILL_DIR>/../../bin/cli-version\"\n  ```\n\n  - **same version, or newer than the pin** → the CLI is current. Tell the user\n    (name the signed-in identity) and stop.\n  - **older than the pin** → an outdated `freckle` is shadowing the bundled\n    launcher. Do step 2 to put the launcher ahead of it on PATH, then re-run\n    this check.\n\n- **`freckle: command not found`** (or exit 127) → the CLI isn't on your PATH.\n  Route by platform:\n  - **Claude Code**: if the plugin was just installed in this session, this is expected —\n    Claude Code only adds a newly installed plugin's `bin/` to PATH starting with the\n    _next_ session. Don't install a forwarder for this: resolve the bundled launcher's\n    absolute path once and invoke that directly for the rest of this session instead of\n    waiting on a restart —\n\n    ```bash\n    launcher=\"$(sh -c 'ls -1dt \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}\"/plugins/cache/*/freckle/*/bin/freckle 2>/dev/null | head -n1')\"\n    [ -x \"$launcher\" ] || { echo \"could not locate the bundled freckle launcher; reinstall the plugin\"; exit 1; }\n    \"$launcher\" auth status; echo \"exit_code=$?\"\n    ```\n\n    Use this same resolved path in place of bare `freckle` for every remaining command in\n    this skill (step 3's `freckle auth` included) — but re-run the `ls -1dt` one-liner\n    fresh immediately before each one rather than reusing `$launcher` across separate tool\n    calls: each Bash call starts a new shell, so a variable set in one call is gone in\n    the next. Bare `freckle` starts working again on its own once the agent is next\n    restarted, so no restart is needed just for PATH. Only fall back to step 2's\n    forwarder if the launcher can't be located at all (e.g. the plugin cache is gone),\n    if another `freckle` install is shadowing the bundled one after a restart, or if\n    bare `freckle` is still not found after a restart — that last case means the\n    next-session auto-PATH isn't happening, so this is no longer a one-restart hiccup\n    the launcher path can paper over.\n\n  - **Codex**: go straight to step 2, then step 3 — Codex does not add a plugin's\n    `bin/` to PATH automatically, so restarting alone won't fix this.\n\n- **Any other nonzero exit** with output saying the CLI isn't authenticated → the CLI\n  works but isn't signed in. Skip to step 3.\n- **Network errors** → check the network and any `HTTP_API_ORIGIN` override; do not\n  restart the sign-in flow.\n\n## 2. Put `freckle` on your PATH (if it was \"command not found\" or is an outdated version)\n\nThe plugin bundles the CLI launcher at `bin/freckle` in the plugin root; it downloads\nand checksum-verifies the real binary on first use. The launcher is version-stable\n(it reads its neighbor `bin/cli-version` and fetches that release), so the forwarder\njust needs to point at the newest launcher on disk.\n\nInstall a small forwarder onto your PATH (in `~/.local/bin`) that resolves the\nnewest bundled launcher **at runtime** rather than baking in one absolute path.\nThis is what lets it survive plugin updates (which install a new version directory)\nand work no matter which agent (Claude Code / Codex) installed the plugin. It picks\nthe most-recently-modified launcher; if one agent's cache lags behind another's, the\nfreshest install wins — every launcher is self-contained, so it still runs a valid\nchecksum-verified CLI.\n\nFirst confirm a launcher actually exists where the forwarder will look — this is\nthe same resolution the forwarder performs, run once now so a missing plugin\ncache fails loudly here instead of as a confusing 127 later (run it through `sh`\nso unmatched globs stay harmless even if your shell is zsh):\n\n```bash\nsh -c 'ls -1dt \\\n  \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}\"/plugins/cache/*/freckle/*/bin/freckle \\\n  \"${CODEX_HOME:-$HOME/.codex}\"/plugins/cache/*/freckle/*/bin/freckle \\\n  2>/dev/null | head -n1'\n```\n\nIf this prints nothing, **stop** — no bundled launcher exists in any known plugin\ncache, so the forwarder below would have nothing to exec. Tell the user to\nreinstall the Freckle plugin, then re-run this skill. (If you read this SKILL.md\nfrom a plugin root outside these caches, report that path to the user — the\nplugin is installed somewhere this forwarder doesn't search.)\n\nIf it printed a path, install the forwarder (keep its search list in sync with\nthe pre-flight above and with step 1's Claude Code one-liner):\n\n```bash\nmkdir -p \"$HOME/.local/bin\"\ncat > \"$HOME/.local/bin/freckle\" <<'EOF'\n#!/bin/sh\n# Resolve the newest bundled freckle launcher at runtime so this forwarder\n# survives plugin version bumps and works whichever agent (Claude Code / Codex)\n# installed it. CLAUDE_CONFIG_DIR and CODEX_HOME relocate those agents' state\n# roots (and with them the plugin cache), so honor them when set — they expand\n# here at runtime, from the invoking process's environment.\nlauncher=\"$(ls -1dt \\\n  \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}\"/plugins/cache/*/freckle/*/bin/freckle \\\n  \"${CODEX_HOME:-$HOME/.codex}\"/plugins/cache/*/freckle/*/bin/freckle \\\n  2>/dev/null | head -n1)\"\nif [ -z \"$launcher\" ] || [ ! -x \"$launcher\" ]; then\n  printf 'Error: %s\\n' 'freckle: no bundled launcher found (reinstall the Freckle plugin)' >&2\n  exit 127\nfi\nexec \"$launcher\" \"$@\"\nEOF\nchmod +x \"$HOME/.local/bin/freckle\"\n```\n\nThen make sure `~/.local/bin` is on PATH (most shells already have it):\n\n```bash\ncase \":$PATH:\" in *\":$HOME/.local/bin:\"*) echo \"on PATH\" ;; *) echo \"not on PATH\" ;; esac\n```\n\nIf it prints `not on PATH`, add `export PATH=\"$HOME/.local/bin:$PATH\"` to the\nuser's shell profile (`~/.zshrc` or `~/.bashrc`) and use the absolute path\n`\"$HOME/.local/bin/freckle\"` for the rest of this session.\n\nRe-run the step 1 check before continuing.\n\n> **Alternative — full install.** The standalone installer\n> `sh -c \"$(curl -fsSL https://install.freckle.io)\"` installs the CLI directly to\n> `~/.local/bin` with self-update enabled and also sets up agent skills outside\n> this plugin. Use it when the user wants Freckle available outside plugin-managed\n> agents; the plugin works with either.\n\n## 3. Sign in\n\n`freckle auth` is a device flow you run on the user's behalf. It opens the approval\npage in the user's browser, prints a short one-time user code, and waits up to 15\nminutes for approval. The credential lands directly in the CLI's local config; nothing\nsensitive crosses the terminal or the conversation, and the user code itself is not a\nsecret — show it to the user so they can match it in the browser.\n\n```bash\nfreckle auth\n```\n\nWhile the command waits, tell the user to approve the request in the opened browser\ntab — signing in or creating an account there first is part of the same flow, and if\nno browser opened, the printed URL gets them there. The command exits 0 once approved;\nconfirm with `freckle auth status`.\n\nWhen device authorization is unavailable or there is no browser (headless or remote\nshells), the user creates a token at https://next.freckle.io/cli-auth and you run:\n\n```bash\nfreckle auth --token <frk_token>\n```\n\nAuth also resolves from `FRECKLE_CLI_TOKEN`.\n\n## 4. Done\n\nRe-run the step 1 check to confirm, tell the user who is signed in, and continue with\nwhatever task brought you here — the `freckle` skill routes all Freckle work.\n"
}