dsh-d365-kit 0.0.0-stage → 0.34.3

package/cordis.patch.yml

@@ -0,0 +1,44 @@
+# dsh-d365-kit (host plugin).
+#
+# Configuration
+# ------------
+# `configFile` is read on every tool call, so environment definitions can be
+# edited without reinstalling the bundle. When it is unset (this shipped shape),
+# the plugin falls back to, in order:
+#   1. the D365_CONFIG_FILE environment variable
+#   2. <USERPROFILE>\Documents\deepseek-harness\default-workspace\d365.config.json
+#      (when that directory exists)
+#   3. <cwd>\d365.config.json
+#
+# Credentials are never written here: name the environment variables instead.
+# Resolution order per value is
+#   1. the inline value (tenantId / clientId / clientSecret)
+#   2. the value saved in d365.secrets.json by the settings page
+#   3. the variable named by <kind>Env
+#   4. D365_<ENV>_<KIND>          e.g. D365_DEV_CLIENT_SECRET
+#   5. D365_<KIND>                e.g. D365_CLIENT_SECRET
+- insert:
+    - id: dsh-d365-kit
+      name: 'dsh-d365-kit'
+      config:
+        # configFile: 'D:\path\to\d365.config.json'
+        defaultEnvironment: dev
+        timeoutMs: 60000
+        maxRecords: 200
+        # Snapshots are large (~125 MB per full pull), so keep only the last two
+        # per environment: enough for `@prev` comparisons, bounded on disk.
+        snapshotKeep: 2
+        environments: {}
+        # environments:
+        #   dev:
+        #     url: 'https://contoso-dev.crm5.dynamics.com'
+        #     label: Dev
+        #     cloud: public          # public | usgovernment | dod | china
+        #     tenantIdEnv: D365_TENANT_ID
+        #     clientIdEnv: D365_DEV_CLIENT_ID
+        #     clientSecretEnv: D365_DEV_CLIENT_SECRET
+        #   uat:
+        #     url: 'https://contoso-uat.crm5.dynamics.com'
+        #     label: UAT
+        #     clientIdEnv: D365_UAT_CLIENT_ID
+        #     clientSecretEnv: D365_UAT_CLIENT_SECRET

package/docs/en/architecture.md

@@ -0,0 +1,172 @@
+# Architecture and Development
+
+**English** | [简体中文](../zh/architecture.md)
+
+## Layout
+
+One DSH bundle in two parts:
+
+```
+index.js      # Host side: registers the 19 tools, mounts the settings page HTTP routes
+client.js     # Web side: settings page (six tabs, no build step, a browser module directly)
+lib/*.js      # All Host-side logic (41 modules)
+```
+
+Zero runtime dependencies: only Node's built-in `fetch` / `fs` / `path`. No TypeScript, no bundler, no `node_modules`.
+
+`cordis.patch.yml` declares the bundle and its default config (`configFile`, `timeoutMs`, `snapshotKeep`, `environments`);
+`package.json`'s `dsh.bundle.patch` points at it, and `dsh.client` declares the Web-side entry.
+
+## Module responsibilities
+
+```
+lib/
+  client.js           Dataverse Web API client: URL building, paging, retries, permission gate, tokens
+  auth.js             Entra ID client-credentials flow; tokens cached per credential fingerprint
+  config.js           Config load/normalize; configFile fallback chain; secret resolution
+  resources.js        Query definitions and field mappings for 19 metadata resource types
+  runtime.js          makeClient(env, config), org info, version
+  snapshot.js         Snapshot writing, manifest, snapshot directory
+  retention.js        Retention policy, disk stats, cleanup, compaction
+  write-policy.js     Capability table (CAPABILITIES) and per-environment authorization
+  write-actions.js    Planner and executor for all writes (the only code that changes an environment)
+  write-store.js      Plan and change-record read/write, plan state machine
+  preflight.js        Pre-execution idle check (msdyn_solutionhistories)
+  settings-store.js   Settings page data layer (environments, permissions, general params, GitLab)
+  settings-http.js    Settings page routes (exact paths on the auth channel)
+  contract.js         Contract fact reading, comparison, rendering
+  migrate.js          Migration assessment (layer lookup per component)
+  code-check.js       MR check (JS/TS)
+  csharp-check.js     MR check (C#)
+  refs.js             Reverse index (forms/views/flows/steps)
+  health.js           Environment health
+  gitlab.js           GitLab API (MR diff, connectivity)
+  waivers.js          Contract waivers
+  contract-history.js Drift trend
+  data-migrate.js     Business-record migration (plan, lookup resolution, writes, run log)
+  tool-*.js           19 tools, one file per tool (or per related group)
+```
+
+## Data flow
+
+```
+agent calls d365_*  ──> tool-*.js ──> lib capability modules ──> client.js ──> Dataverse Web API
+                            │                                                      │
+                            └────────── summary + file paths <─────────────────────┘
+                                                 │
+                           .d365/{snapshots,diffs,reports,query,changes}
+```
+
+Design principles:
+
+1. **Tools return a summary and a path; the body lands in a file** — do not stuff tens of MB of JSON into the conversation;
+2. **Read-only first** — only `d365_write execute` and `d365_data_write` change an environment, and both require human approval;
+3. **Decisions live in one place** — what can be seen and what can be changed are both decided at the request entry point in `lib/client.js`, so new tools cannot bypass them;
+4. **Live beats snapshot** — "how is it now" questions such as drift, migration, and health read live data; snapshots are only for comparison across time or environments;
+5. **Rules are data** — contract rules, retention policy, and the capability table are all table-driven; adding a rule does not change the flow.
+
+## The path of one request
+
+Take `d365_metadata resource=attributes` as an example:
+
+```
+tool-metadata.js
+  → pickEnvironments(args)            select environments
+  → loadConfig(state.rawConfig)       read config (done at every tool entry)
+  → makeClient(env, config)           build the client
+  → resources.js query definitions    build path/params
+  → client.getPagedWithSelectFallback paging + column-name fallback
+      → permission gate (metadata entity sets → metadata.read; other GETs → data.read; writes → data.write)
+      → getAccessToken (cached per credential fingerprint)
+      → fetch; 429/5xx retried per method
+  → cross-environment alignment + summary
+  → more than 12 rows writes .d365/query/*.json
+```
+
+## Adding a tool
+
+```js
+// lib/tool-demo.js
+import { pickEnvironments } from './tool-metadata.js';   // or roll your own
+
+export default function registerDemo(ctx, state) {
+  const disposer = ctx.tools.register({
+    name: 'd365_demo',
+    description: 'One sentence on what question it answers.',
+    parameters: {                    // must be a standard JSON Schema
+      type: 'object',
+      additionalProperties: false,
+      required: ['entity'],
+      properties: {
+        entity: { type: 'string', description: 'Entity logical name' },
+        environment: { type: 'string', description: 'Environment key' },
+      },
+    },
+    output: {
+      schema: {                      // likewise a standard JSON Schema
+        type: 'object',
+        additionalProperties: false,
+        required: ['text'],
+        properties: { text: { type: 'string' } },
+      },
+    },
+    async execute(args, exec) {
+      const config = await loadConfig(state.rawConfig);   // note: rawConfig
+      ...
+      return { text };
+    },
+  });
+  ctx.effect(() => disposer);
+}
+```
+
+Then import it in `index.js`, call `registerDemo(ctx, state)`, and add the disposer to the list.
+
+DSH's hard requirements (all of these have bitten us):
+
+| Requirement | Symptom |
+| --- | --- |
+| Both `parameters` and `output.schema` are standard JSON Schema (root `type: 'object'`, `required` is an array) | `schema must be a JSON Schema of 'type: "object"', got 'type: null'` |
+| Output strictly matches `output.schema`: no extra fields, no `type: ['string','null']` | `value.x is not a declared property` / `type arrays are not supported` |
+| Config comes from `state.rawConfig` (`index.js` passes `{ rawConfig }`) | Environments mysteriously missing, lists empty |
+| Host-side changes require a plugin reload | Tool behavior is still the old one |
+
+## Client (settings page)
+
+`client.js` is a browser module: `window.__ModuleLoader__.load({ id: 'dsh-d365-kit', factory })`.
+
+- The six tabs' panels are **mounted at the same time**, with inactive ones hidden by `display:none` — switching tabs does not lose edit state;
+- Copy ships a built-in Chinese/English dictionary; `t()` computes on every call from `localeService.getLocale().active`, independent of whether `locale.register` succeeded;
+- Language switches re-render by subscribing to locale changes;
+- Every write operation carries `x-d365-meta-write: 1` (the Host uses it to reject requests that do not come from the settings page).
+
+**The module id must match the package name**, otherwise the loader runs it as two modules, reports `duplicate factory registration`, and the whole settings page disappears.
+
+## Local verification
+
+Most logic can be tested without an environment: stub `globalThis.fetch` and `ctx.tools` and call the module functions directly.
+
+```js
+globalThis.fetch = async (url) => new Response(JSON.stringify({ value: [] }), { status: 200 });
+```
+
+Note: `new Response('', { status: 204 })` throws `Invalid response status code 204` in Node; for 204 use a `null` body.
+
+Minimal set for verifying against a real environment:
+
+```
+d365_envs check=true
+d365_metadata resource=entities top=2
+d365_layers component=account componentType=Entity
+d365_health environments=["<env>"]
+```
+
+## Known pitfalls (for the next person to change the code)
+
+- Metadata endpoints do not accept `$top` / `$orderby`; the client degrades progressively. When writing a new query, prefer `getPagedWithSelectFallback`;
+- `getPagedWithSelectFallback` returns `{ page, selectDropped, ... }`; the rows are in `result.page.records`;
+- `odataString()` only escapes quotes and **does not add them**; write your own `'...'` in filters;
+- `client.getOne()` appends `$top=1`, which returns 400 for `solutions` / `solutioncomponents`; use `requestJson` and page manually instead;
+- Virtual/audit tables such as the layer table and `msdyn_solutionhistories` behave differently from normal tables; verify with a small sample first;
+- Do not rewrite files containing non-ASCII with PowerShell 5.1 `Get-Content | Set-Content` (it re-encodes them as ANSI); use an editing tool;
+- Writing `package.json` with `Set-Content -Encoding utf8` adds a BOM, and `JSON.parse` fails outright.

package/docs/en/checks.md

@@ -0,0 +1,184 @@
+# Check Rules
+
+**English** | [简体中文](../zh/checks.md)
+
+Three check tools answer different questions:
+
+| Tool | Question | Data source |
+| --- | --- | --- |
+| `d365_migrate` | What happens when this solution is imported into the target environment | Live read, layer lookup per component |
+| `d365_contract` | Do downstream environments still honor upstream registrations and references | Live read (drift reflects the present) |
+| `d365_code_check` | Will the code changes in this MR run in the target environment | GitLab MR + live environment read |
+
+Shared convention: **high confidence blocks outright, medium confidence drops to a warning, anything static analysis cannot decide goes to manual confirmation** — better to have a human take one more look than to let a single false positive turn the tool into noise.
+
+---
+
+## Migration assessment (d365_migrate assess)
+
+Component-by-component comparison produces these findings:
+
+| Rule | Criterion | Level |
+| --- | --- | --- |
+| `component-missing` | The component does not exist in the target environment | info |
+| `solution-absent` | The target does not have this solution (first import) | warning |
+| `version-not-newer` | The target version is not lower than the source version (the import does not overwrite it with a newer one) | warning |
+| `managed-mismatch` | Managed state differs between source and target | warning |
+| `source-unmanaged` | The source is unmanaged, so the import leaves a layer that cannot be removed by uninstalling | warning |
+| `option-values-lost` | Option values the target has and the source lacks — deleted by the import | **critical** |
+| `option-label-drift` | The same value carries a different label | warning |
+| `shadowed` | Another solution owns the top layer of this component in the target, so its definition is invalidated after import | listed in summary |
+
+### Component types and layers
+
+Only six types can be looked up by name in the layer table:
+
+| `msdyn_solutioncomponentname` | componenttype |
+| --- | --- |
+| `Entity` | 1 |
+| `Attribute` | 2 |
+| `OptionSet` | 9 |
+| `EntityRelationship` | 10 |
+| `Workflow` | 29 |
+| `WebResource` | 61 |
+
+The remaining types (36 reports, 50 chart/security types, 70 app types…) have no matching name in the layer table, so they only get an **existence check** and are marked "not assessed" in the report.
+
+The keys used to identify a component across environments come from the layer record's `msdyn_componentjson`: Entity → `logicalname`, Attribute → `logicalname` + parent table, OptionSet → `name`, EntityRelationship → `schemaname`, Workflow → `name` + `category`, WebResource → `name`.
+
+### Why it is slow
+
+`msdyn_componentlayer` is a virtual entity: it can only be queried one component at a time by "component id + component type" and cannot be fetched in bulk per solution; a single component takes about 2 seconds. Hence `maxComponents` (default 150) and `concurrency` (default 4, max 8), and only `full: true` assesses everything.
+
+### Reading order for the report
+
+1. Start with **critical**: are any option values lost;
+2. Then **shadowing**: whose definition gets invalidated by the import, and is it one of your own managed patches;
+3. Finally **missing pieces and versions**: a component missing from the target usually means the release pipeline skipped a step;
+4. Landing the conclusion: if the change can join a managed solution and ride along with upgrades, do not ship a separate small unmanaged solution — layers stack by import time, and the next patch that comes in covers it again.
+
+---
+
+## Contract drift (d365_contract)
+
+Treat upstream plugin registrations and visual component references as a **contract**, and check whether the downstream still satisfies it.
+
+| Rule | Criterion | Level |
+| --- | --- | --- |
+| `assembly-missing` | Upstream has the assembly, downstream does not | Blocker |
+| `assembly-version-older` | Downstream version is lower than upstream | Warning |
+| `plugin-type-missing` | A type registered upstream is missing downstream | Blocker |
+| `plugin-step-missing` | The type exists but the step for the "message + stage + mode" combination is missing | Blocker |
+| `form-library-missing` | A web resource referenced by a downstream form does not exist | Blocker |
+| `sitemap-missing` | An upstream custom sitemap is missing downstream | Warning |
+| `handler-missing` | The function named by a form handler cannot be found in the project scripts | Warning |
+| `option-value-missing` | Downstream is missing an upstream option value (or has a value upstream lacks) | Warning |
+
+Details:
+
+- Only **unmanaged** assemblies are compared by default; managed assemblies come from Microsoft or from a managed solution and cannot be changed locally;
+- Steps compare by "type + message + stage + mode": async and sync are two different contracts;
+- Option value comparison requires passing `optionSets` explicitly (each one is read from `GlobalOptionSetDefinitions`); without it, nothing is compared;
+- Content that exists downstream but **not** upstream is never a blocker; when an option set has extra values the only hint is "confirm whether it has been back-ported".
+
+### Handler check
+
+With `handlers: true`, the project scripts referenced by forms are downloaded and checked for the existence of `functionName`.
+
+- Only **project scripts** are judged. The prefixes are inferred from the source environment's unmanaged solutions — the publisher prefix that most of them use, plus `new_` — so a fresh install works against any organization without configuration; set `handlerPrefixes` to pin the list exactly. Partner and sample solutions are deliberately left out: their bundles are minified, so their internal names are mangled and every handler would look missing (on one real environment: 94 findings instead of 14);
+- The handler's own library is checked first; if the function is not found, the search widens to the other project libraries the form loads (form-level shared scope really exists: one library provides the function, another binds it);
+- Platform-injected handlers (`absoluteurl_onchange`, `Main_Form_onload`, etc.) come from system scripts and are not judged;
+- Downloading is capped (400 scripts per environment); anything beyond that is treated as "content unreadable, cannot confirm" rather than falsely reported as a blocker.
+
+The first version judged against "every script library a form loads" and produced 306 warnings; narrowed to "project libraries, own library first" it produces 14, all of them cases where the script was read and the function genuinely is not there. **That number is the design goal: a small actionable set, not an unreadable pile.**
+
+### Waivers and trends
+
+```json
+{ "action": "waive", "rule": "form-library-missing", "env": "sit",
+  "object": "/_static/_common/scripts/CommandbarActions.js", "reason": "this environment does not use SLA dialogs", "days": 30 }
+```
+
+- Stored in `.d365/waivers.json`; `env` accepts `*`, `object` accepts `*` and the prefix form `x*`;
+- An expiry is mandatory (default 30 days); once expired the item reappears in the report automatically;
+- The report shows "N waived", and waived items never enter the blocker list;
+- Every drift run appends an entry to `.d365/reports/contract-history.json` (60 kept), and the next run over the same `source → targets` reports "new / gone".
+
+### Why live data
+
+Plugin registration scale: one environment has about 376 assemblies, 6,400 types, and 5,900 types with steps (about 94,000 step records), read in tens of seconds. Drift computed from a snapshot a few days old produces false conclusions, so no snapshots are used here.
+
+---
+
+## Code check (d365_code_check)
+
+Reads the MR once and analyzes only the files it touches. Requires a read-only GitLab token (`read_api`); the token's user must be at least **Reporter**.
+
+### JS / TS
+
+Chain: changed file → match a web resource in the environment by **file name** (when paths differ, take the closest same-name candidate and mark it "inferred, pending confirmation" in the report) → find the forms that reference that resource → compare the changed lines one by one.
+
+| Check | Verdict |
+| --- | --- |
+| A field read by an added line is on **no** form that loads the library | one blocker |
+| The field is only on some forms (the script may never reach that branch on those forms) | warning, listing the missing forms (at most 3) |
+| A referenced entity does not exist (form `datafieldname`, `Xrm.WebApi` entity set) | blocker |
+| A deleted function is still referenced by a form handler | blocker |
+| A deleted file is still referenced by a form | blocker (not reported when no form references it) |
+| `columns.get('x')` | manual confirmation (view/subgrid column — not being a form field is normal) |
+| A prefixed string subscript `["contoso_x"]` | manual confirmation (cannot tell statically whether it is a field or a plain key) |
+| A newly introduced hard-coded GUID, option value, or environment URL | warning or manual confirmation |
+| Configuration data, field-level security, the running user's privileges | manual confirmation (cannot be decided statically) |
+
+Access patterns covered: `getAttribute`, `getControl`, `attributes.get`, `formContext.data.entity.attributes.get`, `Xrm.Page.getAttribute`, `attributes[...]`, and prefixed string subscripts.
+Relying on a single `getAttribute` regex misses a lot of compiled output (measured: a 103 KB compiled TS script hit 0 times), so access is split into three groups: definitely a field, definitely a column, needs human judgment.
+
+### C# / project files
+
+Infer the assembly name from the **innermost project directory** in the path (an `<AssemblyName>` in the `.csproj` wins when present) → **exact match** against `pluginassemblies` in the environment → look up `plugintypes`, `sdkmessageprocessingsteps`, `sdkmessageprocessingstepimages`.
+
+| Check | Verdict |
+| --- | --- |
+| The assembly does not exist in the target environment (shared projects such as `.Processes` fall here) | warning + manual confirmation of which assembly the file ultimately ships in |
+| The source version differs from the environment assembly version | warning |
+| An `IPlugin` class has no matching plugin type in the target environment | blocker |
+| The type exists but has no steps at all (changes will never fire) | warning |
+| Code reads `PreEntityImages["X"]` / `PostEntityImages["X"]` but the step has no such image registered | blocker (Create steps do not check pre-images) |
+| A step's `filteringattributes` references a field that does not exist on the entity | blocker |
+| An enumerated `contoso_*` literal is neither a table nor a global option set in the target | manual confirmation |
+| Two or more steps on the same `message\|stage` | warning (execution order is undefined when ranks collide) |
+| Code uses `secureConfig` / a constructor with two string parameters | manual confirmation (the Web API does not return secure configuration content) |
+| APIs the sandbox may forbid (`System.IO`, `System.Net`, `Thread.Sleep`…) | warning |
+
+Assembly names are matched exactly, never approximated — a wrong guess checks types and steps against the wrong assembly, which is worse than not checking at all.
+
+### Report structure
+
+```
+Changed file table
+Per-file impact (which resource/assembly it maps to, which forms/types)
+Blockers (must fix)
+Warnings (should fix, or register a waiver)
+Manual confirmation (HC-01…, each entry states why a machine cannot decide)
+```
+
+### Known limits
+
+- Only the MR's added and removed lines are analyzed; no other repository files are read (no import resolution, no call-chain following);
+- Path → web resource name is inferred from the file name, and marked "inferred" when the repository path and the resource name disagree;
+- C# filtering attributes, images, and types are judged from registration data only; secure/unsecure configuration content and implicit ordering beyond rank still need manual confirmation;
+- The running user's privileges and the actual shape of the data are not judged.
+
+---
+
+## Division of labor between the three checks
+
+```
+Code change ──d365_code_check──> can this change ship (one-off, MR-level)
+Upstream vs downstream ──d365_contract──> is the contract between environments broken (ongoing, version-level)
+Solution ──d365_migrate──> will this import shadow someone else (one-off, release-level)
+Who overrode it ──d365_layers──> why this environment looks the way it does
+Who uses it ──d365_refs──> the impact of changing or deleting it
+```
+
+They do not replace each other: `d365_layers` tells you who overrode it, `d365_refs` tells you who references it, and `d365_code_check` tells you whether the lines you changed land on something that does not exist.

package/docs/en/installation.md

@@ -0,0 +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.3"
+```
+
+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.3"
+```
+
+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.3"
+```
+
+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.