[Docs Mintlify] - Updates and new additions

docs-mintlify/docs.json

@@ -60,6 +60,8 @@
             "pages": [
               "guides/going-further/stack-app",
               "guides/going-further/backend-integration",
+              "guides/going-further/cli",
+              "guides/going-further/local-emulator",
               "guides/going-further/local-development",
               "guides/going-further/user-metadata"
             ]
@@ -130,6 +132,7 @@
             "group": "Other",
             "pages": [
               "guides/other/self-host",
+              "guides/other/known-errors",
               "guides/other/mcp-setup",
               {
                 "group": "Tutorials",

docs-mintlify/guides/apps/authentication/cli-authentication.mdx

@@ -1,9 +1,14 @@
 ---
-title: CLI Authentication
-description: How to authenticate a command line application using Stack Auth
+title: CLI App Authentication
+description: How to authenticate users in your own command-line application using Stack Auth
+sidebarTitle: CLI App Authentication
 ---
 
-If you're building a command line application that runs in a terminal, you can use Stack Auth to let your users log in to their accounts.
+If you're building your own command-line application, you can use Stack Auth to let users log in from a terminal.
+
+<Info>
+  This page is about adding authentication to your own CLI app. For the official `stack` command, see the [Stack CLI guide](/guides/going-further/cli).
+</Info>
 
 To do so, we provide a Python template that you can use as a starting point. [Download it here](https://github.com/stack-auth/stack-auth/tree/main/docs/public/stack-auth-cli-template.py) and copy it into your project, for example:
 
@@ -33,8 +38,8 @@ if refresh_token is None:
 
 # you can now use the REST API with the refresh token
 def stack_auth_request(method, endpoint, **kwargs):
-  # ... see Stack Auth's Getting Started section to see how this function should look like
-  # https://docs.stack-auth.com/python/getting-started/setup
+  # ... see the REST API overview for required Stack Auth headers
+  # https://docs.stack-auth.com/api/overview
 
 def get_access_token(refresh_token):
   access_token_response = stack_auth_request(

docs-mintlify/guides/apps/authentication/jwts.mdx

@@ -17,9 +17,6 @@ A JWT is a string that consists of three parts separated by dots (`.`):
 
 The structure looks like this: `header.payload.signature`
 
-## JWT Viewer
-
-Use the interactive JWT viewer below to decode and inspect JWT tokens. If you're signed in, it will automatically load and display your current session token:
 
 ## Stack Auth JWT Structure
 
@@ -264,7 +261,7 @@ const { payload } = await jose.jwtVerify(token, jwks, {
 
 ### Debugging JWTs
 
-Use the JWT viewer above to inspect tokens and verify their contents. Pay special attention to:
+Use a JWT viewer such as [jwt.io](https://jwt.io/) to inspect tokens and verify their contents. Pay special attention to:
 
 * Expiration times (`exp` claim)
 * Audience (`aud` claim) matching your project

docs-mintlify/guides/getting-started/setup.mdx

@@ -4,8 +4,6 @@ description: Install and configure Stack Auth for your project
 sidebarTitle: Setup
 ---
 
-# Setup
-
 ## Prerequisites
 
 Before getting started, make sure you have a project set up for your chosen platform:

docs-mintlify/guides/going-further/cli.mdx

@@ -0,0 +1,158 @@
+---
+title: "Stack CLI"
+description: "Use the Stack Auth CLI to initialize projects, manage config, run admin scripts, and start the local emulator"
+sidebarTitle: "Stack CLI"
+---
+
+The Stack Auth CLI is published as `@stackframe/stack-cli` and exposes the `stack` command. Use it for project setup, branch config workflows, quick admin scripts, and the [local emulator](/guides/going-further/local-emulator).
+
+## Install
+
+Install the CLI globally to use the `stack` command from any project:
+
+```sh title="Terminal"
+npm install -g @stackframe/stack-cli@latest
+```
+
+Then check that it is available:
+
+```sh title="Terminal"
+stack --help
+```
+
+You can also run any command without installing globally by prefixing it with `npx @stackframe/stack-cli@latest`, for example:
+
+```sh title="Terminal"
+npx @stackframe/stack-cli@latest init
+```
+
+## Global options
+
+These options can be used before a subcommand:
+
+| Option | Description |
+| --- | --- |
+| `--project-id <id>` | Project ID for commands that operate on one project. You can also set `STACK_PROJECT_ID`. |
+| `--json` | Print JSON output for commands that support it, such as `project list` and `project create`. |
+| `--version` | Print the CLI version. |
+
+The CLI reads Stack Auth endpoints from `STACK_API_URL` and `STACK_DASHBOARD_URL`. If unset, it uses Stack Auth Cloud.
+
+## Authentication
+
+Log in with a browser:
+
+```sh title="Terminal"
+stack login
+```
+
+This stores `STACK_CLI_REFRESH_TOKEN` in the CLI credentials file. You can also provide it through the environment, which is useful in CI.
+
+```sh title="Terminal"
+STACK_CLI_REFRESH_TOKEN=<refresh-token> stack project list
+```
+
+Log out by removing the saved refresh token:
+
+```sh title="Terminal"
+stack logout
+```
+
+If you have an anonymous CLI session that should be linked during login, set `STACK_CLI_ANON_REFRESH_TOKEN` before running `login`.
+
+## Initialize a project
+
+Run the interactive setup wizard:
+
+```sh title="Terminal"
+stack init
+```
+
+The wizard can create a cloud project, create a local config file for the emulator, or link an existing project. In interactive terminals, it can run an agent to apply the setup changes to your app. Use `--no-agent` to print manual setup instructions instead.
+
+### Non-interactive init
+
+Use `--mode` to skip prompts:
+
+| Command | What it does |
+| --- | --- |
+| `stack init --mode create --apps authentication,teams` | Create `stack.config.ts` for local config-driven development. |
+| `stack init --mode create-cloud` | Create a new Stack Auth Cloud project and write keys to `.env`. |
+| `stack init --mode link-config --config-file ./stack.config.ts` | Link setup instructions to an existing local config file. |
+| `stack init --mode link-cloud --select-project-id <id>` | Write keys for an existing cloud project to `.env`. |
+
+Other useful flags:
+
+| Option | Description |
+| --- | --- |
+| `--apps <apps>` | Comma-separated app IDs to enable in `create` mode. |
+| `--config-file <path>` | Existing config file for `link-config` mode. |
+| `--select-project-id <id>` | Existing cloud project for `link-cloud` mode. |
+| `--output-dir <dir>` | Directory where output files should be written. Defaults to the current directory. |
+| `--no-agent` | Skip the setup agent and print manual instructions. |
+
+## Project commands
+
+List projects owned by the logged-in user:
+
+```sh title="Terminal"
+stack project list
+```
+
+Create a project:
+
+```sh title="Terminal"
+stack project create --display-name "My App"
+```
+
+Use `--json` when you want machine-readable output:
+
+```sh title="Terminal"
+stack --json project list
+```
+
+## Config commands
+
+Pull branch config into a local TypeScript config file:
+
+```sh title="Terminal"
+stack --project-id <project-id> config pull --config-file ./stack.config.ts
+```
+
+By default, `config pull` refuses to overwrite an existing file. Add `--overwrite` when that is intended.
+
+Push a local config file to branch config:
+
+```sh title="Terminal"
+stack --project-id <project-id> config push --config-file ./stack.config.ts
+```
+
+`config pull` requires `stack login`. `config push` supports either `stack login` or `STACK_SECRET_SERVER_KEY`.
+
+When running in GitHub Actions, `config push` records `GITHUB_REPOSITORY`, `GITHUB_REF_NAME`, `GITHUB_SHA`, and the config file path as the config source when those environment variables are available.
+
+## Execute admin JavaScript
+
+`stack exec` runs JavaScript with a preconfigured `StackServerApp` available as `stackServerApp`.
+
+```sh title="Terminal"
+stack --project-id <project-id> exec "return await stackServerApp.listUsers()"
+```
+
+The JavaScript is executed as an async function. Return values are printed as formatted JSON; `undefined` prints nothing.
+
+<Warning>
+  `stack exec` has server-level access to the selected project. It requires `stack login` and intentionally rejects `STACK_SECRET_SERVER_KEY` auth.
+</Warning>
+
+## Local emulator commands
+
+The CLI also manages the QEMU local emulator:
+
+```sh title="Terminal"
+stack emulator start
+stack emulator status
+stack emulator stop
+```
+
+See the [local emulator guide](/guides/going-further/local-emulator) for setup, ports, environment variables, and troubleshooting.