DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
## Summary
**Stacked on [#1475](https://github.com/hexclave/stack-auth/pull/1475)**
(`cl/hexclave-pr1`, the invisible compatibility layer). Diff vs that
base = the actual PR 2 code.
This is **PR 2 of the Stack Auth → Hexclave rebrand: the visible flip**.
Old wire identifiers (cookies, request/response headers, Bearer prefix,
JWT issuers, MCP tool name) keep working indefinitely via PR 1's
dual-accept. This PR flips every user-visible surface — package names
taught in docs, SDK class names in code examples, dashboard setup
snippets, page titles, error messages, email content, CLI binary,
default base URLs, GitHub repo slug, contributor guidance — to the
Hexclave brand.
See [`RENAME-TO-HEXCLAVE.md`](./RENAME-TO-HEXCLAVE.md) → *"PR 2: Rebrand
to Hexclave (visible)"* for the full per-work-area spec.
## What's implemented (per the plan's PR 2 scope)
- **SDK base URLs** flipped: `defaultBaseUrl` and
`defaultAnalyticsBaseUrl` in
[common.ts](packages/template/src/lib/stack-app/apps/implementations/common.ts:127)
→ `https://api.hexclave.com` / `https://r.hexclave.com`. PR 1's
[`getHardcodedFallbackUrls`](packages/stack-shared/src/utils/urls.tsx:199)
table now keys on the Hexclave domain.
- **Domain inventory sweep** (16 subdomains from the plan): every
`api/app/docs/discord/demo/mcp/skill/feedback/test/preview/r/api2/api.staging/idp-jwk-audience/built-with.stack-auth.com`
reference in production code, docs-mintlify, examples, READMEs, and
contributor guidance flipped to `*.hexclave.com`. Carve-outs: PR 1's
intentional JWT issuer dual-accept table in
[tokens.tsx](apps/backend/src/lib/tokens.tsx), the legacy `./docs/`
folder, the `unified-docs-widget` allowlist (deliberately accepts both
during DNS transition), and `url-targets.ts` hosted-component default
(baked into existing customer deploys).
- **`@deprecated` JSDoc** on every `Stack*` public export
([packages/template/src/lib/stack-app/index.ts](packages/template/src/lib/stack-app/index.ts)
+ [packages/template/src/index.ts](packages/template/src/index.ts)) —
`StackClientApp`, `StackServerApp`, `StackAdminApp` + every
constructor/options/JSON type, `StackHandler`, `StackProvider`,
`StackTheme`, `useStackApp`, `defineStackConfig`, `StackConfig`.
Hexclave\* aliases are now canonical.
- **Runtime `console.warn`**
([packages/template/src/internal/deprecation-warning.ts](packages/template/src/internal/deprecation-warning.ts))
— once-per-process when the SDK is loaded from a `@stackframe/*`
artifact. Detection uses the existing
`STACK_COMPILE_TIME_CLIENT_PACKAGE_VERSION_SENTINEL` (rewritten at build
time to e.g. `js @stackframe/stack@2.8.92` or `js
@hexclave/next@1.0.0`); `@hexclave/*` mirror artifacts short-circuit the
warning.
- **Tier 3 data migration**: new idempotent SQL migration
[`20260523000000_rename_internal_project_to_hexclave`](apps/backend/prisma/migrations/20260523000000_rename_internal_project_to_hexclave/migration.sql)
— updates the internal Project `displayName` 'Stack Dashboard' →
'Hexclave Dashboard' and `description` only if both still hold the
pre-rebrand defaults. Operator-renamed projects untouched, missing row
no-ops, re-runs are no-ops. [`seed.ts`](apps/backend/prisma/seed.ts:87)
default flipped. `getSharedEmailConfig("Stack Auth")` → `("Hexclave")`.
- **Tier 4 brand strings** (mechanical sweep, ~340 files):
- Page + OpenAPI titles (Hexclave API / Dashboard / REST API / Webhooks
API / Documentation). OpenAPI `info.description` documents
`X-Hexclave-*` headers as canonical with compat note on `X-Stack-*`.
- `HexclaveAssertionError` message text
([errors.tsx:71](packages/stack-shared/src/utils/errors.tsx:71)) — "an
error in Stack." → "an error in Hexclave."
- Known-error message templates
([known-errors.tsx](packages/stack-shared/src/known-errors.tsx)) flipped
to lead with `x-hexclave-*` + the new `docs.hexclave.com` URL; legacy
`x-stack-*` mentioned as compat aliases. **25 e2e test files updated in
lockstep**.
- Email content: failed-emails-digest body, sendTestEmail recipient (now
`sent-with-hexclave.com`), test-email-recipient default.
- `CHANGELOG.md` title → "Hexclave Changelog".
- `AGENTS.md` env var convention: new vars prefix `HEXCLAVE_` /
`NEXT_PUBLIC_HEXCLAVE_` for Category A/B; legacy `STACK_*` explicitly
noted as accepted via PR 1's dual-read.
- **CLI / init wizard**:
- Every dashboard setup snippet, init-stack template, and docs-mintlify
page teaches `npx @hexclave/cli@latest init` (was
`@stackframe/stack-cli`).
[setup-page.tsx](apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/(overview)/setup-page.tsx)
+
[link-existing-onboarding](apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client-parts/link-existing-onboarding.tsx).
- [init-stack](packages/init-stack/src/index.ts:634)
`STACK_*_INSTALL_PACKAGE_NAME_OVERRIDE` defaults flipped to
`@hexclave/*`.
- Generated `stack/client.ts` / `stack/server.ts` import from
`@hexclave/next` and reference `HexclaveClientApp` /
`HexclaveServerApp`.
- Internal `StackAuthKeys` dashboard component renamed to
`HexclaveKeys`.
- **docs-mintlify rewrite** (legacy `./docs/` intentionally untouched
per scoping decision):
- **78 MDX files swept**.
`@stackframe/{react,stack,js,tanstack-start,...}` →
`@hexclave/{react,stack,js,...}` in install snippets and code blocks;
`Stack*` SDK class names → `Hexclave*` in all code examples; 'Stack
Auth' brand phrase → 'Hexclave'.
- `openapi/{server,admin,client,webhooks}.json` titles → 'Hexclave REST
API' / 'Hexclave Webhooks API'.
- **Generators flipped before regeneration**:
-
[`packages/stack-shared/src/helpers/init-prompt.ts`](packages/stack-shared/src/helpers/init-prompt.ts),
[`/ai/prompts.ts`](packages/stack-shared/src/ai/prompts.ts),
[`apps/backend/src/lib/ai/prompts.ts`](apps/backend/src/lib/ai/prompts.ts),
[`apps/backend/src/lib/ai/tools/create-email-{template,draft}.ts`](apps/backend/src/lib/ai/tools/create-email-template.ts),
[`apps/skills/src/app/route.ts`](apps/skills/src/app/route.ts) (taught
MCP tool → `ask_hexclave` with compat note; CLI binary teach →
`hexclave`),
[`docs-mintlify/snippets/home-prompt-island.jsx`](docs-mintlify/snippets/home-prompt-island.jsx),
[`packages/template/README.md`](packages/template/README.md) +
integrations/convex/component/README.md.
- `generate-sdks` propagated changes to `packages/{react,stack,js}`.
- **OpenAPI dual-documentation**:
[`apps/backend/src/app/api/latest/route.ts`](apps/backend/src/app/api/latest/route.ts)
now lists `X-Hexclave-*` headers as primary documented schemas with
`X-Stack-*` duplicates marked `.optional()` (both accepted at runtime by
PR 1's normalize-at-proxy shim).
- **`@stackframe/emails` virtual module**: dual-aliased to
`@hexclave/emails` at the bundler boundary
([email-rendering.tsx:89](apps/backend/src/lib/email-rendering.tsx:89)).
Stored email templates continue to import from either name; new
AI-generated templates and the system prompt teach `@hexclave/emails`.
- **Tier 2 mirror-publish wiring** (new this PR, lays the groundwork for
`@hexclave/*` first publish):
-
[`scripts/rewrite-packages-to-hexclave.ts`](scripts/rewrite-packages-to-hexclave.ts)
— rewrites 9 publishable `@stackframe/*` → `@hexclave/*` `package.json`
files (reads `HEXCLAVE_VERSION` env or `--version=` flag), pins
cross-deps to the shared `@hexclave` version, registers `hexclave` bin
alongside `stack` for `@hexclave/cli`.
-
[`.github/workflows/npm-publish.yaml`](.github/workflows/npm-publish.yaml)
appended with rewrite-then-republish step. `pnpm publish` skips
already-on-npm versions so reruns are safe.
- **Sender email domain**: `noreply@stackframe.co` →
`noreply@sent-with-hexclave.com` (the dedicated transactional-sender
domain split per the plan, to isolate bulk deliverability from
`hexclave.com` reputation); `security@` / `team@stack-auth.com` inbound
mailboxes → `@hexclave.com`.
- **Self-host docs**: docker network / container names in the bash
examples flipped from `stack-auth` to `hexclave` (`hexclave-postgres`,
`hexclave-clickhouse`, `hexclave.env`). The docker image tag
`stackauth/server:latest` stays per the plan's locked decision.
- **GitHub repo slug**: `hexclave/stack-auth` → `hexclave/hexclave` in
every `package.json` `repository` field, README link, CHANGELOG
raw-asset URL.
## Carve-outs (deliberately untouched)
-
**[`apps/backend/src/lib/tokens.tsx`](apps/backend/src/lib/tokens.tsx)**
JWT issuer dual-accept table — PR 1 intentional infrastructure, kept
indefinitely.
- **Legacy `./docs/` folder** — per scoping decision (only
`docs-mintlify/` rewritten).
- **`unified-docs-widget` hostname allowlist** — accepts both
`.hexclave.com` (canonical) and `.stack-auth.com` (transition window)
for DNS rollout.
- **`url-targets.ts`** hosted-domain default
`.built-with-stack-auth.com` — wire identifier baked into existing
customer deploys; indefinite read-fallback.
- **Binary visual assets** (logos, favicons, OG images, README
screenshots) — out of scope for this PR. Need design work; tracked
separately.
## Verification
- **`pnpm typecheck`** on
`packages/{template,stack-shared,react,stack,js}` + `apps/dashboard`:
**all green**. The remaining backend / e-commerce-demo typecheck errors
are pre-existing (Prisma codegen output +
`./generated/api-versions.json` not present in fresh worktrees without
`pnpm run codegen-prisma` + a live DB) and unrelated to this diff.
- **`pnpm lint`** on the same 6 packages: all green.
- **Final grep** for residual `Stack Auth` / `stack-auth.com` /
`@stackframe/stack-cli@latest` references: zero outside the intentional
carve-outs above.
- **25 e2e test files updated in lockstep** with the known-error message
changes (asserted strings flipped to match the new x-hexclave-* +
compat-note messages).
## Deploy blockers (ops sequencing before this rebrand goes live)
This PR is code-complete, but the rebrand's visible surfaces (SDK
default URLs, dashboard links, npm READMEs, REST error messages, runtime
deprecation warning) all point at `*.hexclave.com` / `@hexclave/*`
resources that don't exist yet. None of these are fixable from a PR —
they're ops/registrar/npm work that has to be sequenced before merging
this to a release tag.
Suggested ordering, hardest blockers first:
### Tier 1 — required before customer-facing deploy (everything below
this line *will visibly break customers on day 1* if skipped)
1. **DNS + TLS for `api.hexclave.com` + `api1./api2.hexclave.com`** →
must point at the same backend that serves `api.stack-auth.com` (or a
backend that mirrors PR 1's dual-accept). The SDK's new `defaultBaseUrl`
is `https://api.hexclave.com`; every customer that relied on the old
default and upgrades to a post-PR2 SDK build sends API requests here.
Until this resolves, every default-config customer's API call NXDOMAINs.
2. **DNS for `app.hexclave.com`** → the dashboard. Referenced in the
SDK's default-error messages ("Please create a project on the Hexclave
dashboard at https://app.hexclave.com"), the init-stack flow's
`wizard-congrats` redirect, and the OAuth dashboard handoff.
3. **DNS for `docs.hexclave.com`** + Mintlify deploy → the SDK runtime
deprecation warning (`https://docs.hexclave.com/migration`), every
README, every "Learn more" link in the dashboard, and every REST API
error body (`/api/overview#authentication`) points here. The MDX is in
this PR; the docs build target needs DNS.
4. **DNS for `mcp.hexclave.com`** → the MCP server endpoint that every
taught agent integration (`claude mcp add ...`, `cursor`, `codex`,
`vscode`) registers. Until this resolves, every `npx
@hexclave/cli@latest init` MCP-registration step fails.
5. **Reserve the `@hexclave` npm scope + set repo variable
`HEXCLAVE_VERSION`** → the mirror-publish step in
`.github/workflows/npm-publish.yaml` is gated on this variable. Without
it, the entire taught onboarding command `npx @hexclave/cli@latest init`
404s from the npm registry, *and* every README that says "install
`@hexclave/next`" leads to install failure. Pick the initial version
intentionally (`1.0.0` or aligned to `@stackframe/stack`); don't accept
a silent default.
### Tier 2 — required before announcing the rebrand publicly (lookalike
or low-traffic surfaces, but visibly broken)
6. **DNS for `r.hexclave.com`** → the analytics beacon
`defaultAnalyticsBaseUrl`. Silent failure if missing (analytics drops),
but should land alongside Tier 1.
7. **Register `sent-with-hexclave.com` + full email auth (SPF / DKIM /
DMARC)** → the new default sender domain for shared-sender transactional
emails. Without it the dashboard "send test email" path emits bounces,
and shared-sender flows (`getSharedEmailConfig("Hexclave")`) deliver to
spam at best.
8. **MX + SPF / DMARC for `hexclave.com`** → `team@hexclave.com` and
`security@hexclave.com` mailboxes. The security disclosure mailbox is
referenced in [`.github/SECURITY.md`](.github/SECURITY.md);
`team@hexclave.com` is the actual recipient of internal feedback emails
sent at runtime by
[`apps/backend/src/lib/internal-feedback-emails.tsx`](apps/backend/src/lib/internal-feedback-emails.tsx).
Today, every runtime feedback email bounces.
9. **DNS for `skill.hexclave.com`** → the canonical AI-agent skill fetch
URL (the agent bootstrap pivot). Without it, the entire "agent downloads
`SKILL.md` from a known URL" flow taught in
[`packages/stack-shared/src/helpers/init-prompt.ts`](packages/stack-shared/src/helpers/init-prompt.ts)
fails.
10. **Create `github.com/hexclave/hexclave` as a public repo** (even as
a redirect to `hexclave/stack-auth`) **OR** rewrite every `package.json`
`"repository"` field + dashboard footer "view on GitHub" link to point
at `hexclave/stack-auth` (which already exists). Currently every npm
package page's "Repository" link is dead, and the dashboard's GitHub
button + dev-tool repo link are dead.
### Tier 3 — broken but low-visibility / low-traffic
11. **DNS for `discord.hexclave.com`** → Discord invite redirect, used
in every README's chip and the dashboard footer.
12. **DNS for `demo.hexclave.com`** → "✨ Demo" badge in every npm
package README. Broken-image badge on the package page.
13. **DNS + TLS for `built-with-hexclave.com`** → optional
hosted-handler domain (the default reverted to
`.built-with-stack-auth.com` in this PR's carve-outs, so this only
matters for projects that manually flip).
## Other follow-ups (not deploy-blocking)
- **E2E snapshot regen across the full suite** for the dual-emitted
`x-hexclave-*` response headers (PR 1 follow-up; `vitest -u` in CI
absorbs).
- **Binary visual assets** — logos, favicons, OG images, README
screenshots; need design pass.
- **Backend OpenAPI fumadocs regen** in CI flow — the JSON files in
`docs-mintlify/openapi/` are committed but regen runs in CI. Verify the
workflow that does this still works against the post-PR2 source.
- **Backend typecheck infra debt** — needs `codegen-prisma` +
`codegen-route-info` to clear; pre-existing, unaffected by this PR.
## Test plan
- [ ] CI runs full e2e suite (with `vitest -u` to absorb residual
snapshot deltas, then committed back).
- [ ] Spot-check: new `@hexclave/cli init` (once published) generates
`hexclave.config.ts` and works against a fresh project.
- [ ] Spot-check: existing customer with `@stackframe/stack` import sees
the once-per-process `console.warn` recommending `@hexclave/next` on SDK
init.
- [ ] Manual: dashboard setup page renders the `npx @hexclave/cli@latest
init` snippet and the `x-hexclave-publishable-client-key` API header in
the curl example.
- [ ] Manual: a fresh `pnpm run prisma migrate` against a clean DB sets
the internal project displayName to 'Hexclave Dashboard'.
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
## Summary
**Stacked on #1468** (`docs/hexclave-rename-plan` — the plan doc). Diff
vs that base = the actual PR 1 code.
This is **PR 1 of the Hexclave rebrand: the invisible compatibility
layer**. Everything is additive. Old SDKs, old wire identifiers, and old
env var names keep working unchanged. The backend dual-accepts and
dual-emits; new SDK code emits `x-hexclave-*` headers and the
`hexclave_` Bearer prefix; cookies dual-write; env vars dual-read across
every category. **No user-visible rebranding lands here** — that's PR 2.
See [`RENAME-TO-HEXCLAVE.md`](./RENAME-TO-HEXCLAVE.md) → *"PR 1
implementation guide"* for the full per-work-area spec, file pointers,
and chosen approach.
## What's implemented (all 14 PR-1 work-areas)
- **SDK export aliases** — `Hexclave*` aliases for the user-facing
`Stack*` exports added in `packages/template`; codegen propagates them
to `@stackframe/{js,stack,react,tanstack-start}`. React-only aliases
correctly excluded from `@stackframe/js`. (`e60550a2`)
- **JWT issuer dual-accept** — `decodeAccessToken` accepts both
`api.stack-auth.com` and `api.hexclave.com` issuers. Signing unchanged.
(`fc781def`)
- **Request-header dual-accept** — backend + dashboard proxies normalize
`x-hexclave-*` → `x-stack-*` at the existing empty proxy hook (so
`smart-request.tsx` and every route schema keep working unchanged); CORS
allowlists extended via a derive-once helper. (`2a056eac`)
- **MCP `ask_hexclave`** — registered alongside `ask_stack_auth` via a
shared helper; `ask_stack_auth` behavior byte-identical. (`30ffd604`)
- **Dev-tool** — DOM ids + header emit switched.
`window.HexclaveDevTool` exposed alongside `window.StackDevTool`.
(`32131ea7`)
- **The big consolidated commit** (`7fed864a`):
- **Env vars** — central `getEnvVariable` prefix-transform (HEXCLAVE
first, STACK fallback); dashboard + template client env files dual-read;
`turbo.json` globalEnv; `NEXT_PUBLIC_STACK_PORT_PREFIX` renamed outright
across ~82 files including docker.
- **Cookies** — dual-write/dual-read auth (`stack-access`/`-refresh-*`
and custom-domain variants), OAuth-state
(`stack-oauth-{inner,outer}-*`), and low-risk cookies (`stack-is-https`,
`stack-last-seen-changelog-version`). Bypass sites patched (backend
OAuth callback, dashboard remote-dev auth route, impersonation snippets,
snapshot serializer).
- **Bearer prefix** — SDK token parser accepts both `stackauth_` and
`hexclave_`; emits `hexclave_`. Discovery correction: this is purely
SDK-internal — the backend never parses it.
- **Response headers** — backend dual-emits
`x-hexclave-{request-id,actual-status,known-error}`; SDKs dual-read (new
first, stack fallback).
- **SDK request-header emit switch** —
`client/server/admin-interface.ts` + dashboard `api-headers.ts` +
`internal-project-headers.ts` + `feedback-form.tsx` switched to
`x-hexclave-*`. Plus `stack_response_mode` query param.
- **Storage keys** — dev-tool / cli-auth / oauth-button / docs keys
renamed (straight); `stack:session-replay:v1` dual-read so in-progress
recordings survive SDK upgrades; `stack_mfa_attempt_code` dual-read.
- **Query params** — cross-domain params dual-emit/dual-accept via
shared helpers; backend `oauth/authorize` accepts
`hexclave_response_mode` and `stack_response_mode`; `stack-init-id`
renamed.
- **`Symbol.for`** — app-internals symbol gets a parallel
`Symbol.for("Hexclave--app-internals")` getter on each attach site (no
read-site churn — old symbol still attached). 3 file-private symbols
renamed outright.
- **Config discovery** — prefer `hexclave.config.ts`, fall back to
`stack.config.ts` at every discovery site (CLI / dashboard / backend /
local-emulator); `init` writes the new filename; CLI credentials path
migrates.
- **Internal renames** — `StackAssertionError`,
`StackClient/Server/AdminInterface` renamed outright (no alias, per the
"internal-only → rename" rule). ~264 files touched.
- **Review-pass fixes** (`21217fbe`) — three real bugs found by parallel
review agents and fixed:
- `snapshot-serializer.ts` was interpolating the whole
`keyedCookieNamePrefixes` array (`${arr}`) — adding a second prefix
would have corrupted **every** OAuth-cookie snapshot, not just new ones.
- **Docker port-prefix producer/consumer mismatch** —
`entrypoint.sh`/`run-emulator.sh`/cloud-init `user-data` were still
producing `NEXT_PUBLIC_STACK_PORT_PREFIX` while the dashboard sentinel +
consumers had been renamed; silent self-host regression (custom port
prefix would be ignored).
- **Missing `hexclave-oauth-inner-*` dual-write** in the OAuth authorize
route — callback's fallback masked it but the dual-write was specified
by the plan.
- Plus: `mcp.test.ts` tool-list assertions updated to include
`ask_hexclave`; two dashboard header-emit sites switched to
`x-hexclave-*` for consistency.
- **E2E snapshot serializer follow-up** (`4b16cc5d`) —
`x-hexclave-request-id` added to the hidden-headers list (mirroring
`x-stack-request-id` treatment), and 2 sample inline snapshots
regenerated in `projects.test.ts` to include the new dual-emitted
headers.
## Verification
- **`pnpm typecheck`** — clean (the fresh-worktree `@/.source` / Prisma
codegen gap in `stack-docs` is pre-existing and unrelated).
- **`pnpm lint`** — 29/29 packages green.
- **`pnpm exec turbo run build --filter=./packages/*`** — 13/13 packages
build (including `@stackframe/stack-cli` once the dashboard standalone
is present).
- **Live E2E** against a running backend on `cl/hexclave-pr1`:
- `pnpm test run
apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts` — **6/6
pass** (verifies the new `ask_hexclave` tool — the hand-written inline
snapshot matched actual MCP server output).
- `pnpm test run
apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts` —
**11/11 pass** (verifies wire dual-accept + dual-emit end-to-end; the
snapshot serializer fix was found and applied during this check).
A four-agent parallel **review pass** also audited the full diff for
logic/runtime bugs across the work-areas (wire headers + JWT, cookies +
bearer + symbols, env vars, query params + config + MCP + aliases). All
in-slice review verdicts were ✓ except the three bugs listed above,
which are now fixed.
## Known follow-ups (out of scope for this PR)
- **E2E snapshots across the rest of the suite** — backend now
dual-emits `x-hexclave-{known-error,actual-status}` alongside
`x-stack-*`, which legitimately appears in inline snapshots throughout
`apps/e2e`. Two were regenerated here as a sample; the rest should regen
with `vitest -u` in CI.
- **Docker shell env vars beyond `PORT_PREFIX`** — `entrypoint.sh` still
reads `STACK_*` env vars directly (the JS-side `getEnvVariable`
transform doesn't help the shell). JS consumers dual-read so it works in
practice; full shell-level dual-read is a deeper self-host follow-up.
- **`@stackframe/stack-cli` build ordering** — pre-existing; needs
`build:rde-standalone` first. Not affected by this PR.
## Test plan
- [ ] CI runs full e2e suite (with `vitest -u` to absorb dual-emit
snapshot deltas, then committed back)
- [ ] Spot-check: an old SDK build (emitting only `x-stack-*`) still
authenticates against the new backend
- [ ] Spot-check: a new SDK (emitting `x-hexclave-*` / `Bearer
hexclave_*`) still authenticates against an old backend during deploy
ordering
- [ ] Manual: `npx @stackframe/stack-cli@latest init` (new onboarding
entrypoint) generates `hexclave.config.ts`
- [ ] Manual: existing `stack.config.ts`-only project still resolves (no
migration required)
---------
Co-authored-by: bilal <bilal@stack-auth.com>
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
## Summary
- Adds the generated `@stackframe/tanstack-start` workspace package
registration.
- Adds TanStack Start platform macros/dependencies to the SDK template
and generator.
- Adds TanStack Start cookie/token-store support plus the handler SSR
guard needed by Start.
## Scope
This intentionally excludes Dashboard V2 routes, hooks, components, app
shell logic, and dashboard API type additions. Those stay in the
existing dashboard PR/branch.
## Validation
- `pnpm install --lockfile-only --ignore-scripts`
- `pnpm install --ignore-scripts`
- `pnpm -C packages/template lint
src/components-page/stack-handler-client.tsx src/lib/cookie.ts
src/lib/stack-app/apps/implementations/client-app-impl.ts`
Package typecheck was attempted with `pnpm -C packages/template
typecheck`, but the clean worktree lacks generated package declaration
outputs for workspace dependencies such as `@stackframe/stack-shared`
and `@stackframe/stack-ui`. Per repo instructions, package
builds/codegen are not run by agents.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* TanStack Start integration: published SDK package, example demo app,
dashboard onboarding flow, framework-aware CTAs/docs, and a
TanStack-specific provider for client-only auth routes.
* Improved client/server auth: safer runtime guards and consistent
cookie/token-store behavior across SSR and client.
* **Documentation**
* New Integrations guide and expanded getting-started/setup docs with
TanStack Start examples and env/key guidance.
* **Chores**
* Template, build, tooling, and demo config updates to support the new
platform.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Splits the Stack Auth MCP server out of `apps/backend` and into a
dedicated Next.js app at `apps/mcp/`, served on port `:42` (suffixed via
`NEXT_PUBLIC_STACK_PORT_PREFIX`) and exposed in production at
`https://mcp.stack-auth.com/mcp`. The backend no longer carries the MCP
transport route; clients now point at the new host.
Base: `dev` → Head: `chore/move-mcp-to-a-sep-app`
Scope: 34 files, +1425 / −353
## What changed
- **New app** `apps/mcp/` — standalone Next.js + `@vercel/mcp-adapter`,
with:
- `src/app/api/internal/[transport]/route.ts` — MCP transport handler
(moved from backend)
- `src/app/mcp/route.ts`, `src/app/route.ts` — public landing + setup
page
- `src/app/health/route.ts` — health check
- `src/mcp-handler.ts`, `src/setup-page.ts`, `src/analytics.ts`
- **Backend** drops
`apps/backend/src/app/api/internal/[transport]/route.ts` (−105) — MCP
code is gone from the backend image.
- **Dashboard** install hint updated to point at
`https://mcp.stack-auth.com/mcp` (was `/`).
- **Dev launchpad** gets an MCP tile so the new service shows up
alongside the rest of the local stack.
- **CI** workflows (`db-migration-backwards-compatibility`,
`e2e-api-tests*`) start the MCP service in the background before running
tests.
- **Docs** (`docs-mintlify`, `docs/`) and `init-stack` / `init-prompt`
updated to reference the new URL.
- **E2E** `apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts`
reworked to hit the new host; `helpers.ts` and env files gain an MCP
base-URL var.
## Visuals
### New `apps/mcp` setup page (`https://mcp.stack-auth.com/`)
The standalone app's root now serves a self-contained MCP setup guide
with per-client instructions (Cursor, VS Code, Codex, Claude Code,
Claude Desktop, Windsurf, ChatGPT, Gemini CLI):
### Dev launchpad now lists the MCP service
New tile at port suffix `:42`, importance 2, alongside Backend /
Dashboard / Demo app:
## Notes for reviewers
- The MCP transport endpoint moved path: it was mounted under
`/api/internal/[transport]` in the backend; in the new app it's at the
same path but on the dedicated host. The public-facing URL is
`https://mcp.stack-auth.com/mcp`.
- `apps/mcp` ships its own PostHog analytics client (`src/analytics.ts`)
so the backend doesn't have to proxy events for it anymore.
- Port allocation: `${PORT_PREFIX}42` (default `8142` in dev). Picked to
fit the existing dev-launchpad importance-2 row.
- No DB migrations.
## Test plan
- [x] `apps/mcp` builds and `pnpm dev` serves on `:8142`
- [x] Dev launchpad renders the new MCP tile (screenshot above)
- [x] MCP setup page renders client tabs (screenshot above)
- [x] E2E `mcp.test.ts` updated to hit the new host
- [ ] CI green on `e2e-api-tests*` and
`db-migration-backwards-compatibility` workflows (they were touched to
start the MCP service)
- [ ] `init-stack` / `mcp.ts` install flow lands users on the new URL
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Standalone MCP app added with a public /mcp endpoint and health check.
* MCP appears in the dev-launchpad apps list.
* **Documentation**
* MCP endpoint updated to https://mcp.stack-auth.com/mcp in all setup
guides and installer snippets.
* Setup page enhanced with detailed client install tabs and
instructions.
* **Chores**
* MCP service integrated into CI/e2e workflows and local env configs.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- Move the `/api/internal/[transport]` MCP route from the docs app to
the backend, so the public `ask_stack_auth` MCP tool is served from the
same origin as the AI query API it proxies to.
- Replace the bespoke docs-tools HTTP client in
`apps/backend/src/lib/ai/tools/docs.ts` with an `@ai-sdk/mcp` client
that talks to Mintlify's generated MCP server. The backend AI agent now
consumes Mintlify's lower-level search/fetch tools directly instead of
going through the docs app.
- Swap `STACK_DOCS_INTERNAL_BASE_URL` for `STACK_MINTLIFY_MCP_URL`
(defaults to the Mintlify-hosted MCP URL).
- Move the `@vercel/mcp-adapter` dependency from `docs` to
`apps/backend`.
## Test plan
- [ ] `pnpm typecheck`
- [ ] `pnpm lint`
- [ ] e2e: new
`apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts` covers
`tools/list` and validation on `tools/call`
- [ ] Manual: hit `POST /api/internal/mcp` on the backend and confirm
`ask_stack_auth` is listed and callable
- [ ] Manual: confirm backend AI agent docs tools resolve via the
Mintlify MCP URL
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Backend docs tooling now uses a Mintlify MCP server for documentation
tools and discovery.
* **Chores**
* Development environment variables updated to point to the Mintlify MCP
endpoint.
* Backend dependency added to support MCP integration; docs package
dependency removed.
* **Tests**
* Added end-to-end tests for the internal MCP endpoint and tool
validation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
- Added new internal API endpoint for documentation tools, allowing
actions such as listing available docs, searching, and fetching specific
documentation by ID.
- Updated environment configuration to support optional internal secret
for enhanced security.
- Refactored existing search functionality to utilize the new docs tools
API instead of the previous MCP server.
- Improved error handling and response parsing for documentation-related
requests.
- Expanded documentation to clarify the relationship between the new
tools and existing API functionalities.
This update streamlines the documentation access process and enhances
the overall developer experience.
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Non-stream AI responses now include a consolidated finalText for
clearer answers.
* Added an internal docs-tools HTTP API to power doc listing, search,
and fetch with optional header-based access control and configurable
service origin.
* **Refinement**
* Consolidated multiple doc tooling paths into a single question-focused
flow; backend now routes to the unified docs-tools endpoint.
* **Documentation**
* Updated guides and knowledge base to describe the new docs query flow
and optional env configuration.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Documentation
* Updated setup instructions across all documentation to clarify that
the publishable client key is only required when your project
configuration enforces it, removing confusion about unconditional
requirements.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
adds 2027-track npm package and updates middleware.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added asynchronous visit tracking to improve analytics collection.
* **Chores**
* Added a new tracking dependency.
* Refined middleware: switched to a default export with improved typing
and async handling.
* Expanded redirect path mappings and improved header handling for more
reliable navigation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
This PR implements unified AI endpoint and custom dashboards.
**Unified AI Endpoint**
We now use a single endpoint throughout the codebase that makes the call
to openrouter. Specifically, email drafts, email templates, email
themes, wysiwyg, cmd centre ai search and docs ai, all use this unified
ai endpoint. All the tools are defined in the backend, all the prompts
exist in the backend.
How to review this PR for unified ai endpoint:
This PR will be easier to review if we look at the different folders
that were affected.
under packages - We added streaming functionality, and made renaming
changes
under docs - there are three files that have changed
package.json - we updated the package (we were previously using a very
old version of the package)
route.ts - we changed the call from a direct call to openrouter to the
unified ai endpoint
ai-chat.tsx - because of updating the package, we had to make changes to
adapt to the latest versions of the package
under backend
route.ts - the main unified ai endpoint. this endpoint uses various
support files
forward.ts - this is the forward to production functionality
models.ts - consists of the models, and the rules for selecting those
models
prompts.ts - consists of the base prompt + specific system prompts
depending upon the usage
schema.ts
every single file under ai/tools folder - which as the name suggests,
consists of the implementations of the different tools that can be
provided to the llm
route-handlers - added support for streaming to SmartRoute and response
under dashboard
ai-search/route.ts - refactored the file to use unified ai endpoint
chat-adapters.ts - refactored the file to use unified ai endpoint and
created extra checks for the ai generated code
**Custom Dashboards**
We let the user write their query in english. We then use AI to create
dashboards that are interactive, live and savable. This PR includes a
new package called dashboard-ui-components. This package has components
that are used in the dashboard and more importantly, these components
are being imported from esm in the ai generated code for custom
dashboards. We also change the bar at the top for the products pages.
How to review this PR:
Review the new package (package/dashboard-ui-components), the setup and
the files inside it.
Review the schema changes in stack-shared/src
Review the changes in dashboard. The following changes have been made
Updated the design-components folder since we moved the dashboard
components to the new package
Updated imports for these components accordingly
Updated the title bar of the product pages
Created the files for custom dashboards under the dashboards folder and
components under commands/create-dashboard
Created a script under dashboard/scripts that generates the file with
type definitions that would go to the llm
Review the backend
Started using unified ai endpoint
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added custom dashboards feature allowing users to create and manage
personalized dashboards with AI assistance.
* Integrated AI-assisted dashboard code generation with visual preview
and editing capabilities.
* Introduced new AI query endpoints supporting stream and generate modes
with configurable model quality/speed settings.
* **Improvements**
* Reorganized UI components into a dedicated component library package
for better code reuse.
* Enhanced chat architecture with improved message handling and tool
integration.
* Updated AI provider integration with improved configuration
management.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: Bilal Godil <bg2002@gmail.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated installation and setup instructions across all documentation,
README files, and getting started guides to use the new Stack CLI
command format for project initialization. Users will now see the
updated command throughout documentation and framework-specific setup
guides.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/change-history/e6033b34-4005-4a9e-9d21-d809e2d57896)
Adds documentation for the two new built-in email templates:
`payment_receipt` (sent when payments succeed) and `payment_failed`
(sent when payments fail). Updates the Emails guide to list these new
templates alongside existing authentication templates, and adds a
"Payment Emails" section to the Payments guide explaining that these
notifications are sent automatically for both one-time purchases and
subscription renewals.
### Trigger Events
<details>
<summary><a
href="https://github.com/stack-auth/stack-auth/pull/1106">stack-auth/stack-auth
PR #1106: payment email templates</a></summary>
<br>
**Promptless Research** (1 GitHub PR)
- [Reviewed
stack-auth/stack-auth#1106](https://github.com/stack-auth/stack-auth/pull/1106)
**Agent Response**
> I've completed the documentation updates for PR #1106. Here's a
summary of the changes:
>
> ## Documentation Suggestion Created
>
> **Title:** Document payment email templates
>
> **Changes made:**
>
> 1. **Emails guide** (`docs/content/docs/(guides)/apps/emails.mdx`):
> - Added `payment_receipt` and `payment_failed` to the "Built-in Email
Templates" section, keeping them consistent with the existing format for
other templates
>
> 2. **Payments guide**
(`docs/content/docs/(guides)/apps/payments.mdx`):
> - Added a new "Payment Emails" subsection under Dashboard Management
explaining that Stack Auth automatically sends email notifications when
payments are processed
> - Documents both templates with their key details (receipt link,
failure reason, etc.)
> - Notes that these apply to both one-time purchases and subscription
renewals
> - Includes a pointer to where templates can be customized
>
> The suggestion is ready for review at:
https://app.gopromptless.ai/change-history/e6033b34-4005-4a9e-9d21-d809e2d57896
</details>
---
**Help us improve Promptless** — If this suggestion missed the mark,
please [share quick
feedback](https://app.gopromptless.ai/change-history/e6033b34-4005-4a9e-9d21-d809e2d57896?openFeedback=1).
*If you want Promptless to make further changes on this PR, feel free to
leave a comment tagging Promptless (It won't show up in the user drop
down but Promptless will get it!)*
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/change-history/ea7c7471-778d-42ea-9845-fa380f013560)
Documents the new `is_restricted` and `restricted_reason` JWT claims
introduced for the onboarding/restricted users feature. Updates the JWT
documentation to explain these fields in the claims section, adds them
to the example payload, documents the restricted user token structure,
and adds the `include_restricted` JWKS parameter for manual token
verification.
### Trigger Events
<details>
<summary><a
href="e400985754...de0f937f46">stack-auth/stack-auth
commit (dev): de0f937 [CHANGELOG] - 2026.01.21</a></summary>
<br>
**Promptless Research** (1 webpage, 1 GitHub PR)
- [Read webpage from
github.com](e400985754...de0f937f46)
- [Reviewed
stack-auth/stack-auth#1069](https://github.com/stack-auth/stack-auth/pull/1069)
**Agent Response**
> I've completed my analysis of the changelog entry and created the
necessary documentation update.
>
> ## Summary
>
> After reviewing the changelog entry for **2026.01.21**, I identified:
>
> ### Already Covered by Existing Suggestions
> The payment-related items were already documented by existing
suggestions:
> - **Payments Settings page** → covered by the "Document payment
settings" suggestion
> - **Subscription renewal emails** → covered by the "Document payment
email templates" suggestion
> - **Invoice visibility** → covered by the "Document invoice listing
feature" suggestion
>
> ### New Documentation Created
> I created a new suggestion to address the remaining item: **"Updated
JWT documentation to include `isRestricted` and `restrictedReason`"**
>
> The suggestion updates the JWT Tokens documentation with:
> - **New claims documentation**: Added `is_restricted` (boolean) and
`restricted_reason` (nullable object with `type` field) to the Stack
Auth Specific Claims section
> - **Updated example payload**: Added the new fields to the example JWT
payload
> - **Restricted user tokens**: Documented how restricted user tokens
differ (`:restricted` audience suffix)
> - **JWKS parameter**: Added documentation for the
`include_restricted=true` parameter in the Manual JWT Verification
section
>
> These fields were introduced in PR #1069 "Onboarding app & restricted
users" to support the new onboarding flow where users who haven't
completed requirements (like email verification) are marked as
"restricted."
</details>
---
**Help us improve Promptless** — If this suggestion missed the mark,
please [share quick
feedback](https://app.gopromptless.ai/change-history/ea7c7471-778d-42ea-9845-fa380f013560?openFeedback=1).
*If you want Promptless to make further changes on this PR, feel free to
leave a comment tagging Promptless (It won't show up in the user drop
down but Promptless will get it!)*
---------
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/suggestions/9355c2e9-3f8e-4b9e-8857-92e937f4b7df)
Adds the required `lastModified` field to the sign-up-rules.mdx
frontmatter. Per client documentation requirements, all new MDX
documents must include a `lastModified` field in the frontmatter with
the current date.
### Trigger Events
<details>
<summary><a
href="e9886bc45a...4af15344eb">stack-auth/stack-auth
commit (dev): 4af1534 docs: Document Sign-up Rules feature
(#1183)</a></summary>
<br>
**Promptless Research** (1 GitHub PR)
- [Reviewed
stack-auth/stack-auth#1183](https://github.com/stack-auth/stack-auth/pull/1183)
**Agent Response**
> I've completed my analysis of this commit and created a suggestion to
fix an issue I found.
>
> ## Summary
>
> **Trigger:** Commit `4af1534` merged PR #1183 which documented the
Sign-up Rules feature.
>
> **What I found:** The new `sign-up-rules.mdx` file was missing the
required `lastModified` field in its frontmatter. Per documentation
requirements, all new MDX documents must include this field with the
current date.
>
> **Fix created:** I created a
[suggestion](https://app.gopromptless.ai/suggestions/9355c2e9-3f8e-4b9e-8857-92e937f4b7df)
that adds the missing `lastModified: "2026-02-24"` field to the
sign-up-rules.mdx frontmatter.
>
> The underlying Sign-up Rules documentation content itself is
comprehensive and well-written, covering rule creation, conditions,
actions, priority/default settings, common use cases, analytics, and the
rule testing feature.
</details>
---
_Tip: Set up a GitHub Issues trigger in
[Projects](https://app.gopromptless.ai/projects) to enable @Promptless
mentions in issues 🐙_
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/change-history/f3f4cc12-c710-4d2d-96cd-e5443c52c8f1)
Updates the Email Configuration documentation to mention that port 2465
is now supported alongside port 465 for implicit TLS (SMTPS)
connections. Also clarifies the terminology: 587 uses STARTTLS while
465/2465 use implicit TLS from byte 1.
### Trigger Events
<details>
<summary><a
href="02c67ef532...2288c9c65c">stack-auth/stack-auth
commit (dev): 2288c9c Port 2465 should have implicit TLS from byte
1</a></summary>
<br>
**Promptless Research** (1 webpage)
- [Read webpage from
github.com](02c67ef532...2288c9c65c)
**Agent Response**
> I've completed my analysis and created a documentation suggestion for
this commit.
>
> ## Summary
>
> The commit `2288c9c` adds port 2465 as a supported implicit TLS
(SMTPS) port alongside the existing port 465. This is a small but
meaningful fix for users who use non-standard SMTP ports.
>
> ## Documentation Change
>
> I created a suggestion that updates the **Email Configuration**
section in the Emails guide:
>
> **Before:**
> > Port: SMTP port (typically 587 for TLS or 465 for SSL)
>
> **After:**
> > Port: SMTP port (typically 587 for STARTTLS, or 465/2465 for
implicit TLS)
>
> This change:
> 1. Documents the newly supported port 2465 for implicit TLS
connections
> 2. Clarifies the terminology (STARTTLS vs implicit TLS) to be more
technically precise
>
> The suggestion is available for review at:
https://app.gopromptless.ai/change-history/f3f4cc12-c710-4d2d-96cd-e5443c52c8f1
</details>
---
_Tip: Add or adjust Promptless's style guide in [Agent Knowledge
Base](https://app.gopromptless.ai/configure/settings) ✍️_
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/change-history/ec26b3ff-78d8-4ae0-818b-2ad8b29f9f85)
Adds documentation for the new partial refund feature in the Payments
dashboard. Documents that USD transactions support both full and partial
refunds (specifying an amount up to the original charge), while non-USD
transactions only support full refunds. Also clarifies refund
eligibility requirements (non-test mode purchases with associated
prices).
### Trigger Events
<details>
<summary><a
href="https://github.com/stack-auth/stack-auth/pull/1123">stack-auth/stack-auth
PR #1123: Partial refunds frontend</a></summary>
<br>
**Promptless Research** (1 GitHub PR)
- [Reviewed
stack-auth/stack-auth#1123](https://github.com/stack-auth/stack-auth/pull/1123)
**Agent Response**
> I've completed the documentation update for this PR.
>
> ## Summary
>
> I reviewed PR #1123 which adds partial refund functionality to the
payments system, allowing admins to specify custom USD refund amounts
instead of being limited to full refunds.
>
> ### Documentation Update Created
>
> I updated the **Payments** guide
(`docs/content/docs/(guides)/apps/payments.mdx`) to document this new
feature:
>
> - Added a new **"Issuing Refunds"** subsection under the Transactions
section
> - Documented that USD transactions support both full and partial
refunds (specifying an amount up to the original charge)
> - Noted that non-USD transactions only support full refunds
> - Clarified refund eligibility requirements (non-test mode purchases
with associated prices)
>
> **Suggestion URL**:
https://app.gopromptless.ai/change-history/ec26b3ff-78d8-4ae0-818b-2ad8b29f9f85
</details>
This PR ties with #1123
---
**Help us improve Promptless** — If this suggestion missed the mark,
please [share quick
feedback](https://app.gopromptless.ai/change-history/ec26b3ff-78d8-4ae0-818b-2ad8b29f9f85?openFeedback=1).
*If you want Promptless to make further changes on this PR, feel free to
leave a comment tagging Promptless (It won't show up in the user drop
down but Promptless will get it!)*
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/change-history/09aa88eb-2871-4b0b-9014-bf08503ee645)
Adds new documentation for the Sign-up Rules feature that allows admins
to control who can sign up for their application. Documents how to
create rules in the dashboard, the available context variables (email,
emailDomain, authMethod, oauthProvider), the available actions (allow,
reject, restrict, log), rule priority ordering, default action settings,
common use cases like blocking disposable emails or restricting to
corporate domains, and how to use the built-in rule tester to simulate
sign-up requests before deploying rules. Placed under the Concepts
section.
### Trigger Events
<details>
<summary><a
href="13cd1f0f2b...7a35751f8e">stack-auth/stack-auth
commit (dev): 7a35751 Sign up rules (#1138)</a></summary>
<br>
**Promptless Research** (1 GitHub PR)
- [Reviewed
stack-auth/stack-auth#1138](https://github.com/stack-auth/stack-auth/pull/1138)
**Agent Response**
> I've completed the documentation for the Sign-up Rules feature
introduced in PR #1138.
>
> ## Summary
>
> Created a new documentation page for **Sign-up Rules** that covers:
>
> - **Overview**: How rules let admins control who can sign up using
conditions and actions
> - **Creating Rules**: Step-by-step instructions for the dashboard UI
> - **Available Conditions**: Documented all context variables (`email`,
`emailDomain`, `authMethod`, `oauthProvider`) and supported operations
(`contains`, `startsWith`, `endsWith`, `matches`, `==`, `!=`)
> - **Actions**: Explained all four action types:
> - **Allow** - Let users sign up normally
> - **Reject** - Block sign-up with optional internal logging message
> - **Restrict** - Allow sign-up but mark user for admin review (links
to JWT docs for restricted user tokens)
> - **Log** - Track patterns without affecting sign-up
> - **Priority & Default Action**: How rule ordering works and when to
use reject-by-default
> - **Common Use Cases**: Practical examples like blocking disposable
emails, corporate-only domains, and different rules per auth method
> - **Analytics**: Brief mention of the dashboard analytics showing rule
triggers
>
> The new page has been added to the navigation under the "Apps"
section, positioned near other authentication-related documentation.
</details>
<details>
<summary><a
href="457ff2bdbe...6fcf1a888f">stack-auth/stack-auth
commit (dev): 6fcf1a8 Test sign-up rules widget</a></summary>
<br>
**Promptless Research** (1 webpage)
- [Read webpage from
github.com](457ff2bdbe...6fcf1a888f)
**Agent Response**
> I've completed the documentation update for this commit. Here's a
summary:
>
> ## Summary
>
> I updated the existing [Sign-up Rules documentation
suggestion](https://app.gopromptless.ai/change-history/09aa88eb-2871-4b0b-9014-bf08503ee645)
to document the new **Test Rules widget** introduced in commit 6fcf1a8.
>
> ### Changes Made
>
> Added a new **"Testing rules"** section to the sign-up rules
documentation that covers:
>
> - **How to access the tester**: Navigate to the Sign-up Rules page and
click "Open tester"
> - **Test inputs**: Email address, authentication method (Password,
OTP, OAuth, Passkey), and OAuth provider
> - **Understanding results**:
> - **Outcome** - Whether the sign-up would be allowed or rejected, and
why
> - **Triggered rules** - All rules that matched, with their conditions
and actions
> - **Evaluation trace** - Detailed view of how every rule was evaluated
> - **Normalized context** - How the input was parsed (useful for
debugging conditions)
>
> This addition complements the existing sign-up rules documentation and
helps users test their rule configurations before deploying them to
production.
</details>
---
_Tip: Planning a big docs refactor? Use [Deep
Analysis](https://app.gopromptless.ai/deep-analysis) to get help with
the heavy lifting 🔍_
---------
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
https://www.loom.com/share/3b7c9288149e4f878693281778c9d7e0
## Todos (future PRs)
- Fix pre-login recording
- Better session search (filters, cmd-k, etc)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Analytics → Replays: session recording & multi-tab replay with
timeline, speed, seek, and playback settings; dashboard UI for listing
and viewing replays.
* **Admin APIs**
* Admin endpoints to list recordings, list chunks, fetch chunk events,
and retrieve all events (paginated).
* **Client**
* Client-side rrweb recording with batching, deduplication, upload API
and a send-batch client method.
* **Configuration**
* New STACK_S3_PRIVATE_BUCKET for private session storage.
* **Tests**
* Extensive unit and end-to-end tests for replay logic, streams,
playback, and APIs.
* **Chores**
* Removed an E2E API test GitHub Actions workflow.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Switched AI provider for improved streaming and model selection.
* Updated chat UI: smoother near-bottom scrolling, refined layout, and
visual enhancements.
* **Documentation**
* Removed legacy Stack Auth setup guide from docs.
* **Chores**
* Updated docs dependencies and environment configuration; added new API
key variable and removed an old global key.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* API error responses now include richer metadata (URL, HTTP method, and
inferred error type).
* Error panels show an error type badge (when known) and request
duration for failed calls.
* POST/PUT/PATCH requests consistently send JSON bodies and include
Content-Type headers, even when empty.
* Code examples (curl/JS/Python) updated to reflect consistent body and
header handling.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
[Open this suggestion in Promptless to view citations and reasoning
process](https://app.gopromptless.ai/change-history/2b709902-b62c-491c-ad6d-966069ad5ea7)
Adds documentation for configuring Apple Bundle IDs in the Stack Auth
dashboard, which is required for native iOS/macOS apps using Apple Sign
In. The new "Native App Configuration" section explains that Bundle IDs
are needed in addition to the existing web OAuth setup when using the
Swift SDK's native `ASAuthorizationController` flow, and provides
step-by-step instructions for adding Bundle IDs in the Apple
authentication method modal.
### Trigger Events
<details>
<summary><a
href="2a6b17339a...c8694c7ff5">stack-auth/stack-auth
commit (dev): c8694c7 [Fix] [Feat] Update OAuth Sign-In and Get Token
Functions to Work (#1130)</a></summary>
<br>
**Promptless Research** (1 GitHub PR)
- [Reviewed
stack-auth/stack-auth#1130](https://github.com/stack-auth/stack-auth/pull/1130)
**Agent Response**
> I've completed my analysis of PR #1130 and created a documentation
suggestion.
>
> ## Summary
>
> **PR #1130** adds Apple Native Sign In for iOS/macOS apps, which
requires users to configure Bundle IDs in the Stack Auth dashboard (in
addition to the existing web OAuth setup with Service IDs).
>
> ### What I found:
> - An existing suggestion already documents the Swift SDK and its OAuth
flows
> - However, the **Apple authentication provider page** didn't mention
Bundle IDs configuration for native apps
>
> ### Documentation created:
>
> **New suggestion: "Document Apple Bundle IDs for native iOS/macOS app
sign-in"**
>
> I added a new "Native App Configuration (iOS/macOS)" section to the
Apple authentication page that:
> - Explains that native iOS/macOS apps using the Swift SDK require
Bundle ID configuration
> - Clarifies that this is in addition to the web OAuth setup (not a
replacement)
> - Provides step-by-step instructions for adding Bundle IDs in the
Stack Auth dashboard
> - Notes that Bundle IDs are only required for native apps, not web
applications
>
> This complements the existing Swift SDK documentation suggestion by
covering the Apple-specific dashboard configuration that native app
developers need to complete.
</details>
---
**Help us improve Promptless** — If this suggestion missed the mark,
please [share quick
feedback](https://app.gopromptless.ai/change-history/2b709902-b62c-491c-ad6d-966069ad5ea7?openFeedback=1).
*If you want Promptless to make further changes on this PR, feel free to
leave a comment tagging Promptless (It won't show up in the user drop
down but Promptless will get it!)*
Co-authored-by: promptless[bot] <179508745+promptless[bot]@users.noreply.github.com>
Co-authored-by: Madison <madison.w.kennedy@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Removed Features**
* Dashboard embed functionality has been removed from the platform.
* Python template documentation and guides have been removed.
* **Documentation**
* Documentation structure has been significantly reorganized and
simplified.
* Extensive template content and component guides have been removed.
* Apple OAuth integration guide updated with streamlined secret
generation flow.
* **Refactor**
* Button component styling and variant system updated.
* Routing configuration updated with simplified path handling.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
