chore: reorganize docs image assets

README.md

@@ -19,6 +19,73 @@ mintlify dev
 Use the [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image) extension to paste images into the markdown file.
 Open mdx file and press `cmd + option + v` to paste image.
 
+### Image Assets
+
+Images are shared repo assets. Keep paths stable, names searchable, and
+rendering consistent.
+
+When a change includes images, ask the agent to read this section first and
+commit only images processed according to these rules.
+
+#### Folder Rules
+
+- Use `images/{top-level-group}/{topic}/`.
+- Top-level groups: `docs`, `selfhosted`, `api`, `security`, `changelog`.
+- `docs` maps to the Help Center Docs tab. Do not flatten
+  `images/docs/{topic}/` into `images/{topic}/`.
+- `{topic}` maps to the navigation name in `docs.json`, such as `ai`, `base`,
+  `space`, `sso`, `authority-matrix`, `get-id`, `sql-query`, or `activate`.
+- Do not put new screenshots in the `images/` root.
+- Do not commit random staging folders.
+- Put unreferenced images in `images/orphans/YYYY-MM-DD/...` first. Do not
+  delete them directly.
+- Docs pages must not reference `images/orphans/...`.
+
+#### Naming
+
+Use this format:
+
+```text
+images/{top-level-group}/{topic}/YYYY-MM-DD-page-slug-purpose.png
+images/{top-level-group}/{topic}/YYYY-MM-DD-page-slug-purpose.webp
+images/{top-level-group}/{topic}/YYYY-MM-DD-page-slug-purpose-zh.png
+```
+
+- Date = day the image enters the docs repo.
+- Page slug = docs page or feature area.
+- Purpose = visible UI or action. Do not use `image1` or random hashes.
+- Use `.png` for static UI screenshots.
+- Prefer `.webp` for animated screenshots.
+- English-only screenshot = shared asset. Do not add `-en`.
+- Chinese-specific screenshot = add `-zh`.
+
+#### Image Handling
+
+- Logos, inline icons, external button images, videos, and historical changelog
+  media do not need screenshot styling.
+
+#### MDX Usage
+
+Use explicit `<img>` for docs screenshots:
+
+```mdx
+<img
+  src="/images/docs/ai/YYYY-MM-DD-page-slug-purpose.png"
+  alt="AI Chat context selector"
+  className="docs-screenshot"
+/>
+```
+
+- Use `className="docs-screenshot"` for new PNG/WebP docs screenshots under
+  `images/docs/`, `images/api/`, `images/selfhosted/`, and `images/security/`.
+- Alt text must be non-empty.
+- Alt text describes the visible UI or action. Do not use `screenshot` or the
+  file name.
+- Do not use `![](...)` for new docs screenshots.
+- Avoid `width="400"`, percentage widths, and one-off image sizing.
+- Changelog images keep their historical display. Add useful alt text when
+  context exists. Do not add `docs-screenshot` blindly.
+
 ### Publishing Changes
 
 Push to origin main branch, the changes will be deployed to production automatically.

en/api-doc/get-id.mdx

@@ -6,47 +6,83 @@ title: "Getting IDs"
 
 Click on the target space and copy the string starting with 'spc' from the URL, example: `spcXXXXXXXXXX`
 
-![](/images/2026-02-12-10-43-08.png)
+<img
+  src="/images/api/get-id/2026-05-29-get-id-space-id.png"
+  alt="Space ID in the URL"
+  className="docs-screenshot"
+/>
 
 ## BaseId
 
 Click on the target base and copy the string starting with 'bse' from the URL, example: `bseXXXXXXXXXX`
 
-![](/images/2026-02-12-10-46-49.png)
+<img
+  src="/images/api/get-id/2026-05-29-get-id-base-id.png"
+  alt="Base ID in the URL"
+  className="docs-screenshot"
+/>
 
 ## TableId
 
 Click on the target table and copy the string starting with 'tbl' from the URL, example: `tblXXXXXXXXXX`
 
-![](/images/2026-02-12-10-48-18.png)
+<img
+  src="/images/api/get-id/2026-05-29-get-id-table-id.png"
+  alt="Table ID in the URL"
+  className="docs-screenshot"
+/>
 
 ## ViewId
 
 Click on the target view and copy the string starting with 'viw' from the URL, example: `viwXXXXXXXXXX`
 
-![](/images/2026-02-12-10-48-11.png)
+<img
+  src="/images/api/get-id/2026-05-29-get-id-view-id.png"
+  alt="View ID in the URL"
+  className="docs-screenshot"
+/>
 
 ## FieldId
 
 **Method 1:**
 
 Click the "More" icon (three dots) in the top left corner, then select "Design" to enter the design interface and view all field IDs
 
-<img src="/images/2026-02-12-10-50-30.png" width="400" />
+<img
+  src="/images/api/get-id/2026-05-29-get-id-field-id-design-entry-en.png"
+  alt="Open the design page from the More menu"
+  className="docs-screenshot"
+/>
 
-![](/images/2025-02-14-18-16-26.png)
+<img
+  src="/images/api/get-id/2026-05-29-get-id-field-id-design-list.png"
+  alt="Field IDs in the design page"
+  className="docs-screenshot"
+/>
 
 **Method 2:**
 
 Double-click the column header or select "Edit field" to open the field properties. In the "DB field name" section, you can find the Field ID.
 
-<img src="/images/2026-02-12-10-59-21.png" width="400" />
+<img
+  src="/images/api/get-id/2026-05-29-get-id-field-id-edit-field-entry-en.png"
+  alt="Open field settings from the column menu"
+  className="docs-screenshot"
+/>
 
-<img src="/images/2026-02-12-11-00-16.png" width="400" />
+<img
+  src="/images/api/get-id/2026-05-29-get-id-field-id-db-field-name-en.png"
+  alt="DB field name with the field ID"
+  className="docs-screenshot"
+/>
 
 
 ## RecordId
 
 Expand the record edit form and copy the string starting with 'rec' after 'recordId=' in the URL, example: `recXXXXXXXXXX`
 
-![](/images/2026-02-12-10-55-17.png)
+<img
+  src="/images/api/get-id/2026-05-29-get-id-record-id.png"
+  alt="Record ID in the expanded record URL"
+  className="docs-screenshot"
+/>

en/api-doc/sql-query.mdx

@@ -14,18 +14,30 @@ Teable allows you to connect to its underlying PostgreSQL database through exter
 1. **Open a Table**: First, open any table within the base you want to connect to.
 2. **Enter Design Page**: Click the ⚙️ icon in the top right corner to enter the Base Design page.
 
-![](/images/2025-12-05-01-16-08.png)
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-open-design-page-en.png"
+  alt="Open the Base Design page"
+  className="docs-screenshot"
+/>
 
 3. **Find Database Connection Panel**: In the Design page, locate the "Database Connection" panel.
 4. **Create Connection**: Click create, and the system will automatically generate a read-only PostgreSQL connection with username, password, and host address.
 
-![](/images/2025-12-05-01-17-53.png)
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-database-connection-panel-en.png"
+  alt="Database Connection panel"
+  className="docs-screenshot"
+/>
 
 ### Connecting to the Database
 
 Use the credentials to connect through your preferred tool. Here's an example:
 
-<img alt="Connection example" src="/images/kai-fa-zhe/ceef01dd644628f4.png" />
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-connection-example.png"
+  alt="External database connection example"
+  className="docs-screenshot"
+/>
 
 ### Querying Data
 
@@ -50,25 +62,41 @@ Each Base in Teable corresponds to a **schema** in PostgreSQL. The BaseId is the
 
 **Method 1:** Look at the URL - the string starting with `bse` is the BaseId.
 
-<img alt="baseId" src="/images/kai-fa-zhe/e8ef17c59ac0c067.png" />
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-base-id-url.png"
+  alt="Base ID in the URL"
+  className="docs-screenshot"
+/>
 
 **Method 2:** In the Base Design interface, the schema name shown is the BaseId.
 
-<img alt="Design page" src="/images/kai-fa-zhe/64fbddbd0f5519c4.png" />
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-design-page-schema.png"
+  alt="Schema name in the Base Design page"
+  className="docs-screenshot"
+/>
 
 ### Finding Table Names
 
 Table names in Teable interface don't automatically sync with physical database table names. Check the Base Design Interface for the actual database table name.
 
-<img alt="table info" src="/images/kai-fa-zhe/ba2fdb846b2062ce.png" />
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-table-info.png"
+  alt="Physical table name in the design page"
+  className="docs-screenshot"
+/>
 
 **Tip:** You can modify the physical table name in the design interface if needed.
 
 ### Finding Field Names
 
 Field (column) names in the database may differ from the Teable interface. Check the `dbFieldName` in the design interface.
 
-<img alt="db field name" src="/images/kai-fa-zhe/7609033391e8e7c1.png" />
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-db-field-name.png"
+  alt="DB field name in the design page"
+  className="docs-screenshot"
+/>
 
 **Tip:** Changing field names in Teable won't sync automatically. Modify `dbFieldName` explicitly to change the actual column name in PostgreSQL.
 
@@ -98,7 +126,11 @@ The database connection is scoped to the current base only. PostgreSQL schemas p
 
 You may see other baseIds (schema names) when connecting, but you cannot access their content.
 
-<img alt="base id in TablePlus" src="/images/kai-fa-zhe/093aebb4bc8cf732.png" />
+<img
+  src="/images/api/sql-query/2026-05-29-sql-query-tableplus-base-id.png"
+  alt="Base ID in TablePlus"
+  className="docs-screenshot"
+/>
 
 ### Connection Limits
 

en/basic/admin-panel/multitenancy.mdx

@@ -10,7 +10,11 @@ description: "Teable supports organizations, allowing multiple organizations to
 
 Instance administrators access the organization management panel via `Admin Panel` > `Organizations`
 
-![](/images/2025-10-14-22-14-29.png)
+<img
+  src="/images/selfhosted/admin-panel/2026-05-29-admin-panel-organizations-entry-en.png"
+  alt="Organizations entry in the Admin Panel"
+  className="docs-screenshot"
+/>
 
 <Tip>The first user registered in the instance becomes an instance administrator</Tip>
 
@@ -40,7 +44,11 @@ The organization management interface displays detailed information for all orga
 - **Administrator Settings**: Add or remove administrators for this organization. All users can be selected as administrators except deleted users
 - **Delete Organization**: The organization and its related settings will be deleted and this operation cannot be undone - proceed with caution
 
-![](/images/2025-10-14-22-15-14.png)
+<img
+  src="/images/selfhosted/admin-panel/2026-05-29-admin-panel-organizations-list-en.png"
+  alt="Organization list in the Admin Panel"
+  className="docs-screenshot"
+/>
 
 ## 2. Tiered Administrator System