create-feedbax 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-feedbax",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "bin": {
     "create-feedbax": "./dist/cli.js"
@@ -10,17 +10,17 @@
   },
   "scripts": {
     "check-types": "tsc --noEmit",
-    "test": "vitest run src/index.test.ts src/template.test.ts",
+    "test": "vitest run src",
     "template:sync": "tsx ../../scripts/assemble-template.ts",
     "template:check": "tsx ../../scripts/assemble-template.ts --check",
     "build": "esbuild src/cli.ts src/index.ts --bundle --platform=node --format=esm --alias:@feedbax/config=../config/src/index.ts --alias:@feedbax/feedback=../feedback/src/index.ts --alias:@feedbax/changelog=../changelog/src/index.ts --outdir=dist --external:jsonc-parser --external:@clack/prompts",
     "prepack": "pnpm build"
   },
   "devDependencies": {
-    "esbuild": "0.28.1",
-    "tsx": "4.20.6",
+    "esbuild": "0.28.2",
+    "tsx": "4.23.15",
     "typescript": "catalog:",
-    "vitest": "4.1.11"
+    "vitest": "5.0.4"
   },
   "files": [
     "dist",
@@ -30,7 +30,7 @@
     "@clack/prompts": "^1.8.1",
     "jsonc-parser": "3.3.1"
   },
-  "description": "Create a self-hosted Notion-native feedback portal",
+  "description": "Create a self-hosted feedback portal with Notion or GitHub",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
     "url": "https://github.com/jessequartey/feedbax/issues"
   },
   "engines": {
-    "node": ">=22.14.0"
+    "node": "^24.15.0 || >=26.0.0"
   },
   "publishConfig": {
     "access": "public"

package/template/.feedbax-template.sha256

@@ -1 +1 @@
-93be110d268efb440ed36696b57319dc3fb7a0f89eae77651ac309faf7181494
+38ac71db749b85b9900fd636aa95867390517bc9695bc11534a44892e26810b2

package/template/.gitignore.template

@@ -1,5 +1,6 @@
 .dev.vars
 .env*
+.feedbax/
 dist/
 .wrangler/
 *.log

package/template/.npmignore.template

@@ -1,5 +1,6 @@
 .dev.vars
 .env*
+.feedbax/
 dist/
 .wrangler/
 *.log

package/template/.nvmrc

@@ -0,0 +1 @@
+24.22.0

package/template/AGENTS.md

@@ -0,0 +1,13 @@
+# Working on this Feedbax installation
+
+Read `README.md` for local setup, configuration, and checks. Read `CONNECTED.md` when configuring identity handoff, D1, sessions, verified Votes, or Comment attribution.
+
+This is a flat application, not the Feedbax development monorepo. Product settings are in `src/feedbax.ts`; infrastructure is in `wrangler.jsonc`; secrets are in ignored `.dev.vars` and encrypted Worker secrets. `src/feedbax.test-fixture.ts` is never a live configuration.
+
+Use the copied shadcn primitives in `src/components/ui`. Keep the configured Geist font and theme tokens. After changes, run `pnpm lint`, `pnpm type-check`, `pnpm test`, and `pnpm build`, fixing errors. Use `pnpm format:check` to check formatting.
+
+For setup, `pnpm exec feedbax doctor` must pass with the selected provider’s real credentials/mappings and enabled bindings. For GitHub provisioning, pairing, native publication, public-repository exposure, or provider secrets, read the GitHub setup and publication section in README.md. GitHub requires dedicated D1 independently of Connected identity and disables Changelog. Bootstrap deployment remains unpaired until the GitHub authorization flow completes. Run `pnpm deploy:dry-run` before deployment and verify the actual live URL after `pnpm exec feedbax deploy`. Distinguish copied source, configured local readiness, and a verified deployment in the result.
+
+## Connected social features
+
+For following, in-app/email notifications, or image attachments, use the full Connected guide (CONNECTED.md in a generated app; docs/connected-profile.md in the source repository). Apply every included D1 migration, including the Follow baseline migration, configure the timer and dedicated processing queue for small mode, choose Cloudflare/Resend/custom email when required, and keep the R2 bucket private for images. Never use a Device Profile as verified email evidence. Run doctor and behavior checks; explicitly distinguish local tests from real sender delivery and production authentication acceptance.

package/template/CONNECTED.md

@@ -0,0 +1,418 @@
+# Connected Profile
+
+Connected Profile is optional. Omit `connected` to retain the selected provider’s unsigned participation behavior. Published 0.2.1 uses Notion; 0.2.2 also supports GitHub. A Connected Installation requires a dedicated D1 database (reuse the Installation’s required provider D1 for GitHub) and an existing Product Team application that authenticates Participants on its server. There is no Feedbax email sign-in. Small processing also uses a dedicated Cloudflare Queue for background work.
+
+## Configure an Installation
+
+Create a D1 database using `pnpm exec wrangler d1 create <installation-name>`. Review the target account and add the returned identifiers to `wrangler.jsonc`:
+
+```json
+{
+  "d1_databases": [
+    {
+      "binding": "FEEDBAX_DB",
+      "database_name": "your-installation",
+      "database_id": "your-database-id",
+      "migrations_dir": "migrations"
+    }
+  ]
+}
+```
+
+Apply the included migration using `pnpm exec wrangler d1 migrations apply FEEDBAX_DB --remote` (and `--local` for local testing). Never share this database between Installations. Configure HTTPS for local sign-in testing because identity cookies require Secure.
+
+Add the following to `src/feedbax.ts`, alongside an absolute HTTPS `product.siteUrl`:
+
+```ts
+connected: {
+  issuer: "https://app.example.com",
+  loginUrl: "https://app.example.com/feedbax-login",
+},
+```
+
+Generate at least 32 random bytes for `IDENTITY_HANDOFF_SECRET`. Store the same secret only on the Product Team application's server and in the portal's `.dev.vars` / encrypted Worker secrets. Never place it in `feedbax.ts`, frontend code, a query string, or logs. The lifecycle CLI deploys this secret alongside the other configured secrets. `feedbax doctor` checks the configuration and reads the remote D1 schema without changing it.
+
+## Product application handoff
+
+1. Feedbax's Sign in action visits `/internal/identity/start`, sets a five-minute browser challenge cookie, and redirects to the configured login URL with `state` and `callback` query parameters.
+2. The Product Team application authenticates the current user. It must allow only the exact configured Feedbax callback, retain the supplied state, and derive the stable subject and display name from its authenticated server session. Never sign identity fields supplied by a browser.
+3. Sign the payload below on the application server with HMAC-SHA256. Times are Unix seconds; the token lifetime must be at most 120 seconds. Use an unpredictable nonce. The audience must exactly equal the Feedbax origin and the issuer must exactly equal the configured issuer.
+4. Return an HTML form which posts one `token` field to the allowlisted callback. Use `application/x-www-form-urlencoded` and `Referrer-Policy: strict-origin`. Do not put the token in a redirect URL. HTML-escape interpolated values. The form must retain its application Origin: `no-referrer` makes browser cross-origin form POSTs send `Origin: null`, which the portal rejects. `strict-origin` shares only the application origin, without its path or query.
+5. Feedbax validates the signature, origin, browser challenge, audience, issuer, and expiry, consumes the token nonce and browser challenge once, and creates an opaque seven-day HttpOnly session. Sign out revokes that session in D1. No identity token is stored in browser JavaScript storage.
+
+```js
+import { createHmac, randomBytes } from "node:crypto";
+
+// All identity values come from the application's authenticated server session.
+const now = Math.floor(Date.now() / 1000);
+const payload = Buffer.from(
+  JSON.stringify({
+    purpose: "feedbax-identity-v1",
+    subject: authenticatedUser.id,
+    displayName: authenticatedUser.displayName,
+    issuer: "https://app.example.com",
+    audience: "https://feedback.example.com",
+    state: validatedBrowserState,
+    nonce: randomBytes(32).toString("base64url"),
+    issuedAt: now,
+    expiresAt: now + 120,
+  }),
+).toString("base64url");
+const signature = createHmac("sha256", process.env.IDENTITY_HANDOFF_SECRET)
+  .update(`feedbax-identity-v1:${payload}`)
+  .digest("base64url");
+const token = `${payload}.${signature}`;
+```
+
+The application must use the same stable subject across browsers; never use display name or an unverified email as the subject. “Verified” means asserted by that trusted application, not legal identity or a guarantee of one account per human. The stored identity is scoped to the configured issuer and subject. Changing the issuer or subject scheme requires deliberate identity migration; do not repurpose identifiers for other people. Secret rotation blocks old handoffs; existing opaque sessions remain valid until expiry, logout, or explicit database revocation.
+
+## Data ownership and compatibility
+
+Notion remains authoritative for Posts, publication, Team workflow, and Comment content. D1 owns identity, sessions, unique Votes, and verified Comment attribution. A unique database key enforces one Vote per subject and Post; repeated add/remove requests are idempotent. Counts and Top ordering in Connected Profile use D1, including across browsers. Anonymous historical Notion counts are preserved in Notion but excluded from verified counts; they cannot be migrated into verified Votes without identity evidence. The Notion Vote Count property remains the legacy Notion-only counter, not a synchronized Connected counter.
+
+Native Comments receive the signed display name on the server. Only Comments with durable D1 attribution are labeled Verified; historical Comments remain Unverified. Notion-authored Comments retain the Product Team label. Resolving/deleting a Comment in Notion still removes it from public reads. Browser-held fifteen-minute Comment capabilities and unpublished Post draft capabilities retain their existing scope; this release does not add cross-device Comment editing or recover draft capabilities. Post submission still uses a private contact Device Profile, editable through Contact profile; it does not gain an identity-verification badge.
+
+If D1 is unavailable, Connected operations fail closed. They never fall back to anonymous voting or trust a browser-provided name. Attribution failures reject creation and attempt to remove the just-created Notion Comment; if external cleanup also fails, any surviving Comment remains unverified. The portal does not automatically retry Comment creation, since Notion offers no creation idempotency guarantee.
+
+Back up the database and use Cloudflare D1 recovery before destructive changes. Disabling `connected` retains D1 data but switches visible Vote counts back to Notion-only history. Expired sessions/nonces may be purged during maintenance after their expiry; never delete active rows to reset Votes.
+
+## Verification and operating limits
+
+Before enabling in production, test the real application's sign-in/callback, a second browser, duplicate Votes, sign out, invalid/expired/replayed tokens, and a native Notion Comment with verified attribution. Use the dedicated acceptance Installation; do not turn on the dogfood portal until a real application login endpoint is configured.
+
+Connected Top ranking currently reads all matching Published Posts before ranking and pagination. This favors correct ranking for the initial small-team scope; measure larger installations before adoption. Public counts can be briefly cached under the existing public-read policy; private Vote state and identity endpoints are never publicly cached.
+
+Implementation references: [D1 database batches](https://developers.cloudflare.com/d1/worker-api/d1-database/) and [Drizzle D1 adapter](https://orm.drizzle.team/docs/sqlite/connect-cloudflare-d1).
+
+## Complete application endpoint
+
+Copy the following into your application's server code. It returns a standard Web `Response` and works behind a Node-compatible route handler. Configure the app's existing authentication middleware before this endpoint so an unauthenticated Participant is taken through normal app sign-in and returned to the same handoff URL. If your middleware does not redirect, the example returns an explicit 401; sign in to the product first and retry Feedbax.
+
+The only app-specific dependency is `authenticate(request)`: call the same trusted session lookup used by your protected app pages. Return a stable internal user ID as `subject` and its server-read display name. Never read these values from form input, query parameters, browser storage, or an unsigned header. Do not hardcode a demonstration user in production.
+
+```ts title="server/feedbax-login.ts"
+import { createHmac, randomBytes } from "node:crypto";
+
+export function createIdentityLoginHandler(options: {
+  applicationOrigin: string;
+  portalOrigin: string;
+  issuer: string;
+  secret: string;
+  authenticate(request: Request): Promise<{
+    subject: string;
+    displayName: string;
+    email?: string;
+    emailVerified?: boolean;
+  } | null>;
+}) {
+  const app = new URL(options.applicationOrigin).origin;
+  const portal = new URL(options.portalOrigin).origin;
+  if (
+    ![app, portal, options.issuer].every(
+      (url) => new URL(url).protocol === "https:",
+    ) ||
+    options.secret.length < 32
+  )
+    throw new Error(
+      "Configure HTTPS origins and a server-only handoff secret of at least 32 characters.",
+    );
+  const headers = {
+    "Cache-Control": "no-store",
+    "Referrer-Policy": "strict-origin",
+  };
+  return async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    if (request.method !== "GET")
+      return new Response("Method not allowed", { status: 405, headers });
+    const state = url.searchParams.get("state");
+    const callback = url.searchParams.get("callback");
+    if (
+      url.origin !== app ||
+      !state ||
+      !/^[A-Za-z0-9_-]{43}$/.test(state) ||
+      callback !== `${portal}/internal/identity/callback` ||
+      url.searchParams.getAll("state").length !== 1 ||
+      url.searchParams.getAll("callback").length !== 1
+    )
+      return new Response("Invalid Feedbax sign-in request", {
+        status: 400,
+        headers,
+      });
+    const user = await options.authenticate(request);
+    if (!user)
+      return new Response(
+        "Sign in to your product, then retry Feedbax sign-in.",
+        { status: 401, headers },
+      );
+    if (
+      ![user.subject, user.displayName].every(
+        (value) =>
+          typeof value === "string" &&
+          value.trim().length > 0 &&
+          value.length <= 512,
+      )
+    )
+      return new Response("Application identity is incomplete", {
+        status: 403,
+        headers,
+      });
+    const now = Math.floor(Date.now() / 1000);
+    const payload = Buffer.from(
+      JSON.stringify({
+        purpose: "feedbax-identity-v1",
+        subject: user.subject,
+        displayName: user.displayName,
+        ...(user.emailVerified === true && user.email
+          ? { email: user.email, emailVerified: true }
+          : {}),
+        issuer: options.issuer,
+        audience: portal,
+        state,
+        nonce: randomBytes(32).toString("base64url"),
+        issuedAt: now,
+        expiresAt: now + 120,
+      }),
+    ).toString("base64url");
+    const signature = createHmac("sha256", options.secret)
+      .update(`feedbax-identity-v1:${payload}`)
+      .digest("base64url");
+    const nonce = randomBytes(24).toString("base64url");
+    const html = `<!doctype html><html lang="en"><meta charset="utf-8"><title>Continue to feedback</title><body><form method="post" action="${escapeHtml(callback)}"><input type="hidden" name="token" value="${payload}.${signature}"><button type="submit">Continue to feedback</button></form><script nonce="${nonce}">document.forms[0].requestSubmit()</script></body></html>`;
+    return new Response(html, {
+      headers: {
+        ...headers,
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Security-Policy": `default-src 'none'; form-action ${portal}; script-src 'nonce-${nonce}'; frame-ancestors 'none'`,
+      },
+    });
+  };
+}
+function escapeHtml(value: string) {
+  return value.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[
+        character
+      ]!,
+  );
+}
+```
+
+Register the handler at the exact URL configured as `connected.loginUrl`. For a framework with Web route handlers, the wiring looks like this (adapt the import paths and session lookup to your application):
+
+```ts
+import { createIdentityLoginHandler } from "./server/feedbax-login";
+import { readAuthenticatedAppUser } from "./server/auth";
+
+export const GET = createIdentityLoginHandler({
+  applicationOrigin: "https://app.example.com",
+  portalOrigin: "https://feedback.example.com",
+  issuer: "https://app.example.com",
+  secret: process.env.IDENTITY_HANDOFF_SECRET!,
+  authenticate: async (request) => {
+    const user = await readAuthenticatedAppUser(request);
+    return user ? { subject: user.id, displayName: user.displayName } : null;
+  },
+});
+```
+
+`readAuthenticatedAppUser` is your existing application's authentication adapter, not a Feedbax API. On Next.js, the `GET` export belongs in `app/feedbax-login/route.ts`; keep the factory and session lookup in server-only modules. On TanStack Start, call the same handler from a server route's GET handler. Other frameworks can adapt their request/response objects to the Web API. Keep the route behind your current session middleware and rate limits; Feedbax does not create or manage the product's accounts.
+
+## Verify the entire sign-in loop
+
+1. Run `feedbax doctor`, build, and deploy the configured portal. Confirm its HTTPS origin exactly matches `product.siteUrl` and the application's configured audience/callback.
+2. Sign in to the product, open the portal, and choose Sign in. You should return with your server-provided display name. A handoff form never includes your API key or handoff secret.
+3. Add a Vote, reload, and sign in from another browser with the same product account. The Vote should still be selected. Repeated add requests must not increase it twice.
+4. Post a Comment and confirm Verified appears next to its app-provided name. A historical browser-only Comment still shows Unverified. Reply/resolve from Notion and confirm moderation is reflected after refresh.
+5. Sign out of Feedbax. Its session should stop authorizing Votes/Comments immediately. This signs out only the portal session; product sign-out is managed by the product. An already-issued portal session expires after seven days unless explicitly revoked sooner.
+6. Reuse a captured callback or change its state/audience/signature in a dedicated test environment. Feedbax must reject it. Do not copy production identity tokens into logs or issue reports.
+
+## Authentication troubleshooting
+
+| Symptom                                               | Check                                                                                                                                                                                                     |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Product endpoint returns 401                          | Use your existing session middleware and complete the product's login first; the `authenticate` adapter must read that session.                                                                           |
+| Invalid sign-in request on the product                | Preserve the single `state` and `callback` parameters; allow only the configured exact callback. Do not rebuild the callback from arbitrary browser input.                                                |
+| Callback returns 403                                  | The form must POST directly from the configured login URL's origin. Check reverse-proxy origin handling and sandbox policies.                                                                             |
+| Callback returns 401                                  | Check identical handoff secrets, exact issuer/audience, current server clocks, a lifetime of at most 120 seconds, and an unused browser challenge. Start sign-in again after a failed or expired attempt. |
+| Challenge cookie absent                               | Use HTTPS and the same browser. The challenge uses Secure, HttpOnly, SameSite=None, and the `__Host-` prefix. Cookie-blocking policies may require a normal top-level product/portal flow.                |
+| Doctor or participation returns unavailable           | Check the dedicated `FEEDBAX_DB` binding, applied migration, remote account/database, and required Worker secrets. The profile fails closed.                                                              |
+| Name differs from the current app name                | A session reads the last server-asserted name; sign in again after a profile change. Old Comments retain their recorded attribution.                                                                      |
+| Anonymous vote totals differ after enabling Connected | Historical Notion counters are not verified Vote records; Connected counts only D1 Votes.                                                                                                                 |
+
+## Keep the three server secrets distinct
+
+| Secret                                               | Stored where                                | Purpose                                                                 |
+| ---------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
+| `IDENTITY_HANDOFF_SECRET`                            | Product server and portal secret store      | Sign/verify identity handoffs.                                          |
+| `PARTICIPATION_SIGNING_SECRET`                       | Portal secret store                         | Participation Passes and short-lived Comment capabilities.              |
+| `FEEDBAX_API_SECRET` / portal `FEEDBAX_API_KEY_HASH` | Plaintext on product server; hash on portal | Trusted Post submission from the feedback block or another integration. |
+
+Generate independent random values. Store production values through your platform's secret manager. When rotating the handoff secret, coordinate both servers; existing portal sessions require separate revocation if they must be ended immediately.
+
+## Following and notifications
+
+Connected defaults to `processing: "small"`. Its five-minute timer only enqueues a constant work signal into a dedicated Cloudflare Queue; a consumer then prepares one Follow history page, observes one followed Post, attempts one notification email, and cleans up at most five images. This separates the Free timer's 10 ms CPU allowance from Queues' documented default consumer limit of 30 seconds. The queue contains no Participant identity, email, or content. Set `connected.processing: "standard"` for ten preparations/observed Posts, twenty emails, and fifty cleanups directly in the timer; that mode targets Workers Paid and needs no processing queue. Cloudflare Email Service separately requires Workers Paid for arbitrary recipients. Resend/custom delivery supports the small Free setup. See [Workers limits](https://developers.cloudflare.com/workers/platform/limits/), [Queues limits](https://developers.cloudflare.com/queues/platform/limits/), [Queues pricing](https://developers.cloudflare.com/queues/platform/pricing/), and [D1 limits](https://developers.cloudflare.com/d1/platform/limits/).
+
+### Create and bind the processing queue
+
+Create one queue for this Installation in the same Cloudflare account, before running the guided creator or deploying:
+
+```sh
+pnpm exec wrangler queues create your-installation-updates
+```
+
+The guided creator asks for its name and writes both bindings. For a manual setup, add this beside the existing D1 bindings in `wrangler.jsonc`:
+
+```json
+{
+  "triggers": { "crons": ["*/5 * * * *"] },
+  "queues": {
+    "producers": [
+      { "binding": "FEEDBAX_UPDATES", "queue": "your-installation-updates" }
+    ],
+    "consumers": [
+      {
+        "queue": "your-installation-updates",
+        "max_batch_size": 1,
+        "max_batch_timeout": 1,
+        "max_concurrency": 1,
+        "max_retries": 3,
+        "retry_delay": 60
+      }
+    ]
+  }
+}
+```
+
+Keep producer and consumer names identical, and use a dedicated queue for each Installation. Small mode fails closed when the binding is absent; it does not run the heavy work inline. `doctor` validates the paired bindings, bounds, remote queue existence, and all D1 migrations. Template-only output needs this configuration added manually. Local Wrangler simulates queues but does not prove remote capacity or email receipt.
+
+At five-minute intervals, normal small processing produces 288 signals/day, usually 864 queue operations (write/read/delete). Three queue redeliveries per signal would raise that to 1,728 operations; other queues share the account's Free allowance of 10,000 operations/day. Free retention is 24 hours. Keep the batch and concurrency at one. A failed queue invocation is retried up to three times, at least a minute apart; D1 remains the authority for unfinished work and the next timer signal can resume it. Leases, transactional checkpoints, event deduplication, and provider delivery keys protect repeated attempts. This is not an exactly-once guarantee. Watch timer CPU, queue backlog/failed consumers, D1 quotas, and provider limits on the actual account. No plan upgrade or billing change is performed by these settings.
+
+Connected Participants can explicitly Follow a Published Post from its detail view. Following is independent of voting; submitting, commenting, or voting does not silently subscribe a Participant. The header bell opens a private inbox with unread state, Mark read, Mark all read, pagination, and email preferences. Signing out hides these controls and private state is never publicly cached.
+
+The timer signals the small consumer every five minutes; standard mode observes directly. Small processing checks one active followed Post, prioritizing the least recently checked; standard checks ten. Each observation reads one 50-Comment cursor page and resumes later pages on subsequent jobs. Normal small cadence budgets 288 observations and email attempts per day, with additional attempts possible after queue redelivery. Busy Installations and long histories have longer latency; delivery older than 24 hours is skipped. Status notifications compare each Follow's recorded status, so minute-rounded Notion timestamps cannot hide an observed transition. Intermediate states between observations may be coalesced.
+
+A new Follow snapshots existing Comment IDs from its current minute, preventing both historical notices and missing later Comments with the same rounded timestamp. Small mode prepares every new Follow in the queue, reading one 50-Comment page per run; the request does not read Comment history. Standard mode prepares the first page immediately and resumes longer histories in the background. The button shows preparation with a cancel action until the baseline is complete. Updates begin when preparation completes; earlier Comments and status changes during preparation are excluded. Repeating Follow from another browser preserves the original baseline. Unfollowing cancels preparation and removes its private baseline. Participants do not receive notifications about Comments with their own recorded attribution.
+
+In-app notifications are deduplicated by event and Participant, survive browser changes, and retain independent read state. Notifications and outbound delivery recheck that the Post is still Published. Stop following from the same Post to stop future updates. Email is independently opt-in through the inbox switch and can be disabled there or through the unsubscribe link in each email. Unsubscribe links show a confirmation page on GET and accept a one-click POST from supporting mail clients. A link scanner's GET does not change preferences.
+
+### Verified delivery address
+
+Application identity and email ownership are separate assertions. To offer email notifications, derive both of these additional signed claims from your application's authenticated server record:
+
+```ts
+...(user.emailVerified === true
+  ? { email: user.email, emailVerified: true }
+  : {}),
+```
+
+Never accept these values from the browser or copy the unverified Device Profile. Feedbax ignores an email unless the signed `emailVerified` claim is true. The contact address is stored privately in D1, is refreshed at the next successful handoff, and never appears in public identity, Post, Comment, or notification responses. Existing handoff implementations without these optional claims keep working for in-app notifications. A subsequent handoff without a verified address removes email eligibility.
+
+### Choose one email sender
+
+All choices share notification content, opt-in, unsubscribe, the D1 delivery queue, and a stable `Idempotency-Key`. The sender address belongs to your verified sending domain. Do not use a Participant's address as the sender.
+
+**Cloudflare Email Service** uses the current structured Workers sending API. Onboard and verify your sending domain in Cloudflare Email Service, then configure:
+
+```ts
+connected: {
+  issuer: "https://app.example.com",
+  loginUrl: "https://app.example.com/feedbax-login",
+  email: { provider: "cloudflare", from: "updates@example.com" },
+},
+```
+
+```json
+{
+  "send_email": [
+    {
+      "name": "FEEDBAX_EMAIL",
+      "allowed_sender_addresses": ["updates@example.com"]
+    }
+  ]
+}
+```
+
+Use Email Service's outbound sending capability, not a restricted legacy inbound-routing destination. See [Workers sending API](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/) and [domain setup](https://developers.cloudflare.com/email-service/configuration/domains/). Local Wrangler simulation does not deliver real messages. Do not enable a remote email binding during general local testing; it sends real mail.
+
+**Resend** requires a verified domain and a sending API key. Set `email: { provider: "resend", from: "updates@example.com" }` and store the key as `EMAIL_PROVIDER_SECRET` in `.dev.vars` and `pnpm exec wrangler secret put EMAIL_PROVIDER_SECRET`. No email binding is required. Feedbax posts to `https://api.resend.com/emails`, passing its stable delivery key in the `Idempotency-Key` header. See [Resend sending](https://resend.com/docs/api-reference/emails/send-email) and [idempotency](https://resend.com/docs/dashboard/emails/idempotency-keys).
+
+**Custom HTTPS sender** connects your own backend or mail provider adapter:
+
+```ts
+email: {
+  provider: "custom",
+  from: "updates@example.com",
+  endpoint: "https://app.example.com/internal/feedbax-email",
+},
+```
+
+Store a dedicated shared bearer secret as `EMAIL_PROVIDER_SECRET`. Your endpoint must validate `Authorization: Bearer <secret>`, accept the following JSON, deliver or durably enqueue it, and return 2xx only after acceptance. It must persist `Idempotency-Key` uniqueness for at least 24 hours and return the same successful result for retries without sending again. Keep this endpoint private to the authenticated server contract; a browser must never receive the secret.
+
+```ts
+interface NotificationEmail {
+  from: string;
+  to: string[]; // exactly one recipient per Feedbax request
+  subject: string;
+  text: string;
+  headers: {
+    "List-Unsubscribe": string;
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click";
+  };
+}
+```
+
+Preserve the unsubscribe headers, disable tracking unless your Product Team has deliberately chosen it, and never return provider credentials or recipient details to the portal. Feedbax requires HTTPS, refuses redirects, and times out custom/Resend requests after ten seconds. This adapter can use SMTP or another provider behind your server; Feedbax does not require a general plugin system or expose SMTP passwords in application configuration.
+
+### Delivery limits and recovery
+
+Each small queue job attempts at most one email; a standard scheduled invocation attempts at most twenty. D1 leases serialize workers, and failures use bounded exponential retry, starting at one minute and capped at six hours. Delivery is abandoned after eight failed attempts or 24 hours, whichever comes first. Resend's provider deduplication window is 24 hours; Cloudflare's documented binding has no equivalent idempotency parameter, so a crash or ambiguous timeout after acceptance can result in a duplicate email. Custom senders must supply their own durable deduplication. No adapter promises exactly-once inbox delivery, and provider acceptance does not prove final recipient delivery. In-app notifications remain available when email fails. Inspect provider suppression/bounce logs and the private D1 delivery state to investigate delivery failures; never publish these records.
+
+## Image attachments
+
+Set `connected.images: true` and bind a dedicated private R2 bucket:
+
+```json
+{
+  "r2_buckets": [
+    { "binding": "FEEDBAX_IMAGES", "bucket_name": "your-installation-images" }
+  ]
+}
+```
+
+Create the bucket with `pnpm exec wrangler r2 bucket create your-installation-images`. Keep its r2.dev endpoint and public custom-domain access disabled; only Feedbax serves its objects. Apply all included D1 migrations. `PARTICIPATION_SIGNING_SECRET` must contain at least 32 random characters; it already supports participation capabilities and also signs scoped image review and unsubscribe links using independent purposes.
+
+Verified Participants can add up to four JPEG, PNG, or WebP images to a new Post or Comment. Each image is at most 5 MiB. The server checks MIME type, image signatures, size, ownership, and association permissions; SVG, video, and general file attachments are rejected. The form shows upload progress, previews, and removal controls and waits for uploads before submission. Text is still required. Images can be added on creation; replacing attachments on an existing Post or Comment is not part of this release.
+
+Images attach to the newly created Notion content through D1 records. Pending uploads are private to their authenticated uploader and expire after 24 hours. Scheduled cleanup removes unused uploads and retries interrupted deletions. Public image requests recheck Post publication and, for Comment images, that the Comment still exists in an open Thread. The uploader can inspect pending images and their own existing Draft Post images privately; removing the associated content also removes uploader and review-link access. Unpublishing a Post or resolving/deleting a Comment stops public image access; downloads use no-store and cannot be embedded from another origin.
+
+For a Draft Post, Feedbax writes read-only image review links into its private Notion page body. Team Members use them to inspect attachments before publication. These links are bearer capabilities: keep the page body private, do not paste its review URLs into public Description or Team Response fields, and restrict Notion workspace access normally. Public Post projections contain only the ordinary visibility-checked image route, never the review token. Rotating `PARTICIPATION_SIGNING_SECRET` invalidates existing private review links and email unsubscribe links as well as older participation capabilities.
+
+Images retain their original bytes; Feedbax does not transcode them or strip EXIF. R2 and D1 need coordinated backups because the association records authorize access to the objects. Removing the R2 binding must be paired with disabling `connected.images`; missing storage fails closed. Images are not included in the stable trusted `/api/v1/posts` submission contract or the copied feedback block in this release.
+
+## Expanded production acceptance
+
+In a dedicated Installation, apply all D1 migrations, configure the timer and processing queue for small mode, verify the sender domain, and use a private R2 bucket. Run `feedbax doctor`, then verify:
+
+1. Sign in from two browsers through the real product app, including a verified email assertion. Follow/unfollow the same Published Post and check continuity. Confirm a Device Profile cannot substitute for identity.
+2. Change a followed Post's status and add a Product Team Comment directly in Notion. Wait for the timer and queue consumer (or the standard scheduled invocation). Inspect their separate outcomes and CPU limits. Confirm exactly one in-app event per observed change, private read state across browsers, and no access from another Participant.
+3. Opt in to email for a test recipient, confirm provider acceptance and actual receipt, force a retry in the dedicated test adapter, and verify its documented deduplication behavior. Check unsubscribe GET is non-mutating and POST disables future email while retaining in-app updates.
+4. Upload an image to a Draft Post. Confirm only the uploader and private Notion review link can access it; publish the Post and confirm public display, then unpublish and confirm public access stops. Repeat for a Comment and resolve it in Notion.
+5. Reject a forged review link, wrong-owner image association, oversized/unsupported image, unsigned mutation, and cross-origin mutation. Check mobile previews, unread states, empty/error/retry states, and cleanup of abandoned uploads.
+
+These checks require your real application, sender, and infrastructure. Local tests and builds do not constitute production delivery or release evidence.
+
+## GitHub and My feedback in 0.2.2
+
+Provider setup and Participant authentication are separate. Complete the GitHub App service pairing and use the same Installation D1 database for Connected; GitHub needs no Notion token and disables Changelog. The existing issuer/subject trust pair, signed handoff, consent and session revocation rules remain unchanged. GitHub Participants need no GitHub account. Follow the GitHub setup guide before adding Connected bindings and secrets.
+
+My feedback provides private Submitted, Supported and Following views with bounded pagination. New submissions from a server-verified portal session gain ownership independently of their Device Profile. The owner can view eligible pending context and edit or withdraw a New, unpublished draft from another verified device. Publication or advancement beyond New ends edit authority.
+
+An older unsigned draft is not automatically owned. While its lifecycle remains eligible, sign in on the browser that still holds its capability, open My feedback, and explicitly link the draft. Both proofs are required. Matching names/email, browser storage alone without verified identity, and public URLs do not establish ownership. Existing ownership cannot be transferred by another Participant's claim.
+
+Private owner responses use an explicit projection and `no-store`; no provider handles, contacts, capability hashes or identity subjects are returned. The browser resets private lists and editors before a session refresh, using an opaque session key rather than a display name to separate cached views. Sign-out revokes the session and reloads the page.
+
+Apply every included D1 migration before enabling the new views, including `0007_ownership.sql`; GitHub also needs the integration/recovery migrations. These additions do not create ownership for historical Posts or send historical Notifications. Existing 0.2.1 Comment editing limits remain; the new cross-device authority concerns eligible owned Post drafts, not arbitrary provider moderation.
+
+GitHub Comments use explicit App-created public records and private attribution mappings. Private image access still follows current publication and Comment visibility. GitHub issues contain no private review links; native Notion's private page-body review links remain specific to Notion. The selected Content Provider stays authoritative for feedback content and publication, and D1 stays authoritative for verified participation.

package/template/README.md

@@ -0,0 +1,97 @@
+# Your Feedbax portal
+
+This is an application you own. Product Teams manage Posts, statuses, Comments, and release notes in the selected Notion or GitHub Content Provider; the portal runs on Cloudflare Workers.
+
+[Feedbax on GitHub](https://github.com/jessequartey/feedbax) · [Setup and operations](https://feedbax-docs.jessefquartey.workers.dev/docs)
+
+## Start locally
+
+Use Node.js 24.15+ (Node 24 LTS) and pnpm 10. The included `.nvmrc` pins the tested version; with nvm installed, run `nvm install` and `nvm use` before working on the Installation. Guided setup already installs dependencies and configures the app:
+
+```sh
+pnpm dev
+```
+
+Open the local address printed by Vite. If this directory was created with `--template-only`, run `pnpm install` and finish configuration first; copied source still requires provider configuration.
+
+## Configuration
+
+| File                | Purpose                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------- |
+| `src/feedbax.ts`    | Product settings, feature switches, selected provider mapping, and optional Connected settings           |
+| `.dev.vars`         | Ignored local provider/pairing credentials, API-key hash, and enabled signing/Turnstile/identity secrets |
+| `wrangler.jsonc`    | Worker name, hostnames, rate-limit bindings, and optional dedicated D1 binding                           |
+| `src/components/ui` | Your copied shadcn primitives, utilities, and theme                                                      |
+| `CONNECTED.md`      | Complete existing-application authentication setup and verification                                      |
+
+The plaintext trusted API key printed during setup belongs on your product server. The portal stores its hash. Never expose either Notion credentials or signing secrets through browser configuration. Existing `src/feedbax.test-fixture.ts` is for tests only.
+
+For template-only output, follow the [agent setup guide](https://github.com/jessequartey/feedbax/blob/main/docs/agent-setup.md) and supply real provider mappings and secrets before diagnostics. For Connected, follow `CONNECTED.md`, implement the signed application endpoint, bind a dedicated D1 database, and apply the included migration.
+
+## Check and deploy
+
+```sh
+pnpm exec feedbax doctor
+pnpm format:check
+pnpm lint
+pnpm type-check
+pnpm test
+pnpm build
+pnpm deploy:dry-run
+pnpm exec feedbax deploy
+```
+
+`doctor` checks actual configuration, permissions, and enabled bindings. `deploy:dry-run` checks the bundle. The final command publishes the configured Worker and uploads only supported secrets. Confirm the live URL and enabled flows afterward.
+
+## Customize and integrate
+
+Keep the included Geist font and shadcn theme tokens consistent. Run `pnpm lint` after UI changes; it checks theme colors, unknown Tailwind classes, and inspectable component classes. Update individual primitives instead of reapplying a full preset.
+
+Use the [feedback block guide](https://github.com/jessequartey/feedbax/blob/main/apps/docs/content/docs/integrations/feedback-block.mdx) to add feedback collection to your product. Its server helper uses a trusted submission key and new Posts remain unpublished until your Product Team publishes them through its selected provider. The portal’s standard footer links to Feedbax on GitHub.
+
+Keep Device Profiles and browser capabilities distinct from verified identity: names/email supplied by the browser are unverified, Votes without Connected are best-effort, and recent Comment editing uses short-lived browser capabilities. Connected adds signed identity, unique Votes, and durable attribution while keeping content in the selected provider.
+
+See `AGENTS.md` for the short agent workflow.
+
+## Connected social features
+
+For following, in-app/email notifications, or image attachments, use the full Connected guide (CONNECTED.md in a generated app; docs/connected-profile.md in the source repository). Apply every included D1 migration, including the Follow baseline migration, configure the timer and dedicated processing queue for small mode, choose Cloudflare/Resend/custom email when required, and keep the R2 bucket private for images. Never use a Device Profile as verified email evidence. Run doctor and behavior checks; explicitly distinguish local tests from real sender delivery and production authentication acceptance.
+
+## GitHub setup and publication
+
+GitHub requires a dedicated D1 database even without Participant sign-in. It uses no Notion token, and Changelog must be disabled. A GitHub App service holds the App key; this portal stores only its own directional binding credentials. Setup must use the public-fetch compatibility flag for Worker-to-Worker calls, or an explicitly configured Service Binding. Never copy an App private key into the portal.
+
+Apply every included D1 migration before deploying updated source:
+
+```sh
+pnpm exec wrangler d1 migrations apply FEEDBAX_DB --local
+pnpm exec wrangler d1 migrations apply FEEDBAX_DB --remote
+pnpm exec feedbax deploy --pairing-bootstrap
+pnpm exec feedbax pair-github GITHUB_APP_INSTALLATION_ID
+```
+
+Complete the printed GitHub authorization flow, then run `pnpm exec feedbax doctor`. Bootstrap deployment intentionally leaves feedback unavailable until authorization finishes. Local development uses local D1; production pairing writes credentials only into remote D1. A production binding does not automatically authorize a local development origin. Use a separately configured development Installation/repository when testing GitHub writes locally.
+
+Native GitHub workflow uses exactly one label: `feedbax:new`, `feedbax:reviewing`, `feedbax:planned`, `feedbax:in-progress`, `feedbax:shipped`, or `feedbax:closed`. Add `feedbax:published` independently to display a Post in the portal. Issue closure alone does not change its Feedbax status. Missing/conflicting status labels block draft changes until repaired.
+
+The issue body contains a versioned JSON section between `<!-- feedbax:public:v1 -->` and `<!-- /feedbax:public -->`. Edit its title, description, type and optional Team Response/release-notes URL to change approved portal content. Keep its immutable slug. Notes outside this section and ordinary engineering comments are never portal content. Portal Comments are separately marked App-created records with private attribution mappings.
+
+**A public repository exposes issue titles and bodies on GitHub immediately, including Posts awaiting portal moderation.** Use a private Feedback Repository for confidential intake. Portal moderation cannot make an existing public GitHub issue private.
+
+Connected identity remains independent: only verified application sessions get cross-device ownership, My feedback, unique Votes and Follows. D1 alone does not establish identity. Browser drafts can be explicitly linked only while New/unpublished and while the browser still possesses their capability.
+
+## Integration checks
+
+The [integration checklist](https://github.com/jessequartey/feedbax/blob/main/docs/integration-checklist.md) brings together provider setup, product-server intake, credential locations and authentication.
+
+Post details show Comments by default, with observed progress under Activities when enabled. Follow controls appear after Connected sign-in.
+
+For an observed public timeline, explicitly add root-level `history: true`, bind `FEEDBAX_DB`, apply all migrations including `0009_observed_history.sql`, and configure a timer. Reuse this Installation's existing GitHub/Connected D1 when present. The first public Post read establishes a baseline; later checks record public status and Team Response changes without backfilling private history. Follow the [history guide](https://github.com/jessequartey/feedbax/blob/main/apps/docs/content/docs/guides/progress-history.mdx). Omit the switch to preserve an existing Notion Installation's storage footprint.
+
+Before connecting your product, test a disposable submission from its server, retry with the same `Idempotency-Key`, and confirm one New, unpublished Post. Publish through the selected provider and check that only approved fields appear. Remove publication and verify the Post, Comments and images become unavailable.
+
+For Connected, verify two application accounts and two browsers: each account should see only its own My feedback and Notifications. Sign out, then check that private views clear. Test email and images only when enabled; a local build does not verify production sender delivery, identity handoff or private R2 access.
+
+Keep the product server's trusted key private. A trusted API submission does not acquire verified ownership from a submitted name, email or subject. Use the signed Identity Handoff for Participant identity. Follow the [submission API guide](https://github.com/jessequartey/feedbax/blob/main/apps/docs/content/docs/integrations/submission-api.mdx) and `CONNECTED.md` for working examples.
+
+For an existing customized 0.2.1 Installation, follow the [source upgrade guide](https://github.com/jessequartey/feedbax/blob/main/apps/docs/content/docs/guides/upgrading.mdx). The 0.2.2 CLI previews against the exact published baseline, preserves configuration, and supports source resume/rollback. Review private diffs and back up data separately; source recovery is not a complete archive/restore.

package/template/components.json

@@ -5,7 +5,7 @@
   "tsx": true,
   "tailwind": {
     "config": "",
-    "css": "src/components/ui/styles/globals.css",
+    "css": "src/index.css",
     "baseColor": "neutral",
     "cssVariables": true,
     "prefix": ""