diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..50ee761
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,42 @@
+name: Publish to crates.io
+
+# Publishes the crate when a version tag (v*) is pushed.
+# Auth uses crates.io Trusted Publishing (OIDC) — no long-lived token is
+# stored in GitHub. One-time setup on crates.io: add a Trusted Publisher for
+# this repository pointing at this workflow file (publish.yml).
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Required for Trusted Publishing: the OIDC token exchange with crates.io.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Verify tag matches Cargo.toml version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          CRATE_VER="$(grep -m1 '^version' Cargo.toml | sed -E 's/.*"(.*)".*/\1/')"
+          echo "tag=$TAG crate=$CRATE_VER"
+          if [ "$TAG" != "$CRATE_VER" ]; then
+            echo "::error::tag v$TAG does not match Cargo.toml version $CRATE_VER"
+            exit 1
+          fi
+
+      - name: Authenticate to crates.io (Trusted Publishing)
+        uses: rust-lang/crates-io-auth-action@v1
+        id: auth
+
+      - name: Publish
+        run: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ steps.auth.outputs.token }}
diff --git a/.gitignore b/.gitignore
index 6c4ee60..3193004 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,10 @@ Cargo.lock
 
 # Local-only design/plan docs (not part of the published crate)
 /.plans/
+/docs/superpowers/
+
+# JetBrains IDE files
+/.idea/
 
 # Local-only tooling scratch (not part of the published crate)
 /.superpowers/