[codex] update billing guide and simplify docs navigation

.gitignore

@@ -1,2 +1,8 @@
 **/.DS_Store
 .idea
+
+# Local agent handoff and screenshot scratch output.
+/HANDOFF.md
+/images/_scratch/
+/images/_tmp/
+/images/_preview/

AGENT.md

@@ -0,0 +1,66 @@
+# Agent Notes
+
+## Help Center Screenshot Processing
+
+Use the local Teable screenshot skill for docs screenshot work:
+
+```bash
+python3 /Users/leo/.agents/skills/teable-doc-screenshots/scripts/stage_image.py \
+  --input /tmp/clean.png \
+  --output images/staged-field-preview/2026-05-11-topic.png \
+  --padding-y 24 \
+  --auto-fit-width
+```
+
+Final screenshot PNGs in the docs repo should be baked assets, not raw captures.
+
+- Keep raw screenshots and experiment outputs in `/tmp` or an ignored scratch directory.
+- Commit only final PNGs that are referenced by Markdown or MDX.
+- Use one standard canvas for normal docs images: `1600px` wide.
+- Normal output uses `padding-x=48` and `padding-y=24`.
+- `--auto-fit-width` may reduce horizontal padding to `24px` and upscale modestly when all of these are true:
+  - source width is at least `1200px`
+  - aspect ratio is between `1.35` and `2.6`
+  - ordinary rendered width would be below `1472px`
+  - required scale is at most `1.3`
+  - final height is at most `1000px`
+- Very wide local UI strips should not be fit-width; leave them at normal size.
+- Do not use legacy `wide`, `panel`, `small`, or `tall` presets for normal docs images.
+- Dotted background, screenshot corner radius, and screenshot shadow are baked into the PNG.
+- Docs CSS owns only the outer image border and small radius.
+
+In MDX, prefer:
+
+```mdx
+<img
+  src="/images/staged-field-preview/2026-05-11-topic.png"
+  alt="Describe the UI state"
+  className="docs-screenshot"
+/>
+```
+
+Avoid random per-image widths such as `50%`, `65%`, or `100%`, and avoid
+`docs-screenshot-full`, `docs-screenshot-panel`, `docs-screenshot-sm`, and
+`docs-screenshot-tall`.
+
+Before committing screenshot batches, verify that every staged screenshot is
+referenced and no experiment image is included:
+
+```bash
+python3 - <<'PY'
+import re, subprocess
+from pathlib import Path
+
+refs = set()
+for root in ("en", "zh"):
+    for path in Path(root).rglob("*"):
+        if path.suffix.lower() in {".md", ".mdx"}:
+            refs.update(r.lstrip("/") for r in re.findall(r"/images/staged-[^\s)\"']+\.png", path.read_text(errors="ignore")))
+
+staged = subprocess.check_output(["git", "diff", "--cached", "--name-only"], text=True).splitlines()
+images = {path for path in staged if path.startswith("images/staged-") and path.endswith(".png")}
+
+print("extra staged images", sorted(images - refs))
+print("missing staged image refs", sorted(refs - images))
+PY
+```

docs.json

@@ -148,7 +148,7 @@
               {
                 "group": "Base",
                 "pages": [
-                  "en/basic/base/base",
+                  "en/basic/base",
                   {
                     "group": "Table",
                     "pages": [
@@ -161,13 +161,7 @@
                     "group": "Field",
                     "pages": [
                       "en/basic/field",
-                      {
-                        "group": "AI Field",
-                        "pages": [
-                          "en/basic/field/ai/ai-field",
-                          "en/basic/field/ai/ai-field-practical-guide"
-                        ]
-                      },
+                      "en/basic/field/ai/ai-field",
                       {
                         "group": "Basic Field",
                         "pages": [
@@ -233,6 +227,11 @@
                   {
                     "group": "View",
                     "pages": [
+                      "en/basic/view/grid",
+                      "en/basic/view/form",
+                      "en/basic/view/kanban",
+                      "en/basic/view/gallery",
+                      "en/basic/view/calendar",
                       {
                         "group": "Toolbar",
                         "pages": [
@@ -242,12 +241,7 @@
                           "en/basic/view/toolbar/share",
                           "en/basic/view/toolbar/collaboration-mode"
                         ]
-                      },
-                      "en/basic/view/grid",
-                      "en/basic/view/form",
-                      "en/basic/view/kanban",
-                      "en/basic/view/gallery",
-                      "en/basic/view/calendar"
+                      }
                     ]
                   }
                 ]
@@ -258,7 +252,7 @@
                   {
                     "group": "Authority Matrix",
                     "pages": [
-                      "en/basic/authority-matrix/authority-matrix",
+                      "en/basic/authority-matrix",
                       "en/basic/authority-matrix/authority-matrix-practical-guide"
                     ]
                   }
@@ -516,7 +510,7 @@
               {
                 "group": "数据库",
                 "pages": [
-                  "zh/basic/base/base",
+                  "zh/basic/base",
                   {
                     "group": "表格",
                     "pages": [
@@ -529,13 +523,7 @@
                     "group": "字段",
                     "pages": [
                       "zh/basic/field",
-                      {
-                        "group": "AI 字段",
-                        "pages": [
-                          "zh/basic/field/ai/ai-field",
-                          "zh/basic/field/ai/ai-field-practical-guide"
-                        ]
-                      },
+                      "zh/basic/field/ai/ai-field",
                       {
                         "group": "基础字段",
                         "pages": [
@@ -601,6 +589,11 @@
                   {
                     "group": "视图",
                     "pages": [
+                      "zh/basic/view/grid",
+                      "zh/basic/view/form",
+                      "zh/basic/view/kanban",
+                      "zh/basic/view/gallery",
+                      "zh/basic/view/calendar",
                       {
                         "group": "工具栏",
                         "pages": [
@@ -610,12 +603,7 @@
                           "zh/basic/view/toolbar/share",
                           "zh/basic/view/toolbar/collaboration-mode"
                         ]
-                      },
-                      "zh/basic/view/grid",
-                      "zh/basic/view/form",
-                      "zh/basic/view/kanban",
-                      "zh/basic/view/gallery",
-                      "zh/basic/view/calendar"
+                      }
                     ]
                   }
                 ]
@@ -626,7 +614,7 @@
                   {
                     "group": "权限矩阵",
                     "pages": [
-                      "zh/basic/authority-matrix/authority-matrix",
+                      "zh/basic/authority-matrix",
                       "zh/basic/authority-matrix/authority-matrix-practical-guide"
                     ]
                   }

en/basic/automation/actions/communication/send-email-overview.mdx

@@ -19,7 +19,7 @@ Describe the goal once, and the workflow is ready — no manual setup needed.
 
 This action sends an email to one or more recipients. You can customize every part of the email — recipients, subject, body, attachments — and use dynamic values from previous steps to personalize each message.
 
-By default, emails are sent from Teable's built-in mail service. If you need to send from your own domain, configure a [custom SMTP server](smtp-sender).
+By default, emails are sent from Teable's built-in mail service. If you need to send from your own domain, configure a [custom SMTP server](/en/basic/automation/actions/communication/smtp-sender).
 
 ## Configuration
 
@@ -110,6 +110,6 @@ Note that attachments increase email size. Large attachments may cause delivery
 
 ## Related
 
-- [Set up SMTP and sender](smtp-sender) — send emails from your own domain
+- [Set up SMTP and sender](/en/basic/automation/actions/communication/smtp-sender) — send emails from your own domain
 - [Loop (batch)](../logic/loop-run) — send emails in bulk by looping through a list of records
 - [AI generate](/en/basic/automation/actions/ai/ai-generate) — generate personalized email content with AI

en/basic/automation/actions/communication/send-email.mdx

@@ -11,7 +11,7 @@ Instead of configuring this action manually, you can describe what you need in t
 
 This action sends an email to one or more recipients. You can customize every part of the email — recipients, subject, body, attachments — and use dynamic values from previous steps to personalize each message.
 
-By default, emails are sent from Teable's built-in mail service. If you need to send from your own domain, configure a [custom SMTP server](smtp-sender).
+By default, emails are sent from Teable's built-in mail service. If you need to send from your own domain, configure a [custom SMTP server](/en/basic/automation/actions/communication/smtp-sender).
 
 ## Configuration
 
@@ -102,6 +102,6 @@ Note that attachments increase email size. Large attachments may cause delivery
 
 ## Related
 
-- [Set up SMTP and sender](smtp-sender) — send emails from your own domain
+- [Set up SMTP and sender](/en/basic/automation/actions/communication/smtp-sender) — send emails from your own domain
 - [Loop (batch)](../logic/loop-run) — send emails in bulk by looping through a list of records
 - [AI generate](/en/basic/automation/actions/ai/ai-generate) — generate personalized email content with AI

en/basic/automation/actions/communication/smtp-sender.mdx

@@ -77,5 +77,5 @@ In the **Send Email** action, click the transport configuration option to set up
 
 ## Related
 
-- [Send email action](send-email) — the action that uses SMTP configuration
+- [Send email action](/en/basic/automation/actions/communication/send-email-overview) — the action that uses SMTP configuration
 - [Set up Gmail IMAP](../../trigger/email/gmail-imap) — instructions for Gmail App Passwords

en/basic/automation/actions/logic/http-request.mdx

@@ -123,11 +123,11 @@ This is useful for chaining API calls — for example, create something via POST
 - Use `application/json` as the Content-Type for most modern APIs. If the API expects form data, switch to `x-www-form-urlencoded`.
 - If the API returns an error (4xx or 5xx status), the action still completes — but subsequent steps will see the error response. Check the status code in your workflow if you need conditional handling.
 - For APIs that return large responses, only reference the specific fields you need in subsequent steps.
-- Combine with [Loop (Batch)](loop-run) to make multiple API calls, one per record. Be mindful of the external API's rate limits.
-- Use the [HTTP Array Body](loop-run) feature when you need to send multiple items in a single request instead of one request per item.
+- Combine with [Loop (Batch)](/en/basic/automation/actions/logic/loop-run) to make multiple API calls, one per record. Be mindful of the external API's rate limits.
+- Use the [HTTP Array Body](/en/basic/automation/actions/logic/loop-run) feature when you need to send multiple items in a single request instead of one request per item.
 
 ## Related
 
-- [Loop (batch)](loop-run) — make HTTP requests for each item in an array
+- [Loop (batch)](/en/basic/automation/actions/logic/loop-run) — make HTTP requests for each item in an array
 - [When webhook received](/en/basic/automation/trigger/external/webhook-received) — the inbound counterpart: receive HTTP requests from external systems
 - [AI script guide](/en/basic/automation/ai/scripting/ai-script-guide) — for more complex API interactions with custom code

en/basic/automation/actions/logic/loop-run.mdx

@@ -99,5 +99,5 @@ To use Array Body:
 
 - [Get records](/en/basic/automation/actions/records/get-records) — the most common source of arrays for Loop
 - [Create record](/en/basic/automation/actions/records/create-record) — commonly used inside a Loop to bulk-create records
-- [HTTP request](http-request) — commonly used inside a Loop for per-item API calls
+- [HTTP request](/en/basic/automation/actions/logic/http-request) — commonly used inside a Loop for per-item API calls
 - [Send email](/en/basic/automation/actions/communication/send-email) — commonly used inside a Loop for bulk email sends

en/basic/automation/actions/records/create-record.mdx

@@ -29,7 +29,7 @@ Creates a new record in a specified table. You can map data from previous steps
 ## How to set it up
 
 1. Add a **Create Record** action to your workflow.
-2. Choose the **Table** where you want the record created. By default this is a table in the same base, but you can use [Cross-Base Access](cross-base) to target a table in another base.
+2. Choose the **Table** where you want the record created. By default this is a table in the same base, but you can use [Cross-Base Access](/en/basic/automation/actions/records/cross-base) to target a table in another base.
 3. The field mapping area shows all fields in the target table. For each field you want to fill:
    - **Static value:** Type a value directly into the field (e.g., type "New" for a Status field).
    - **Dynamic value:** Click the **+** button next to the field to insert a variable from a previous step. For example, insert the trigger's "Name" field to copy the name from the triggering record.
@@ -69,11 +69,11 @@ This is useful when you need to chain actions. For example: create a record, the
 - You can create records in bulk by combining this action with [Loop (Batch)](../logic/loop-run). For example, get 50 records from one table and create 50 corresponding records in another.
 - Fields you do not map will use the table's default values (if any) or remain empty.
 - Linked record fields expect Record IDs, not display values. If you need to link to a record, make sure you are passing the Record ID, not the record's name.
-- Use [Cross-Base Access](cross-base) when the target table is in a different base than the automation.
+- Use [Cross-Base Access](/en/basic/automation/actions/records/cross-base) when the target table is in a different base than the automation.
 
 ## Related
 
-- [Update record](update-record) — modify existing records instead of creating new ones
-- [Get records](get-records) — retrieve records to use as input for creating new ones
-- [Cross-base access](cross-base) — create records in tables outside the current base
+- [Update record](/en/basic/automation/actions/records/update-record) — modify existing records instead of creating new ones
+- [Get records](/en/basic/automation/actions/records/get-records) — retrieve records to use as input for creating new ones
+- [Cross-base access](/en/basic/automation/actions/records/cross-base) — create records in tables outside the current base
 - [Loop (batch)](../logic/loop-run) — create multiple records in a single action step

en/basic/automation/actions/records/cross-base.mdx

@@ -75,6 +75,6 @@ To fix this:
 
 ## Related
 
-- [Create record](create-record) — create records in the current or another base
-- [Update record](update-record) — update records in the current or another base
-- [Get records](get-records) — retrieve records from the current or another base
+- [Create record](/en/basic/automation/actions/records/create-record) — create records in the current or another base
+- [Update record](/en/basic/automation/actions/records/update-record) — update records in the current or another base
+- [Get records](/en/basic/automation/actions/records/get-records) — retrieve records from the current or another base

en/basic/automation/actions/records/get-records.mdx

@@ -32,7 +32,7 @@ Retrieves records from a table and returns them as an array. Use the results in
 ## How to set it up
 
 1. Add a **Get Records** action to your workflow.
-2. Choose the **Table** you want to query. Use [Cross-Base Access](cross-base) if the table is in a different base.
+2. Choose the **Table** you want to query. Use [Cross-Base Access](/en/basic/automation/actions/records/cross-base) if the table is in a different base.
 3. (Optional) Select a **View** to inherit that view's filter, sort, and field visibility settings.
 4. (Optional) Add **Filter** conditions to narrow the results. For example, `Status` equals `Active` and `Due Date` is before today.
 5. (Optional) Set **Skip** and **Take** for pagination. For example, Skip 0 and Take 100 to get the first 100 records.
@@ -83,7 +83,7 @@ To process an entire large table, you could use multiple Get Records steps with
 
 ## Related
 
-- [Cross-base access](cross-base) — query tables in other bases
+- [Cross-base access](/en/basic/automation/actions/records/cross-base) — query tables in other bases
 - [Loop (batch)](../logic/loop-run) — iterate over the results array
-- [Create record](create-record) — create records based on retrieved data
-- [Update record](update-record) — update records found by Get Records
+- [Create record](/en/basic/automation/actions/records/create-record) — create records based on retrieved data
+- [Update record](/en/basic/automation/actions/records/update-record) — update records found by Get Records

en/basic/automation/actions/records/update-record.mdx

@@ -92,11 +92,11 @@ If your automation is triggered by **When record updated** and your Update Recor
 - Updating a record may trigger other automations watching the same table. Be aware of cascading effects.
 - When updating multiple records with comma-separated IDs, all records receive the same field values. For different values per record, use a [Loop](../logic/loop-run) step instead.
 - If you need to clear a field, map it to an empty value. Simply leaving it unmapped will *not* clear it.
-- Use [Cross-Base Access](cross-base) to update records in a table that lives in a different base.
+- Use [Cross-Base Access](/en/basic/automation/actions/records/cross-base) to update records in a table that lives in a different base.
 
 ## Related
 
-- [Create record](create-record) — add new records instead of modifying existing ones
-- [Get records](get-records) — retrieve records to find their IDs before updating
-- [Cross-base access](cross-base) — update records in tables outside the current base
+- [Create record](/en/basic/automation/actions/records/create-record) — add new records instead of modifying existing ones
+- [Get records](/en/basic/automation/actions/records/get-records) — retrieve records to find their IDs before updating
+- [Cross-base access](/en/basic/automation/actions/records/cross-base) — update records in tables outside the current base
 - [Loop (batch)](../logic/loop-run) — update multiple records with different values

en/basic/automation/ai-action.mdx

@@ -55,4 +55,4 @@ Choose from specialized model types to match your task requirements:
 
 
 
-<Tip> In addition to Teable's native models, the platform supports [integration with third-party model APIs](/en/basic/space/custom-api), configurable via Space → Settings. </Tip>
+<Tip> In addition to Teable's native models, the platform supports [integration with third-party model APIs](/en/basic/ai/custom-model), configurable via Space → Settings. </Tip>

en/basic/automation/ai/scripting/ai-script-guide.mdx

@@ -273,6 +273,6 @@ output.set("isVIP", vipDomains.includes(domain));
 
 ## Related
 
-- [Sample scripts](sample-scripts) — ready-to-use examples for common tasks
+- [Sample scripts](/en/basic/automation/ai/scripting/sample-scripts) — ready-to-use examples for common tasks
 - [AI generate](/en/basic/automation/actions/ai/ai-generate) — for prompt-based AI tasks that do not need custom code
 - [HTTP request](/en/basic/automation/actions/logic/http-request) — for simple API calls that do not need scripting

en/basic/automation/ai/scripting/sample-scripts.mdx

@@ -339,6 +339,6 @@ output.set("recordCount", records.length);
 
 ## Related
 
-- [AI script guide](ai-script-guide) — full reference for the scripting environment
+- [AI script guide](/en/basic/automation/ai/scripting/ai-script-guide) — full reference for the scripting environment
 - [HTTP request](/en/basic/automation/actions/logic/http-request) — for simple API calls without scripting
 - [Loop (batch)](/en/basic/automation/actions/logic/loop-run) — for iterating without code