## Summary
- Adds a `hexclave` SKILL.md pointer skill that fetches the live skill
body on every invocation
- Adds an `/SKILL.md` route on the MCP app that renders the full skill
(CLI usage + docs sidebar generated from `docs.json`)
- Expands `docs-mintlify/guides/getting-started/ai-integration.mdx` with
three install paths (CLI, Skill, MCP) and per-agent config snippets
- Updates `packages/stack-shared/src/helpers/init-prompt.ts` to install
both the MCP server and skill file, with per-project vs global scope
detection
## Test plan
- [ ] `pnpm typecheck`
- [ ] `pnpm lint`
- [ ] Hit the MCP app's `/SKILL.md` endpoint locally and verify it
returns valid markdown with the full docs sidebar
- [ ] Render the updated `ai-integration.mdx` in Mintlify preview and
confirm tabs/cards render
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Rewrote the AI integration guide with complete, user-facing
instructions for connecting Stack Auth to coding agents; removed the
separate MCP setup page and updated site navigation.
* Added the canonical Stack Auth skill content and guidance that clients
should fetch the latest skill at runtime.
* **New Features**
* MCP now serves the canonical Stack Auth skill dynamically and provides
interactive skill responses.
* Init prompts now include full MCP + skill install workflows and scope
guidance.
* Added a health-check endpoint.
* **Chores**
* Added scaffold and configs for a new skills app (build, dev, lint, and
type settings).
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1434?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
With the new bulldozer rework we dont support default products anymore.
Users are encouraged to currently manually handle granting products to
their end users.
We block api requests and new product creations that attempt to set no
price, and we remove any options to set include-by-default. We also
migrate users' existing product snapshots in `Subscriptions`,
`OneTimePurchases`, and `ProductVersions` to have no price set if it's
an include-by-default product. This will make it so that next time a
user goes onto their products page, they will be informed that the
pricing is invalid and it is no longer delivered by default.
Note, however, that these products will still be providing items and the
like to the users who have them.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Migrated legacy product snapshots so missing included-items no longer
break readers.
* Removed deprecated "include-by-default" pricing sentinel; pricing now
requires explicit price entries and write validation rejects the old
sentinel.
* **Chores**
* Simplified dashboard pricing flows: create/edit/save now use explicit
prices and surface an alert when a formerly implicit free plan needs an
explicit $0 price.
* Config overrides and stored data are auto-normalized to explicit price
objects.
* **Tests**
* Updated and added tests covering migration, validation, and switching
behavior for explicit prices.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mantrakp04 <mantrakp@gmail.com>
Co-authored-by: Mantra <87142457+mantrakp04@users.noreply.github.com>
## Summary
Refreshes the docs around Stack Auth setup, CLI workflows, local
development, the local emulator, known SDK errors, self-hosting, and the
public showcase. This also wires the new docs into Mintlify navigation
and normalizes `sharp` dependency resolution for docs/image tooling.
Base: `dev` -> Head: `docs-mintlify/updates`
Scope: 17 files, +1154 / -435
## What's New
- Adds a dedicated **Stack CLI** guide covering install, auth, init
modes, project commands, config pull/push, `stack exec`, and emulator
commands.
- Adds a full **Local Emulator** guide for QEMU requirements, ports,
default credentials, config-file backed projects, image pulls, state,
and troubleshooting.
- Reworks **Local Development** around two supported workflows:
cloud-backed local dev and emulator-backed local dev, including app env
vars, local config files, CI usage, and common failure modes.
- Rewrites **Self-host** around the supported `stackauth/server` Docker
deployment path, including Postgres, ClickHouse, cron scheduling, seeded
admin access, reverse proxy setup, SDK env vars, email, webhooks, S3
storage, upgrades, and common issues.
- Adds a **Known Errors** reference for public SDK-exposed known errors,
runtime `errorCode` values, and REST API handling.
- Clarifies **CLI App Authentication** so users can distinguish
authenticating their own CLI app from using the official `stack`
command.
- Updates the JWT guide to remove the missing inline viewer reference
and recommend an external JWT viewer.
- Adds showcase cards for Browser Use and Overworld with supporting
images and styles.
- Pins `sharp` to `0.34.5` through pnpm overrides and lockfile cleanup.
## Review Notes
- The self-host guide was audited against the current Docker entrypoint,
server env templates, seed script, ClickHouse migration behavior, cron
endpoints, and SDK API URL env resolution.
- The Docker image starts the backend and dashboard, but not production
schedulers, so the new cron section is called out explicitly.
- Managed Domain email setup is documented as operator-managed because
it depends on server-side Resend/DNSimple credentials; self-hosters are
directed toward Custom SMTP or their own Resend API key.
- `self-host-old.mdx` is kept as a legacy reference file and is not
added to navigation.
- `emulator run` documentation now matches CLI behavior: it stops the
emulator only when it started that emulator instance.
## Test Plan
- [x] Reviewed all files changed by `origin/dev...HEAD`.
- [x] Ran `git diff --check origin/dev...HEAD`.
- [x] Checked IDE diagnostics for the changed docs/CLI files.
- [ ] Preview Mintlify docs locally and click through new navigation
entries.
- [ ] Verify showcase cards and images in light and dark themes.
- [ ] Smoke-test the copied self-host commands in a non-production
Docker environment.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added comprehensive Stack CLI, Local Emulator, Known Errors, and Local
Development guides
* Restructured Self-Hosting guide for production deployments and
expanded authentication docs
* Updated site navigation to include new guide pages
* **New Features**
* Added visual showcase section with responsive cards and hover/zoom
interactions (and supporting styles)
<!-- 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
## Summary
- The CLI auth-attempt schema in
`apps/backend/src/app/api/latest/auth/cli/route.tsx` changed
`expires_in_millis.default` from 7,200,000 (2hr) to 120,000 (2min), but
the checked-in OpenAPI JSONs in `docs-mintlify/openapi/` were never
regenerated.
- This causes `lint_and_build` to fail on `dev` (and on every PR
branched off `dev`) because CI runs the codegen and then errors on the
resulting uncommitted diff.
## Changes
- Regenerated `admin.json`, `client.json`, `server.json` via `pnpm
--filter=@stackframe/backend codegen-docs`.
## Test plan
- [ ] CI's `lint_and_build` passes on this PR.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated CLI authentication token default expiration time from 2 hours
to 2 minutes across API specifications.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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 -->
