@taylorwong/ichartjs 2.0.19 → 2.0.21

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2.0.21 - 2026-10-01
+
+- Completed Iteration 17 production trust and Agent reliability hardening with unknown-option diagnostics, effective Spec explanations, unsupported-renderer planning diagnostics, and stable normalization records.
+- Added `agentReliability` capability metadata, npm package-content checks, bilingual production-trust guidance, and release-gate coverage for the ESM, TypeScript, headless, SVG, and Canvas consumer paths.
+
+## 2.0.20 - 2026-09-30
+
+- Completed Iteration 16 preference precedence, Agent source resolution, conversational workflow guidance, capability discovery, and Gallery acceptance coverage.
+- Replaced Flow start/end polygon approximations with native ellipse geometry across Scene Graph, SVG, Canvas, export, scaling, and hit testing.
+- Synchronized runtime, package, Playground, Skill, documentation, and release-pinned installation references.
+
 ## 2.0.19 - 2026-09-29
 
 - Added Iteration 15 adaptive text fitting for Flow, Architecture, Mindmap, and Swimlane nodes, with inline-first edge labels, diagram-only contrast plates, unified diagnostics, and shared SVG/Canvas behavior.

package/README.md

@@ -36,6 +36,7 @@ getCapabilities
 | Frontend integration | [`docs/agent/frontend-integration.md`](docs/agent/frontend-integration.md) |
 | Visual style and themes | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md) |
 | Chart and page preferences | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md#chart-and-page-preferences) |
+| Natural-language chart changes | [`docs/agent/conversational-workflow.md`](docs/agent/conversational-workflow.md) |
 | Official Agent Skill for Codex and WorkBuddy | [`skills/ichartjs/SKILL.md`](skills/ichartjs/SKILL.md) |
 
 ### Install
@@ -44,7 +45,7 @@ getCapabilities
 npm install @taylorwong/ichartjs@^2
 ```
 
-As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.19`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.21`.
 
 ### Optional Agent Skill
 
@@ -66,7 +67,7 @@ For a non-interactive global Codex installation:
 npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
 ```
 
-For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.19/skills/ichartjs --agent codex --global --yes`. WorkBuddy users can import the same tagged `skills/ichartjs` URL through the host's Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it. Package consumers can still copy `node_modules/@taylorwong/ichartjs/skills/ichartjs` as a manual fallback. After installation, invoke `$ichartjs` when named Skill invocation is supported, or select `ichartjs` in the host UI.
+For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.21/skills/ichartjs --agent codex --global --yes`. WorkBuddy users can import the same tagged `skills/ichartjs` URL through the host's Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it. Package consumers can still copy `node_modules/@taylorwong/ichartjs/skills/ichartjs` as a manual fallback. After installation, invoke `$ichartjs` when named Skill invocation is supported, or select `ichartjs` in the host UI.
 
 ### Agent workflow
 

package/docs/agent/coding-agent-integration.md

@@ -33,7 +33,7 @@ Install the official Skill with the standard Agent Skills CLI:
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-For global non-interactive Codex setup, append `--agent codex --global --yes`. To pin the released workflow, install `https://github.com/wanghetommy/ichartjs/tree/v2.0.19/skills/ichartjs`. WorkBuddy can import that tagged directory through its Skill interface; only use a host-specific `--agent` value when the installed CLI declares it.
+For global non-interactive Codex setup, append `--agent codex --global --yes`. To pin the released workflow, install `https://github.com/wanghetommy/ichartjs/tree/v2.0.21/skills/ichartjs`. WorkBuddy can import that tagged directory through its Skill interface; only use a host-specific `--agent` value when the installed CLI declares it.
 
 Verify discovery with `npx skills add wanghetommy/ichartjs --list`; the result should include `ichartjs`.
 

package/docs/agent/conversational-workflow.md

@@ -0,0 +1,134 @@
+# Conversational Workflow
+
+iChart.js does not parse natural-language requests inside the runtime. The host Agent, such as Codex or WorkBuddy, maps the user's request to the public JavaScript contract. The runtime then validates, applies, renders, explains, and exports the result.
+
+## Safe Request Loop
+
+Use this loop for every conversational change:
+
+```text
+read current state
+  -> classify the request
+  -> build a structured change
+  -> validate or preview
+  -> confirm destructive changes
+  -> commit
+  -> explain and inspect state
+  -> return preview or export artifacts
+```
+
+Read `getCapabilities()`, `chart.getSpec()`, `chart.getState()`, and `chart.getPreferences()` before changing an existing chart. Preserve the user's original wording separately from the structured change. Do not pass natural-language prose directly as `planChart().intent`; map it to a registered intent token first.
+
+## Request Routing
+
+| User request | Runtime operation | Confirmation |
+| --- | --- | --- |
+| Change theme, palette, font size, legend, labels, or grid | `setTheme()` or `setPreferences()` | No, unless the host policy requires it |
+| Replace all rows | `setData()` | Usually no; host decides |
+| Change a task, milestone, node, edge, or project record | `previewEdit()` then `applyEdit()` | Yes for bulk, delete, or structural changes |
+| Change chart type, field mapping, axes, title, labels, or layout | `update()` | No, unless it changes the product contract |
+| Change one exact JSON path | `applyPatch()` | Prefer `update()` first |
+| Export a result | `export()`, `downloadSVG()`, or `downloadPNG()` | No |
+
+## Visual Change
+
+Use the allowlisted preference contract instead of inventing CSS or theme tokens:
+
+```js
+const capabilities = getPreferenceCapabilities(chart.getSpec().type, { locale: 'en' });
+const patch = {
+  theme: { mode: 'dark', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+};
+const checked = validatePreferences(patch, { partial: true });
+if (!checked.valid) throw new Error(JSON.stringify(checked.errors));
+chart.setPreferences(checked.value, { source: 'agent' });
+
+const state = chart.getState();
+console.log(state.preferences, state.preferenceResolution, state.style);
+```
+
+Use `scope: 'global'` when the request applies to every chart sharing a `PreferencesStore`. Use the default chart scope for one chart.
+
+## Data and Business Change
+
+Use `setData()` only when replacing the chart's complete row set:
+
+```js
+chart.setData(nextRows);
+```
+
+For a semantic business change, preview a typed edit and commit the exact preview:
+
+```js
+const preview = chart.previewEdit({
+  type: 'data-edit',
+  operations: [{ op: 'updateProgress', taskId: 'task-2', progress: 80 }]
+});
+if (!preview.valid) return preview.errors;
+
+const result = chart.applyEdit(preview.command, {
+  preview,
+  confirmed: true,
+  source: 'agent'
+});
+```
+
+This preserves validation, revision checks, ChangeSet information, history, and undo/redo. Never mutate business rows directly when a typed edit operation exists.
+
+## Spec Change
+
+Use `update()` for normal configuration changes:
+
+```js
+chart.update({
+  title: { text: 'Monthly revenue' },
+  yAxis: { title: 'Revenue', nice: true },
+  labels: { enabled: true }
+});
+```
+
+Use `applyPatch()` only when the Agent must address a known JSON path. Validate the result and inspect diagnostics after either operation.
+
+## Required Self-check
+
+After a committed change, inspect:
+
+```js
+const explanation = chart.explain();
+const state = chart.getState();
+
+return {
+  revision: state.revision,
+  health: state.health,
+  warnings: state.warnings,
+  assumptions: state.assumptions,
+  style: state.style,
+  preferenceResolution: state.preferenceResolution,
+  lineage: explanation.lineage
+};
+```
+
+Report `UNKNOWN_INTENT`, `LABELS_SUPPRESSED`, `LABEL_TRUNCATED`, `FUNNEL_LABEL_TRUNCATED`, `VALUE_CLAMPED`, `NEGATIVE_VALUE_DROPPED`, `ZERO_TOTAL`, and unsupported-request diagnostics rather than hiding them.
+
+## Prompt Template
+
+The following prompt is suitable for Codex or WorkBuddy:
+
+```text
+Use the iChart.js Skill. Read the current Spec, state, preferences, and capabilities first.
+Classify my request as visual style, complete data replacement, business record edit,
+Spec configuration, diagram edit, or export.
+
+Use setPreferences/setTheme for visual changes, setData for complete replacement,
+previewEdit/applyEdit for business or diagram edits, update for normal Spec changes,
+and applyPatch only for a precise JSON path. Validate or preview before committing.
+Ask for confirmation before deletion, bulk edits, or structural changes. After applying,
+run chart.explain() and chart.getState(), then return the changed values, warnings,
+assumptions, lineage, preview URL, and artifact paths.
+
+Request: <describe the desired change>
+```
+
+The host remains responsible for authentication, permissions, persistence, confirmation UI, and the natural-language model. iChart.js remains the validated JavaScript runtime and does not require a CLI, MCP server, or HTTP service for this workflow.

package/docs/agent/development/2.0-release-readiness.md

@@ -40,7 +40,7 @@ iChart.js 2.0 is a new Agent-first product line. Compatibility with 1.x and a 1.
 
 ## Iteration 13 Addendum — 2026-09-23
 
-The historical 2.0.0 release decision remains unchanged. Release `v2.0.19` includes Iteration 13 contract hardening, Iteration 14 lightweight Flow semantics, and Iteration 15 text-readability hardening without adding a chart type: 18 chart profiles, 25 commands, 11 schemas, contract version `1.1`, atomic mutation validation, Mindmap edge discovery, strict TypeScript consumer compilation, no active source cycles, Node tests, Chromium browser acceptance, package dry-run verification, the 13F axis-free layout strategy, Timeline/Milestone layout hardening, renderer-parity Flow semantic shapes, adaptive diagram labels, diagram-only edge-label plates, and polar label layout diagnostics for Pie, Donut, and Gauge.
+The historical 2.0.0 release decision remains unchanged. Release `v2.0.21` includes Iteration 13 contract hardening, Iteration 14 lightweight Flow semantics, Iteration 15 text-readability hardening, Iteration 16 Agent presentation and acceptance hardening, and Iteration 17 production trust and Agent reliability hardening without adding a chart type: 18 chart profiles, 25 commands, 11 schemas, contract version `1.1`, atomic mutation validation, Mindmap edge discovery, strict TypeScript consumer compilation, no active source cycles, Node tests, Chromium browser acceptance, package dry-run verification, the 13F axis-free layout strategy, Timeline/Milestone layout hardening, renderer-parity Flow semantic shapes, native Flow ellipse primitives, adaptive diagram labels, diagram-only edge-label plates, polar label layout diagnostics for Pie, Donut, and Gauge, preference source resolution, conversational workflow guidance, effective-option explanations, stable normalization diagnostics, unsupported-renderer planning diagnostics, package-content checks, and Gallery browser acceptance.
 
 ## Deferred npm Publication
 

package/docs/agent/development/iteration-16.md

@@ -0,0 +1,70 @@
+# Iteration 16 — Agent-ready Presentation and Acceptance Hardening
+
+Iteration 16 consolidates the runtime after the chart, diagram, preference, and readability work. It adds no chart type. The goal is to make page-level configuration, Agent changes, browser rendering, lifecycle behavior, and conversational workflows explicit and testable.
+
+## 16A — Gallery and Preference Precedence
+
+- Make page, chart, Spec, and automatic style sources observable.
+- Keep page-level Gallery controls authoritative for the charts they target.
+- Keep chart-menu changes isolated to one chart.
+- Allow `auto` to clear an override.
+- Version persisted preferences and keep storage failures non-fatal.
+- Test `project-gallery.html` and `preferences-lab.html` in a real browser.
+
+The runtime precedence is:
+
+```text
+defaults → chart Spec → global PreferencesStore → chart PreferencesStore
+```
+
+`chart.getState().preferenceResolution` reports the precedence, storage mode, and source of each active scope.
+
+## 16B — Agent State and Discoverability
+
+- Expose preference resolution beside effective preferences.
+- Publish the conversational routing contract through `getCapabilities()` and `capabilities.json`.
+- Keep diagnostics for hidden, truncated, clamped, or unsupported content machine-readable.
+- Document minimal executable examples for visual, data, Spec, project, and Diagram changes.
+- Keep the Skill and English/Chinese Agent guides aligned.
+
+## 16C — Renderer, Responsive, and Accessibility Acceptance
+
+- Check SVG/Canvas parity for themes, labels, diagrams, and edge-label plates.
+- Test narrow containers, long CJK labels, multiple legends, Funnel stages, and polar labels.
+- Test settings-menu focus, keyboard operation, Escape closing, and ARIA labels.
+- Use browser screenshots for visual acceptance in addition to SVG text assertions.
+
+## 16D — Lifecycle and Performance Stability
+
+- Repeated theme, preference, update, resize, and destroy operations must not duplicate listeners or menus.
+- Recreate Gallery charts without stale observers or subscriptions.
+- Record a baseline for the 18-chart Gallery and representative larger datasets.
+- Keep package, export, Skill, docs, and manifest checks in the release gate.
+
+## 16E — Conversational Workflow
+
+- Define natural-language request classification without adding an NLP parser to the library.
+- Route visual changes to `setPreferences()`/`setTheme()`.
+- Route complete data replacement to `setData()`.
+- Route business and Diagram edits through `previewEdit()`/`applyEdit()`.
+- Route normal Spec changes to `update()` and precise JSON changes to `applyPatch()`.
+- Require preview, validation, confirmation for destructive changes, and post-commit `explain()`/`getState()` checks.
+- Add `docs/agent/conversational-workflow.md` and its Chinese companion.
+
+## Acceptance
+
+- Gallery top-level theme controls change the targeted charts and remain visible in `getState()`.
+- A preference change reports its source and effective precedence.
+- An Agent can follow one documented workflow to modify style, data, Spec, or Diagram content.
+- Invalid changes remain atomic and produce structured diagnostics.
+- SVG and Canvas remain behaviorally aligned for supported features.
+- Repeated create/update/destroy cycles leave no stale runtime resources.
+- `npm test`, browser tests, `npm run agent:check`, and `git diff --check` pass.
+
+## Out of Scope
+
+- New chart types.
+- CLI, MCP, or HTTP services.
+- A built-in natural-language model or parser.
+- Collaborative editing.
+- Arbitrary CSS injection or a large theme designer.

package/docs/agent/development/iteration-17.md

@@ -0,0 +1,55 @@
+# Iteration 17 — Production Trust and Agent Reliability
+
+Iteration 17 hardens the existing chart runtime for production Agent use. It adds no chart type, no CLI, no MCP server, and no HTTP service.
+
+## 17A — Contract Reliability
+
+- Diagnose unknown top-level Spec options instead of silently ignoring them.
+- Keep `validateSpec()`, normalization, `createChart()`, capabilities, TypeScript, and manifests aligned.
+- Preserve stable diagnostic codes, JSON paths, expected values, and actionable suggestions.
+
+## 17B — Agent Self-check
+
+- Expose effective rendering options and normalization results through `chart.explain()`.
+- Report unsupported renderer requests during `planChart()` instead of returning only a fallback.
+- Publish `agentReliability` in `getCapabilities()` and `capabilities.json`.
+- Keep navigation, editing, and motion safe by default.
+
+## 17C — Package and Integration Confidence
+
+- Add a package dry-run gate for required runtime, TypeScript, Skill, recipes, and capability files.
+- Reject accidental publication of `.trae`, `.github`, tests, and Playground development paths.
+- Keep the consumer TypeScript fixture and ESM/headless examples in the release gate.
+
+## 17D — Rendering and Accessibility Acceptance
+
+- Continue SVG/Canvas parity checks for labels, diagrams, exports, and responsive layouts.
+- Keep browser acceptance separate from headless checks and require explicit local-server evidence.
+- Preserve static, safe defaults while testing opt-in navigation and editing.
+
+## 17E — Open Source Maintenance
+
+- Keep `CONTRIBUTING.md`, `SECURITY.md`, CI, release SOP, Skill, and Agent guides aligned.
+- Record package and contract checks as mandatory contribution and release gates.
+
+## Acceptance
+
+```text
+inspect data
+→ plan chart
+→ validate Spec
+→ create chart
+→ inspect effective options and health
+→ preview/export
+```
+
+- Invalid or ignored configuration is diagnosable.
+- An Agent can verify what actually rendered without reading renderer internals.
+- The npm tarball contains only supported consumer artifacts.
+- `npm run agent:check`, browser acceptance, and `git diff --check` pass.
+
+## Out of Scope
+
+- New chart types.
+- NLP parsing inside the runtime.
+- CLI, MCP, HTTP, Python, or 1.x compatibility layers.

package/docs/agent/development/roadmap.md

@@ -1,6 +1,6 @@
 # iChart.js 2.0 Roadmap
 
-> Roadmap baseline: 2026-09-14. Current release status: `v2.0.19` includes the completed Iteration 12 structured-diagram work, Iteration 13 contract hardening, Iteration 14 lightweight Flow semantics, Iteration 15 text-readability hardening, sector-aware Pie/Donut labels, radius-aware Gauge metrics, and the preceding layout and diagnostic improvements. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.21` includes the completed Iteration 12 structured-diagram work, Iteration 13 contract hardening, Iteration 14 lightweight Flow semantics, Iteration 15 text-readability hardening, Iteration 16 Agent presentation and acceptance hardening, Iteration 17 production trust and Agent reliability hardening, native Flow ellipse primitives, sector-aware Pie/Donut labels, radius-aware Gauge metrics, and the preceding layout and diagnostic improvements. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -18,6 +18,9 @@
 - Iteration 13A–13F is complete and included in `v2.0.18`: canonical contract registry and generated capability projection, atomic Spec/data/style mutations, row-complete project validation, explicit Mindmap edge metadata, complete public TypeScript declarations and consumer fixture, module-cycle and documentation/example gates, browser acceptance, package dry-run evidence, an axis-free layout strategy for Pie, Funnel, Gauge, and Radar, Timeline/Milestone layout hardening, and runtime diagnostics for constrained Funnel labels and Swimlane label aliases. No chart type was added.
 - Iteration 14A–14D is complete and included in `v2.0.18`: lightweight Flow semantics for start/end, process, decision, input/output, and connector nodes, explicit decision branches and loops, shared SVG/Canvas geometry, capability discovery, validation, and Gallery coverage. No new chart type was added.
 - Iteration 15A–15D is complete and included in `v2.0.19`: adaptive diagram node labels, semantic inline-first edge labels, diagram edge-label background plates, plate-free generic chart labels, shared SVG/Canvas fitting, unified label diagnostics, Agent/diagram documentation, and polar label layout hardening for Pie, Donut, and Gauge.
+- Iteration 16A–16E is complete and included in `v2.0.20`: Gallery preference precedence, preference source resolution, conversational Agent routing, bilingual workflow guidance, manifest discovery, lifecycle regression coverage, and browser acceptance for Gallery theme controls.
+- Flow start/end nodes now use native ellipse geometry across Scene Graph, SVG, Canvas, export, scaling, and hit testing.
+- Iteration 17A–17E is complete and included in `v2.0.21`: unknown-option diagnostics, effective Agent explanations, unsupported renderer planning diagnostics, `agentReliability` discovery, npm package-content checks, and production-trust documentation. See `docs/agent/development/iteration-17.md`.
 - The original `2.0.0` readiness record is historical and superseded by the published `2.0.x` releases. Current release checks are defined by `docs/agent/development/release-sop.md`.
 
 ## Iteration 4 — Agent Data Contract and Business Editing
@@ -276,6 +279,20 @@ Allow users and Agents to adjust a chart's visual presentation after creation th
 - Settings UI is excluded from SVG, PNG, and JSON chart exports.
 - `npm run agent:check`, `git diff --check`, and `http://localhost:3000/playground/preferences-lab.html` acceptance pass.
 
+## Iteration 16 — Agent-ready Presentation and Acceptance Hardening
+
+### Goal
+
+Make page-level configuration, Agent changes, browser rendering, lifecycle behavior, and natural-language workflows explicit and testable without adding chart types or a separate service. The complete plan and acceptance contract are in `docs/agent/development/iteration-16.md`.
+
+### Deliverables
+
+- `chart.getState().preferenceResolution` and `PreferencesStore.getResolution()`.
+- Capability and manifest entries for conversational routing and preference precedence.
+- Bilingual `conversational-workflow.md` guidance for style, data, Spec, Diagram, and export requests.
+- Gallery theme-control browser regression and Iteration 16 runtime tests.
+- Updated Skill, README, runtime contract, usage scenarios, TypeScript declarations, and generated manifests.
+
 ## Recommended Execution Order
 
 1. Finish Iteration 3 browser acceptance.
@@ -286,4 +303,5 @@ Allow users and Agents to adjust a chart's visual presentation after creation th
 6. Execute Iteration 8 to complete existing chart behavior, Agent adaptation, and the 2.0 release gates.
 7. Execute Iteration 9 to standardize adaptive visual styling without expanding chart count.
 8. Execute Iteration 11 to add post-creation chart and page preferences without expanding chart count.
-9. Re-evaluate geographic and 3D scope only after usage data confirms demand.
+9. Complete Iteration 16 acceptance hardening before introducing another chart family or service integration.
+10. Re-evaluate geographic and 3D scope only after usage data confirms demand.

package/docs/agent/diagram-scenario.md

@@ -71,6 +71,8 @@ For a mindmap, prefer the compact parent contract:
 
 Supported kinds are `start`, `end`, `process`, `decision`, `io`, and `connector`. A decision should have at least two outgoing labeled edges. Loops are ordinary explicit `from`/`to` edges and are allowed. Connectors are circular hand-off points; they do not use implicit matching, so every connection remains visible in `edges`.
 
+Flow `start` and `end` nodes render as true ellipse shapes; `process` nodes are rectangles, `decision` nodes are diamonds, and `io` nodes are parallelograms.
+
 Node labels are centered on the node and use adaptive fitting: they wrap to at most two lines, reduce to a bounded minimum font size, and truncate only as a last resort. Compact nodes such as small connectors suppress their internal label rather than rendering unreadable text; the full label remains in the node data and accessibility surface. Edge labels stay inline when space permits, use a high-opacity background plate when the line would reduce contrast, and move aside only when they collide with nodes or other labels. `getState().layout.labels` and `explain().warnings` expose any wrapping, scaling, truncation, or suppression.
 
 ## Current Capabilities

package/docs/agent/frontend-integration.md

@@ -10,7 +10,7 @@ This is the production component path. For one-off files or Agent-led repository
 npm install @taylorwong/ichartjs@^2
 ```
 
-For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.19`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.21`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 

package/docs/agent/runtime-contract.md

@@ -12,6 +12,8 @@ Agents should use `getCapabilities()` first instead of hard-coding undeclared ty
 
 For post-creation visual settings, use `getPreferenceCapabilities(chartType, { locale }) → chart.getPreferences() → validatePreferences(patch) → chart.setPreferences(patch, { source: 'agent' }) → chart.getState().preferences`. This keeps Agent changes on the same allowlisted contract as the built-in settings menu.
 
+The effective preference precedence is `defaults → chart Spec → global PreferencesStore → chart PreferencesStore`. Use `chart.getState().preferenceResolution` to inspect the active scopes, storage mode, and source metadata. The runtime does not parse natural-language prose; use the [Conversational Workflow](conversational-workflow.md) to route prose to the correct mutation API.
+
 Iteration 8 adds per-chart profiles through `getChartCapability(type)`. Each profile declares required data roles, supported interactions, renderers, feature status, exports, and practical limits. Unsupported behavior must be handled from this profile or from validation diagnostics rather than guessed.
 
 `planChart(data, { intent, renderer })` returns a versioned planning result with a primary chart, alternatives, confidence, reasons, required fields, suggested encodings, assumptions, warnings, unsupported requests, safe next actions, and the selected capability profile. `intent` must be one exact token from `getCapabilities().intents`; natural-language prose must be mapped before planning. An unknown token returns `UNKNOWN_INTENT` and a fallback plan, so Agents must inspect warnings before accepting `primary`. Planning never invents business meaning, units, dates, or missing fields.
@@ -127,7 +129,7 @@ chart.downloadSVG()
 chart.downloadJSON()
 ```
 
-Validation results contain separate `errors`, `warnings`, and `normalizations`. Diagnostics use stable codes, JSON-oriented paths, expected values where useful, and actionable suggestions. `chart.explain()` returns encodings, transforms, interactions, assumptions, warnings, stable record lineage, and an accessibility summary.
+Validation results contain separate `errors`, `warnings`, and `normalizations`. Diagnostics use stable codes, JSON-oriented paths, expected values where useful, and actionable suggestions. Unknown top-level options return `UNKNOWN_SPEC_OPTION` instead of being silently treated as valid configuration. `chart.explain()` returns encodings, transforms, interactions, effective options, normalizations, assumptions, warnings, stable record lineage, and an accessibility summary.
 
 For lineage checks and linked updates, provide stable string `id` values on input rows. Without one, the runtime uses deterministic positional IDs such as `record-0`; these are suitable for a local self-check but not for durable business identity.
 

package/docs/agent/usage-scenarios.md

@@ -8,6 +8,8 @@ iChart.js has three layers:
 
 The Skill is not a second renderer or service. A Skill-enabled Agent still needs a JavaScript host to render an interactive chart or create a file.
 
+For natural-language changes to an existing chart, use the [Conversational Workflow](conversational-workflow.md). The Runtime does not parse prose itself; the host Agent maps prose to validated Runtime calls.
+
 ## Choose a Scenario
 
 | Need | Use | Runtime location | Typical output |
@@ -79,6 +81,8 @@ const chart = createChart({
 
 The host application owns data loading, authentication, routing, persistence, and state management. Call `setData()` for row changes, `update()` for Spec changes, and `destroy()` before replacing the component.
 
+For a request such as “use a dark theme, hide the grid, and change the March value,” route the style part through `setPreferences()` and the business-record part through `previewEdit()`/`applyEdit()` rather than mutating rows directly. Return the resulting `explain()` and `getState()` diagnostics.
+
 Use this scenario for dashboards, admin pages, project management products, editors, and embedded analytics.
 
 ## Scenario 2: Ask a Coding Agent to Modify a Project
@@ -121,7 +125,7 @@ npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --ye
 For reproducible installation, pin the released Skill directory:
 
 ```bash
-npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.19/skills/ichartjs \
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.21/skills/ichartjs \
   --agent codex --global --yes
 ```
 

package/docs/agent/zh-CN/coding-agent-integration.md

@@ -22,7 +22,7 @@ npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目
 npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.19/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.21/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
 
 使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
 

package/docs/agent/zh-CN/conversational-workflow.md

@@ -0,0 +1,128 @@
+# 自然语言修改工作流
+
+iChart.js Runtime 不在内部解析自然语言。Codex、WorkBuddy 等宿主 Agent 负责理解用户请求，并将请求转换成公开的 JavaScript API；Runtime 负责校验、提交、渲染、解释和导出。
+
+## 安全执行流程
+
+所有对话式修改都遵循：
+
+```text
+读取当前状态
+  → 判断请求类型
+  → 生成结构化变更
+  → 校验或预览
+  → 破坏性操作请求确认
+  → 提交
+  → explain 和 getState 自检
+  → 返回预览或导出结果
+```
+
+修改已有图表前，先读取 `getCapabilities()`、`chart.getSpec()`、`chart.getState()` 和 `chart.getPreferences()`。原始自然语言应单独保留，不能直接把自然语言句子传给 `planChart().intent`，应先映射为已注册的 intent token。
+
+## 请求分流
+
+| 用户请求 | Runtime 操作 | 是否确认 |
+| --- | --- | --- |
+| 修改主题、配色、字号、图例、标签、网格 | `setTheme()` 或 `setPreferences()` | 通常不需要 |
+| 替换全部数据行 | `setData()` | 由宿主策略决定 |
+| 修改任务、里程碑、节点、连线或项目记录 | `previewEdit()` → `applyEdit()` | 批量、删除、结构调整需要 |
+| 修改图表类型、字段、坐标轴、标题、标签或布局 | `update()` | 通常不需要 |
+| 修改一个明确的 JSON 路径 | `applyPatch()` | 优先使用 `update()` |
+| 导出结果 | `export()`、`downloadSVG()` 或 `downloadPNG()` | 不需要 |
+
+## 修改样式
+
+使用白名单偏好接口，不要让 Agent 自行发明 CSS 或颜色 Token：
+
+```js
+const capabilities = getPreferenceCapabilities(chart.getSpec().type, { locale: 'zh-CN' });
+const patch = {
+  theme: { mode: 'dark', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+};
+const checked = validatePreferences(patch, { partial: true });
+if (!checked.valid) throw new Error(JSON.stringify(checked.errors));
+chart.setPreferences(checked.value, { source: 'agent' });
+
+const state = chart.getState();
+console.log(state.preferences, state.preferenceResolution, state.style);
+```
+
+使用共享 `PreferencesStore` 时，`scope: 'global'` 表示修改页面全部图表；默认作用于当前图表。
+
+## 修改数据和业务记录
+
+只有在替换整批数据时使用 `setData()`：
+
+```js
+chart.setData(nextRows);
+```
+
+修改任务、里程碑、节点、边等业务记录时，使用带预览的编辑命令：
+
+```js
+const preview = chart.previewEdit({
+  type: 'data-edit',
+  operations: [{ op: 'updateProgress', taskId: 'task-2', progress: 80 }]
+});
+if (!preview.valid) return preview.errors;
+
+const result = chart.applyEdit(preview.command, {
+  preview,
+  confirmed: true,
+  source: 'agent'
+});
+```
+
+这样可以保留校验、revision、ChangeSet、历史记录和撤销/重做。存在对应编辑命令时，不要直接修改业务数据对象。
+
+## 修改 Spec 配置
+
+普通配置修改使用 `update()`：
+
+```js
+chart.update({
+  title: { text: '月度收入' },
+  yAxis: { title: '收入', nice: true },
+  labels: { enabled: true }
+});
+```
+
+只有在必须修改明确 JSON 路径时才使用 `applyPatch()`。两种修改后都要检查校验结果和诊断信息。
+
+## 提交后的自检
+
+```js
+const explanation = chart.explain();
+const state = chart.getState();
+
+return {
+  revision: state.revision,
+  health: state.health,
+  warnings: state.warnings,
+  assumptions: state.assumptions,
+  style: state.style,
+  preferenceResolution: state.preferenceResolution,
+  lineage: explanation.lineage
+};
+```
+
+`UNKNOWN_INTENT`、`LABELS_SUPPRESSED`、`LABEL_TRUNCATED`、`FUNNEL_LABEL_TRUNCATED`、`VALUE_CLAMPED`、`NEGATIVE_VALUE_DROPPED`、`ZERO_TOTAL` 和不支持的配置都必须报告，不能静默忽略。
+
+## 推荐提示词
+
+```text
+使用 iChart.js Skill。先读取当前 Spec、状态、偏好和能力清单。
+判断我的请求属于视觉样式、整批数据替换、业务记录编辑、Spec 配置、Diagram 编辑还是导出。
+
+视觉调整使用 setPreferences/setTheme；整批替换使用 setData；
+业务和 Diagram 编辑使用 previewEdit/applyEdit；普通 Spec 配置使用 update；
+只有精确 JSON 路径修改才使用 applyPatch。提交前先校验或预览。
+删除、批量修改和结构调整先请求确认。提交后调用 chart.explain() 和 chart.getState()，
+返回变更内容、警告、假设、lineage、预览地址和文件路径。
+
+请求：<描述需要的修改>
+```
+
+宿主负责权限、确认界面、持久化和自然语言模型；iChart.js 负责可校验的 JavaScript Runtime，不需要为了这个工作流增加 CLI、MCP 或 HTTP 服务。

package/docs/agent/zh-CN/diagram-scenario.md

@@ -70,6 +70,8 @@ Architecture 的 `layers` 是从上到下排列的水平分层。同层自动布
 
 支持的 `kind` 为 `start`、`end`、`process`、`decision`、`io` 和 `connector`。判断节点建议至少有两条带标签的出边；循环就是普通的显式 `from` / `to` 回边。Connector 是圆形的断开连接点，不使用隐式同名匹配，所有连接都必须明确写在 `edges` 中。
 
+Flow 的 `start` 和 `end` 节点使用真正的椭圆图元；`process` 使用矩形，`decision` 使用菱形，`io` 使用平行四边形。
+
 节点文字默认在节点内居中，并按自适应规则处理：优先保持字号，必要时最多换成两行，再缩小到有限的最小字号，最后才截断。尺寸过小的节点（例如小型 Connector）会隐藏内部文字，避免显示不全；完整文字仍保留在节点数据和无障碍语义中。连线文字在空间足够时优先贴近连线显示；线条影响对比度时使用高不透明度背景底板，只有与节点或其他文字冲突时才移到连线旁边。`getState().layout.labels` 和 `explain().warnings` 会暴露换行、缩放、截断和隐藏结果。
 
 ## 当前能力

package/docs/agent/zh-CN/frontend-integration.md

@@ -6,7 +6,7 @@ iChart.js 应作为普通 JavaScript UI 组件运行在浏览器应用中。数
 npm install @taylorwong/ichartjs@^2
 ```
 
-无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.19`。
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.21`。
 
 ```js
 import { createChart } from '@taylorwong/ichartjs';