zidane 7.0.15 → 7.0.17

package/docs/PLUGINS.md

@@ -22,6 +22,8 @@ if (plugin.ok) {
 
 Agent Plugins deliberately does **not** redefine either component format — skills are Agent Skills, MCP config is MCP config. So `zidane/plugins` owns only the packaging contract and hands back plain `SkillConfig[]` / `McpServerConfig[]` that every other zidane surface already consumes.
 
+Contents: [Why a separate loader](#why-a-separate-loader) · [Discovery](#discovery) · [Loading a plugin](#loading-a-plugin) · [`plugin.json`](#pluginjson) · [`skills/`](#skills) · [`mcp.json`](#mcpjson) · [The package boundary](#the-package-boundary) · [Results and diagnostics](#results-and-diagnostics) · [Naming and collisions](#naming-and-collisions) · [Settings](#settings) · [Conformance](#conformance)
+
 ## Why a separate loader
 
 zidane already reads both component types, but both existing readers are deliberately *lenient*: `discoverSkills` recurses into nested category directories, and `normalizeMcpServers` infers a transport from the presence of `command` / `url` and accepts `httpUrl` / `sseUrl` / `type: "http"` aliases. That leniency is correct for a file the user wrote, and wrong for a third-party package — guessing on behalf of a stranger's `mcp.json` is how you spawn a command the author never wrote.

package/docs/README.md

@@ -0,0 +1,57 @@
+# Zidane docs
+
+Each topic has exactly one owner doc; the others link to it. If two docs seem to explain the same thing, the one in the table below wins.
+
+## Index
+
+| Area | Doc | Owns |
+|---|---|---|
+| Core SDK | [SKILL.md](./SKILL.md) | `createAgent` options, providers, **the hooks table**, `ToolDef`, sessions API, skills, MCP, `spawn`. Also loaded as a skill (keep its frontmatter). |
+| Core SDK | [ARCHITECTURE.md](./ARCHITECTURE.md) | Loop internals: run lifecycle, turn/tool flow diagrams, hook firing order, tool-gate mutations, built-in tool defaults, cache-stable configuration, budgets. |
+| Core SDK | [EXECUTION_CONTEXT.md](./EXECUTION_CONTEXT.md) | `process` / `docker` / `e2b` / `daytona` contexts: capabilities, flags, isolation. |
+| Core SDK | [RUN_IN_BACKGROUND.md](./RUN_IN_BACKGROUND.md) | Background shell tasks end to end: tools, notifications, caps, teardown, subagent reassignment, replay. |
+| Core SDK | [INTERACTIONS.md](./INTERACTIONS.md) | `present_plan` / `ask_user`: tool contract, host wiring, TUI wizard. |
+| Core SDK | [HEADLESS.md](./HEADLESS.md) | `runHeadless()` + CLI: result shape, exit codes, output formats. |
+| Chat + surfaces | [CHAT.md](./CHAT.md) | `zidane/chat`: `resolveConfig`, session store + metadata, settings, safe mode, per-edit approval, todos, built-in commands, completion providers, theme, OAuth. |
+| Chat + surfaces | [TUI.md](./TUI.md) | `zidane/tui`: screens, **keybindings table**, modals, transcript rendering, code highlighting, embedding, file layout. |
+| Chat + surfaces | [IPC.md](./IPC.md) | `zidane/ipc`: daemon lifecycle, **every RPC and signal**, multi-window convergence, TUI/GUI parity matrix, `zidane attach`. |
+| Chat + surfaces | [ARTIFACTS.md](./ARTIFACTS.md) | Session artifacts: model, producers, storage, extension kinds, surfaces, RPCs, lazy refresh. |
+| Chat + surfaces | [EXTENSIONS.md](./EXTENSIONS.md) | Extensions: `defineExtension`, **the full `ctx` API**, discovery, install, collisions, settings UI, authoring patterns. |
+| Integrations | [PLUGINS.md](./PLUGINS.md) | Agent Plugins 1.0.0 loader: manifest, validation, filesystem boundary. |
+| Integrations | [ACP.md](./ACP.md) | Agent Client Protocol adapter: `zidane-acp`, editor config, stdio framing. |
+| Integrations | [RESTATE.md](./RESTATE.md) | Durable execution: the four wrappers, journal/replay semantics, strictness flags, demo runner. |
+
+## Where does X live
+
+| Looking for… | Go to |
+|---|---|
+| A hook name, its payload, or firing order | SKILL.md § Hooks (table) · ARCHITECTURE.md § Hook firing order (sequence) |
+| `AgentBehavior` / budget / retry / cache options | SKILL.md (options) · ARCHITECTURE.md § Cache-stable configuration (economics) |
+| Built-in tool names and output caps | ARCHITECTURE.md § Built-in tools |
+| Writing a custom tool or preset | SKILL.md § Tools / Presets |
+| Session persistence, `SessionStore` backends, sqlite schema | CHAT.md § Sessions |
+| Artifacts (PRs, files a session produced) | ARTIFACTS.md |
+| Settings keys and defaults | CHAT.md § Settings |
+| Safe mode, approvals, per-edit approval | CHAT.md § Safe mode / Per-edit approval |
+| Todos (`todowrite`) contract | CHAT.md § Todos |
+| Slash commands (`/help`, `/reload`, extension commands) | CHAT.md § Commands (runtime) · EXTENSIONS.md (authoring) |
+| `@` `/` `#` `!` completion | CHAT.md § Completion |
+| Keybindings and rebinding | TUI.md § Keyboard |
+| A modal or screen | TUI.md § Modals / Screens |
+| Daemon, `zidane attach`, RPC list, signals | IPC.md |
+| What differs between TUI and GUI | IPC.md § Parity |
+| `ctx.*` in an extension | EXTENSIONS.md § The ctx surface |
+| Background shell (`run_in_background`, `wait_task`, `shell_kill`) | RUN_IN_BACKGROUND.md |
+| `--context docker` / `e2b` / `daytona` | EXECUTION_CONTEXT.md |
+| `present_plan` / `ask_user` | INTERACTIONS.md |
+| Non-interactive runs, RL rollouts | HEADLESS.md |
+| Zed / editor integration | ACP.md |
+| Restate wrappers and replay | RESTATE.md |
+| Agent Plugins packages | PLUGINS.md |
+
+## Conventions
+
+- Lead with what / when / entry point; `Contents:` line for anything over ~150 lines.
+- Contracts as tables, behavior as bullets, rationale in one sentence only when a reader would otherwise do the wrong thing. No history.
+- Every path, symbol, flag, and default is verified against `src/` when written. Unverified claims carry a `<!-- VERIFY -->` comment; none should ship.
+- Cross-reference by `See [X.md § Heading](./X.md#anchor)`; never re-explain another doc's topic.