chore: untrack .claude/ (private local config)

Two new pre-flight guards in scripts/release.sh, evaluated right after the
branch check:

1. Reject if HEAD subject matches `(X.Y.Z)` — historical pattern where the
   feature commit itself bumped the version (e.g. `feat(...) (0.9.14)`).
   Forces every release to land in a dedicated `chore(release): X.Y.Z`
   commit so the changelog + tag point at a clean release boundary.

2. Reject if HEAD is already `chore(release): …` — prevents re-running the
   script with no new commits since the previous release (would otherwise
   produce an empty release on top of itself).

Scope deliberately `chore(scripts)` (not `chore(release)`) so this very
commit doesn't trip guard 2 the next time release.sh runs.

.claude/commands/publish.md

@@ -1,161 +0,0 @@
----
-description: Release unarr CLI end-to-end (bump + tag + binaries + Hetzner + Docker Hub + smoke). Standalone, does not depend on GitHub Actions.
-argument-hint: "[patch|minor|major|X.Y.Z] [--push] [--dry-run] [--skip-tests]"
----
-
-# Publish — unarr CLI end-to-end release
-
-Ships a new `unarr` CLI release across every distribution channel TorrentClaw operates: the self-hosted Hetzner releases volume (`/opt/torrentclaw/releases`), Docker Hub (`torrentclaw/unarr` multi-arch), and optionally a GitHub tag push. The pipeline is implemented in `torrentclaw-cli/scripts/ship.sh` and orchestrated here.
-
-**Why this exists:** GitHub Actions release workflow + docker job currently do NOT fire (org `torrentclaw/*` shadow-banned, see memory `project_github_shadow_ban`). Until support resolves it, this command is the canonical release path.
-
-## Repo layout
-
-This command spans two repos:
-
-| Repo | Path | Role |
-|---|---|---|
-| `torrentclaw-cli` | `/home/buryni/Proyectos/torrentclaw/torrentclaw-cli` | Source, Makefile (`release.sh`, `ship.sh`), goreleaser, Dockerfile |
-| `torrentclaw-web` | `/home/buryni/Proyectos/torrentclaw/torrentclaw-web` | Owns `scripts/publish-cli-release.sh` (Hetzner rsync) — invoked by `ship.sh` |
-
-All commands below run from the **CLI repo** root unless noted.
-
-## Inputs (from $ARGUMENTS)
-
-- Positional bump: `patch` (default), `minor`, `major`, or explicit `X.Y.Z`
-- `--push` — also `git push origin main --follow-tags` after publishing (creates GH tag for the day shadow-ban lifts; harmless if Actions stays silent)
-- `--dry-run` — preview every step, mutate nothing
-- `--skip-tests` — skip `go test` step (use ONLY for emergency reships of an already-validated tree)
-
-## Pre-flight (always run, even on `--dry-run`)
-
-1. **Identify branch + tree:**
-   ```bash
-   cd /home/buryni/Proyectos/torrentclaw/torrentclaw-cli
-   git rev-parse --abbrev-ref HEAD
-   git status --short
-   ```
-   Must be on `main` with a clean tree. If dirty, stop and surface what's uncommitted — do not auto-stash.
-
-2. **Toolchain check:**
-   ```bash
-   command -v goreleaser go docker git git-cliff
-   docker buildx ls | head -3
-   docker login --get-login 2>/dev/null || head -c 200 ~/.docker/config.json
-   ```
-   Need `torrentclaw` logged in to `index.docker.io`. If missing, stop and ask.
-
-3. **Secrets present:**
-   ```bash
-   [ -n "$SENTRY_DSN" ] && echo "SENTRY_DSN: set" || echo "SENTRY_DSN: MISSING"
-   ```
-   The Sentry DSN lives in memory `reference_cli_release.md`. If unset, export it before invoking `ship.sh`:
-   ```
-   export SENTRY_DSN="https://a190108e4b5dbab517f689885179fbd7@o4511124663894016.ingest.de.sentry.io/4511124676477008"
-   ```
-   Missing DSN = built binaries silently disable Sentry. Acceptable but warn.
-
-## Validate (unless `--skip-tests`)
-
-```bash
-go vet ./...
-go test ./...
-```
-
-Stop on any failure. Don't release a broken tree.
-
-## Step 1 — Bump + tag (creates a `chore(release): X.Y.Z` commit and `vX.Y.Z` annotated tag)
-
-Pick the bump from $ARGUMENTS. Default is `patch`.
-
-```bash
-make release-patch              # auto from latest tag
-# OR
-make release V=0.9.12           # explicit
-```
-
-`scripts/release.sh` is interactive — it shows the changelog preview and asks `y/N`. Pipe `y`:
-```bash
-echo y | make release-patch
-```
-
-After this step:
-- `internal/cmd/version.go` shows new version
-- `CHANGELOG.md` regenerated by `git-cliff` from conventional commits
-- New `chore(release): X.Y.Z` commit on `main`
-- New annotated tag `vX.Y.Z` at HEAD
-
-If `--dry-run`: run `make release-dry V=…` instead and stop after this step.
-
-## Step 2 — Ship (binaries + Hetzner + Docker Hub + smoke)
-
-```bash
-SENTRY_DSN="…" make ship           # without --push
-SENTRY_DSN="…" make ship-push      # adds git push at the end
-```
-
-`scripts/ship.sh` does, in order:
-1. Re-checks tree clean, tag exists at HEAD, version.go matches
-2. `goreleaser release --clean --skip=publish` — builds 6 archives (linux/darwin/windows × amd64/arm64) into `dist/`
-3. `../torrentclaw-web/scripts/publish-cli-release.sh $V` — rsync archives to `root@100.117.187.33:/opt/torrentclaw/releases/v$V/` over Tailscale, then flips `version.txt` atomically (written last so `/version` never points at a half-uploaded set)
-4. `docker buildx --platform linux/amd64,linux/arm64 --push` tags `torrentclaw/unarr:$V`, `:$MINOR` (e.g. `0.9`), `:latest`
-5. Smoke probes:
-   - `curl torrentclaw.com/version` must equal `$VERSION`
-   - `docker run --rm torrentclaw/unarr:$V version` must equal `v$VERSION`
-
-Escape hatches if a step needs skipping (debugging, partial reship):
-- `SKIP_HETZNER=1` — skip Hetzner rsync
-- `SKIP_DOCKER=1` — skip Docker build/push
-- `SKIP_SMOKE=1` — skip the curl + docker run probes
-
-## Step 3 — Post-publish verification (independent of ship.sh smoke)
-
-After `make ship` exits clean, confirm externally:
-
-```bash
-# Canonical version endpoint (no CF cache — cf-cache-status: DYNAMIC)
-curl -fsSL https://torrentclaw.com/version
-
-# get. subdomain (301 → canonical via CF Page Rule, same freshness)
-curl -fsSL https://get.torrentclaw.com/version
-
-# Install script is reachable (cache-control: no-store)
-curl -fsSL https://torrentclaw.com/install.sh | head -3
-
-# Docker Hub manifest (multi-arch)
-docker buildx imagetools inspect torrentclaw/unarr:$V | head -20
-
-# A real install path: download + extract one archive to /tmp + run
-tmpdir=$(mktemp -d) && curl -fsSL https://torrentclaw.com/releases/download/v$V/unarr_${V}_linux_amd64.tar.gz | tar -xz -C $tmpdir && $tmpdir/unarr version
-```
-
-All four must agree on `$V`. If `torrentclaw.com/version` reports the old version, `publish-cli-release.sh` likely failed mid-flight — re-run `make ship`. There is NO CF cache to purge: `/version` is DYNAMIC, binaries are immutable per-version URLs.
-
-## Step 4 — Optional GH push (if `--push` was passed and not done by `ship-push`)
-
-```bash
-git push origin main --follow-tags
-```
-
-This pushes the `chore(release)` commit + the `vX.Y.Z` tag. CI workflows (`release.yml` + docker) would normally fire here. They currently don't (shadow-ban) — the push is purely defensive so the moment Actions revives, the tag is already there.
-
-## Output to user
-
-After the run, surface:
-- Version shipped (`vX.Y.Z`)
-- Live version on `torrentclaw.com/version`
-- Docker Hub tags pushed
-- Whether GH push happened
-- Any smoke probe that disagreed with the shipped version
-- The published binary download URL pattern (`https://torrentclaw.com/releases/download/v$V/unarr_${V}_<os>_<arch>.{tar.gz,zip}`)
-
-If anything failed mid-pipeline, explain WHERE in the 5 ship.sh steps the failure happened and the exact command to resume from (e.g. `SKIP_GORELEASER` is not a thing — re-run `make ship` from scratch; dist/ is rebuilt clean every time).
-
-## Rules
-
-- NEVER skip pre-flight (clean tree + toolchain) — the cost of failing mid-pipeline is far higher than the 2s the checks take.
-- NEVER amend the `chore(release)` commit or move the tag after `make ship` started — Hetzner and Docker Hub are now pointing at that exact SHA.
-- NEVER manually edit `version.txt` on Hetzner. Re-run `make ship` (or just step 3 via `SKIP_DOCKER=1 SKIP_HETZNER=0 make ship`).
-- DO NOT `git push --force` over a released tag.
-- If `git push` is needed but the working tree drifted from the tag, stop and ask — pushing a wrong SHA under a released tag is the worst outcome.
-- Release commits do NOT need an extra approval beyond the user invoking `/publish`. Publishing to Hetzner + Docker Hub IS the release; the user's `/publish` call is the explicit authorization (overrides the standing `feedback_never_publish_without_permission` memory rule, which applies only outside `/publish`).

.gitignore

@@ -43,18 +43,5 @@ tmp/
 config/
 dist-ffbinaries/
 
-# Claude Code: global ~/.gitignore excludes .claude/ by default, which hides
-# project-shared agents/commands/hooks. Override here to commit the shared
-# pieces (agents, commands, hooks, settings.json). Keep per-user state local.
-!.claude/
-!.claude/agents/
-!.claude/agents/**
-!.claude/commands/
-!.claude/commands/**
-!.claude/hooks/
-!.claude/hooks/**
-!.claude/settings.json
-.claude/settings.local.json
-.claude/projects/
-.claude/scheduled_tasks.lock
-.claude/skills/
+# Claude Code: keep entirely local, do not track
+.claude/

DOCKERHUB.md

@@ -1,8 +1,9 @@
 # unarr
 
-**The single binary that replaces your whole *arr stack.** Search 30+ torrent
-sources, inspect real quality before you download, grab subtitles, and manage
-your media library — all from one terminal tool or a headless daemon.
+**The single binary that replaces your whole *arr stack.** Built-in torrent,
+debrid, and usenet engines. Stream, transcode, and organize your library from
+one terminal — or run it as a headless daemon with a web dashboard, WireGuard
+split-tunnel, and Cloudflare Funnel remote access.
 
 **[Website & docs](https://torrentclaw.com/unarr)** · **[Install guide](https://torrentclaw.com/cli)** · **[Get an API key](https://torrentclaw.com)**
 

README.md

@@ -11,9 +11,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Go Version](https://img.shields.io/github/go-mod/go-version/torrentclaw/unarr)](go.mod)
 
-Powerful terminal tool for torrent search and management. **Free and open source.**
+The single-binary terminal client for torrent, debrid, and usenet downloads. **Free and open source.**
 
-Search 30+ torrent sources, inspect torrent quality, discover popular content, find streaming providers, and manage your media collection — all from your terminal.
+Built-in torrent engine, debrid (Real-Debrid / AllDebrid), and NZB support. Stream to mpv/vlc, transcode on the fly with hardware acceleration, and manage your library — one binary or a headless daemon with WireGuard split-tunnel and Cloudflare Funnel remote access.
 
 <!-- GIF demo placeholder -->
 <!-- ![unarr Demo](docs/demo.gif) -->

internal/agent/state.go

@@ -2,6 +2,8 @@ package agent
 
 import (
 	"encoding/json"
+	"errors"
+	"fmt"
 	"os"
 	"path/filepath"
 	"time"
@@ -9,6 +11,11 @@ import (
 	"github.com/torrentclaw/unarr/internal/config"
 )
 
+// ErrDaemonNotRunning is returned by callers that need a running daemon but
+// find no state file on disk. Sentinel so user-facing commands (stop/reload)
+// can wrap it and Sentry can filter it out as a non-bug.
+var ErrDaemonNotRunning = errors.New("daemon does not appear to be running (state file not found)")
+
 // DaemonState is written to disk every heartbeat for external tools to read.
 type DaemonState struct {
 	AgentID         string         `json:"agentId"`
@@ -69,17 +76,31 @@ func WriteState(state *DaemonState) {
 	os.Rename(tmp, path)
 }
 
-// ReadState reads the daemon state from disk. Returns nil if not found.
+// ReadState reads the daemon state from disk. Returns nil if not found or
+// unreadable. Use LoadState when callers need to distinguish "not running"
+// from "state file corrupted".
 func ReadState() *DaemonState {
+	state, _ := LoadState()
+	return state
+}
+
+// LoadState reads the daemon state and returns explicit errors:
+//   - ErrDaemonNotRunning when the state file does not exist
+//   - a wrapped json error when the file exists but cannot be decoded
+//     (a real bug worth reporting to Sentry)
+func LoadState() (*DaemonState, error) {
 	data, err := os.ReadFile(StateFilePath())
 	if err != nil {
-		return nil
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, ErrDaemonNotRunning
+		}
+		return nil, err
 	}
 	var state DaemonState
-	if json.Unmarshal(data, &state) != nil {
-		return nil
+	if err := json.Unmarshal(data, &state); err != nil {
+		return nil, fmt.Errorf("decode daemon state %s: %w", StateFilePath(), err)
 	}
-	return &state
+	return &state, nil
 }
 
 // RemoveState deletes the state file (called on clean shutdown).

internal/agent/state_test.go

@@ -1,6 +1,7 @@
 package agent
 
 import (
+	"errors"
 	"os"
 	"path/filepath"
 	"testing"
@@ -104,3 +105,39 @@ func TestReadStateCorruptedJSON(t *testing.T) {
 		t.Errorf("ReadState() should return nil for corrupted JSON, got %+v", state)
 	}
 }
+
+func TestLoadStateNotFound(t *testing.T) {
+	tmpDir := t.TempDir()
+	origFn := stateFilePathFn
+	stateFilePathFn = func() string { return filepath.Join(tmpDir, "nonexistent.json") }
+	defer func() { stateFilePathFn = origFn }()
+
+	state, err := LoadState()
+	if state != nil {
+		t.Errorf("LoadState() state = %+v, want nil", state)
+	}
+	if !errors.Is(err, ErrDaemonNotRunning) {
+		t.Errorf("LoadState() err = %v, want ErrDaemonNotRunning", err)
+	}
+}
+
+func TestLoadStateCorruptedJSON(t *testing.T) {
+	tmpDir := t.TempDir()
+	origFn := stateFilePathFn
+	path := filepath.Join(tmpDir, "daemon.state.json")
+	stateFilePathFn = func() string { return path }
+	defer func() { stateFilePathFn = origFn }()
+
+	os.WriteFile(path, []byte("not valid json{{{"), 0o644)
+
+	state, err := LoadState()
+	if state != nil {
+		t.Errorf("LoadState() state = %+v, want nil", state)
+	}
+	if err == nil {
+		t.Fatal("LoadState() err = nil, want decode error")
+	}
+	if errors.Is(err, ErrDaemonNotRunning) {
+		t.Error("corrupt state must not be reported as ErrDaemonNotRunning — it would be filtered from Sentry")
+	}
+}

internal/cmd/daemon_control.go

@@ -262,9 +262,9 @@ func runDaemonReload() error {
 // stopDaemonByPID reads the state file and sends a graceful stop to the daemon PID.
 // Used as fallback on platforms without a service manager (and as Windows implementation).
 func stopDaemonByPID() error {
-	state := agent.ReadState()
-	if state == nil {
-		return fmt.Errorf("daemon does not appear to be running (state file not found)")
+	state, err := agent.LoadState()
+	if err != nil {
+		return err
 	}
 	return killPID(state.PID)
 }

internal/cmd/reload_unix.go

@@ -43,9 +43,9 @@ func startReloadWatcher(rc *ReloadableConfig) {
 
 // sendReloadSignal sends SIGUSR1 to the running daemon process.
 func sendReloadSignal() error {
-	state := agent.ReadState()
-	if state == nil {
-		return fmt.Errorf("daemon does not appear to be running (state file not found)")
+	state, err := agent.LoadState()
+	if err != nil {
+		return err
 	}
 	p, err := os.FindProcess(state.PID)
 	if err != nil {

internal/cmd/root.go

@@ -25,16 +25,20 @@ var (
 
 func init() {
 	rootCmd = &cobra.Command{
-		Use:   "unarr",
-		Short: "unarr — torrent search and management",
-		Long: `unarr is a powerful terminal tool for torrent search and management.
-
-Search 30+ torrent sources, inspect torrent quality, discover popular content,
-find streaming providers, and manage your media collection — all from your terminal.
+		Use:     "unarr",
+		Version: Version,
+		Short:   "Terminal torrent + debrid + usenet client — download, stream, transcode",
+		Long: `unarr is a terminal-native client that downloads torrents, debrid links,
+and usenet (NZB) — all from the same binary. It streams content straight
+to mpv/vlc with sequential piece prioritization, transcodes on the fly via
+ffmpeg with hardware acceleration (NVENC, QSV, VA-API, VideoToolbox), and
+organizes your library into Movies/TV folders. Run it one-shot or as a
+long-running daemon with a built-in WireGuard split-tunnel and remote
+playback over Cloudflare Funnel.
 
 Get started:
   unarr init                           First-time configuration wizard
-  unarr search "breaking bad"          Search for content
+  unarr download <magnet|hash>         Grab a torrent one-shot
   unarr start                          Start the download daemon
 
 Documentation:  https://torrentclaw.com/cli
@@ -55,7 +59,7 @@ Source:         https://github.com/torrentclaw/unarr`,
 	// Command groups for organized help output
 	rootCmd.AddGroup(
 		&cobra.Group{ID: "start", Title: "Getting Started:"},
-		&cobra.Group{ID: "search", Title: "Search & Discovery:"},
+		&cobra.Group{ID: "search", Title: "Catalog & Discovery:"},
 		&cobra.Group{ID: "download", Title: "Downloads & Streaming:"},
 		&cobra.Group{ID: "daemon", Title: "Daemon Management:"},
 		&cobra.Group{ID: "system", Title: "System & Diagnostics:"},

internal/sentry/sentry.go

@@ -1,12 +1,16 @@
 package sentry
 
 import (
+	"errors"
 	"os"
 	"runtime"
 	"strings"
 	"time"
 
 	gosentry "github.com/getsentry/sentry-go"
+	"github.com/spf13/pflag"
+
+	"github.com/torrentclaw/unarr/internal/agent"
 )
 
 // dsn is injected at build time via ldflags. If empty, Sentry is disabled.
@@ -45,8 +49,10 @@ func Close() {
 }
 
 // CaptureError sends a non-fatal error to Sentry with optional command context.
+// User-input errors (unknown flag/command, bad value) are skipped — they are
+// not bugs, just noise.
 func CaptureError(err error, command string) {
-	if err == nil {
+	if err == nil || isUserInputError(err) {
 		return
 	}
 
@@ -58,6 +64,23 @@ func CaptureError(err error, command string) {
 	})
 }
 
+func isUserInputError(err error) bool {
+	if errors.Is(err, agent.ErrDaemonNotRunning) {
+		return true
+	}
+	var notExist *pflag.NotExistError
+	var valueReq *pflag.ValueRequiredError
+	var invalidVal *pflag.InvalidValueError
+	var invalidSyn *pflag.InvalidSyntaxError
+	if errors.As(err, &notExist) || errors.As(err, &valueReq) ||
+		errors.As(err, &invalidVal) || errors.As(err, &invalidSyn) {
+		return true
+	}
+	msg := err.Error()
+	return strings.HasPrefix(msg, "unknown command ") ||
+		strings.HasPrefix(msg, "required flag(s)")
+}
+
 // RecoverPanic captures a panic and re-panics after reporting.
 // Usage: defer sentry.RecoverPanic()
 func RecoverPanic() {

internal/sentry/sentry_test.go

@@ -1,6 +1,11 @@
 package sentry
 
-import "testing"
+import (
+	"fmt"
+	"testing"
+
+	"github.com/torrentclaw/unarr/internal/agent"
+)
 
 func TestEnvironment(t *testing.T) {
 	tests := []struct {
@@ -45,3 +50,13 @@ func TestSetUser(t *testing.T) {
 	// Should not panic without initialization
 	SetUser("agent-123")
 }
+
+func TestIsUserInputErrorDaemonNotRunning(t *testing.T) {
+	if !isUserInputError(agent.ErrDaemonNotRunning) {
+		t.Error("ErrDaemonNotRunning should be treated as user-input error")
+	}
+	wrapped := fmt.Errorf("stop daemon: %w", agent.ErrDaemonNotRunning)
+	if !isUserInputError(wrapped) {
+		t.Error("wrapped ErrDaemonNotRunning should be treated as user-input error")
+	}
+}

scripts/release.sh

@@ -55,6 +55,17 @@ fi
 CURRENT_BRANCH=$(git branch --show-current)
 [ "$CURRENT_BRANCH" = "main" ] || warn "Not on main branch (current: $CURRENT_BRANCH)"
 
+HEAD_SUBJECT=$(git log -1 --pretty=%s)
+if [[ "$HEAD_SUBJECT" =~ \(([0-9]+\.[0-9]+\.[0-9]+)\) ]]; then
+  die "HEAD commit subject contains inline version bump: \"$HEAD_SUBJECT\"
+Release contract: version bumps MUST live in a dedicated 'chore(release): X.Y.Z' commit.
+Revert the inline bump and re-run this script — it will create the proper commit."
+fi
+if [[ "$HEAD_SUBJECT" =~ ^chore\(release\): ]]; then
+  die "HEAD is already a chore(release) commit: \"$HEAD_SUBJECT\"
+Nothing new to release. Add commits since the last release or amend intentionally outside this script."
+fi
+
 # ── Resolve version ────────────────────────────────────────────────
 LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
 LATEST_VERSION="${LATEST_TAG#v}"