docs: make Kest docs workspace-first

.github/workflows/deploy-docs.yml

@@ -0,0 +1,57 @@
+name: Deploy Docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/deploy-docs.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+jobs:
+  validate-docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Mintlify CLI
+        run: npm install -g mint
+
+      - name: Validate docs.json
+        run: node -e "JSON.parse(require('fs').readFileSync('docs.json','utf8')); console.log('docs.json valid')"
+
+      - name: Validate Mintlify docs
+        run: mint validate
+
+  trigger-mintlify-deploy:
+    runs-on: ubuntu-latest
+    needs: validate-docs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Trigger Mintlify deployment
+        env:
+          MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
+          MINTLIFY_PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
+        run: |
+          if [ -z "$MINTLIFY_API_KEY" ] || [ -z "$MINTLIFY_PROJECT_ID" ]; then
+            echo "Mintlify deploy skipped: MINTLIFY_API_KEY or MINTLIFY_PROJECT_ID is not configured."
+            exit 0
+          fi
+
+          curl --fail --request POST \
+            --url "https://api.mintlify.com/v1/project/update/${MINTLIFY_PROJECT_ID}" \
+            --header "Authorization: Bearer ${MINTLIFY_API_KEY}"

docs-site/docs.json

@@ -51,17 +51,27 @@
                   "en/documentation/quickstart",
                   "en/documentation/kest-web-cloud",
                   "en/documentation/kest-cli",
+                  "en/documentation/kest-ci",
                   "en/documentation/authentication",
                   "en/documentation/errors",
                   "en/documentation/rate-limits",
-                  "en/documentation/cli-sync"
+                  "en/documentation/cli-sync",
+                  "en/documentation/troubleshooting"
+                ]
+              },
+              {
+                "group": "Reference",
+                "pages": [
+                  "en/documentation/flow-authoring",
+                  "en/documentation/assertions-variables",
+                  "en/documentation/local-bridge"
                 ]
               },
               {
                 "group": "Workflows",
                 "pages": [
                   "en/workflows/api-spec-lifecycle",
-                  "en/workflows/project-collaboration",
+                  "en/workflows/workspace-collaboration",
                   "en/workflows/testing-requests"
                 ]
               }
@@ -104,17 +114,27 @@
                   "zh/documentation/quickstart",
                   "zh/documentation/kest-web-cloud",
                   "zh/documentation/kest-cli",
+                  "zh/documentation/kest-ci",
                   "zh/documentation/authentication",
                   "zh/documentation/errors",
                   "zh/documentation/rate-limits",
-                  "zh/documentation/cli-sync"
+                  "zh/documentation/cli-sync",
+                  "zh/documentation/troubleshooting"
+                ]
+              },
+              {
+                "group": "参考",
+                "pages": [
+                  "zh/documentation/flow-authoring",
+                  "zh/documentation/assertions-variables",
+                  "zh/documentation/local-bridge"
                 ]
               },
               {
                 "group": "工作流",
                 "pages": [
                   "zh/workflows/api-spec-lifecycle",
-                  "zh/workflows/project-collaboration",
+                  "zh/workflows/workspace-collaboration",
                   "zh/workflows/testing-requests"
                 ]
               }

docs-site/en/documentation/assertions-variables.mdx

@@ -0,0 +1,142 @@
+---
+title: Assertions and Variables
+description: Capture values, interpolate variables, use built-in dynamic values, and assert API behavior in Kest flows.
+---
+
+# Assertions and Variables
+
+Kest flows use variables to pass values between steps and assertions to verify API behavior.
+
+## Variable Interpolation
+
+Use `{{name}}` anywhere in URLs, headers, bodies, captures, and assertions:
+
+```md
+GET {{base_url}}/v1/users/{{user_id}}
+Authorization: Bearer {{token}}
+```
+
+Provide a default value:
+
+```md
+{{email | default: "demo@example.com"}}
+```
+
+Pass values from the CLI:
+
+```bash
+kest run auth.flow.md --var email=demo@example.com --var password=secret
+```
+
+## Built-in Values
+
+Common built-ins:
+
+- `{{$uuid}}`
+- `{{$timestamp}}`
+- `{{$unixMs}}`
+- `{{$isoDate}}`
+- `{{$randomEmail}}`
+- `{{$randomString}}`
+- `{{$randomInt}}`
+- `{{$env.NAME}}`
+
+Example:
+
+```json
+{
+  "email": "{{$randomEmail}}",
+  "request_id": "{{$uuid}}",
+  "sent_at": "{{$isoDate}}"
+}
+```
+
+## Captures
+
+Capture values from a response:
+
+```md
+[Captures]
+token = body.access_token
+user_id = body.data.id
+first_item = body.items.0.id
+```
+
+Captured values are available to later steps in the same run:
+
+```md
+GET {{base_url}}/v1/users/{{user_id}}
+Authorization: Bearer {{token}}
+```
+
+## Assertions
+
+Use `[Asserts]` for hard failures:
+
+```md
+[Asserts]
+status == 200
+duration < 1000
+body.id exists
+body.email contains "@"
+```
+
+Use `[Soft Asserts]` when a failed check should be reported without failing the whole run:
+
+```md
+[Soft Asserts]
+body.warning not exists
+```
+
+## Operators
+
+Supported assertion operators include:
+
+- `==`
+- `!=`
+- `>`
+- `>=`
+- `<`
+- `<=`
+- `exists`
+- `not exists`
+- `contains`
+- `startsWith`
+- `endsWith`
+- `matches`
+- `length`
+
+Examples:
+
+```md
+[Asserts]
+status == 201
+body.items length > 0
+body.email matches ".*@example.com"
+body.name startsWith "Demo"
+```
+
+## Strict Mode
+
+Strict mode fails early when a required variable is missing:
+
+```bash
+kest run auth.flow.md --strict
+```
+
+Debug variable resolution:
+
+```bash
+kest run auth.flow.md --debug-vars
+```
+
+## Variable Precedence
+
+Use the most specific source for test data:
+
+- Values passed with `--var` for one run.
+- Captures produced earlier in the run.
+- Environment and config variables.
+- Defaults in `{{name | default: "value"}}`.
+
+For CI, prefer explicit environment configuration plus `--strict` so missing values fail clearly.

docs-site/en/documentation/authentication.mdx

@@ -1,6 +1,6 @@
 ---
 title: Authentication
-description: JWT authentication and project-scoped CLI token authentication.
+description: JWT authentication and workspace-scoped CLI token authentication.
 ---
 
 # Authentication
@@ -9,27 +9,27 @@ Kest currently exposes two authentication modes.
 
 ## Bearer JWT
 
-Most user, project, and collaboration endpoints require a bearer JWT in the `Authorization` header.
+Most user, workspace, and collaboration endpoints require a bearer JWT in the `Authorization` header.
 
 ```http
 Authorization: Bearer <jwt-token>
 ```
 
 You receive this token from `POST /login`.
 
-## Project-scoped CLI token
+## Workspace-scoped CLI token
 
-CLI sync endpoints accept a project token instead of a user JWT.
+Kest Cloud Sync endpoints accept a workspace CLI token instead of a user JWT.
 
 ```http
 Authorization: Bearer <kest_pat_...>
 ```
 
-These tokens are created with `POST /projects/{id}/cli-tokens` and are scoped per project.
+These tokens are created with `POST /workspaces/{id}/cli-tokens` and are scoped to one workspace.
 
 ## Practical rules
 
 - Use JWTs for browser or user-driven platform actions.
-- Use CLI tokens for machine-to-platform sync flows.
+- Use CLI tokens for machine-to-Cloud sync flows.
 - Do not mix a CLI token with user endpoints such as `/users/profile`.
-- Treat project IDs in the URL and request body as a contract: Kest rejects mismatches for CLI sync requests.
+- Treat workspace IDs in the URL and request body as a contract: Kest rejects mismatches for sync requests.

docs-site/en/documentation/errors.mdx

@@ -34,7 +34,7 @@ Most Kest responses use a consistent JSON envelope.
 - `204` for successful deletes without a body
 - `400` for invalid parameters or malformed bodies
 - `401` for missing or invalid authentication
-- `403` for project or workspace permission failures
+- `403` for workspace permission failures
 - `404` for missing resources
 - `409` for resource conflicts such as duplicate slugs
 - `503` for temporarily unavailable subsystems such as an unconfigured CLI syncer