docs: rewrite the manual around reader tasks

docs/README.md

@@ -11,6 +11,21 @@ page automatically falls back to the English version with a notice banner.
 - `src/content/docs/zh-cn/` — Chinese translations (same filenames)
 - `astro.config.mjs` — site title, locales, and sidebar structure
 
+## Writing conventions
+
+- Each page is one of three kinds: a task guide (how to do something), a
+  concept page (why it works that way), or a reference (a complete list or
+  contract). Keep each section to one kind.
+- Property IDs, JSON, and error codes belong only in the Setting IDs and MCP
+  pages. A guide links there in at most one line.
+- Write a new feature into the page and section that own its task, not at the
+  end of the page edited most recently.
+- State each fact in one place and link to it from elsewhere.
+- A task page that an AI client can also perform ends with a "With an AI
+  client" section in the format used by the existing pages.
+- When adding or moving a page, update its Simplified Chinese counterpart and
+  the sidebar in `astro.config.mjs` in the same change.
+
 ## Commands
 
 Run from this directory:

docs/astro.config.mjs

@@ -29,14 +29,30 @@ export default defineConfig({
 					],
 				},
 				{
-					label: 'Working with Data',
+					label: 'AI Assistant',
+					translations: { 'zh-CN': 'AI 助手' },
+					items: [
+						{ slug: 'ai/connect' },
+						{ slug: 'ai/working-with-ai' },
+						{ slug: 'ai/control-and-review' },
+					],
+				},
+				{
+					label: 'Data',
 					translations: { 'zh-CN': '准备数据' },
 					items: [
 						{ slug: 'guides/importing-data' },
-						{ slug: 'guides/organizing-data' },
+						{ slug: 'guides/supported-formats' },
 						{ slug: 'guides/tables' },
+						{ slug: 'guides/organizing-data' },
+					],
+				},
+				{
+					label: 'Processing',
+					translations: { 'zh-CN': '处理' },
+					items: [
 						{ slug: 'guides/processing' },
-						{ slug: 'guides/craft' },
+						{ slug: 'guides/templates' },
 					],
 				},
 				{
@@ -49,55 +65,92 @@ export default defineConfig({
 						{ slug: 'guides/custom-models' },
 						{ slug: 'guides/statistics' },
 						{ slug: 'guides/spectrum-tools' },
+					],
+				},
+				{
+					label: 'By data type',
+					translations: { 'zh-CN': '按数据类型' },
+					items: [
 						{
-							label: 'By technique',
-							translations: { 'zh-CN': '按数据类型' },
+							label: 'NMR',
 							items: [
+								{ slug: 'guides/craft' },
 								{ slug: 'guides/pseudo-2d' },
 								{ slug: 'guides/dosy' },
 								{ slug: 'guides/2d-integration' },
 								{ slug: 'guides/symmetry-review' },
-								{ slug: 'guides/electrophysiology' },
-								{ slug: 'guides/xps' },
 							],
 						},
+						{ slug: 'guides/mass-spectrometry' },
+						{ slug: 'guides/xps' },
+						{ slug: 'guides/electrophysiology' },
 					],
 				},
 				{
-					label: 'Figures and Export',
-					translations: { 'zh-CN': '图形与导出' },
+					label: 'Figures',
+					translations: { 'zh-CN': '图形' },
 					items: [
-						{ slug: 'guides/layout-and-export' },
+						{ slug: 'guides/plots-and-charts' },
+						{ slug: 'guides/axes' },
+						{ slug: 'guides/legends-and-lines' },
+						{ slug: 'guides/themes-and-styles' },
+						{ slug: 'guides/multi-panel-figures' },
+						{ slug: 'guides/images' },
+						{ slug: 'guides/annotations' },
 						{ slug: 'guides/contour-levels' },
 						{ slug: 'guides/heatmap-range' },
-						{ slug: 'guides/annotations' },
 						{ slug: 'guides/exporting' },
 						{ slug: 'guides/present-mode' },
 					],
 				},
 				{
-					label: 'Batch and Automation',
-					translations: { 'zh-CN': '批量与自动化' },
+					label: 'Batch and Scripting',
+					translations: { 'zh-CN': '批量与脚本' },
 					items: [
 						{ slug: 'guides/automation' },
-						{ slug: 'guides/templates' },
 						{ slug: 'reference/cli' },
 					],
 				},
 				{
 					label: 'Reference',
 					translations: { 'zh-CN': '参考' },
 					items: [
-						{ slug: 'reference/shortcuts' },
-						{ slug: 'reference/command-palette' },
 						{ slug: 'reference/ui-overview' },
 						{ slug: 'reference/ribbon' },
+						{ slug: 'reference/command-palette' },
+						{ slug: 'reference/shortcuts' },
 						{ slug: 'reference/preferences' },
-						{ slug: 'reference/mcp' },
 						{ slug: 'reference/file-formats' },
-						{ slug: 'reference/updates' },
+					],
+				},
+				{
+					label: 'Setting IDs and MCP',
+					translations: { 'zh-CN': '设置 ID 与 MCP' },
+					items: [
+						{ slug: 'reference/settings-ids' },
+						{
+							label: 'MCP',
+							items: [
+								{ slug: 'reference/mcp' },
+								{ slug: 'reference/mcp/discovery' },
+								{ slug: 'reference/mcp/tables' },
+								{ slug: 'reference/mcp/plots' },
+								{ slug: 'reference/mcp/styling' },
+								{ slug: 'reference/mcp/layout' },
+								{ slug: 'reference/mcp/review' },
+								{ slug: 'reference/mcp/save-and-export' },
+								{ slug: 'reference/mcp/scientific' },
+							],
+						},
+					],
+				},
+				{
+					label: 'Help',
+					translations: { 'zh-CN': '帮助' },
+					items: [
 						{ slug: 'reference/troubleshooting' },
 						{ slug: 'reference/reporting-problems' },
+						{ slug: 'reference/updates' },
 					],
 				},
 			],

docs/src/content/docs/ai/connect.md

@@ -0,0 +1,70 @@
+---
+title: Connect an AI client
+description: Connect Codex, Claude Code or Claude Desktop to Plotium so it can work with your open project.
+---
+
+An AI client connected to Plotium can look at your open project, build and
+adjust figures, and run supported analyses while you keep working in the
+desktop app. You talk to it in the client (Codex, Claude Code or Claude
+Desktop); Plotium has no built-in chat window. The connection runs on your own
+computer and uses the Model Context Protocol (MCP).
+
+## Before you start
+
+- Install the AI client you want to use.
+- Keep the Plotium installation complete. The macOS app already contains the
+  connector; for a ZIP installation keep `plotium-mcp` (`plotium-mcp.exe` on
+  Windows) beside the main program.
+
+## Connect
+
+1. Open Plotium.
+2. Open **Preferences → AI connections (MCP)**. You can also click the robot
+   icon beside Operation history in the Ribbon, or choose **File → AI
+   connections (MCP)…**.
+3. Turn on **Enable MCP**.
+4. Under **Access**, choose **Read only** to let the AI look without changing
+   anything, or **Read and modify** to allow supported edits. The default is
+   **Read and modify**; [Access, review and undo](/ai/control-and-review/)
+   explains both.
+5. Add your client:
+
+| Client | In Plotium | In the client |
+| --- | --- | --- |
+| Codex | Press **Add** in the Codex card | Reload MCP configuration or restart the client if needed |
+| Claude Code | Press **Add** in the Claude Code card | Reload MCP configuration or restart the client if needed |
+| Claude Desktop (macOS and Windows) | Press **Add to Claude Desktop…** | Confirm installation of the extension, then reload or restart if needed |
+
+Each client only needs to be added once. Plotium remembers **Enable MCP** and
+the access level across restarts.
+
+## Check the connection
+
+Start your AI client yourself; Plotium does not launch it. **Configured** on a
+card only means the settings were added. To check that the client can reach
+Plotium, send this first request:
+
+> Use Plotium to list the datasets and figures in my current project. Do not
+> change anything.
+
+The client should describe your project, and the robot icon in Plotium turns
+green while the client is active. Opening the Claude Desktop extension package
+alone does not confirm a working connection. If nothing happens, see
+[If the connection does not work](/ai/control-and-review/#if-the-connection-does-not-work).
+
+Next, see [Working with an AI client](/ai/working-with-ai/) for what to ask.
+
+## Other MCP clients
+
+For another MCP client on the same computer, expand **Manual configuration and
+diagnostics** and press **Copy stable stdio configuration**, then paste the
+copied configuration into your client. The connection works only for clients
+on the same computer and user account; remote connections and access between
+Windows and WSL are not supported.
+[MCP setup and permissions](/reference/mcp/) has the manual registration
+commands and the technical reference.
+
+## After updating Plotium
+
+Restart the Plotium connection in your AI client (or restart the client) so it
+loads the updated tools. You do not need to add the client again.

docs/src/content/docs/ai/control-and-review.md

@@ -0,0 +1,132 @@
+---
+title: Access, review and undo
+description: Control what an AI client can do, follow and undo its changes, and fix connection problems.
+---
+
+You stay in charge of what an AI client does in Plotium: you choose whether it
+may change anything, every change can be undone, and nothing is written to disk
+without your confirmation in Plotium.
+
+## Choose what the AI may do
+
+Set this in **Preferences → AI connections (MCP)**, or click the robot icon in
+the Ribbon.
+
+| Setting | Effect |
+| --- | --- |
+| **Access → Read only** | The AI can look at data, tables and figures, including images of the current figures, but cannot prepare, preview or apply changes. Switching to Read only also blocks changes it has prepared but not yet applied |
+| **Access → Read and modify** | The AI can also make supported changes. This is the default |
+| **Enable MCP** off | Stops all access immediately and discards changes the AI prepared but did not apply. Your client setup is kept |
+
+The access level applies to every connected client and every project you open,
+and Plotium remembers it across restarts. Closing Preferences or switching
+projects keeps the connection running; exiting Plotium stops it. After a
+restart you can continue in the same AI conversation without adding the client
+again. After you switch projects, ask the AI to look at the current project
+before it continues editing.
+
+Your AI client may also ask you to approve its tool calls. That approval is
+the client's own and separate from Plotium's access level: approving a call in
+the client never bypasses **Read only** or the save and export confirmations.
+
+## Review and undo changes
+
+- Every change appears in Plotium immediately and is one step in **Undo** and
+  **Redo**, however many items it touched. A save or export is not a change to
+  the project and cannot be undone.
+- Values you set by hand, such as a colour you chose in the Object inspector or
+  a legend you dragged, are kept when the AI restyles a figure or applies a
+  theme, unless you ask it to change them.
+- Looking, previewing and checking do not change the project and do not mark
+  it as unsaved.
+- **Operation history** (the clock-arrow button in the Ribbon) lists the results
+  of recent AI operations under **Results**, with links to view them.
+
+## Save and export confirmation
+
+When the AI asks to save or export, Plotium shows **Allow AI to save this
+project?** or **Allow AI to export this figure?** with the exact file paths.
+
+- Press **Allow save** or **Allow export** to go ahead, or **Deny** to write
+  nothing.
+- Replacing an existing file needs its own checkbox in the same prompt.
+- Each confirmation covers that one request. A changed path needs a new one.
+- This confirmation is needed even with **Read and modify** access, and the AI
+  can ask for it even in **Read only**.
+
+A save captures the project at the moment you allow it; later edits are still
+unsaved. Export does not change the project or mark it as saved.
+
+## Follow AI results
+
+By default, the workspace follows the AI: it shows the canvas affected by the
+latest completed operation. Results that touch several canvases are shown
+together, and a canvas already in view keeps its zoom. Requests that only look
+at the project, and empty canvases, do not move the workspace.
+
+The follow button beside the robot icon shows whether following is active,
+paused or off. Working yourself pauses following: opening or selecting other
+content, panning, zooming or editing. Hovering and reading operation details do
+not. In Operation history's **Results**, use **Pause**, **Resume**, **Stop
+following** or **View latest**.
+
+While following is paused:
+
+- A badge on the follow button counts new or updated results you have not
+  viewed. Repeated changes to the same object count once. Viewing a result marks
+  it as seen; **View latest** shows the latest result but leaves older ones in
+  the count, and does not turn following back on. Resuming clears the count.
+  Open **Results** to review them without resuming.
+- Updates to the object in view also show a brief notification you can close.
+- A reminder offers **Resume following**, **Dismiss** and **Don't remind
+  again**. It closes after about eight seconds. **Dismiss** hides it without
+  marking results as seen; further changes to the same object do not bring it
+  back, but a new result object can. **Don't remind again** turns reminders off across restarts;
+  turn them back on in **Preferences → General → Remind me about results while
+  following is paused**. Result counts and error notifications stay available.
+
+Pausing freezes the view at once, including an unfinished automatic zoom.
+Resuming, or viewing the latest result, shows the latest operation's results
+only. Changing projects or losing the connection
+stops following; resume it yourself when you are ready. Following never cancels
+a running task.
+
+A spinner on the robot icon means a scientific task is running. Hover over it
+for the operation, progress when known, and whether editing now could stop the
+result from being applied. It shows Plotium's own running work, not whether the
+AI has finished your request.
+
+## The robot icon
+
+Hover over the robot for the project, access level and last activity. Click it
+to open the connection settings; it stays available when the Ribbon is
+collapsed.
+
+| Appearance | Status | What it means |
+| --- | --- | --- |
+| Gray, short slash | Off | Turn on **Enable MCP** when you want to connect |
+| Blue, hollow dot | Starting / Ready | Wait for startup, or send a request from your client |
+| Green, filled dot | Active | A client was active in the last 30 seconds; this does not mean its task is finished |
+| Orange, exclamation | Needs attention | Open the connection settings, read the error and follow the suggested action |
+
+## If the connection does not work
+
+| What you see | What to try |
+| --- | --- |
+| Plotium cannot find Codex or Claude Code | Use **Installation help** to install the client, or **Choose executable…** to select it, then press **Add** |
+| An error mentions Node.js | Check the client's Node.js installation, or select a standalone client executable, then try again |
+| A different server named `plotium` already exists | Review the existing entry. Choose **Back up and replace this entry** only if you want to replace it; Plotium backs it up and leaves other servers unchanged |
+| **Configured**, but no client activity | Reload the client's MCP configuration or restart it, then send the [first request](/ai/connect/#check-the-connection). Check whether the client has disabled or blocked the server |
+| The AI says the project has changed or its information is out of date | Ask it to look at the current project again before continuing |
+| Another Plotium instance owns the connection | Use the instance providing the connection, or exit it so this one can connect. Switching window focus does not switch the AI's target |
+| Windows reports that the connector is in use during an update | Exit AI clients using Plotium, then press **Retry** in the connection settings |
+| The connector or Claude Desktop extension is missing | Extract the complete Plotium release again and keep its files together |
+
+Startup failures retry automatically. The connection settings show recent
+operations and errors; press **Retry** when offered after fixing the cause.
+
+If the connection breaks while the AI is changing something, look at the
+project before asking it to try again: the change may already have been made,
+and repeating it could create duplicate content. The same applies to saves and
+exports: ask the AI to check what happened to the request rather than sending
+it again.