docs(skills): document ZCode's executed-vs-recorded component boundary

build/release-evidence.json

@@ -2,11 +2,11 @@
   "schema_version": 2,
   "module": {
     "repository": "NDDev-it-com/nddev-zcode-app",
-    "setup_digest": "sha256:0c6047fe00792d965c03bb3bdfc1cf12d93176fb8353c01ed9619ef3dd88339d"
+    "setup_digest": "sha256:b0e22d023e2d56303eedd3bb8ffefdd91608b25ba3f3e7182a14af26ce720e5a"
   },
   "harness": {
     "repository": "NDDev-it-com/nddev-harnesses",
-    "commit": "066428831895a58ab964d1aa07587430eba1061f"
+    "commit": "275354c5fca5af5da0baff1be96f0c15219a7587"
   },
   "adapter": {
     "id": "zcode",
@@ -30,8 +30,8 @@
     }
   ],
   "lanes": [],
-  "generated_at_utc": "2026-07-18T03:22:57Z",
-  "expires_at_utc": "2027-01-14T03:22:57Z",
+  "generated_at_utc": "2026-07-18T06:15:06Z",
+  "expires_at_utc": "2027-01-14T06:15:06Z",
   "promotion": {
     "decision": "pending",
     "waivers": []

zcode_tools/marketplaces/nddev-builder/plugins/core/references/zcode-native-format.md

@@ -1,8 +1,8 @@
 # ZCode native format reference
 
 A condensed reference for the rules every component in this repository must follow.
-Authoritative source: the `repo-orientation` skill and the `zcode-configuration-guide`
-skill (official ZCode docs).
+Authoritative source: the `nddev-builder-orientation` skill and the built-in
+`zcode-configuration-guide` / `diagnosing-plugins` skills (the ZCode runtime's own guide).
 
 ## Marketplaces and plugin bundles
 
@@ -38,7 +38,29 @@ marketplaces/<marketplace>/
 | `keywords` | no | English tags |
 | `dependencies` | no | other plugin names this one requires |
 
-Never add: `commands`, `skills`, `hooks`, `mcpServers`, `agents` arrays.
+Never add component arrays (`commands`, `skills`, `hooks`, `mcpServers`, `agents`)
+or the inert fields listed below — the manifest is metadata-only and discovery is
+by convention.
+
+## Component execution model (ZCode 3.3.6)
+
+The pinned ZCode 3.3.6 runtime **executes only four plugin-manifest component
+fields** — `commands`, `skills`, `hooks`, `mcpServers` — plus `agents`, which
+execute only from user scope (which is why the installer flattens `agents/` into
+`~/.zcode/agents/` instead of trusting a plugin.json `agents` field).
+
+**Recorded but NOT executed** as plugin.json fields (declaring them has no
+runtime effect, so never author them expecting behavior): `channels`,
+`lspServers`, `outputStyles`, `settings`. In particular an
+`lspServers` / `.lsp.json` block is **inert** on this runtime — there is **no
+loadable LSP component**, so this toolkit ships no `add-lsp` skill by design.
+(The desktop `v2-setting` file this repo renders is a different surface: it is
+the ZCode app's own settings, written directly to `~/.zcode/v2/`, not the inert
+plugin.json `settings` field.) If a future pinned runtime executes these fields,
+this reference and the runtime pin move together.
+
+Authoritative source: the built-in `zcode-guide` plugin
+(`zcode-configuration-guide`, `diagnosing-plugins`).
 
 ## Skills
 

zcode_tools/marketplaces/nddev-builder/plugins/core/skills/add-plugin/SKILL.md

@@ -58,7 +58,9 @@ zcode_tools/marketplaces/<marketplace>/
    ```
 
 4. **Write the manifest** at `.zcode-plugin/plugin.json`. Metadata-only — do NOT add
-   `commands`, `skills`, `hooks`, `mcpServers`, or `agents` arrays. Use this shape:
+   `commands`, `skills`, `hooks`, `mcpServers`, or `agents` arrays, nor the inert
+   `lspServers`, `outputStyles`, `channels`, or `settings` fields (ZCode 3.3.6
+   records but never executes them; see `nddev-builder-orientation`). Use this shape:
    ```json
    {
      "name": "<name>",

zcode_tools/marketplaces/nddev-builder/plugins/core/skills/nddev-builder-orientation/SKILL.md

@@ -60,6 +60,16 @@ each, a component **basename must be unique across every plugin in the
 marketplace**. A cross-plugin clash makes the install **fail closed**, not
 shadow one silently.
 
+## Fields ZCode records but never executes
+
+Only `commands`, `skills`, `hooks`, and `mcpServers` execute on the pinned ZCode
+3.3.6 runtime (plus `agents`, via the user-scope flatten above). The
+plugin-manifest fields **`lspServers` (LSP/language servers), `outputStyles`,
+`channels`, and `settings` are recorded but not executed** — authoring them
+produces dead config. There is **no sixth "LSP component"** to add, so this
+toolkit ships no skill for one by design. See
+`references/zcode-native-format.md` for the full execution model.
+
 ## Lifecycle
 
 - **install** — backup → build clean `~/.zcode` from the setup → flatten to user