feedback-kit-skills 0.1.0

package/README.md

@@ -0,0 +1,323 @@
+# FeedbackKit
+
+[![Release to TestFlight](https://github.com/tianhaoz95/feedback-kit/actions/workflows/testflight.yml/badge.svg)](https://github.com/tianhaoz95/feedback-kit/actions/workflows/testflight.yml)
+[![Release macOS Demo](https://github.com/tianhaoz95/feedback-kit/actions/workflows/release-macos-demo.yml/badge.svg)](https://github.com/tianhaoz95/feedback-kit/actions/workflows/release-macos-demo.yml)
+[![Publish CLI Package](https://github.com/tianhaoz95/feedback-kit/actions/workflows/publish-cli.yml/badge.svg)](https://github.com/tianhaoz95/feedback-kit/actions/workflows/publish-cli.yml)
+[![Publish Skills Package](https://github.com/tianhaoz95/feedback-kit/actions/workflows/publish-skills.yml/badge.svg)](https://github.com/tianhaoz95/feedback-kit/actions/workflows/publish-skills.yml)
+[![Deploy web dashboard](https://github.com/tianhaoz95/feedback-kit/actions/workflows/deploy-web.yml/badge.svg)](https://github.com/tianhaoz95/feedback-kit/actions/workflows/deploy-web.yml)
+
+An iOS + macOS + watchOS SDK for capturing in-app user feedback (screenshot +
+annotations + description + device/app/screen info on iOS/macOS; text +
+context only on watchOS), plus an optional Supabase-backed dashboard for
+collecting it and turning it into prompts for a coding agent.
+
+See [DESIGN.md](DESIGN.md) for how it's put together and why.
+
+## Quickstart
+
+Prerequisites: Xcode, Homebrew, Node.js — all standard on a dev Mac. The one
+thing you may need to install yourself is **Docker Desktop**
+(https://www.docker.com/products/docker-desktop/), needed only for running
+Supabase locally.
+
+```bash
+./scripts/setup.sh      # installs xcodegen + Supabase CLI, npm install for web/
+```
+
+### Run the iOS demo app
+
+```bash
+./scripts/run-ios.sh
+```
+
+Builds and launches `DemoApp` (a small sample app with FeedbackKit wired up —
+shake-to-report, a floating trigger button, and manual "Report a Problem"
+buttons on both a SwiftUI and a UIKit screen) in the iOS Simulator.
+
+### Run the macOS demo app
+
+```bash
+./scripts/run-macos.sh
+```
+
+Builds and launches natively — no simulator needed. Exercises the floating
+trigger button, a Help-menu "Report a Problem…" item (⌘⇧R, the menu-item
+trigger style the SDK's docs show), and manual "Report a Problem" buttons on
+a sidebar Home/Cart pair sharing the same `CartStore` the iOS demo uses.
+`FeedbackKit.present(from: window)` and `FeedbackKit.showFloatingTriggerButton { ... }`
+are the macOS equivalents of the iOS calls above, minus a shake trigger (no
+motion sensor on a Mac).
+
+You can also build/test just the SDK itself, without the demo app:
+
+```bash
+swift build
+swift test
+```
+
+### Run the watchOS demo app
+
+```bash
+./scripts/run-watchos.sh
+```
+
+A standalone watch app (no iOS companion needed) built and launched on a
+watch simulator. watchOS is a deliberately stripped-down flow — no
+screenshot, no annotation tools, just a text description plus device/app
+context — via `FeedbackQuickNoteView`, a plain SwiftUI view embedded in a
+`.sheet`. See [DESIGN.md](DESIGN.md) for why.
+
+To test just the SDK itself on a watch simulator instead:
+
+```bash
+# Find a watch simulator id: xcrun simctl list devices available
+xcodebuild test -scheme FeedbackKit -destination 'id=<WATCH_SIMULATOR_UDID>'
+```
+
+### Run the web dashboard
+
+Needs Docker Desktop running first (see above).
+
+```bash
+./scripts/start-web.sh
+```
+
+Starts a local Supabase stack (Postgres, Auth, Storage, Edge Functions —
+with this project's schema and the `ingest-feedback` function already
+applied), points the dashboard at it, and starts it at http://localhost:3000.
+Supabase Studio (to poke at the database/storage directly) is at
+http://127.0.0.1:54323.
+
+Sign up on the dashboard, create a project, and copy the Swift snippet shown
+on the project page into `DemoApp/DemoApp/FeedbackKitDemoApp.swift` (it's
+already there, commented out) to see feedback submitted from the simulator
+show up live.
+
+### Use the CLI / MCP server
+
+Install globally from npm (or run directly with `npx feedbackkit-cli`):
+
+```bash
+npm install -g feedbackkit-cli
+feedbackkit login   # sign in via browser
+feedbackkit list
+```
+
+Or connect it to your local dev stack:
+
+```bash
+feedbackkit login --dashboard-url http://localhost:3000
+```
+
+Lets a coding agent fetch a feedback report's generated prompt directly
+(`feedbackkit mcp`) instead of a human copying it out of the dashboard —
+see [cli/README.md](cli/README.md) for the full command/tool list and how
+its browser-based login works.
+
+### Agent Skills
+
+FeedbackKit provides a catalog of [Agent Skills](https://github.com/vercel-labs/skills) compatible with
+Claude Code, Cursor, Antigravity, Gemini CLI, and other AI coding assistants to automate SDK setup and MCP integration.
+
+## Skills Catalog
+
+| Category | Skill | Description |
+|---|---|---|
+| [`setup/`](skills/setup/README.md) | [`setup-ios-sdk`](skills/setup/setup-ios-sdk/SKILL.md) | Integrate FeedbackKit SDK into an iOS project (SwiftUI or UIKit). |
+| [`setup/`](skills/setup/README.md) | [`setup-macos-sdk`](skills/setup/setup-macos-sdk/SKILL.md) | Integrate FeedbackKit SDK into a macOS desktop app (SwiftUI or AppKit). |
+| [`setup/`](skills/setup/README.md) | [`setup-watchos-sdk`](skills/setup/setup-watchos-sdk/SKILL.md) | Integrate FeedbackKit SDK into a watchOS app using FeedbackQuickNoteView. |
+| [`setup/`](skills/setup/README.md) | [`setup-mcp-server`](skills/setup/setup-mcp-server/SKILL.md) | Configure FeedbackKit CLI and MCP server for AI coding agents. |
+
+#### Layout
+
+```
+skills/
+  <category>/
+    <skill-name>/
+      SKILL.md        # required: frontmatter (name, description) + agent instructions
+      templates/      # optional: code/config template files (.template)
+```
+
+#### Commands
+
+```bash
+npm run new            # Interactively scaffold a new skill with @clack/prompts
+npm run validate       # Validate all SKILL.md frontmatter
+npm run list           # List all discoverable skills via npx skills
+```
+
+You can also pass arguments directly to scaffold non-interactively:
+```bash
+npm run new -- <category>/<skill-name> "one-line description"
+```
+
+#### Installing into an Agent
+
+From within your agent CLI or another project's working directory, install using the dedicated npm package name:
+```bash
+npx skills add feedback-kit-skills
+```
+
+To install a specific skill directly:
+```bash
+npx skills add feedback-kit-skills --skill setup-ios-sdk --yes
+```
+
+You can also install directly using the GitHub repository shorthand:
+```bash
+npx skills add tianhaoz95/feedback-kit --skill setup-ios-sdk --yes
+```
+
+## Deploying the web dashboard to GitHub Pages
+
+`.github/workflows/deploy-web.yml` builds `web/` and deploys it to GitHub
+Pages via GitHub Actions (`actions/deploy-pages` — no `gh-pages` branch)
+on every push to `main` that touches `web/`. One-time setup:
+
+1. **Settings → Pages → Source: "GitHub Actions"** on the repo (not "Deploy
+   from a branch").
+2. **Settings → Secrets and variables → Actions → Variables**, add:
+   - `VITE_SUPABASE_URL`
+   - `VITE_SUPABASE_ANON_KEY`
+
+   These are the anon/publishable key and project URL — safe to expose in a
+   client bundle, so repo **variables** (not secrets) are the right place for
+   them, same as `web/.env.local`.
+
+The workflow assumes the site is served from `https://<user>.github.io/feedback-kit/`
+(a project page, not a `<user>.github.io` user/org page) — see the `base` in
+`web/vite.config.ts` and `basename` in `web/src/main.tsx` if that ever
+changes. It also copies `dist/index.html` to `dist/404.html` after building
+so direct loads/refreshes of deep links (e.g. `/projects/abc`) still resolve
+client-side, since GitHub Pages has no server-side rewrites.
+
+## Deploying Supabase (migrations + edge functions)
+
+**Migrations** deploy automatically via Supabase's own native GitHub
+integration (Dashboard → Project Settings → Integrations → GitHub), not a
+custom Actions workflow — it applies `supabase/migrations/` to the
+production database whenever `main` changes. This is deliberately preferred
+over a custom workflow: it's a GitHub App connection Supabase manages and
+scopes to this repo/project itself, so no Postgres password or access token
+needs to live in this repo's GitHub Secrets at all. One-time setup, on that
+integration page:
+
+- GitHub repository: this repo
+- Working directory: `.` (repo root, since `supabase/` lives directly there)
+- Deploy to production: on, with production branch `main`
+
+**Edge Functions** (`ingest-feedback`, plus `create-checkout-session` /
+`create-portal-session` / `stripe-webhook` for billing — see below) are
+deployed manually:
+
+```bash
+supabase login              # once per machine — interactive browser OAuth
+./scripts/deploy-functions.sh                # deploy every function
+./scripts/deploy-functions.sh ingest-feedback   # or just one
+```
+
+This isn't automated because, unlike the database sync above, there's no
+project-scoped credential for it — `supabase functions deploy` needs a
+Supabase personal access token, which grants Management API access to
+every project on the account, not just this one. Not worth storing an
+account-wide secret in CI for a function that changes rarely.
+
+### Turning on real billing
+
+FeedbackKit is free today — every organization is permanently on the free
+plan (`organization_billing`, `supabase/migrations/0009_billing.sql`) until
+a real Stripe account exists. The dashboard's Billing page and the three
+billing Edge Functions are already built and deployed; they just detect the
+missing Stripe credentials and say so (`{"error": "billing_not_configured"}`)
+instead of doing anything. To make it real:
+
+1. Create the Stripe product/price for the paid plan, and a webhook
+   endpoint pointed at
+   `https://<project-ref>.supabase.co/functions/v1/stripe-webhook`
+   subscribed to at least `checkout.session.completed`,
+   `customer.subscription.updated`, and `customer.subscription.deleted`.
+2. Set the secrets the functions read (`supabase/functions/_shared/stripe.ts`):
+   ```bash
+   supabase secrets set STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... STRIPE_PRICE_ID_PRO=price_...
+   ```
+3. Nothing else — no schema change, no dashboard code change. The next
+   request to any billing function picks up the new secrets immediately.
+
+**Auth/MFA/pooler/storage config** (`supabase config push`) isn't automated
+either, and for a sharper reason: unlike migrations or function code, it
+syncs config.toml's *entire* declared state to the project on every push,
+which risks silently overwriting live settings that were never meant to
+match config.toml's (often local-dev-oriented) defaults — this happened
+during development (see git history around the GitHub-auth config).
+Always review `supabase config diff --project-ref <ref>` yourself before
+`supabase config push --project-ref <ref>`.
+
+## Releasing the demo app to TestFlight
+
+```bash
+APPLE_TEAM_ID=68CTFST8W2 ./scripts/release_testflight.sh
+```
+
+Archives `DemoApp` (Release configuration) and uploads it to App Store
+Connect for TestFlight, directly from this Mac — no Fastlane, no manually
+exported `.p12`. Signing is automatic via an App Store Connect API key
+(`FA_ASC_KEY_ID` / `FA_ASC_ISSUER_ID` / `FA_KEY_LOCATION`, set in `~/.zshrc`
+on this machine). `APPLE_TEAM_ID` is passed per invocation rather than
+defaulting globally, since this machine has signing identities for more
+than one Apple Developer Team — `68CTFST8W2` (HEJI TECHNOLOGY LLC) is the
+team that owns the `com.feedbackkit.demo` app record in App Store Connect.
+An app record with that bundle ID must already exist there before you run
+this; the script doesn't create one.
+
+## Cutting a release
+
+Release the entire suite with a single command:
+
+```bash
+./scripts/cut_release.sh 1.0.0 --notes "Version 1.0.0 release"
+```
+
+This publishes the GitHub release and triggers all release pipelines in parallel:
+1. **`.github/workflows/testflight.yml`**: Archives `FeedbackKitDemo` and uploads it to App Store Connect for TestFlight.
+2. **`.github/workflows/release-macos-demo.yml`**: Archives `FeedbackKitDemoMac`, signs it with a **Developer ID Application** certificate, notarizes with Apple, and attaches the notarized `FeedbackKitDemoMac-1.0.0.dmg` directly to the GitHub release.
+3. **`.github/workflows/publish-cli.yml`**: Builds, tests, and publishes `feedbackkit-cli` to both the public npm registry (`feedbackkit-cli`) and GitHub Packages (`@tianhaoz95/feedbackkit-cli`).
+4. **`.github/workflows/publish-skills.yml`**: Validates and publishes `feedback-kit-skills` to both the public npm registry (`feedback-kit-skills`) and GitHub Packages (`@tianhaoz95/feedback-kit-skills`).
+
+Unlike TestFlight signing (an "Apple Development" identity Xcode manages
+automatically), Developer ID distribution needs a real exported `.p12` in CI,
+so `release-macos-demo.yml` imports one into a throwaway keychain rather than relying on
+`-allowProvisioningUpdates`. You can also trigger either workflow by hand from the Actions tab
+(`workflow_dispatch`) — for macOS, check "Pipeline validation (no-upload)" there to validate
+the full build, sign, and notarization pipeline without touching a real release.
+
+To verify your local credentials and tooling before releasing:
+
+```bash
+./scripts/release-mac.sh --check
+```
+
+To build, sign, and notarize locally instead (e.g. to debug a notarization
+rejection without spending a CI run):
+
+```bash
+./scripts/release-mac.sh --version 1.0.0 --no-upload
+```
+
+Needs a "Developer ID Application" certificate already in your keychain
+(Xcode > Settings > Accounts > Manage Certificates > +) and the same
+`FA_ASC_KEY_ID`/`FA_ASC_ISSUER_ID`/`FA_KEY_LOCATION` App Store Connect API
+key the TestFlight release above uses — notarization just needs *an* ASC
+API key with access to the team, the same one works for both.
+
+## Repo layout
+
+| Path | What |
+|---|---|
+| `Sources/FeedbackKit/` | The iOS SDK (Swift Package) |
+| `Tests/FeedbackKitTests/` | SDK unit tests |
+| `DemoApp/` | Sample apps exercising the SDK on iOS, macOS, and watchOS (one XcodeGen project, three targets) |
+| `web/` | Static SPA dashboard (Vite + React), deployable to any static host |
+| `supabase/` | Postgres migrations, storage policies, the ingestion Edge Function, billing (Stripe) Edge Functions |
+| `cli/` | `feedbackkit` CLI + MCP server (Node/TypeScript) |
+| `skills/` | Agent Skills catalog (`vercel-labs/skills`) for automated setup via AI coding agents |
+| `scripts/` | `setup.sh`, `run-ios.sh`, `run-macos.sh`, `run-watchos.sh`, `start-web.sh`, `deploy-functions.sh`, `cut_release.sh`, `generate_mac_icon.py`, `release_testflight.sh`, `release-mac.sh`, `release_macos_demo.sh` |

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "feedback-kit-skills",
+  "version": "0.1.0",
+  "description": "Agent Skills for FeedbackKit — automated setup for iOS, macOS, watchOS, and MCP server",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tianhaoz95/feedback-kit.git"
+  },
+  "homepage": "https://github.com/tianhaoz95/feedback-kit#readme",
+  "bugs": {
+    "url": "https://github.com/tianhaoz95/feedback-kit/issues"
+  },
+  "keywords": [
+    "skills",
+    "agent-skills",
+    "feedbackkit",
+    "ios",
+    "macos",
+    "watchos",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "antigravity",
+    "codex"
+  ],
+  "author": "Tianhao Zhao",
+  "license": "MIT",
+  "files": [
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "new": "node scripts/new-skill.mjs",
+    "validate": "node scripts/validate-skills.mjs",
+    "list": "npx skills add . --list",
+    "prepublishOnly": "npm run validate"
+  },
+  "devDependencies": {
+    "@clack/core": "^0.4.1",
+    "@clack/prompts": "^0.9.1",
+    "picocolors": "^1.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/setup/README.md

@@ -0,0 +1,19 @@
+# FeedbackKit Setup Skills
+
+This category contains [Agent Skills](https://github.com/vercel-labs/skills) that guide AI coding agents (Claude Code, Cursor, Antigravity, Codex, etc.) to set up and configure FeedbackKit across Apple platforms (iOS, macOS, watchOS) and configure the MCP server.
+
+## Skills in this Category
+
+| Skill | Description |
+|---|---|
+| [`setup-ios-sdk`](setup-ios-sdk/SKILL.md) | Integrate FeedbackKit into an iOS app (SwiftUI or UIKit) with package setup, triggers, and screen tracking. |
+| [`setup-macos-sdk`](setup-macos-sdk/SKILL.md) | Integrate FeedbackKit into a macOS app (SwiftUI or AppKit) with window triggers, menu items, and screen tracking. |
+| [`setup-watchos-sdk`](setup-watchos-sdk/SKILL.md) | Integrate FeedbackKit into a watchOS app using `FeedbackQuickNoteView`. |
+| [`setup-mcp-server`](setup-mcp-server/SKILL.md) | Configure the FeedbackKit CLI and MCP server for Claude Code, Cursor, Antigravity, and Codex. |
+
+## Prerequisites
+
+- **Xcode 14+** installed with Swift 5.7+ toolchain.
+- For hosted dashboard sync: A FeedbackKit project key and endpoint URL from your dashboard.
+- For local development: FeedbackKit local development stack running via `./scripts/start-web.sh`.
+- For MCP server: Node.js 18+ and an active FeedbackKit dashboard account.

package/skills/setup/setup-ios-sdk/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: setup-ios-sdk
+description: Integrate FeedbackKit SDK into an iOS project (SwiftUI or UIKit) — adds package dependency, configures project key/endpoint at app launch, sets up shake or floating triggers, and adds screen tracking.
+---
+
+# setup-ios-sdk
+
+Integrates the FeedbackKit SDK into an iOS application (SwiftUI or UIKit). The agent inspects the project structure, adds the Swift Package dependency, initializes the SDK with project credentials, wires up user triggers (shake-to-report or floating button), and adds screen tracking.
+
+## When to Use
+
+- Use when integrating FeedbackKit into a new or existing iOS project.
+- Trigger phrases: "add feedbackkit to ios", "setup feedbackkit in swiftui", "install feedbackkit", "add feedback reporting to ios app", "configure feedbackkit".
+
+## Prerequisites
+
+- iOS 15.0+ deployment target.
+- Xcode 14+ / Swift 5.7+ toolchain.
+- A FeedbackKit project key and endpoint URL (if sending to the dashboard; optional for standalone local capture).
+
+## Step-by-Step Instructions
+
+### Step 1 -- Detect Project Type and Architecture
+
+Inspect the repository root and project files to determine:
+1. **Project Definition**: Is it defined by an Xcode project (`.xcodeproj`), an XcodeGen specification (`project.yml`), or a Swift Package (`Package.swift`)?
+2. **UI Framework & Lifecycle**: Is the app using SwiftUI (`@main struct App: App`) or UIKit (`AppDelegate` / `SceneDelegate`)?
+
+### Step 2 -- Add Swift Package Dependency
+
+#### XcodeGen (`project.yml`)
+If the project uses XcodeGen, add the dependency to `project.yml` under `packages` and target `dependencies`:
+```yaml
+packages:
+  FeedbackKit:
+    url: https://github.com/tianhaoz95/feedback-kit
+    from: 1.0.0
+targets:
+  YourAppTarget:
+    dependencies:
+      - package: FeedbackKit
+```
+Then regenerate the Xcode project:
+```bash
+xcodegen generate
+```
+
+#### Swift Package (`Package.swift`)
+If the target is a Swift package:
+```swift
+dependencies: [
+    .package(url: "https://github.com/tianhaoz95/feedback-kit", from: "1.0.0")
+],
+targets: [
+    .target(
+        name: "YourAppTarget",
+        dependencies: [
+            .product(name: "FeedbackKit", package: "feedback-kit")
+        ]
+    )
+]
+```
+
+#### Xcode Project (`.xcodeproj`)
+Add the package dependency using Xcode or by referencing the package URL:
+- Repository URL: `https://github.com/tianhaoz95/feedback-kit`
+- Version rule: Up to Next Major from `1.0.0` (or branch `main`)
+- Add product `FeedbackKit` to your main iOS app target.
+
+### Step 3 -- Configure FeedbackKit at App Launch
+
+Initialize `FeedbackKit.configure` at the earliest point in the application lifecycle.
+
+#### SwiftUI (`@main App`)
+Place inside your `App` struct's `init()` method:
+```swift
+import SwiftUI
+import FeedbackKit
+
+@main
+struct MyApp: App {
+    init() {
+        FeedbackKit.configure(.init(
+            endpointURL: URL(string: "https://<your-project-ref>.supabase.co/functions/v1/ingest-feedback")!,
+            projectKey: "<your-project-key>"
+        ))
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+```
+
+#### UIKit (`AppDelegate.swift`)
+Place in `application(_:didFinishLaunchingWithOptions:)`:
+```swift
+import UIKit
+import FeedbackKit
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+    func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        FeedbackKit.configure(.init(
+            endpointURL: URL(string: "https://<your-project-ref>.supabase.co/functions/v1/ingest-feedback")!,
+            projectKey: "<your-project-key>"
+        ))
+        return true
+    }
+}
+```
+
+### Step 4 -- Install User Feedback Triggers
+
+FeedbackKit provides multiple trigger options. Install one or more based on user needs:
+
+#### Option A: Shake to Report (Recommended for iOS)
+Triggers the capture and annotation UI whenever the user physically shakes the device or triggers a shake in the Simulator (`Device > Shake Gesture` / `⌃⌘Z`):
+
+```swift
+FeedbackKit.enableShakeToReport {
+    UIApplication.shared.connectedScenes
+        .compactMap { $0 as? UIWindowScene }
+        .flatMap { $0.windows }
+        .first { $0.isKeyWindow }?
+        .rootViewController
+}
+```
+
+#### Option B: Draggable Floating Trigger Button
+Places a persistent, draggable floating button over the UI:
+
+```swift
+FeedbackKit.showFloatingTriggerButton {
+    UIApplication.shared.connectedScenes
+        .compactMap { $0 as? UIWindowScene }
+        .flatMap { $0.windows }
+        .first { $0.isKeyWindow }?
+        .rootViewController
+}
+```
+
+#### Option C: Programmatic Presentation from UI
+Call directly from a button, menu item, or help screen:
+
+```swift
+// Present and automatically submit to the configured dashboard:
+FeedbackKit.presentAndSubmit(from: viewController)
+
+// Or present and handle the FeedbackReport manually:
+FeedbackKit.present(from: viewController) { report in
+    guard let report else { return } // User canceled
+    print("Report description: \(report.userDescription)")
+}
+```
+
+### Step 5 -- Track Screens (Recommended)
+
+Keep `FeedbackKit.currentScreen` updated during navigation so reports capture the active screen name:
+
+#### SwiftUI
+```swift
+struct CheckoutView: View {
+    var body: some View {
+        VStack {
+            // view content
+        }
+        .onAppear {
+            FeedbackKit.currentScreen = "Checkout"
+        }
+    }
+}
+```
+
+#### UIKit
+```swift
+override func viewDidAppear(_ animated: Bool) {
+    super.viewDidAppear(animated)
+    FeedbackKit.currentScreen = "Checkout"
+}
+```
+
+### Step 6 -- Optional Theming
+
+Customize the accent colors to match the app branding (hex color strings):
+```swift
+FeedbackKit.theme = .init(
+    primaryColorHex: "#0A84FF",
+    secondaryColorHex: "#64D2FF"
+)
+```
+
+### Step 7 -- Verify the Build
+
+Build the project to verify clean compilation:
+```bash
+xcodebuild build -scheme YourScheme -destination 'generic/platform=iOS Simulator'
+```
+
+## Non-Obvious Pitfalls
+
+- **Key Window Resolution**: In iOS 15+, `UIApplication.shared.keyWindow` is deprecated. Use the multi-scene resolution pattern shown in Step 4 (`connectedScenes -> UIWindowScene -> windows -> isKeyWindow`).
+- **Simulator Shake Testing**: To test shake-to-report in the iOS Simulator, select `Features > Shake Gesture` or press `Ctrl + Cmd + Z`.
+- **Window-Level Capture**: FeedbackKit captures screenshot at the window level (`UIWindow`), rendering both UIKit and SwiftUI hierarchies without needing view-controller-specific hooks.
+- **Optional Screenshot**: `FeedbackReport.screenshotRawPNG` and `FeedbackReport.screenshotAnnotatedPNG` are `Data?` (nullable) because users can toggle the screenshot off in the composer UI. Always handle optionality when processing reports manually.

package/skills/setup/setup-macos-sdk/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: setup-macos-sdk
+description: Integrate FeedbackKit SDK into a macOS desktop app (SwiftUI or AppKit) — adds package dependency, configures project credentials, sets up floating button or menu item triggers, and configures screen tracking.
+---
+
+# setup-macos-sdk
+
+Integrates the FeedbackKit SDK into a macOS desktop application (SwiftUI or AppKit). The agent adds the Swift package, initializes credentials at application startup, wires up macOS triggers (floating button or menu item), and configures screen tracking.
+
+## When to Use
+
+- Use when adding FeedbackKit feedback reporting to a macOS desktop application.
+- Trigger phrases: "add feedbackkit to macos", "setup feedbackkit in mac app", "install feedbackkit macos", "add feedback to appkit app".
+
+## Prerequisites
+
+- macOS 12.0+ deployment target.
+- Xcode 14+ / Swift 5.7+ toolchain.
+- A FeedbackKit project key and endpoint URL (optional if only handling local reports).
+
+## Step-by-Step Instructions
+
+### Step 1 -- Add Swift Package Dependency
+
+#### XcodeGen (`project.yml`)
+```yaml
+packages:
+  FeedbackKit:
+    url: https://github.com/tianhaoz95/feedback-kit
+    from: 1.0.0
+targets:
+  YourMacAppTarget:
+    dependencies:
+      - package: FeedbackKit
+```
+Regenerate Xcode project if using XcodeGen:
+```bash
+xcodegen generate
+```
+
+#### Swift Package (`Package.swift`)
+```swift
+dependencies: [
+    .package(url: "https://github.com/tianhaoz95/feedback-kit", from: "1.0.0")
+],
+targets: [
+    .target(
+        name: "YourMacAppTarget",
+        dependencies: [
+            .product(name: "FeedbackKit", package: "feedback-kit")
+        ]
+    )
+]
+```
+
+### Step 2 -- Configure FeedbackKit at Launch
+
+#### SwiftUI (`@main App`)
+```swift
+import SwiftUI
+import FeedbackKit
+
+@main
+struct MyMacApp: App {
+    init() {
+        FeedbackKit.configure(.init(
+            endpointURL: URL(string: "https://<your-project-ref>.supabase.co/functions/v1/ingest-feedback")!,
+            projectKey: "<your-project-key>"
+        ))
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+        .commands {
+            // Optional: Help menu feedback item
+            CommandGroup(replacing: .help) {
+                Button("Report a Problem…") {
+                    FeedbackKit.presentAndSubmit(from: NSApplication.shared.keyWindow)
+                }
+                .keyboardShortcut("r", modifiers: [.command, .shift])
+            }
+        }
+    }
+}
+```
+
+#### AppKit (`NSApplicationDelegate`)
+```swift
+import AppKit
+import FeedbackKit
+
+@main
+class AppDelegate: NSObject, NSApplicationDelegate {
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        FeedbackKit.configure(.init(
+            endpointURL: URL(string: "https://<your-project-ref>.supabase.co/functions/v1/ingest-feedback")!,
+            projectKey: "<your-project-key>"
+        ))
+    }
+}
+```
+
+### Step 3 -- Install Feedback Triggers on macOS
+
+macOS apps do not have shake sensors. The recommended triggers are floating buttons and menu items:
+
+#### Option A: Floating Trigger Button (Recommended)
+Places a draggable button over the main window content:
+```swift
+FeedbackKit.showFloatingTriggerButton {
+    NSApplication.shared.keyWindow
+}
+```
+
+#### Option B: Menu Bar Item
+Add a menu item in SwiftUI commands or an AppKit `NSMenuItem` action:
+```swift
+FeedbackKit.presentAndSubmit(from: NSApplication.shared.keyWindow)
+```
+
+#### Option C: Custom Button or Settings Action
+```swift
+// Present sheet and automatically submit to dashboard:
+FeedbackKit.presentAndSubmit(from: NSApplication.shared.keyWindow)
+
+// Or present sheet and process report manually:
+FeedbackKit.present(from: NSApplication.shared.keyWindow) { report in
+    guard let report else { return }
+    print("Report submitted: \(report.id)")
+}
+```
+
+### Step 4 -- Configure Screen Tracking
+
+Because macOS does not have a single mobile view-controller stack, set `FeedbackKit.currentScreen` when the user navigates:
+
+```swift
+.onAppear {
+    FeedbackKit.currentScreen = "Preferences"
+}
+```
+
+### Step 5 -- Verify the Build
+
+Verify that the macOS app compiles cleanly:
+```bash
+swift build
+# or
+xcodebuild build -scheme YourMacScheme
+```
+
+## Non-Obvious Pitfalls
+
+- **Sheet Presentation**: On macOS, FeedbackKit presents as a sheet attached to the target `NSWindow` rather than taking over the entire screen. Ensure `NSApplication.shared.keyWindow` or a specific window reference is non-nil when presenting.
+- **No Shake Sensor**: `FeedbackKit.enableShakeToReport` is iOS-only and does not exist on macOS. Use `showFloatingTriggerButton` or menu commands instead.
+- **No Screen Recording Permission Needed**: The SDK uses `NSView.cacheDisplay(in:to:)` to render the window's content hierarchy, which does not require macOS Screen Recording permissions.
+- **Trackpad Gestures**: Scaling and rotating annotations on macOS uses two-finger trackpad pinch and rotation (`NSMagnificationGestureRecognizer` and `NSRotationGestureRecognizer`).

package/skills/setup/setup-mcp-server/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: setup-mcp-server
+description: Configure the FeedbackKit CLI and Model Context Protocol (MCP) server for AI coding agents — installs feedbackkit-cli, completes browser-based authentication, and registers MCP server in Claude Code, Cursor, Antigravity, or Codex.
+---
+
+# setup-mcp-server
+
+Configures the FeedbackKit CLI and Model Context Protocol (MCP) server so that AI coding agents (Claude Code, Cursor, Antigravity, Codex, etc.) can directly query user feedback reports, inspect annotated screenshots, retrieve generated debugging prompts, and update ticket statuses without human copy-pasting.
+
+## When to Use
+
+- Use when connecting an AI coding agent to the FeedbackKit dashboard.
+- Trigger phrases: "setup feedbackkit mcp", "connect feedbackkit to claude code", "add feedbackkit mcp to cursor", "configure feedbackkit agent".
+
+## Prerequisites
+
+- Node.js 18+ and npm installed.
+- An account on the FeedbackKit hosted dashboard (or a running local instance).
+- An AI coding assistant that supports MCP (Claude Code, Cursor, Antigravity, Codex, Windsurf, etc.).
+
+## Step-by-Step Instructions
+
+### Step 1 -- Install the FeedbackKit CLI
+
+Install the CLI globally from npm, or run via `npx`:
+
+```bash
+npm install -g feedbackkit-cli
+```
+
+Verify installation:
+```bash
+feedbackkit --version
+```
+
+### Step 2 -- Authenticate the CLI
+
+Log in to your FeedbackKit account. This launches a browser window to complete GitHub OAuth and seamlessly passes credentials back to a temporary local server:
+
+```bash
+feedbackkit login
+```
+
+If connecting to a self-hosted or local development stack:
+```bash
+feedbackkit login --dashboard-url http://localhost:3000
+```
+
+Verify that access is active by listing projects:
+```bash
+feedbackkit list
+```
+
+### Step 3 -- Register the MCP Server with Your AI Agent
+
+The MCP server runs over stdio via `feedbackkit mcp` (or `npx -y feedbackkit-cli mcp`).
+
+#### Claude Code
+Add the MCP server to Claude Code using the CLI:
+```bash
+claude mcp add feedbackkit -- npx -y feedbackkit-cli mcp
+```
+
+Or configure Claude Desktop in `~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "feedbackkit": {
+      "command": "npx",
+      "args": ["-y", "feedbackkit-cli", "mcp"]
+    }
+  }
+}
+```
+
+#### Cursor
+Open Cursor Settings > MCP (or edit `.cursor/mcp.json` in your workspace):
+```json
+{
+  "mcpServers": {
+    "feedbackkit": {
+      "command": "npx",
+      "args": ["-y", "feedbackkit-cli", "mcp"]
+    }
+  }
+}
+```
+
+#### Google Antigravity
+Add via the `agy` CLI:
+```bash
+agy mcp add feedbackkit --command npx --args -y,feedbackkit-cli,mcp
+```
+Or add to your project's `.gemini/settings.json` under `mcpServers`.
+
+#### OpenAI Codex / Generic MCP Clients
+Configure an stdio server with:
+- **Command**: `npx`
+- **Arguments**: `["-y", "feedbackkit-cli", "mcp"]`
+
+### Step 4 -- Verify Available Tools
+
+Once connected, your agent will have access to five FeedbackKit tools:
+
+1. `list_feedback`: List feedback items filtered by project or status (`new`, `in_progress`, `resolved`, `closed`).
+2. `get_feedback`: Retrieve full details of an item including signed URLs for raw and annotated screenshots.
+3. `get_feedback_prompt`: Fetch the pre-formatted coding prompt generated by the dashboard's prompt template.
+4. `update_feedback_status`: Update the status of a feedback item (e.g. mark as `in_progress` or `resolved`).
+5. `get_docs`: Retrieve FeedbackKit documentation topics directly inside agent context.
+
+### Step 5 -- Test MCP Integration
+
+Prompt your agent:
+> "Use the feedbackkit MCP server to list any open feedback reports for this project."
+
+The agent should invoke `list_feedback` and present the feedback items.
+
+## Non-Obvious Pitfalls
+
+- **Authentication Storage**: `feedbackkit login` stores tokens securely in `~/.config/feedbackkit/config.json` (or OS equivalent). The MCP server automatically reads these credentials.
+- **Revocation**: Sessions can be audited or revoked at any time from the dashboard under **CLI Sessions** (`/cli-sessions`).
+- **No Token Overhead**: FeedbackKit does not require special API tokens or secret management for MCP — authentication inherits your dashboard account permissions and respects PostgreSQL Row-Level Security (RLS).

package/skills/setup/setup-watchos-sdk/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: setup-watchos-sdk
+description: Integrate FeedbackKit SDK into a watchOS app using FeedbackQuickNoteView — adds package dependency, configures project credentials, presents quick note modal, and tracks watch screen state.
+---
+
+# setup-watchos-sdk
+
+Integrates the FeedbackKit SDK into a watchOS application. Because Apple Watch screens are too small for freehand screenshot annotation, FeedbackKit provides `FeedbackQuickNoteView` — a streamlined text and context reporting interface embedded directly in SwiftUI.
+
+## When to Use
+
+- Use when adding in-app feedback to a standalone or companion watchOS app.
+- Trigger phrases: "add feedbackkit to watchos", "setup feedbackkit in apple watch app", "install feedbackkit watchos", "apple watch feedback reporting".
+
+## Prerequisites
+
+- watchOS 8.0+ deployment target (9.0+ for standalone watch apps).
+- SwiftUI-based watchOS project.
+- A FeedbackKit project key and endpoint URL (optional if consuming reports locally).
+
+## Step-by-Step Instructions
+
+### Step 1 -- Add Swift Package Dependency
+
+#### XcodeGen (`project.yml`)
+```yaml
+packages:
+  FeedbackKit:
+    url: https://github.com/tianhaoz95/feedback-kit
+    from: 1.0.0
+targets:
+  YourWatchAppTarget:
+    dependencies:
+      - package: FeedbackKit
+```
+Regenerate Xcode project if using XcodeGen:
+```bash
+xcodegen generate
+```
+
+#### Swift Package (`Package.swift`)
+```swift
+dependencies: [
+    .package(url: "https://github.com/tianhaoz95/feedback-kit", from: "1.0.0")
+],
+targets: [
+    .target(
+        name: "YourWatchAppTarget",
+        dependencies: [
+            .product(name: "FeedbackKit", package: "feedback-kit")
+        ]
+    )
+]
+```
+
+### Step 2 -- Configure FeedbackKit at Launch
+
+Initialize FeedbackKit inside your watchOS `@main App` struct's `init()`:
+
+```swift
+import SwiftUI
+import FeedbackKit
+
+@main
+struct MyWatchApp: App {
+    init() {
+        FeedbackKit.configure(.init(
+            endpointURL: URL(string: "https://<your-project-ref>.supabase.co/functions/v1/ingest-feedback")!,
+            projectKey: "<your-project-key>"
+        ))
+    }
+
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+```
+
+### Step 3 -- Present `FeedbackQuickNoteView`
+
+watchOS does not support modal window overlays or shake triggers. Embed `FeedbackQuickNoteView` inside a SwiftUI `.sheet`:
+
+```swift
+import SwiftUI
+import FeedbackKit
+
+struct ContentView: View {
+    @State private var showingFeedback = false
+
+    var body: some View {
+        List {
+            Section("Settings") {
+                Button {
+                    showingFeedback = true
+                } label: {
+                    Label("Send Feedback", systemImage: "bubble.left.and.exclamationmark")
+                }
+            }
+        }
+        .sheet(isPresented: $showingFeedback) {
+            FeedbackQuickNoteView { report in
+                guard let report else {
+                    // User canceled
+                    return
+                }
+                print("Submitted watch feedback: \(report.userDescription)")
+            }
+        }
+    }
+}
+```
+
+### Step 4 -- Configure Screen Tracking
+
+Set `FeedbackKit.currentScreen` on active watch views:
+
+```swift
+.onAppear {
+    FeedbackKit.currentScreen = "HeartRateMonitor"
+}
+```
+
+### Step 5 -- Verify the Build
+
+Verify the watchOS target compiles cleanly:
+```bash
+xcodebuild build -scheme YourWatchScheme -destination 'generic/platform=watchOS Simulator'
+```
+
+## Non-Obvious Pitfalls
+
+- **No Window Overlay or Shake**: `FeedbackKit.present(from:)`, `FeedbackKit.enableShakeToReport`, and `FeedbackKit.showFloatingTriggerButton` are not available on watchOS (there is no `UIWindow` or shake responder). Use `FeedbackQuickNoteView` directly in a SwiftUI sheet or view hierarchy.
+- **Placeholder Screenshot**: Since watchOS does not offer a public window-capture API, FeedbackKit automatically generates a lightweight, labeled placeholder card for `FeedbackReport.screenshotRawPNG` so that database fields and downstream prompt generators receive valid images.
+- **Dictation and Scribble**: `FeedbackQuickNoteView` uses standard SwiftUI text fields, enabling watchOS voice dictation, scribble, and QWERTY keyboards automatically.