`/write-pr-description-to-freshjots <pr-url>` — craft a PR write-up, store it, back it up locally

I want you to install a `/write-pr-description-to-freshjots` slash command for Claude Code, end to end. Walk me through it conversationally; ask me only what you genuinely can't figure out yourself. Be safe: show diffs before writing any file in my home directory, and never write my API token to any file in the current project or echo it back to me after I paste it.

End state we're aiming for:
- A slash command file at ~/.claude/commands/write-pr-description-to-freshjots.md (full content in step 3 below).
- A "pr_descriptions" folder created on freshjots.com, with its id cached locally at ~/.claude/freshjots-stash/.pr-descriptions-folder-id.
- My shell profile (~/.zshrc if my $SHELL ends in zsh, otherwise ~/.bashrc) exports FRESHJOTS_TOKEN (skipped if it already does).

After setup, typing `/write-pr-description-to-freshjots <pr-url>` in any Claude Code session will: (a) read that PR through the GitHub CLI, (b) compose a structured PR description, (c) write a local backup to ~/.claude/freshjots-stash/ that is kept indefinitely, (d) POST the description to Fresh Jots as a new note inside pr_descriptions, (e) report the note id, the backup path, and a ready-to-run `gh pr edit` command.

Idempotent by design: if I re-run this prompt later, every step should detect existing state (env var set, slash command file unchanged, folder already created) and no-op. Tell me which steps you skipped and why.

Step 1 — Confirm intent. Tell me in one sentence what you're about to do. Ask me to type "yes" before you touch any file. After I've confirmed once, you can proceed through the remaining steps without asking again unless you hit a destructive edit you can't reverse.

Step 2 — Token bootstrap.
- Check presence without printing the value: `[ -n "${FRESHJOTS_TOKEN:-}" ] && echo set || echo unset`. Use that output, never `printenv FRESHJOTS_TOKEN` or `echo $FRESHJOTS_TOKEN` (those would dump the value into the transcript).
- **If "set"** (the token was already exported when Claude Code launched): verify with `curl -sS -o /dev/null -w '%{http_code}' --max-time 15 -H "Authorization: Bearer $FRESHJOTS_TOKEN" https://freshjots.com/api/v1/folders`. The literal `$FRESHJOTS_TOKEN` stays in the command as written; the shell expands it at runtime, so the actual value never appears in stdout, stderr, or the transcript. Expect 200. On 401, tell me my token is set but rejected, and ask me to generate a fresh one. On success, jump to step 2b (you must still run the GitHub CLI check — the slash command depends on `gh`) — and do NOT touch my shell profile, the token is already wired in.
- **If "unset"**, tell me: "Go to https://freshjots.com, sign up (free, no card). At onboarding, pick 'Software development' mode — that gets you a 14-day Pro trial token automatically. If you already have a Pro account, Settings → API tokens → Create token. Either way, you'll end up with an `mn_...` string. Paste it here when you have it."
- Once I paste a token, verify it with one curl call, substituting the literal `mn_...` value into the Authorization header (this single command is the only place the value appears outside my shell profile — unavoidable for the paste-in-chat flow): `curl -sS -o /dev/null -w '%{http_code}' --max-time 15 -H "Authorization: Bearer mn_THE_VALUE_I_PASTED" https://freshjots.com/api/v1/folders`. Expect 200. On 401, tell me politely "that token didn't work — paste another?" and retry up to 3 times.
- After verification, append `export FRESHJOTS_TOKEN="mn_..."` to my shell profile (~/.zshrc if my $SHELL ends in zsh, otherwise ~/.bashrc). Show me the diff before writing. If `grep -l FRESHJOTS_TOKEN ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null` finds it elsewhere already, skip this step and tell me where it lives.
- Never write the raw token to any file in the current repo, and never echo it back into the chat after that one verify call. From this step on, refer to it only as `$FRESHJOTS_TOKEN` in any bash command — let the shell expand it.

Step 2b — GitHub CLI check. Confirm `gh` is installed (`command -v gh`) and authenticated (`gh auth status`). If `gh` is missing, tell me the one install command for my platform (apt/dnf/brew/pacman based on what's on $PATH) and wait for my "go." If it's installed but not authenticated, tell me to run `gh auth login` and wait. Do not proceed to step 3 until both are green.

Step 3 — Slash command file. Write the content below to ~/.claude/commands/write-pr-description-to-freshjots.md (create the directory if missing). If the file already exists with identical content, skip. If it exists with different content, show me the diff and ask before overwriting.

Slash command content (write this verbatim, no edits, no improvements — the leading `---` and frontmatter fields are load-bearing):

---
description: Craft a PR description for a given PR URL and store it in the pr_descriptions folder at freshjots.com, with a local backup
argument-hint: <url of PR>
allowed-tools: Bash, Write
---

Craft a pull-request description for the PR I pass as the command argument, keep a local backup, and store it in the user's Fresh Jots `pr_descriptions` folder.

The PR URL is: $ARGUMENTS

If that is empty, ask me for the PR URL and stop until I give it. Otherwise treat it as PR_URL for every step below.

## Step 1 — read the PR, then compose

Run these via the Bash tool to ground the description in the real PR (set PR_URL to the URL I passed; do not invent the content from memory):

PR_URL="<the PR URL from the command argument>"
gh pr view "$PR_URL" --json number,title,url,headRefName,baseRefName,additions,deletions,changedFiles,body,commits
gh pr diff "$PR_URL" | head -c 60000

If `gh pr view` fails, stop and tell me what gh reported (auth, wrong URL, or no access to a private repo) — do not guess the contents.

Then compose a markdown PR description from that output plus your working context. Use this structure exactly:

# PR #<number>: <concise, imperative title — what this change does>

## Summary
1–3 sentences: what this PR does and the outcome, in plain language.

## Changes
- One bullet per coherent change (group related files); state *what* and *why*, not the raw diff.
- Call out new dependencies, migrations, config, or env vars explicitly.

## Why
The motivating problem or goal. Fold in anything useful from the existing PR body and any linked issue.

## Test plan
- Concrete steps or commands to verify this — enough that a reviewer can re-run them.

## Risk & rollout
- Migrations / data changes, backward compatibility, feature flags, and how to revert.

## Notes for reviewers
- Non-obvious decisions, trade-offs, and follow-ups deliberately left out of scope.

Once composed, write it to `/tmp/cc-pr-description.md` using the Write tool.

## Step 2 — back it up locally, then post

Run this bash block via the Bash tool. Set PR_URL to the same URL. It resolves the PR number, titles the note `pr-<number>-YYYY-MM-DD-hh-mm-ss`, resolves the `pr_descriptions` folder (creating it if missing, caching the id locally), writes the local backup FIRST and keeps it forever, then POSTs to Fresh Jots:

set -uo pipefail
PR_URL="<the PR URL from the command argument>"
[ -n "${FRESHJOTS_TOKEN:-}" ] || { echo "FRESHJOTS_TOKEN not set"; exit 1; }
[ -s /tmp/cc-pr-description.md ] || { echo "description file missing or empty"; exit 1; }

PR_NUM=$(gh pr view "$PR_URL" --json number -q .number 2>/dev/null)
[ -z "$PR_NUM" ] && PR_NUM=$(printf '%s' "$PR_URL" | sed -nE 's#.*/pull/([0-9]+).*#\1#p')
case "$PR_NUM" in ''|*[!0-9]*) echo "Could not determine a PR number from: $PR_URL"; exit 1;; esac

FOLDER_NAME="pr_descriptions"
STASH_DIR="$HOME/.claude/freshjots-stash"
CACHE="$STASH_DIR/.pr-descriptions-folder-id"
mkdir -p "$STASH_DIR"

TITLE="pr-${PR_NUM}-$(date +%Y-%m-%d-%H-%M-%S)"

# Local backup FIRST — this file is the durable copy and is never deleted,
# so the description survives an API outage, a revoked token, or a deleted branch.
STASH_PATH="$STASH_DIR/${TITLE}.md"
cp /tmp/cc-pr-description.md "$STASH_PATH"
echo "Local backup: $STASH_PATH"

folder_id=""
if [ -s "$CACHE" ]; then
    cached=$(cat "$CACHE")
    [ "$(curl -sS -o /dev/null -w '%{http_code}' --max-time 15 \
          -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
          "https://freshjots.com/api/v1/folders/$cached")" = "200" ] && folder_id=$cached
fi
if [ -z "$folder_id" ]; then
    folder_id=$(curl -sS --max-time 15 -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
        https://freshjots.com/api/v1/folders \
      | jq -r --arg n "$FOLDER_NAME" '.folders[]? | select((.name // "" | ascii_downcase) == ($n | ascii_downcase)) | .id' | head -1)
fi
if [ -z "$folder_id" ]; then
    folder_id=$(curl -sS --max-time 15 -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
        -H "Content-Type: application/json" \
        -X POST -d "{\"folder\":{\"name\":\"$FOLDER_NAME\"}}" \
        https://freshjots.com/api/v1/folders \
      | jq -r '.id // empty')
fi
[ -n "$folder_id" ] && echo "$folder_id" > "$CACHE"

if [ -n "$folder_id" ]; then
    PAYLOAD=$(jq -Rs --arg t "$TITLE" --arg f "$folder_id" \
        '{note: {title: $t, plain_body: ., format: "plain", folder_id: ($f|tonumber? // $f)}}' \
        < /tmp/cc-pr-description.md)
else
    PAYLOAD=$(jq -Rs --arg t "$TITLE" \
        '{note: {title: $t, plain_body: ., format: "plain"}}' \
        < /tmp/cc-pr-description.md)
fi

RESP=$(mktemp); trap 'rm -f "$RESP"' EXIT
STATUS=$(curl -sS -o "$RESP" -w '%{http_code}' --max-time 30 \
    -X POST https://freshjots.com/api/v1/notes \
    -H "Authorization: Bearer $FRESHJOTS_TOKEN" \
    -H "Content-Type: application/json" \
    --data "$PAYLOAD")

case "$STATUS" in
    201)
        ID=$(jq -r '.id // "?"' < "$RESP")
        rm -f /tmp/cc-pr-description.md
        echo "Created note #${ID}: ${TITLE} (folder_id=${folder_id:-root})"
        echo "Backup kept at: ${STASH_PATH}"
        echo "Push it onto the PR: gh pr edit \"${PR_URL}\" --body-file \"${STASH_PATH}\""
        ;;
    *)
        echo "Upload failed: status=$STATUS body=$(head -c 256 "$RESP")"
        echo "Your description is SAFE — local backup at ${STASH_PATH} (and /tmp/cc-pr-description.md)."
        echo "Use it now anyway: gh pr edit \"${PR_URL}\" --body-file \"${STASH_PATH}\"  (or cat it and paste into GitHub)."
        exit 2
        ;;
esac

## Step 3 — report

Tell the user the note id and title, the local backup path, and the ready-to-run `gh pr edit "<pr-url>" --body-file <path>` command. If the upload failed, lead with the reassurance that the description is preserved locally, give the backup path, and the `gh pr edit` command so they can update the PR regardless of Fresh Jots being reachable. Do not run `gh pr edit` yourself — print it and let the user decide; it changes their live PR.

(End of slash command content — that's everything between `---` and here.)

Step 4 — Folder bootstrap. Eagerly create the pr_descriptions folder so I see a visible confirmation it worked before the first `/write-pr-description-to-freshjots` invocation:
- `GET https://freshjots.com/api/v1/folders` with the bearer token; look for a folder named "pr_descriptions".
- If absent: `POST https://freshjots.com/api/v1/folders` with body `{"folder":{"name":"pr_descriptions"}}`.
- Persist the returned id (or the existing one) to ~/.claude/freshjots-stash/.pr-descriptions-folder-id. `mkdir -p ~/.claude/freshjots-stash` first.
- If the auto-archive or summarize setup already created ~/.claude/freshjots-stash/, this just adds another cache file alongside the existing ones. The folders are independent.

Step 5 — Tell me what to do next. Print a single clear three-line block:
  1. Quit Claude Code completely (close every window / Ctrl-D out of every session). Slash commands only register at session start.
  2. Reload your shell (`source ~/.zshrc` or `source ~/.bashrc`, depending on which I just edited). Skip if FRESHJOTS_TOKEN was already exported before this run.
  3. Relaunch Claude Code anywhere, ask anything trivial, then type `/write-pr-description-to-freshjots https://github.com/owner/repo/pull/123`. Within a few seconds you get a PR description in your pr_descriptions folder, a local backup path, and a `gh pr edit` command.

Step 6 — Verification helpers. Tell me I can:
  - `ls -1t ~/.claude/freshjots-stash/pr-*.md` to see every PR description I've ever generated (kept indefinitely — these are durable backups, not a rotating stash).
  - `cat ~/.claude/freshjots-stash/.pr-descriptions-folder-id` to confirm the cached folder id resolved.
  - Visit https://freshjots.com → the pr_descriptions folder to see every description in the UI.

Constraints:
- Use absolute paths everywhere ($HOME expands; ~ inside JSON does not).
- Prefer jq over hand-rolled JSON manipulation.
- Treat every file edit as needing diff + my "yes" the first time, then proceed.
- The local backup must be written BEFORE the upload and must never be deleted on success — it is the whole point.
- Never run `gh pr edit` (or any command that mutates the PR) automatically — only print it for me to run.
- If any API call returns non-200/201, stop and explain, and make clear the local backup is intact — don't paper over it.
- If `jq`, `curl`, or `gh` is missing, tell me which package manager to use to install it (apt/dnf/brew/pacman based on what's on $PATH) and ask before installing.

Begin.