dsh-d365-kit 0.34.1 → 0.34.4

package/docs/en/installation.md

@@ -1,151 +1,151 @@
-# Installation & Configuration
-
-**English** | [简体中文](../zh/installation.md)
-
-## Prerequisites
-
-| Item | Requirement |
-| --- | --- |
-| DSH | Desktop edition, able to open the Web GUI (the settings page is a Web client plugin) |
-| Network | Able to reach the environment domain (`*.crm*.dynamics.com` or the matching region) and the sign-in endpoint |
-| Application user | An app registration in Entra ID plus an application user created in Dataverse, giving you `ClientId` / `ClientSecret` / `TenantId` |
-| Permissions | Read metadata, read solutions (`prvReadSolution`), read custom APIs (`prvReadCustomAPI`), read the layer table (`prvReadmsdyn_componentlayer`) |
-
-A read-only application user is enough; for the write capabilities, messages such as `CreateAttribute` require the matching permission on that user in the environment (system customizer, or the matching privileges ticked in a custom role).
-
-> Once the application user is created in one environment, create it again in **every** target environment (the same ClientId can be reused).
-
-## Installation
-
-### Option 1: install from npm (shortest)
-
-```bash
-plugin_manager install_bundle target="dsh-d365-kit@0.34.1"
-```
-
-Works once the package is published to the registry pnpm is configured against — public npm or an internal mirror. The package has no scope, so no scope mapping is needed. To install a specific version pin it as `dsh-d365-kit@<version>`.
-
-> **GitHub alone is not a registry.** A repository on GitHub is reachable directly through the `git+https://...` spec (option 2), and plain `npm install` can also take `github:<user>/<repo>#<tag>`; but `install_bundle target="dsh-d365-kit"` only resolves after the package is published to a registry. The repo ships `.github/workflows/publish.yml`: configure the `NPM_TOKEN` secret, push a `v*` tag, and the package is published for you.
-
-### Option 2: install from Git (no registry needed)
-
-```bash
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.1"
-```
-
-DSH pulls the package from git with pnpm. After installing, check:
-
-```
-plugin_manager list_plugins
-```
-
-Success means `include:dsh-d365-kit` is present with `enabled=true` and `fiberPhase=active`.
-
-### Option 3: install from a local directory
-
-Put the whole repository directory anywhere on this machine:
-
-```bash
-plugin_manager install_bundle target="D:\path\to\dsh-d365-kit"
-```
-
-This is a `link:` install: code changes take effect immediately (the Host side still needs a reload), and upgrading means running `git pull` yourself.
-
-### Option 4: zip
-
-Unzip it, then install it as in option 3.
-
-### A restart is required after installing
-
-Host-side tools work as soon as the plugin is installed; the **settings page** belongs to the Web client plugin, and DSH caches the client plugin module graph, so DSH must be restarted before the page is loaded.
-
-After restarting, open Settings and you should see "D365 Toolkit". If it is missing, run `d365_envs` first to confirm the Host side has loaded, then check the entry name in `plugin_manager list_plugins`.
-
-## First-time configuration
-
-1. Settings → D365 Toolkit → **Environments** → Add environment:
-
-   | Field | Description |
-   | --- | --- |
-   | key | Short name the tools use, e.g. `dev`, `sit`. **Once it goes into a plan it is recorded in the audit log, so pick a stable name** |
-   | URL | Environment URL, e.g. `https://contoso-dev.crm5.dynamics.com` |
-   | Cloud | `public` / `usgovernment` / `dod` / `china`; determines the sign-in endpoint |
-   | Tenant ID | Entra tenant GUID |
-   | ClientId | Application (client) ID of the app registration |
-   | Client secret | Secret value generated in the app registration |
-
-2. Click "Test connection"; an organization name and version number coming back means the credentials are correct.
-3. **Save**. The secret goes into `d365.secrets.json`, everything else into `d365.config.json`.
-4. The **Permissions** tab lists capabilities per environment: "Read metadata" is on by default (turn it off and tables, fields and views become unreadable); tick "Read business data" to read records (off by default).
-5. To write, tick the matching capabilities and fill in "Default solution for changes" (the unique name of an **existing unmanaged** solution).
-
-## Where the configuration lives
-
-The environment list and tool parameters live in `configFile`:
-
-```
-<workspace>/d365.config.json      # environment list, default environment, tool parameters, permissions
-<workspace>/d365.secrets.json     # holds only clientSecret and gitlabToken (plaintext)
-```
-
-`configFile` is resolved in this order:
-
-1. `configFile` in `cordis.patch.yml` (an absolute path, machine-specific configuration from install time)
-2. The `D365_CONFIG_FILE` environment variable
-3. `<USERPROFILE>\Documents\deepseek-harness\default-workspace\d365.config.json` (when that directory exists)
-4. `<current working directory>\d365.config.json`
-
-The repository's `cordis.patch.yml` carries no `configFile`, so the default falls through to item 3; when the workspace is elsewhere, set it with the environment variable or the patch.
-`d365.secrets.json` always sits in the same directory as `configFile`.
-
-**Do not commit these two files to Git**: the repository's `.gitignore` already covers them and `.d365/`.
-
-## Credential resolution order
-
-Each value (`tenantId` / `clientId` / `clientSecret`) is taken in this order:
-
-1. The inline value in the environment configuration;
-2. The `clientSecret` the settings page writes into `d365.secrets.json` (an overlay);
-3. The environment variable name given by `<kind>Env` in that environment's configuration, e.g. `"clientSecretEnv": "D365_DEV_SECRET"`;
-4. The derived name `D365_<ENV>_<KIND>`, e.g. `D365_dev_CLIENT_SECRET` (the key as-is, hyphens included);
-5. The shared names `D365_TENANT_ID` / `D365_CLIENT_ID` / `D365_CLIENT_SECRET`.
-
-Production is better served by environment variables; the settings page is enough for local debugging.
-
-Tokens are cached in process memory and keyed by a fingerprint of "URL + tenant + ClientId + secret" — changed credentials are fetched immediately, with no restart.
-
-## Verification
-
-```
-d365_envs check=true
-d365_metadata resource=entities top=3
-```
-
-If both return content, it works. The first `d365_sync` pulls the full metadata (about 125 MB, three minutes on a real environment); if you would rather not use the disk, skip it and query on demand with `d365_metadata`.
-
-## Upgrade
-
-```bash
-# installed from Git
-plugin_manager remove_bundle target=dsh-d365-kit
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.1"
-```
-
-After changing the version number you must **remove first, then install**: link/pnpm returns `already-installed` when it believes the package exists, and does not replace the code.
-
-Restart DSH after upgrading (the settings page code has to re-enter the module graph).
-
-## Uninstall
-
-```bash
-plugin_manager remove_bundle target=dsh-d365-kit
-```
-
-Local data (`d365.config.json`, `d365.secrets.json`, `.d365/`) is not deleted; clean it up manually when needed.
-
-## Sharing with a team
-
-- Everyone installs a copy and fills in their own `d365.config.json` and secrets;
-- **Permissions are granted per machine**: ticks on someone else's machine do not affect yours, and vice versa;
-- Reports and snapshots live in each person's workspace and are not shared;
-- To give the whole team the same environment definitions, put the `environments` from `d365.config.json` into an internal document — each person still fills in their own secrets.
+# Installation & Configuration
+
+**English** | [简体中文](../zh/installation.md)
+
+## Prerequisites
+
+| Item | Requirement |
+| --- | --- |
+| DSH | Desktop edition, able to open the Web GUI (the settings page is a Web client plugin) |
+| Network | Able to reach the environment domain (`*.crm*.dynamics.com` or the matching region) and the sign-in endpoint |
+| Application user | An app registration in Entra ID plus an application user created in Dataverse, giving you `ClientId` / `ClientSecret` / `TenantId` |
+| Permissions | Read metadata, read solutions (`prvReadSolution`), read custom APIs (`prvReadCustomAPI`), read the layer table (`prvReadmsdyn_componentlayer`) |
+
+A read-only application user is enough; for the write capabilities, messages such as `CreateAttribute` require the matching permission on that user in the environment (system customizer, or the matching privileges ticked in a custom role).
+
+> Once the application user is created in one environment, create it again in **every** target environment (the same ClientId can be reused).
+
+## Installation
+
+### Option 1: install from npm (shortest)
+
+```bash
+plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+```
+
+Works once the package is published to the registry pnpm is configured against — public npm or an internal mirror. The package has no scope, so no scope mapping is needed. To install a specific version pin it as `dsh-d365-kit@<version>`.
+
+> **GitHub alone is not a registry.** A repository on GitHub is reachable directly through the `git+https://...` spec (option 2), and plain `npm install` can also take `github:<user>/<repo>#<tag>`; but `install_bundle target="dsh-d365-kit"` only resolves after the package is published to a registry. The repo ships `.github/workflows/publish.yml`: once either the `NPM_TRUSTED_PUBLISHING` variable or the `NPM_TOKEN` secret exists, every push to `main` with a new `package.json` version is published for you.
+
+### Option 2: install from Git (no registry needed)
+
+```bash
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+```
+
+DSH pulls the package from git with pnpm. After installing, check:
+
+```
+plugin_manager list_plugins
+```
+
+Success means `include:dsh-d365-kit` is present with `enabled=true` and `fiberPhase=active`.
+
+### Option 3: install from a local directory
+
+Put the whole repository directory anywhere on this machine:
+
+```bash
+plugin_manager install_bundle target="D:\path\to\dsh-d365-kit"
+```
+
+This is a `link:` install: code changes take effect immediately (the Host side still needs a reload), and upgrading means running `git pull` yourself.
+
+### Option 4: zip
+
+Unzip it, then install it as in option 3.
+
+### A restart is required after installing
+
+Host-side tools work as soon as the plugin is installed; the **settings page** belongs to the Web client plugin, and DSH caches the client plugin module graph, so DSH must be restarted before the page is loaded.
+
+After restarting, open Settings and you should see "D365 Toolkit". If it is missing, run `d365_envs` first to confirm the Host side has loaded, then check the entry name in `plugin_manager list_plugins`.
+
+## First-time configuration
+
+1. Settings → D365 Toolkit → **Environments** → Add environment:
+
+   | Field | Description |
+   | --- | --- |
+   | key | Short name the tools use, e.g. `dev`, `sit`. **Once it goes into a plan it is recorded in the audit log, so pick a stable name** |
+   | URL | Environment URL, e.g. `https://contoso-dev.crm5.dynamics.com` |
+   | Cloud | `public` / `usgovernment` / `dod` / `china`; determines the sign-in endpoint |
+   | Tenant ID | Entra tenant GUID |
+   | ClientId | Application (client) ID of the app registration |
+   | Client secret | Secret value generated in the app registration |
+
+2. Click "Test connection"; an organization name and version number coming back means the credentials are correct.
+3. **Save**. The secret goes into `d365.secrets.json`, everything else into `d365.config.json`.
+4. The **Permissions** tab lists capabilities per environment: "Read metadata" is on by default (turn it off and tables, fields and views become unreadable); tick "Read business data" to read records (off by default).
+5. To write, tick the matching capabilities and fill in "Default solution for changes" (the unique name of an **existing unmanaged** solution).
+
+## Where the configuration lives
+
+The environment list and tool parameters live in `configFile`:
+
+```
+<workspace>/d365.config.json      # environment list, default environment, tool parameters, permissions
+<workspace>/d365.secrets.json     # holds only clientSecret and gitlabToken (plaintext)
+```
+
+`configFile` is resolved in this order:
+
+1. `configFile` in `cordis.patch.yml` (an absolute path, machine-specific configuration from install time)
+2. The `D365_CONFIG_FILE` environment variable
+3. `<USERPROFILE>\Documents\deepseek-harness\default-workspace\d365.config.json` (when that directory exists)
+4. `<current working directory>\d365.config.json`
+
+The repository's `cordis.patch.yml` carries no `configFile`, so the default falls through to item 3; when the workspace is elsewhere, set it with the environment variable or the patch.
+`d365.secrets.json` always sits in the same directory as `configFile`.
+
+**Do not commit these two files to Git**: the repository's `.gitignore` already covers them and `.d365/`.
+
+## Credential resolution order
+
+Each value (`tenantId` / `clientId` / `clientSecret`) is taken in this order:
+
+1. The inline value in the environment configuration;
+2. The `clientSecret` the settings page writes into `d365.secrets.json` (an overlay);
+3. The environment variable name given by `<kind>Env` in that environment's configuration, e.g. `"clientSecretEnv": "D365_DEV_SECRET"`;
+4. The derived name `D365_<ENV>_<KIND>`, e.g. `D365_dev_CLIENT_SECRET` (the key as-is, hyphens included);
+5. The shared names `D365_TENANT_ID` / `D365_CLIENT_ID` / `D365_CLIENT_SECRET`.
+
+Production is better served by environment variables; the settings page is enough for local debugging.
+
+Tokens are cached in process memory and keyed by a fingerprint of "URL + tenant + ClientId + secret" — changed credentials are fetched immediately, with no restart.
+
+## Verification
+
+```
+d365_envs check=true
+d365_metadata resource=entities top=3
+```
+
+If both return content, it works. The first `d365_sync` pulls the full metadata (about 125 MB, three minutes on a real environment); if you would rather not use the disk, skip it and query on demand with `d365_metadata`.
+
+## Upgrade
+
+```bash
+# installed from Git
+plugin_manager remove_bundle target=dsh-d365-kit
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+```
+
+After changing the version number you must **remove first, then install**: link/pnpm returns `already-installed` when it believes the package exists, and does not replace the code.
+
+Restart DSH after upgrading (the settings page code has to re-enter the module graph).
+
+## Uninstall
+
+```bash
+plugin_manager remove_bundle target=dsh-d365-kit
+```
+
+Local data (`d365.config.json`, `d365.secrets.json`, `.d365/`) is not deleted; clean it up manually when needed.
+
+## Sharing with a team
+
+- Everyone installs a copy and fills in their own `d365.config.json` and secrets;
+- **Permissions are granted per machine**: ticks on someone else's machine do not affect yours, and vice versa;
+- Reports and snapshots live in each person's workspace and are not shared;
+- To give the whole team the same environment definitions, put the `environments` from `d365.config.json` into an internal document — each person still fills in their own secrets.

package/docs/en/permissions.md

@@ -1,161 +1,161 @@
-# Permissions & Writes
-
-**English** | [简体中文](../zh/permissions.md)
-
-## Default posture
-
-Right after installation the plugin is **read-only**:
-
-- Metadata (entities, fields, forms, views, plugins, solutions, layers, sitemaps…) is governed by `metadata.read`, which is **on by default** — an environment that is not listed explicitly counts as granted;
-- **Business records** are not readable by default; grant `data.read` per environment;
-- Any change needs the matching capability granted per environment, and every execution needs a human confirmation.
-
-"What you can see" and "what you can change" share one per-environment capability table, because the two belong together. The page renders one block per environment, separated by a rule.
-
-## Capability table
-
-Configured in `d365.config.json`:
-
-```json
-{
-  "write": {
-    "capabilityVersion": 2,
-    "environments": {
-      "dev": ["metadata.read", "data.read", "optionValue.add", "attribute.add", "view.columns"],
-      "sit": ["metadata.read", "data.read"],
-      "uat": []
-    },
-    "solutionUniqueName": "ContosoBase"
-  }
-}
-```
-
-- An environment with **no entry** has never been configured and keeps the default (only `metadata.read`);
-- An environment whose entry is an **empty array** has everything revoked, including metadata;
-- `capabilityVersion` is written by the settings page when it saves. Older files (without the field) get `metadata.read` added back to their existing entries, which preserves the pre-upgrade "metadata is always readable" behaviour.
-
-| Capability | Real HTTP operation | Group | Effect |
-| --- | --- | --- | --- |
-| `metadata.read` | metadata `GET` | Metadata | Read tables/fields/forms/views/plugins/layers (on by default) |
-| `data.read` | business-data `GET` | Data | Read business records |
-| `data.write` | `POST` / `PATCH` | Data | Create or update business records (high risk, no deletions) |
-| `optionValue.add` | `InsertOptionValue` | Option set | Add option values (global or field-local) |
-| `optionValue.updateLabel` | `UpdateOptionValue` | Option set | Change option labels |
-| `optionValue.delete` | `DeleteOptionValue` | Option set | **Permanently delete** option values (high risk) |
-| `attribute.add` | `POST EntityDefinitions(...)/Attributes` | Field | Add fields |
-| `attribute.update` | `PUT` field URL (`MSCRM.MergeLabels`) | Field | Change display name, description, required level |
-| `attribute.delete` | `DELETE` field URL | Field | **Permanently delete** the field and its data (high risk) |
-| `entity.update` | `PUT` entity URL (`MSCRM.MergeLabels`) | Table | Change table display name and description |
-| `view.columns` | `PATCH savedqueries(id)` | View | Add or remove columns in system views (`layoutxml` only) |
-| `layer.remove` | `RemoveActiveCustomizations` | Layer | **Permanently remove** the top-most unmanaged layer of a component (high risk; tables, fields, global option sets, forms, views, workflows, web resources, plug-ins, custom APIs) |
-| `message.invoke` | any `POST` action | Message | Call one Dataverse message. The message is implemented by the target environment's plug-ins, so it may write data, send notifications or call external systems (high risk; every call is confirmed in the chat) |
-
-Tick them per environment under Permissions in the settings page; "Copy to all environments" is supported.
-
-## Three gates, one decision point
-
-The decision lives in one place, `lib/client.js`, so a new tool cannot bypass it — every request (including "test connection" in the settings page) goes through it:
-
-- **Metadata read**: the entity set name in the request URL is on the metadata allowlist (`EntityDefinitions`, `systemforms`, `savedqueries`, `webresourceset`, `solutions`, `msdyn_componentlayers`…) and requires `metadata.read`; it fails with `metadata-read-forbidden`;
-- **Business-data read**: every other `GET` is blocked as business data and requires `data.read`; it fails with `data-read-forbidden`;
-- **Write**: a request that is not `GET` and does not belong to a metadata message (`PublishXml`, `InsertOptionValue`, `CreateAttribute`, `RemoveActiveCustomizations`…) must have `data.write` first, otherwise it fails with `data-write-forbidden`. A `d365_invoke` `POST` goes through `message.invoke` instead (failing as `message-invoke-forbidden`), while its `GET` function is still a read and needs `data.read`.
-
-Every gate fires **before a token is acquired**, so the request never reaches the environment. Decisions are cached per environment for 2 seconds, so a change in the settings page applies to the next tool call.
-
-## Two-step writes
-
-### Step 1: generate a plan (read-only)
-
-`plan-*` reads the current state, skips items with no change, writes the operations to a plan file (`.d365/pending-writes/`) and returns the operation list.
-
-| Plan | Constraint |
-| --- | --- |
-| `plan-add-options` | Dedupes by the code before `\|`; new values continue from the current maximum +1; existing codes go to `skipped` |
-| `plan-relabel` | Only items whose label actually changes go into the plan |
-| `plan-option-delete` | Requires `acknowledge: true`; missing values go to `skipped`, and Dataverse refuses the delete when existing records reference the value |
-| `plan-add-attribute` | The table must exist and the field must not; `SchemaName` must carry the publisher prefix |
-| `plan-update-attribute` | Only items that really change are included |
-| `plan-delete-attribute` | Requires `acknowledge: true`, otherwise it is rejected outright |
-| `plan-update-entity` | Changes the display name / description only |
-| `plan-view-columns` | Locates the system view by view name (same name distinguished by `entity`); only the cell list in `layoutxml` changes, filter conditions are left alone |
-
-Local option sets (an option set carried by a field) are addressed with `entity` + `attribute`; global option sets with `optionSet`.
-
-### Step 2: execute (needs a human)
-
-```
-Run mw04aul6-1ci6aa
-```
-
-The agent calls `d365_write action=execute planId=...`, which:
-
-1. Reads the plan and checks that its status is `pending`;
-2. Checks that the environment **still** holds this capability;
-3. Checks whether the environment is importing/publishing (see below);
-4. Shows a confirmation card: environment, targets, operation count, the first 10 operations; with deletions it adds an unrecoverable warning;
-5. Click "Execute now" → operations are written one by one → publish runs in the background → the run is audited.
-
-You can also review and execute from the Pending changes tab in the settings page (the same second, red confirmation). Both entry points share the same checks.
-
-### Plan states
-
-`pending → running → done / failed`
-
-`running` is persisted before the first write, so a process killed midway never leaves behind a plan that still looks clickable. For a plan that is not `pending`, both the tool and the settings page **refuse** to execute or cancel it — writes are not idempotent, and a rerun would resubmit the parts that already took effect. To redo the work, generate a new plan.
-
-### Pre-flight check
-
-Dataverse holds a customization lock while importing or publishing. Microsoft first-party updates arrive as solution imports, and an environment spends a large part of the day doing exactly that — during which writes either fail with `0x80071151` or wait for the lock until they time out.
-
-So before executing, the plugin looks for rows in `msdyn_solutionhistories` where `msdyn_endtime` is null:
-
-| Case | Behavior |
-| --- | --- |
-| A row exists and its start time is within `busyWindowMinutes` (default 120 minutes) | Refuse to execute and report the operation in progress (`environment-busy`) |
-| Only older rows (leftover zombie rows) | Do not block; mention it in the result |
-| The table cannot be queried (no permission) | Skip the check and note in the result that it was skipped |
-
-`force: true` skips it; use it only when you are sure the row is a leftover.
-
-### Default solution
-
-Every metadata change is recorded in some **solution layer**. Without a solution it goes into the active default layer (Default Solution), which does not travel with an exported solution, and downstream this shows up as "the field does not exist".
-
-So fill in "Default solution for changes": the unique name of an **existing unmanaged** solution. It is validated at plan time — a name that does not exist fails with `unknown-solution`, a managed one with `managed-solution`, instead of waiting until execution to fail.
-
-### Publish scope
-
-After writing, only the **affected components** are published:
-
-- Option set operations → the corresponding option set (field-local option set → the table that owns it);
-- Field / table / view operations → the table that owns them.
-
-The payload looks like:
-
-```xml
-<importexportxml>
-  <entities><entity>account</entity></entities>
-  <optionsets><optionset>contoso_taxcategoryos</optionset></optionsets>
-</importexportxml>
-```
-
-One publish takes seconds to a dozen seconds, instead of the minutes `PublishAllXml` needs to recompute two thousand-plus tables. Only when the affected components cannot be derived does it fall back to a full publish. Publishing happens in the background, the result is written to `.d365/changes/publish-<planId>.json`, and the execute response carries `publishState` (`skipped` / `running`).
-
-## Writing business data
-
-Three constraints on `d365_data_write`:
-
-- It needs `data.write`, off by default;
-- It can write to **one** environment only;
-- Every write shows a confirmation card; the request goes out only after approval.
-
-Writes need no publish (business data is not metadata). The audit records field names only, never values. There is no delete.
-
-## Safety boundaries
-
-- **Write endpoints accept only the settings page**: `/write/policy`, `/write/cancel`, `/write/execute`, `/write/publish` require an `x-d365-meta-write: 1` header. A cross-site page must pass a CORS preflight to send that header, and these routes never answer preflights; if the request carries an `Origin`, it must also be same-origin. The auth channel rewrites the URL to `http://dsh.internal` and swallows `Origin`, so Origin alone cannot be the test. Rejected requests are logged to `.d365/write-guard.log`.
-- **Retries only for safe methods**: `GET`/`HEAD` retry on network errors and 5xx; `POST`/`PATCH`/`DELETE` retry only on **429** (the server explicitly did not execute). A write timeout is reported as "may have taken effect", for a human to check in the environment, rather than being silently resent.
-- **Republishing passes the same gate**: the environment must still hold the capability it had at the time, and an idle check runs first (a busy environment returns 409 rather than a raw 429).
-- **Cancel rejects non-`pending` just like execute**: there is no "the page says cancelled while the backend keeps writing".
-- **No rollback**: metadata deletions cannot be undone, so a delete requires `acknowledge: true`, and the card calls it out separately.
-- Write endpoints expose no bulk script entry point and no "skip confirmation" switch; `force` skips only the idle check, never the confirmation.
+# Permissions & Writes
+
+**English** | [简体中文](../zh/permissions.md)
+
+## Default posture
+
+Right after installation the plugin is **read-only**:
+
+- Metadata (entities, fields, forms, views, plugins, solutions, layers, sitemaps…) is governed by `metadata.read`, which is **on by default** — an environment that is not listed explicitly counts as granted;
+- **Business records** are not readable by default; grant `data.read` per environment;
+- Any change needs the matching capability granted per environment, and every execution needs a human confirmation.
+
+"What you can see" and "what you can change" share one per-environment capability table, because the two belong together. The page renders one block per environment, separated by a rule.
+
+## Capability table
+
+Configured in `d365.config.json`:
+
+```json
+{
+  "write": {
+    "capabilityVersion": 2,
+    "environments": {
+      "dev": ["metadata.read", "data.read", "optionValue.add", "attribute.add", "view.columns"],
+      "sit": ["metadata.read", "data.read"],
+      "uat": []
+    },
+    "solutionUniqueName": "ContosoBase"
+  }
+}
+```
+
+- An environment with **no entry** has never been configured and keeps the default (only `metadata.read`);
+- An environment whose entry is an **empty array** has everything revoked, including metadata;
+- `capabilityVersion` is written by the settings page when it saves. Older files (without the field) get `metadata.read` added back to their existing entries, which preserves the pre-upgrade "metadata is always readable" behaviour.
+
+| Capability | Real HTTP operation | Group | Effect |
+| --- | --- | --- | --- |
+| `metadata.read` | metadata `GET` | Metadata | Read tables/fields/forms/views/plugins/layers (on by default) |
+| `data.read` | business-data `GET` | Data | Read business records |
+| `data.write` | `POST` / `PATCH` | Data | Create or update business records (high risk, no deletions) |
+| `optionValue.add` | `InsertOptionValue` | Option set | Add option values (global or field-local) |
+| `optionValue.updateLabel` | `UpdateOptionValue` | Option set | Change option labels |
+| `optionValue.delete` | `DeleteOptionValue` | Option set | **Permanently delete** option values (high risk) |
+| `attribute.add` | `POST EntityDefinitions(...)/Attributes` | Field | Add fields |
+| `attribute.update` | `PUT` field URL (`MSCRM.MergeLabels`) | Field | Change display name, description, required level |
+| `attribute.delete` | `DELETE` field URL | Field | **Permanently delete** the field and its data (high risk) |
+| `entity.update` | `PUT` entity URL (`MSCRM.MergeLabels`) | Table | Change table display name and description |
+| `view.columns` | `PATCH savedqueries(id)` | View | Add or remove columns in system views (`layoutxml` only) |
+| `layer.remove` | `RemoveActiveCustomizations` | Layer | **Permanently remove** the top-most unmanaged layer of a component (high risk; tables, fields, global option sets, forms, views, workflows, web resources, plug-ins, custom APIs) |
+| `message.invoke` | any `POST` action | Message | Call one Dataverse message. The message is implemented by the target environment's plug-ins, so it may write data, send notifications or call external systems (high risk; every call is confirmed in the chat) |
+
+Tick them per environment under Permissions in the settings page; "Copy to all environments" is supported.
+
+## Three gates, one decision point
+
+The decision lives in one place, `lib/client.js`, so a new tool cannot bypass it — every request (including "test connection" in the settings page) goes through it:
+
+- **Metadata read**: the entity set name in the request URL is on the metadata allowlist (`EntityDefinitions`, `systemforms`, `savedqueries`, `webresourceset`, `solutions`, `msdyn_componentlayers`…) and requires `metadata.read`; it fails with `metadata-read-forbidden`;
+- **Business-data read**: every other `GET` is blocked as business data and requires `data.read`; it fails with `data-read-forbidden`;
+- **Write**: a request that is not `GET` and does not belong to a metadata message (`PublishXml`, `InsertOptionValue`, `CreateAttribute`, `RemoveActiveCustomizations`…) must have `data.write` first, otherwise it fails with `data-write-forbidden`. A `d365_invoke` `POST` goes through `message.invoke` instead (failing as `message-invoke-forbidden`), while its `GET` function is still a read and needs `data.read`.
+
+Every gate fires **before a token is acquired**, so the request never reaches the environment. Decisions are cached per environment for 2 seconds, so a change in the settings page applies to the next tool call.
+
+## Two-step writes
+
+### Step 1: generate a plan (read-only)
+
+`plan-*` reads the current state, skips items with no change, writes the operations to a plan file (`.d365/pending-writes/`) and returns the operation list.
+
+| Plan | Constraint |
+| --- | --- |
+| `plan-add-options` | Dedupes by the code before `\|`; new values continue from the current maximum +1; existing codes go to `skipped` |
+| `plan-relabel` | Only items whose label actually changes go into the plan |
+| `plan-option-delete` | Requires `acknowledge: true`; missing values go to `skipped`, and Dataverse refuses the delete when existing records reference the value |
+| `plan-add-attribute` | The table must exist and the field must not; `SchemaName` must carry the publisher prefix |
+| `plan-update-attribute` | Only items that really change are included |
+| `plan-delete-attribute` | Requires `acknowledge: true`, otherwise it is rejected outright |
+| `plan-update-entity` | Changes the display name / description only |
+| `plan-view-columns` | Locates the system view by view name (same name distinguished by `entity`); only the cell list in `layoutxml` changes, filter conditions are left alone |
+
+Local option sets (an option set carried by a field) are addressed with `entity` + `attribute`; global option sets with `optionSet`.
+
+### Step 2: execute (needs a human)
+
+```
+Run mw04aul6-1ci6aa
+```
+
+The agent calls `d365_write action=execute planId=...`, which:
+
+1. Reads the plan and checks that its status is `pending`;
+2. Checks that the environment **still** holds this capability;
+3. Checks whether the environment is importing/publishing (see below);
+4. Shows a confirmation card: environment, targets, operation count, the first 10 operations; with deletions it adds an unrecoverable warning;
+5. Click "Execute now" → operations are written one by one → publish runs in the background → the run is audited.
+
+You can also review and execute from the Pending changes tab in the settings page (the same second, red confirmation). Both entry points share the same checks.
+
+### Plan states
+
+`pending → running → done / failed`
+
+`running` is persisted before the first write, so a process killed midway never leaves behind a plan that still looks clickable. For a plan that is not `pending`, both the tool and the settings page **refuse** to execute or cancel it — writes are not idempotent, and a rerun would resubmit the parts that already took effect. To redo the work, generate a new plan.
+
+### Pre-flight check
+
+Dataverse holds a customization lock while importing or publishing. Microsoft first-party updates arrive as solution imports, and an environment spends a large part of the day doing exactly that — during which writes either fail with `0x80071151` or wait for the lock until they time out.
+
+So before executing, the plugin looks for rows in `msdyn_solutionhistories` where `msdyn_endtime` is null:
+
+| Case | Behavior |
+| --- | --- |
+| A row exists and its start time is within `busyWindowMinutes` (default 120 minutes) | Refuse to execute and report the operation in progress (`environment-busy`) |
+| Only older rows (leftover zombie rows) | Do not block; mention it in the result |
+| The table cannot be queried (no permission) | Skip the check and note in the result that it was skipped |
+
+`force: true` skips it; use it only when you are sure the row is a leftover.
+
+### Default solution
+
+Every metadata change is recorded in some **solution layer**. Without a solution it goes into the active default layer (Default Solution), which does not travel with an exported solution, and downstream this shows up as "the field does not exist".
+
+So fill in "Default solution for changes": the unique name of an **existing unmanaged** solution. It is validated at plan time — a name that does not exist fails with `unknown-solution`, a managed one with `managed-solution`, instead of waiting until execution to fail.
+
+### Publish scope
+
+After writing, only the **affected components** are published:
+
+- Option set operations → the corresponding option set (field-local option set → the table that owns it);
+- Field / table / view operations → the table that owns them.
+
+The payload looks like:
+
+```xml
+<importexportxml>
+  <entities><entity>account</entity></entities>
+  <optionsets><optionset>contoso_taxcategoryos</optionset></optionsets>
+</importexportxml>
+```
+
+One publish takes seconds to a dozen seconds, instead of the minutes `PublishAllXml` needs to recompute two thousand-plus tables. Only when the affected components cannot be derived does it fall back to a full publish. Publishing happens in the background, the result is written to `.d365/changes/publish-<planId>.json`, and the execute response carries `publishState` (`skipped` / `running`).
+
+## Writing business data
+
+Three constraints on `d365_data_write`:
+
+- It needs `data.write`, off by default;
+- It can write to **one** environment only;
+- Every write shows a confirmation card; the request goes out only after approval.
+
+Writes need no publish (business data is not metadata). The audit records field names only, never values. There is no delete.
+
+## Safety boundaries
+
+- **Write endpoints accept only the settings page**: `/write/policy`, `/write/cancel`, `/write/execute`, `/write/publish` require an `x-d365-meta-write: 1` header. A cross-site page must pass a CORS preflight to send that header, and these routes never answer preflights; if the request carries an `Origin`, it must also be same-origin. The auth channel rewrites the URL to `http://dsh.internal` and swallows `Origin`, so Origin alone cannot be the test. Rejected requests are logged to `.d365/write-guard.log`.
+- **Retries only for safe methods**: `GET`/`HEAD` retry on network errors and 5xx; `POST`/`PATCH`/`DELETE` retry only on **429** (the server explicitly did not execute). A write timeout is reported as "may have taken effect", for a human to check in the environment, rather than being silently resent.
+- **Republishing passes the same gate**: the environment must still hold the capability it had at the time, and an idle check runs first (a busy environment returns 409 rather than a raw 429).
+- **Cancel rejects non-`pending` just like execute**: there is no "the page says cancelled while the backend keeps writing".
+- **No rollback**: metadata deletions cannot be undone, so a delete requires `acknowledge: true`, and the card calls it out separately.
+- Write endpoints expose no bulk script entry point and no "skip confirmation" switch; `force` skips only the idle check, never the confirmation.