@explyt/ai-agent 0.1.0-rc.1 → 0.1.3

package/README.md

@@ -1,24 +1,23 @@
 # @explyt/ai-agent
 
-Explyt AI Agent. Requires Node.js 22 or newer; everything else ships with the package.
+Explyt AI Agent: a terminal AI coding agent. Requires Node.js 22 or newer;
+everything else ships with the package.
 
-## Installation
+## Usage
+
+There is nothing to install. Pin the version, so what runs is exactly what this
+build ships:
 
 ```bash
-npx -y @explyt/ai-agent@0.1.0-rc.1 install
+npx -y "@explyt/ai-agent@0.1.3"          # start the terminal UI
+npx -y "@explyt/ai-agent@0.1.3" login    # store a provider credential, once
 ```
 
-That single command registers the agent for your user account. Use `uninstall` to
-remove it again.
-
-## Using it from an IDE
-
-Configure your ACP client with:
-
-```json
-{ "command": "npx", "args": ["-y", "@explyt/ai-agent@0.1.0-rc.1", "acp"] }
-```
+The agent runs with exactly the extensions this build ships with and ignores any
+others present on the machine, so that version is the whole description of what
+you get.
 
-Restart the IDE afterwards: clients read their configuration at startup.
+IDE (ACP) integration is not part of this package: it is provided by the Explyt
+managed backend, which the Neo plugin downloads and manages.
 
-Run `npx -y @explyt/ai-agent@0.1.0-rc.1 --help` for the full list of commands.
+Run `npx -y @explyt/ai-agent@0.1.3 --help` for the available options.

package/THIRD-PARTY-NOTICES.md

@@ -67,12 +67,92 @@ License or other written license agreements with the Company.
 - Licensed under the MIT License
 
 **Modifications Made:**
-- none; `@earendil-works/pi-coding-agent` is required as a peer dependency and is not
-  redistributed by Explyt. `pi-mcp-adapter` and `pi-subagents` are redistributed
-  unmodified as bundled runtime dependencies.
+- `@earendil-works/pi-coding-agent` is required as a peer dependency; the public npm
+  package does not contain it, while the managed backend archive redistributes the
+  installed package as-is. The installed package is not modified in any way. At launch,
+  the Explyt wrapper creates a directory of its own holding a copy of the engine's
+  `package.json` with `piConfig.name` set — the configuration key upstream provides for
+  renamed distributions — and symbolic links to the engine's files, and points the engine
+  at it through its own `PI_PACKAGE_DIR` override, so the engine presents itself under the
+  Explyt name. The original copyright and license notice above apply to the engine
+  unchanged.
+- `pi-mcp-adapter` and `pi-subagents` are redistributed as bundled runtime
+  dependencies. Text they contribute to the model (tool descriptions and prompt
+  guidelines) is rewritten at request time by the Explyt identity extension to remove
+  the engine's name; the packages' files are not altered for that purpose.
+- `pi-mcp-adapter` is redistributed with one textual modification made at build time:
+  in its `index.ts`, the slash-command alias registered as `pi-mcp` (a second name for
+  the package's `mcp` status command) is renamed to `explyt-mcp`. The command's behavior,
+  the primary `mcp` name, the package's event names and diagnostics are unchanged. The
+  modification is applied by `scripts/build-release.mjs` (`scripts/bundled-command-rename.mjs`)
+  and is documented here as required by the MIT License; the original copyright and
+  license notice above apply to the modified package unchanged.
+- Seven units of `@earendil-works/pi-coding-agent` 0.84.4 are **copied** (from the TypeScript in
+  the shipped sourcemaps' `sourcesContent`) into `extensions/bash/engine/` under spec 006
+  (RQ-37); the whitespace-normalized originals sit next to each copy as `*.upstream.txt`, and every
+  changed line is marked `// 006:` (enforced by `extensions/bash/engine/pin.test.ts`):
+  - `waitForChildProcess` — `src/utils/child-process.ts` → `wait-for-child-process.ts`;
+    modified: idle drain timer suspended while the output writer is busy, promise settles
+    after the last awaited write, injectable and unref-ed timers.
+  - `killProcessTree` — `src/utils/shell.ts` → `kill-process-tree.ts`; modified: Windows
+    `taskkill` awaited through an injected runner with exit code 128 = already exited and
+    other failures reported; POSIX ESRCH/EPERM told apart; signal and platform are parameters.
+  - `getShellEnv` — `src/utils/shell.ts` → `shell-env.ts`; modified: non-public `getBinDir()`
+    replaced by `join(getAgentDir(), "bin")`.
+  - `sanitizeBinaryOutput` — `src/utils/shell.ts` → `sanitize-binary-output.ts`; unmodified.
+  - `OutputAccumulator` — `src/core/tools/output-accumulator.ts` → `output-accumulator.ts`;
+    modified: the `os.tmpdir()` spill file is removed.
+  - `resolveSpawnContext` — `src/core/tools/bash.ts` → `spawn-context.ts`; modified: produces only the
+    `PI_*` session variables (`sessionEnvFrom`); the env merge, `spawnHook` and `exposeSessionEnvironment` are gone.
+  - `formatOutput` — `src/core/tools/bash.ts` (closure inside `execute`) → `format-preview.ts`; modified:
+    hoisted to a function over the accumulator and the durable output path; truncation details returned flat.
 
 ---
 
+### 4. better-custom-provider derivative (local custom-provider extension)
+
+**Original Work:**
+- Name: `better-custom-provider` 1.4.2
+- Available at: https://github.com/real-wudaoshi/better-custom
+- Licensed under the MIT License; original license is retained at `extensions/custom-provider/LICENSE`
+
+**Modifications Made:**
+- local Explyt extension with current `@earendil-works` imports
+- shell API-key execution removed; credential files use locked atomic writes and private permissions
+
+### 5. model-probe, @opencode-ai/models, yaml and minimatch
+
+- `model-probe` 0.6.0, MIT, https://www.npmjs.com/package/model-probe
+  - Copyright (c) 2025 ratatulieoi
+  - Copyright (c) 2026 real-wudaoshi
+- `@opencode-ai/models` 0.0.53, MIT, https://www.npmjs.com/package/@opencode-ai/models
+  - Copyright (c) 2025 models.dev
+- `yaml` 2.9.0, ISC, https://www.npmjs.com/package/yaml
+  - Copyright Eemeli Aro <eemeli@gmail.com>
+- `minimatch` 10.2.6, Blue Oak Model License 1.0.0, https://www.npmjs.com/package/minimatch
+  - Copyright Isaac Z. Schlueter <i@izs.me> and minimatch contributors
+
+The MIT text below applies to the derivative, `model-probe` and `@opencode-ai/models`
+with the copyright notices above. The ISC text immediately below applies to `yaml` alone;
+`minimatch` is covered by the separate Blue Oak Model License text further down, and its
+copyright holder is the one listed for it above rather than the one named in the ISC text:
+
+```
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+```
+
 ## Full License Texts
 
 ### MIT License
@@ -310,6 +390,74 @@ verbatim below.
    limitations under the License.
 ```
 
+### Blue Oak Model License 1.0.0
+
+Applies to: `minimatch`.
+
+`minimatch` is redistributed unmodified as a bundled runtime dependency, so its own
+`LICENSE.md` is present inside its package directory in the shipped artifact. The Blue Oak
+"Notices" clause requires everyone who receives a copy to also get the license text or a
+link to <https://blueoakcouncil.org/license/1.0.0>; the text is reproduced verbatim below
+so this notice satisfies that clause on its own.
+
+```
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules. The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice. If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+**_As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim._**
+```
+
 ---
 
 ## Bundled package metadata for this build
@@ -317,5 +465,5 @@ verbatim below.
 Generated at build time. It records the license metadata declared by the npm packages
 physically bundled into this artifact; consult each package for its complete license text.
 
-- pi-mcp-adapter@2.23.0: license metadata = MIT
-- pi-subagents@0.47.1: license metadata = MIT
+- pi-mcp-adapter@2.31.0: license metadata = MIT
+- pi-subagents@0.62.0: license metadata = MIT

package/agent-docs/README.md

@@ -0,0 +1,43 @@
+# Explyt Ai Agent documentation
+
+This directory describes how **this agent** is configured, for the agent itself to read before
+answering a configuration question or editing a configuration file.
+
+Read one of these files when the user asks how something is configured, or asks you to configure
+it. Read the whole file before editing anything it describes.
+
+| File | Covers |
+|---|---|
+| `settings.md` | `settings.json`, its two layers, and every setting that exists |
+| `rules.md` | persistent instructions: where rule files live, their frontmatter, how to disable one |
+| `skills.md` | Skills: where they are found, the `SKILL.md` frontmatter, how to disable one |
+| `mcp.md` | MCP servers: the two `mcp.json` files, the entry shape, disabling a server or a tool |
+
+## User configuration lives under `.explyt/`
+
+Everything a user configures in this product lives under `.explyt/` — in the home directory for
+all projects, and in the project directory for one project:
+
+```text
+~/.explyt/settings.json              settings for every project
+~/.explyt/rules/**/*.md              rules for every project
+~/.explyt/skills/<name>/SKILL.md     skills for every project
+~/.explyt/mcp.json                   MCP servers for every project
+
+<project>/.explyt/settings.json      settings for this project
+<project>/.explyt/rules/**/*.md      rules for this project
+<project>/.explyt/skills/<name>/SKILL.md
+<project>/.explyt/mcp.json           MCP servers for this project
+```
+
+Create these files and directories when they do not exist; nothing has to be registered anywhere
+for them to take effect.
+
+## Do not create or edit `.pi/` files
+
+`.pi/` belongs to a different product. A setting or a rule written there configures nothing here
+and leaves the user with a file that looks like it works.
+
+Some locations of *other* agent tools are read — `rules.md` and `skills.md` list them, and
+`.pi/skills` is among the Skill roots — so an existing file there may well be active. But a file
+this agent creates always belongs under `.explyt/`.

package/agent-docs/mcp.md

@@ -0,0 +1,111 @@
+# MCP servers
+
+An MCP server gives the agent extra tools, resources and prompts. Servers are declared in JSON.
+
+## Where server definitions are read from
+
+| Source | Location | Written by |
+|---|---|---|
+| global | `~/.explyt/mcp.json` | the user |
+| project | `<project>/.explyt/mcp.json` | the user |
+| session | the `mcpServers` field of the IDE's session request | the IDE |
+
+These three and nothing else. Other tools' MCP files are **not** read — not `~/.config/mcp/mcp.json`,
+not `~/.agents/mcp.json`, not `<project>/.mcp.json`, and not the legacy
+`~/.explyt/mcp_servers.json`. A server the user declared for another product will not appear here;
+it has to be copied into one of the two files above.
+
+Either file may be absent. With none of the sources present the session simply starts with no MCP
+server.
+
+## Shape of the file
+
+```json
+{
+  "mcpServers": {
+    "searxng": {
+      "command": "npx",
+      "args": ["-y", "mcp-searxng"],
+      "env": { "SEARXNG_URL": "${SEARXNG_URL}" }
+    },
+    "docs": {
+      "url": "https://mcp.example.com/sse",
+      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
+    }
+  }
+}
+```
+
+The key is the server name. A stdio server uses `command` with optional `args`, `env` and `cwd`; an
+HTTP server uses `url` with optional `headers`.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `command` | string | executable for a stdio server |
+| `args` | array of strings | its arguments |
+| `env` | object of strings | environment for the server process |
+| `cwd` | string | working directory for the server process |
+| `url` | string | endpoint for an HTTP server |
+| `headers` | object of strings | headers sent with each request |
+| `disabled` | boolean | `true` keeps the definition but does not start the server |
+| `excludeTools` | array of strings | tools of this server the model must not see |
+
+An entry whose field has the wrong type is skipped with a warning, and the rest of the file still
+loads. A file that is not valid JSON, or whose top level is not an object, contributes no servers
+and is reported.
+
+## Environment variables
+
+A string anywhere in an entry may reference a variable in three spellings: `${NAME}`, `$env:NAME`
+and `{env:NAME}`. This is how a secret stays out of the file — write `"Bearer ${DOCS_TOKEN}"`, not
+the token.
+
+A reference to a variable that is not set is reported against that server rather than guessed at,
+and the literal text is passed through unchanged.
+
+## The same name in two files
+
+A project entry **replaces** the global entry of the same name, as a whole. It does not inherit
+single fields from it: to change one field for one project, repeat the whole entry.
+
+A name that collides between the merged files and the servers the IDE supplied is a different
+matter — that makes the configuration invalid, and it is reported rather than resolved by
+preferring a source or renaming a server. Rename one of them.
+
+## Turning a server off
+
+Set `disabled` on its entry:
+
+```json
+{ "mcpServers": { "docs": { "url": "https://mcp.example.com/sse", "disabled": true } } }
+```
+
+The definition stays in the file, so it can be turned back on without retyping it.
+
+## Hiding individual tools
+
+`excludeTools` lists tools of that server the model must not be offered:
+
+```json
+{ "mcpServers": { "docs": { "url": "…", "excludeTools": ["delete_page", "admin_*"] } } }
+```
+
+An entry matches the bare tool name (`delete_page`) or its prefixed form (`docs_delete_page`), and
+`*` and `?` are glob wildcards. By default a server's tools reach the model prefixed with the server
+name, which is why both spellings match.
+
+## When a change takes effect
+
+The configuration is resolved once, before the session's MCP runtime starts. Editing a file does
+**not** affect a session that is already running — the user starts a new session, or applies the
+change from the `/mcp` screen, which reloads the runtime itself.
+
+A server that fails to connect never fails the session: it stays listed with its failure state, and
+every other server keeps working. A server that has not connected yet is reported as not connected,
+which is not an error.
+
+## The `/mcp` screen
+
+In the terminal UI, `/mcp` lists the servers, their status and their tools, and can toggle a server
+or an individual tool — writing the same `disabled` and `excludeTools` fields described above. That
+command does not exist in an IDE session; there, edit the files.

package/agent-docs/rules.md

@@ -0,0 +1,92 @@
+# Rules
+
+A rule is a Markdown file holding instructions that reach the model automatically, so the user
+does not repeat them in every conversation.
+
+## Where rules are read from
+
+| Path | Rule ID | Format |
+|---|---|---|
+| `~/.explyt/rules/**/*.md` | `global:.explyt/rules/team.md` | frontmatter + Markdown |
+| `<project>/.explyt/rules/**/*.md` | `project:.explyt/rules/team.md` | frontmatter + Markdown |
+| `~/.claude/CLAUDE.md` | `user:.claude/CLAUDE.md` | plain Markdown |
+| `<project>/AGENTS.md` | `project:AGENTS.md` | plain Markdown |
+| `<project>/CLAUDE.md` | `project:CLAUDE.md` | plain Markdown |
+| `<project>/.claude/CLAUDE.md` | `project:.claude/CLAUDE.md` | plain Markdown |
+| `<project>/CLAUDE.local.md` | `project:CLAUDE.local.md` | plain Markdown |
+
+Only these locations. A `CLAUDE.md` or `AGENTS.md` in a subdirectory is not picked up, and there is
+no search up the directory tree — the project is the session's working directory.
+
+A new rule belongs in `.explyt/rules/`: project-wide in `<project>/.explyt/rules/`, or for every
+project in `~/.explyt/rules/`. The file may sit in subdirectories; every `.md` below the directory
+is a rule.
+
+The plain-Markdown files are read as-is, have no frontmatter, and always apply to the whole
+session.
+
+## Frontmatter of an Explyt rule
+
+YAML frontmatter, then the Markdown body. Both fields are optional.
+
+| Field | Values | Meaning |
+|---|---|---|
+| `strictness` | `system`, `user-message`, `tool-call` | when the body reaches the model; defaults to `system` |
+| `filePattern` | a glob such as `**/*.kt` | the body reaches the model after a matching file is read |
+
+- `system` — part of the system prompt for the whole session.
+- `user-message` — delivered once with every message the user sends.
+- `tool-call` — delivered after each batch of tool results.
+- `filePattern` — delivered after a successful read of a matching file, at most once per turn. When
+  `filePattern` is present, `strictness` is ignored entirely.
+
+Paths are matched with `/` separators; a pattern like `src/**/*.kt` matches only inside the
+project, while `**/*.kt` matches anywhere. Matching is case-sensitive.
+
+A valid rule:
+
+```markdown
+---
+strictness: user-message
+---
+Answer in English and keep code comments in English.
+```
+
+A file-pattern rule:
+
+```markdown
+---
+filePattern: "**/*.kt"
+---
+This project targets Kotlin 2.0. Prefer data classes over records.
+```
+
+A rule is **invalid** — and silently does not apply — when its frontmatter is missing, when its
+YAML does not parse or is not a mapping of fields, when `strictness` has an unknown value or the
+wrong type **and no `filePattern` is present**, or when `filePattern` is not a string. Only the body is sent to the model; the
+frontmatter is not. An empty body is valid and sends nothing.
+
+Changes take effect on the next message the user sends; the current turn keeps the rules it
+started with.
+
+## Disabling a rule
+
+`rules.disabledRules` in `settings.json` (see `settings.md`) holds exact rule IDs:
+
+```json
+{
+  "rules": {
+    "disabledRules": ["project:AGENTS.md", "global:.explyt/rules/team.md"]
+  }
+}
+```
+
+The ID is the scope prefix (`project:`, `global:`, `user:`) followed by the path from its location
+root, as in the table above. Entries are compared literally: no globs, no prefixes, no
+case-insensitive matching. An entry matching no rule is kept and ignored.
+
+A rule owned by the project — any ID starting with `project:` — can be disabled only through the
+**project** layer. Such an entry written into the global layer is kept but has no effect.
+
+In the terminal UI the user can see the current list of rules and their state with the `/rules`
+command. That command does not exist in an IDE session — there, answer from the files above.

package/agent-docs/settings.md

@@ -0,0 +1,54 @@
+# Settings
+
+Settings are JSON, grouped into sections, and stored in two independent layers.
+
+| Layer | File | Applies to |
+|---|---|---|
+| global | `~/.explyt/settings.json` | every project |
+| project | `<project>/.explyt/settings.json` | the current project only |
+
+The project layer is the session's working directory. There is no search up the directory tree: a
+`.explyt/settings.json` in a parent directory of the project is not read.
+
+Neither file has to exist, and nothing here fails a session. An absent file, or a value of the
+wrong type, falls back to the setting's default. A file that becomes unreadable or stops being
+valid JSON keeps the values that were last read successfully in this session, and falls back to the
+defaults only when none were ever read.
+
+## Shape of the file
+
+One object per section, with the setting's keys inside it:
+
+```json
+{
+  "rules": {
+    "disabledRules": ["project:AGENTS.md"]
+  },
+  "skills": {
+    "disabledSkills": ["pdf-tools"]
+  }
+}
+```
+
+When editing, keep every key the file already has: write the one key that changes and leave the
+rest of the file as it is.
+
+## Every setting
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `rules.disabledRules` | array of strings | `[]` | rule IDs that do not apply; see `rules.md` |
+| `skills.disabledSkills` | array of strings | `[]` | Skill names that are unavailable; see `skills.md` |
+
+Both settings take exact, case-sensitive entries. Neither supports globs or prefixes: `"pdf-*"`
+matches nothing. An entry matching nothing is kept, not an error.
+
+Both are read per layer rather than merged, so a value written in the project layer does not
+replace the global one — each layer's list is applied on its own. Which layer to write is a
+question for the user: the project layer for this project, the global layer for all of them.
+
+## How the two layers combine
+
+A rule or Skill is affected when its ID or name appears in **either** layer's array, with one
+exception stated in `rules.md`: a rule owned by the project can be disabled only through the
+project layer.

package/agent-docs/skills.md

@@ -0,0 +1,90 @@
+# Skills
+
+A Skill is a directory holding a `SKILL.md` file with reusable instructions. Unlike a rule, a Skill
+is not always active: it is applied when the model chooses it, or when the user invokes it by name.
+
+## Where Skills are found
+
+A Skill is any directory containing a `SKILL.md` anywhere below one of these roots:
+
+| Project root | Global root |
+|---|---|
+| `<project>/.explyt/skills` | `~/.explyt/skills` |
+| `<project>/.claude/skills` | `~/.claude/skills` |
+| `<project>/.agents/skills` | `~/.agents/skills` |
+| `<project>/.pi/skills` | `~/.pi/agent/skills` |
+| `<project>/.opencode/skills` | `~/.config/opencode/skills` |
+| `<project>/.kilo/skills` | `~/.kilo/skills` |
+| `<project>/.gemini/skills` | `~/.gemini/skills` |
+| `<project>/.cursor/skills` | `~/.cursor/skills` |
+
+The whole tree below a root is searched, so `<project>/.explyt/skills/team/deploy/SKILL.md` is a
+Skill as much as `<project>/.explyt/skills/deploy/SKILL.md` is. Symlinks are not followed.
+
+The roots of other tools are read so existing collections work, but a **new** Skill belongs in
+`<project>/.explyt/skills/<name>/SKILL.md`, or in `~/.explyt/skills/<name>/SKILL.md` for every
+project. No root outranks another, and the tool a Skill was written for is never recorded.
+
+The project root is the session's working directory; there is no search up the directory tree.
+
+## `SKILL.md`
+
+YAML frontmatter, then the Markdown body that carries the instructions.
+
+| Field | Required | Rule |
+|---|---|---|
+| `name` | yes | 1–64 characters, lowercase letters, digits, single hyphens: `^[a-z0-9]+(-[a-z0-9]+)*$` |
+| `description` | yes | non-empty string; may span several lines |
+| `when_to_use` | no | non-empty string, appended to the description after ` - ` |
+| `user-invocable` | no | boolean, default `true`: the user may invoke it as `/<name>` |
+| `disable-model-invocation` | no | boolean, default `false`: `true` hides it from the model |
+
+A valid example, at `<project>/.explyt/skills/release-notes/SKILL.md`:
+
+```markdown
+---
+name: release-notes
+description: Draft release notes from merged pull requests
+when_to_use: Use when the user asks for a changelog or release notes
+---
+
+1. Collect merged pull requests since the last tag.
+2. Group them by area, one line each.
+3. Put breaking changes first.
+```
+
+The `name` in the frontmatter is the Skill's identity; it does not have to match the directory
+name, but making them equal keeps things findable. Two `SKILL.md` files claiming one name make
+**both** unavailable — neither wins.
+
+A Skill is **invalid** — and unavailable — when the frontmatter is missing, unparseable or not a
+YAML mapping, when `name` or `description` breaks a rule above, when an optional field has the
+wrong type, or when `name` is already taken by a command that exists — a built-in such as `model`,
+`compact` or `settings`, or one this product registers such as `rules` or `skills`; renaming the
+Skill is the fix. A field that is not in the table is
+ignored and never makes a Skill invalid. An empty body is valid.
+
+The body is read at the moment the Skill is applied, so editing instructions takes effect
+immediately; adding, renaming or removing a Skill takes effect on the next message the user sends.
+
+## Disabling a Skill
+
+`skills.disabledSkills` in `settings.json` (see `settings.md`) holds exact Skill names:
+
+```json
+{
+  "skills": {
+    "disabledSkills": ["release-notes"]
+  }
+}
+```
+
+Names are compared literally and case-sensitively: `"release-*"` matches nothing. A name in either
+layer makes that Skill unavailable to both the model and the user. An entry matching no Skill is
+kept and ignored.
+
+Disabling never edits a `SKILL.md`: to hide a Skill from the model but keep it available to the
+user, set `disable-model-invocation: true` in its frontmatter instead.
+
+In the terminal UI the user can see every Skill and its state with the `/skills` command. That
+command does not exist in an IDE session — there, answer from the files above.