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

package/README.md

@@ -1,24 +1,31 @@
 # @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
+
+Install globally for a stable terminal command, or use npx for a one-off run:
 
 ```bash
-npx -y @explyt/ai-agent@0.1.0-rc.1 install
+npm i -g @explyt/ai-agent    # installs the pinned engine and the `explyt` command
+explyt                       # start the terminal UI
+explyt login                 # store a provider credential, once
+explyt update                # install the newer latest, then restart open sessions
 ```
 
-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:
+For a one-off pinned run:
 
-```json
-{ "command": "npx", "args": ["-y", "@explyt/ai-agent@0.1.0-rc.1", "acp"] }
+```bash
+npx -y "@explyt/ai-agent@0.1.4"          # start the terminal UI
+npx -y "@explyt/ai-agent@0.1.4" login    # store a provider credential, once
 ```
 
-Restart the IDE afterwards: clients read their configuration at startup.
+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.
+
+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.4 --help` for the available options.

package/THIRD-PARTY-NOTICES.md

@@ -16,11 +16,13 @@ The Explyt AI Agent — including all modifications to the original third-party
 proprietary software with closed-source code and is licensed only under the Company
 License or other written license agreements with the Company.
 
-> **Scope of this file.** It records the top-level components that Explyt derives from or
-> redistributes. The release pipeline additionally generates a machine-collected list of
-> license metadata for every bundled npm package. That generated list is not a substitute
-> for reviewing the licenses and NOTICE files of all transitive dependencies before a
-> commercial release.
+> **Scope of this file.** It records the top-level components that Explyt derives from,
+> depends on or redistributes. The release pipeline additionally generates a
+> machine-collected list of license metadata for every runtime npm dependency of the
+> artifact, marking which of them are bundled inside it. The public npm package bundles
+> none of them: npm installs them beside it. The managed backend archive redistributes its
+> whole installed tree. The generated list is not a substitute for reviewing the licenses
+> and NOTICE files of all transitive dependencies before a commercial release.
 
 ---
 
@@ -67,17 +69,131 @@ 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 runtime dependencies. The public npm package
+  declares them with exact versions and does not contain them: npm installs the
+  unmodified registry packages beside it. The managed backend archive redistributes them
+  as bundled 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.
+- The public npm package contains `dist/mcp-adapter.js`, an unobfuscated compilation of
+  the unmodified `pi-mcp-adapter` entrypoint (`index.ts`) together with the package's
+  small runtime helper files, so that Node can load it outside the engine's TypeScript
+  loader.
+- In the managed backend archive only, `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. The public npm package does not carry the
+  adapter and therefore carries no modification of it.
+- 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, minimatch and semver
+
+- `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
+- `semver` 7.8.5, ISC, https://www.npmjs.com/package/semver
+  - Copyright (c) Isaac Z. Schlueter and 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` and
+`semver`, each with its own copyright holder listed above (the ISC terms are identical);
+`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.
+```
+
+### 6. rpiv-ask-user-question
+
+**Original Work:**
+- Name: `@juicesharp/rpiv-ask-user-question` (version 2.11.0)
+- Available at: https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question
+  (source: https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question)
+- Licensed under the MIT License
+  - Copyright (c) 2026 juicesharp
+
+**Modifications Made:**
+- the package's code is redistributed unobfuscated, compiled by `scripts/build-release.mjs`
+  (`extensions/ask-user-question/sidecar.mjs`) into `dist/rpiv-ask-user-question/`; its own
+  source files are not altered
+- its dependency `@juicesharp/rpiv-config` is not redistributed: the bundle resolves it to an
+  Explyt-owned provider that reads no configuration file and returns the defaults
+- the Explyt `ask-user-question` extension changes the registered tool at runtime: sequential
+  execution, surface-neutral wording of the tool description, parameter descriptions and prompt
+  guidelines plus one added guideline, a replacement text for the not-answered result, and, in
+  IDE sessions, a native form in place of the package's terminal overlay
+
+The MIT License text below applies to this package with the copyright notice above.
+
 ## Full License Texts
 
 ### MIT License
 
-Applies to: pi-acp, `@earendil-works/pi-coding-agent`, `pi-mcp-adapter`, `pi-subagents`.
+Applies to: pi-acp, `@earendil-works/pi-coding-agent`, `pi-mcp-adapter`, `pi-subagents`,
+`@juicesharp/rpiv-ask-user-question`.
 
 ```
 MIT License
@@ -310,12 +426,98 @@ verbatim below.
    limitations under the License.
 ```
 
+### Blue Oak Model License 1.0.0
+
+Applies to: `minimatch`.
+
+`minimatch` is an unmodified runtime dependency: the public npm package declares it and
+npm installs it beside the package, and the managed backend archive carries it in its
+installed tree. Either way its own `LICENSE.md` is present inside its package directory on
+the user's machine. 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
+## Runtime dependency metadata for this build
 
 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
+this package depends on at runtime; none is bundled into the tarball, npm installs them beside it.
+Consult each package for its complete license text.
+
+- @modelcontextprotocol/client@2.0.0: license metadata = MIT (installed by npm beside this package)
+- @modelcontextprotocol/core@2.0.0: license metadata = MIT (installed by npm beside this package)
+- @modelcontextprotocol/ext-apps@1.7.5: license metadata = MIT (installed by npm beside this package)
+- @napi-rs/keyring@1.3.0: license metadata = MIT (installed by npm beside this package)
+- ajv@8.20.0: license metadata = MIT (installed by npm beside this package)
+- ajv-formats@3.0.1: license metadata = MIT (installed by npm beside this package)
+- cross-spawn@7.0.6: license metadata = MIT (installed by npm beside this package)
+- minimatch@10.2.6: license metadata = BlueOak-1.0.0 (installed by npm beside this package)
+- model-probe@0.6.0: license metadata = MIT (installed by npm beside this package)
+- open@10.2.0: license metadata = MIT (installed by npm beside this package)
+- pi-mcp-adapter@2.31.0: license metadata = MIT (installed by npm beside this package)
+- pi-subagents@0.62.0: license metadata = MIT (installed by npm beside this package)
+- recheck@4.5.0: license metadata = MIT (installed by npm beside this package)
+- semver@7.8.5: license metadata = ISC (installed by npm beside this package)
+- smol-toml@1.9.0: license metadata = BSD-3-Clause (installed by npm beside this package)
+- strip-json-comments@5.0.3: license metadata = MIT (installed by npm beside this package)
+- yaml@2.9.0: license metadata = ISC (installed by npm beside this package)

package/agent-docs/README.md

@@ -0,0 +1,49 @@
+# 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.
+
+## Updates of the agent itself
+
+The terminal UI shows one line when a newer version is published; nothing updates on its own.
+The user updates with `explyt update` (a global npm install) and silences the check with
+`PI_OFFLINE=1`. Neither is a `.explyt/` setting.
+
+## 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/plugins.md

@@ -0,0 +1,40 @@
+# Marketplace plugins
+
+## Project activation
+
+Plugins are enabled per project in `.explyt/plugins.json`. Commit the exact plugin version and each MCP server's zero-based `runModes` index; do not put credentials or filesystem paths in this file.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "plugins": {
+    "security-pack": {
+      "version": "1.3.1",
+      "runModes": { "Github MCP": 1 }
+    }
+  }
+}
+```
+
+## Plugin commands
+
+Use `/plugin install`, `/plugin uninstall`, `/plugin update`, `/plugin enable`, `/plugin disable`, `/plugin list`, `/plugin details`, `/plugin verify`, `/plugin config set`, and `/plugin config set-run-mode` in the terminal. Plugin activation requires an installed exact version. When enabling a plugin is not a no-op, provide an explicit run-mode choice for every declared MCP server; an existing selection for the same exact version in the current project may be reused.
+
+## Values and credentials
+
+Credentials and other plugin values stay in the local plugin store, not in the project manifest. Configure them with:
+
+```text
+/plugin config set <plugin-id>@<version> <values-file>
+/plugin config set <plugin-id>@<version> --project <values-file>
+```
+
+The first command patches global values; the second patches values for the current project. A project value overrides the global value for that project. The values file for `config set` contains a `values` object and may contain an `unset` array; omitted keys are preserved.
+
+To remove an installed version, use `/plugin uninstall <plugin-id>[@<version>]`. Removing the last installed version also removes that plugin's stored values and per-version `${PLUGIN_DATA}` directories. To change one MCP server's selection for an enabled version, use:
+
+```text
+/plugin config set-run-mode <plugin-id>@<version> <server-name> <index>
+```

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,67 @@
+# 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` |
+| `sessionTitle.enabled` | boolean | `true` | whether a new chat gets a short title generated by the model after its first turn succeeds |
+| `tui.mascot` | string | `"cat"` | the animated mascot in the terminal's working row: `cat`, `snake`, `pacman`, `tetris`, `fishing`, `robot`, `pong` or `crab` |
+
+The two list settings take exact, case-sensitive entries. Neither supports globs or prefixes:
+`"pdf-*"` matches nothing. An entry matching nothing is kept, not an error.
+
+Both lists 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.
+
+`sessionTitle.enabled` is different: it is read from the **global** layer only. A value in a
+project's `.explyt/settings.json` is ignored, so write it to `~/.explyt/settings.json`. `false`
+turns generation off everywhere; the chat then keeps the truncated first prompt as its title. A
+name the user sets with `/name` is never replaced either way.
+
+`tui.mascot` is also read from the **global** layer only; write it to `~/.explyt/settings.json`.
+The value is one of the eight ids above, lowercase and exact. Any other value, or a value that is
+not a string, shows the cat. The terminal command `/mascot` writes this key and switches the
+mascot at once; a hand edit applies from the next session. It has no effect in an IDE, which has no
+working row.
+
+## 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.