<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **High Risk**
> Touches core sign-up/auth flows and user restriction semantics
(including new DB constraints) and introduces dynamic rule
evaluation/logging; misconfiguration or CEL/parser bugs could block
sign-ups or incorrectly restrict users.
>
> **Overview**
> Introduces **CEL-based sign-up rules** (config-driven) that are
evaluated during password/OTP/OAuth sign-ups and anonymous upgrades;
matching rules can reject sign-ups or mark users as admin-restricted,
and triggers are logged for analytics.
>
> Extends `ProjectUser` with `restrictedByAdmin` plus public/private
restriction details, updates restriction computation/filtering, and
exposes these fields via user CRUD (including validation + DB constraint
enforcing consistency when unrestricted).
>
> Adds a new dashboard **Sign-up Rules** page with a visual condition
builder (CEL <-> visual tree), drag-reorder by priority, per-rule 48h
sparkline analytics via a new hidden internal endpoint, and adds
user-page UI to view/edit manual restrictions. Also refactors ClickHouse
client initialization to require env vars (removing
`isClickhouseConfigured` checks) and adjusts CI container startup wait
time.
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
2141e689e8c1b72303b805e9234f996010d0880. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Sign-up Rules: visual rule builder, in-project CRUD with drag-reorder,
per-rule analytics, backend evaluation, and admin UI.
* Admin user restrictions: dashboard controls, banners/status,
public/private admin details surfaced in user views.
* **APIs & Schema**
* Config and user schemas extended; new SignUpRejected error and sign-up
rule types added.
* **Tests**
* Extensive unit and E2E coverage for rules, parser, evaluator,
analytics, and restricted-user flows.
* **Docs**
* Editorial guidance added to AGENTS.md.
* **Chores**
* DB statement timeout, updated clean script, minor dependency
additions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
- restricted users
- onboarding app
- waitlist app
- fixed an exception when setting primary email
- automatically update the JWT token on the client when the user object
changes
<!--
ONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR changes the default development ports for several background
services to avoid conflicts. PostgreSQL moves from port `5432` to
`8128`, Inbucket SMTP from `2500` to `8129`, Inbucket POP3 from `1100`
to `8130`, and the OpenTelemetry collector from `4318` to `8131`. All
references across configuration files, Docker Compose setups,
environment files, CI/CD workflows, test files, and documentation have
been updated to reflect these new port assignments. A knowledge base
document has been added to document the new port mappings.
⏱️ Estimated Review Time: 15-30 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
| --- | --- |
| 1 | `claude/CLAUDE-KNOWLEDGE.md` |
| 2 | `apps/dev-launchpad/public/index.html` |
| 3 | `docker/dependencies/docker.compose.yaml` |
| 4 | `docker/emulator/docker.compose.yaml` |
| 5 | `apps/backend/.env` |
| 6 | `apps/backend/.env.development` |
| 7 | `docker/server/.env.example` |
| 8 | `package.json` |
| 9 | `.devcontainer/devcontainer.json` |
| 10 | `apps/e2e/.env.development` |
| 11 | `.github/workflows/check-prisma-migrations.yaml` |
| 12 | `.github/workflows/docker-server-test.yaml` |
| 13 | `.github/workflows/e2e-api-tests.yaml` |
| 14 | `.github/workflows/e2e-source-of-truth-api-tests.yaml` |
| 15 | `.github/workflows/restart-dev-and-test.yaml` |
| 16 |
`apps/e2e/tests/backend/endpoints/api/v1/internal/email-drafts.test.ts`
|
| 17 | `apps/e2e/tests/backend/endpoints/api/v1/internal/email.test.ts`
|
| 18 | `apps/e2e/tests/backend/endpoints/api/v1/send-email.test.ts` |
| 19 |
`apps/e2e/tests/backend/endpoints/api/v1/unsubscribe-link.test.ts` |
| 20 | `apps/e2e/tests/backend/workflows.test.ts` |
| 21 | `docs/templates/others/self-host.mdx` |
</details>
[](https://discord.gg/n3SsVDAW6U)
[
<!-- RECURSEML_SUMMARY:END -->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> This PR introduces customizable development ports using
`NEXT_PUBLIC_STACK_PORT_PREFIX`, updating configurations, documentation,
and tests accordingly.
>
> - **Behavior**:
> - Default development ports for services are now customizable via
`NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - PostgreSQL port changed from `5432` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}28`.
> - Inbucket SMTP port changed from `2500` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}29`.
> - Inbucket POP3 port changed from `1100` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}30`.
> - OpenTelemetry collector port changed from `4318` to
`${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}31`.
> - **Configuration**:
> - Updated `docker.compose.yaml` to use new port variables for services
like PostgreSQL, Inbucket, and OpenTelemetry.
> - Environment files in `apps/backend`, `apps/dashboard`, and
`apps/e2e` updated to use `NEXT_PUBLIC_STACK_PORT_PREFIX`.
> - `package.json` scripts updated to reflect new port configurations.
> - **Documentation**:
> - Added `CLAUDE-KNOWLEDGE.md` to document new port mappings.
> - Updated `self-host.mdx` to reflect new port configurations.
> - **Testing**:
> - Updated test files in `apps/e2e/tests` to use new port
configurations.
> - Added `helpers/ports.ts` for port-related utilities in tests.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 76ef55f58f. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
----
<!-- ELLIPSIS_HIDDEN -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Enable configurable development ports via a
NEXT_PUBLIC_STACK_PORT_PREFIX, allowing parallel local environments with
custom port prefixes.
- **Bug Fixes**
- Updated local service port mappings and CI/workflow settings so
tooling and tests use the new prefixed ports consistently.
- **Documentation**
- Added docs and contributor guidance for running multiple parallel
workspaces with custom port prefixes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: N2D4 <N2D4@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
Removes Platform selection, moves docs to single /content folder and no
longer gens docs. Only API docs are generated here.
<!-- RECURSEML_SUMMARY:START -->
## High-level PR Summary
This PR makes significant changes to the documentation structure by
removing platform-specific content organization and consolidating docs
into a single `/content` folder. The primary goal is to simplify the
documentation architecture by eliminating the platform-specific routing
(Next.js, React, JavaScript, Python) and instead organizing content by
topic (guides, SDK, components) regardless of platform. The PR removes
platform selection functionality, platform-specific navigation, and the
automatic generation of platform-specific documentation pages. It
introduces a new docs tree filtering system that organizes content by
section rather than by platform. These changes should make the
documentation more maintainable and easier to navigate while focusing on
the content itself rather than platform-specific variations.
⏱️ Estimated Review Time: 30-90 minutes
<details>
<summary>💡 Review Order Suggestion</summary>
| Order | File Path |
|-------|-----------|
| 1 | `docs/package.json` |
| 2 | `docs/src/lib/docs-tree.ts` |
| 3 | `docs/src/lib/navigation-utils.ts` |
| 4 | `docs/src/components/homepage/iconHover.tsx` |
| 5 | `docs/src/components/sdk/overview.tsx` |
| 6 | `docs/src/components/layouts/shared/section-utils.ts` |
| 7 | `docs/src/components/layout/custom-search-dialog.tsx` |
| 8 | `docs/src/app/api/search/route.ts` |
| 9 | `docs/src/app/docs/[[...slug]]/page.tsx` |
| 10 | `docs/src/components/layouts/docs-header-wrapper.tsx` |
| 11 | `docs/src/components/layouts/docs-layout-router.tsx` |
| 12 | `docs/src/components/layouts/docs.tsx` |
| 13 | `package.json` |
</details>
[](https://discord.gg/n3SsVDAW6U)
<!-- RECURSEML_SUMMARY:END -->
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added many new guides (auth providers, OAuth, JWT, API keys, emails,
webhooks, orgs/teams, permissions, onboarding, customization), expanded
SDK & component reference pages, examples, and navigation metadata.
* Switched docs to a simpler section-based, platform-agnostic structure
and improved getting-started and production checklists.
* **Developer Experience**
* Enhanced docs UX: improved code-example UI with platform/framework
selectors, theme-aware highlighted code blocks, image zoom, and a
centralized code-sample registry.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Introduces an automated database migration system, replacing manual
Prisma commands with new scripts and updating workflows, configurations,
and tests accordingly.
>
> - **Auto-Migration System**:
> - Introduces `db-migrations.ts` script for handling database
migrations automatically.
> - Adds utility functions in `utils.tsx` for managing migration files.
> - Implements `applyMigrations` and `runMigrationNeeded` in `index.tsx`
for executing migrations.
> - **Workflow and Scripts**:
> - Updates GitHub workflows (`check-prisma-migrations.yaml`,
`e2e-api-tests.yaml`) to use new migration commands.
> - Replaces `prisma migrate` commands with `db:init`, `db:migrate`,
etc., in `package.json` and `README.md`.
> - **Testing**:
> - Adds `auto-migration.tests.ts` for testing migration logic and
concurrency handling.
> - **Configuration**:
> - Updates `.env.development` and `vitest.config.ts` for new
environment variables and paths.
> - Modifies `turbo.json` and `package.json` to include new migration
tasks and scripts.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 2c24183879. You can
[customize](https://app.ellipsis.dev/stack-auth/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
<!--
Make sure you've read the CONTRIBUTING.md guidelines:
https://github.com/stack-auth/stack-auth/blob/dev/CONTRIBUTING.md
-->
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Port dashboard to Next.js 15, update dependencies, and enhance Docker
workflows.
>
> - **Next.js 15 Migration**:
> - Update `next` to `15.2.3` in `apps/backend/package.json`,
`apps/dashboard/package.json`, and `examples/demo/package.json`.
> - Remove MDX support in `next.config.mjs`.
> - Use `turbopack` in `dev` scripts in `apps/dashboard/package.json`
and `examples/demo/package.json`.
> - **Docker Workflows**:
> - Add `docker-emulator-test.yaml` for testing Docker emulator.
> - Rename `docker-build.yaml` to `docker-server-build.yaml` and
`docker-test.yaml` to `docker-server-test.yaml`.
> - Update `docker-compose.yaml` for emulator setup.
> - **Code Refactoring**:
> - Convert several `Page` components to async functions in
`apps/dashboard/src/app`.
> - Use `dynamic` import for `react-globe.gl` in `globe.tsx`.
> - Remove `experimental` config in `next.config.mjs`.
> - **Dependency Updates**:
> - Update `react` and `react-dom` to `19.0.0` in
`apps/backend/package.json`, `apps/dashboard/package.json`, and
`examples/demo/package.json`.
> - Add `pnpm` overrides for `@types/react` and `@types/react-dom` in
multiple `package.json` files.
> - **Miscellaneous**:
> - Add `docker/readme.md` for Docker instructions.
> - Update `entrypoint.sh` for Docker server setup.
> - Remove `globals.d.ts` as it's empty.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 5f5d8fd65c. It will automatically
update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: ellipsis-dev[bot] <65095814+ellipsis-dev[bot]@users.noreply.github.com>
Co-authored-by: Zai Shi <zaishi00@outlook.com>
- fixes https://github.com/stack-auth/stack-auth/issues/530
Adding [commander](https://github.com/tj/commander.js) to parse CLI
arguments and options. Commander auto generates a help section based on
configured options.
Both `npx @stackframe/init-stack` and `npx @stacframe/init-stack --next`
both should initialize auth in working directory
```bash
➜ init-stack git:(dev) ✗ node dist/index.js --version
2.7.25
➜ init-stack git:(dev) ✗ node dist/index.js --help
Usage: @stackframe/init-stack [project-path] [options]
Stack Auth Initialization Tool
Arguments:
project-path Path to your project
Options:
-V, --version output the version number
--dry-run Run without making any changes
--neon Use Neon database
--js Initialize for JavaScript project
--next Initialize for Next.js project
--npm Use npm as package manager
--yarn Use yarn as package manager
--pnpm Use pnpm as package manager
--bun Use bun as package manager
--client Initialize client-side only
--server Initialize server-side only
--no-browser Don't open browser for environment variable setup
-h, --help display help for command
For more information, please visit https://docs.stack-auth.com/getting-started/setup
```
<!-- ELLIPSIS_HIDDEN -->
----
> [!IMPORTANT]
> Replaces manual CLI argument parsing with `commander` in `init-stack`,
simplifying code and auto-generating help text.
>
> - **Behavior**:
> - Replaces manual CLI argument parsing with `commander` in `index.ts`.
> - Automatically generates help and version output using `commander`.
> - Supports options like `--dry-run`, `--neon`, `--js`, `--next`,
`--npm`, `--yarn`, `--pnpm`, `--bun`, `--client`, `--server`,
`--no-browser`.
> - **Dependencies**:
> - Adds `commander` as a dependency in `package.json` and
`packages/init-stack/package.json`.
> - **Code Cleanup**:
> - Removes manual argument parsing logic from `index.ts`.
> - Simplifies `main()` function by using `commander` to handle options.
>
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=stack-auth%2Fstack-auth&utm_source=github&utm_medium=referral)<sup>
for 4d4e2a8324. It will automatically
update as commits are pushed.</sup>
<!-- ELLIPSIS_HIDDEN -->
---------
Co-authored-by: Konsti Wohlwend <n2d4xc@gmail.com>
Co-authored-by: Zai Shi <zaishi00@outlook.com>
