feat+docs: settings JSON schema + image input + migration guide

docs/MIGRATION_FROM_CLAUDE_CODE.md

@@ -0,0 +1,163 @@
+# Migrating from Claude Code
+
+DeepCode targets Claude Code parity. If you already use Claude Code,
+most of your workflow ports over with renames + a different API key.
+
+## TL;DR — the 5-minute switch
+
+```bash
+# 1. Install DeepCode CLI
+npm install -g deepcode-cli
+
+# 2. Set your DeepSeek key
+mkdir -p ~/.deepcode
+cat > ~/.deepcode/credentials.json <<EOF
+{ "apiKey": "sk-..." }
+EOF
+chmod 600 ~/.deepcode/credentials.json
+
+# 3. Convert your existing CLAUDE.md → AGENTS.md
+mv ~/CLAUDE.md ~/AGENTS.md  # global one
+# Project-scoped:
+mv <project>/CLAUDE.md <project>/AGENTS.md  # if you have one
+
+# 4. Convert ~/.claude/ → ~/.deepcode/
+mv ~/.claude/settings.json ~/.deepcode/settings.json
+mv ~/.claude/skills ~/.deepcode/skills
+mv ~/.claude/agents ~/.deepcode/agents
+mv ~/.claude/plugins ~/.deepcode/plugins
+mv ~/.claude/keybindings.json ~/.deepcode/keybindings.json
+
+# 5. Run
+deepcode
+```
+
+## Field-by-field mapping
+
+| Claude Code                          | DeepCode                                  | Notes |
+| ------------------------------------ | ----------------------------------------- | ----- |
+| `~/.claude/credentials.json`         | `~/.deepcode/credentials.json`            | Same shape; just rename. |
+| `~/.claude/settings.json`            | `~/.deepcode/settings.json`               | Schema mostly identical; see Settings table below. |
+| `<proj>/.claude/settings.json`       | `<proj>/.deepcode/settings.json`          | Same. |
+| `~/.claude/skills/<name>/SKILL.md`   | `~/.deepcode/skills/<name>/SKILL.md`      | Same frontmatter format. |
+| `~/.claude/agents/*.md`              | `~/.deepcode/agents/*.md`                 | Same shape. |
+| `~/.claude/plugins/`                 | `~/.deepcode/plugins/`                    | Plugin manifest is identical (plugin.json). |
+| `CLAUDE.md` (project root)           | `AGENTS.md` (project root)                | Or `DEEPCODE.md`. Both names recognized; AGENTS.md preferred. |
+| `claude` CLI                         | `deepcode` CLI                            | Most flags identical (-p, --mode, --model, --effort). |
+| `claude doctor`                      | `deepcode doctor`                         | Same. |
+| `/login`                             | n/a — re-onboard via `deepcode` no-args   | We don't have separate login state. |
+
+## Settings.json — model field
+
+Claude Code:
+```json
+{ "model": "claude-sonnet-4-5" }
+```
+
+DeepCode:
+```json
+{ "model": "deepseek-chat" }
+```
+
+Valid values: `deepseek-chat` (general/tool-use) · `deepseek-reasoner`
+(multi-step reasoning) · `deepseek-v4-flash` · `deepseek-v4-pro`.
+
+## Slash commands
+
+Most commands are identical:
+
+| Command            | Claude Code | DeepCode |
+| ------------------ | ----------- | -------- |
+| `/help`, `/?`      | ✓           | ✓        |
+| `/clear`           | ✓           | ✓        |
+| `/exit`, `/quit`   | ✓           | ✓        |
+| `/model`           | ✓           | ✓ (constrained to DeepSeek) |
+| `/mode`            | ✓           | ✓        |
+| `/effort`          | ✓           | ✓        |
+| `/cost`            | ✓           | ✓        |
+| `/context`         | ✓           | ✓        |
+| `/init`            | ✓           | ✓        |
+| `/mcp`             | ✓           | ✓        |
+| `/todos`           | ✓           | ✓        |
+| `/plugins`         | ✓           | ✓        |
+| `/keybindings`     | ✓           | ✓        |
+| `/vim`             | ✓           | ✓        |
+
+See `docs/BEHAVIOR_PARITY.md` for the full comparison.
+
+## Hooks
+
+Identical schema. Copy your `hooks` block from Claude's settings.json
+verbatim. DeepCode supports the same 10 event types (PreToolUse,
+PostToolUse, Stop, SubagentStop, PreCompact, PostCompact, SessionStart,
+SessionEnd, UserPromptSubmit, Notification) and the same 5 handler
+types (command, http, mcp_tool, prompt, agent).
+
+## Permission rules
+
+Identical syntax: `Tool(spec)`. The 4 sub-syntaxes (bare, subcommand,
+prefix, domain) work the same way:
+
+```jsonc
+{
+  "permissions": {
+    "deny":  ["Bash(rm -rf /:*)", "WebFetch(domain:internal.corp)"],
+    "ask":   ["Bash(npm install:*)"],
+    "allow": ["Read", "Bash(git diff:*)"]
+  }
+}
+```
+
+## Sandbox
+
+Claude Code's sandbox subsystem maps directly. `sandbox.filesystem`,
+`sandbox.network`, `sandbox.excludedCommands` all work identically.
+**Difference**: DeepCode's M3.5-ext adds shell-pipeline analysis — a
+pipeline like `git status && rm -rf /` will NOT bypass `excludedCommands`
+even if `git` is excluded. (Claude Code allows the bypass.) See
+`docs/security-model.md`.
+
+## Plugins
+
+Plugin manifest schema is identical. Plugins authored for Claude Code
+should load in DeepCode unmodified. The trust ladder + hash pin work
+the same way. **Difference**: DeepCode's M5.2 ships marketplace +
+ed25519 signature verification; if you want that, sign your plugins.
+
+## MCP servers
+
+Identical. Copy your `mcpServers` block verbatim. DeepCode uses
+`@modelcontextprotocol/sdk` so all standard stdio/http/sse MCP servers
+work as-is.
+
+## Sub-agents
+
+`~/.deepcode/agents/<name>.md` — same frontmatter shape as Claude Code's
+sub-agents. Both reference systems work.
+
+## Behaviors that DIFFER
+
+1. **Models**: only DeepSeek models. The `/model` picker constrains to
+   `deepseek-*`. To use Claude/GPT, keep Claude Code (or use the LSP
+   bridge once IDE-provider-routing lands — TBD).
+2. **Pricing**: DeepSeek is 10-20× cheaper than Claude for similar
+   token counts. `/cost` reflects DeepSeek pricing.
+3. **No image input yet**: vision provider abstraction exists but no
+   provider configured (v1.1).
+4. **`/rewind`**: skeleton only — full rewind UX is in M7 (Mac client).
+
+## Behaviors that are NEW in DeepCode
+
+- `auto` classifier mode (LLM-judged per-tool-call approval)
+- Effort-bench (`packages/core/scripts/effort-bench.ts`) for measuring
+  cost/latency per tier
+- Pipeline-aware sandbox bypass (vs Claude Code's leading-token-only)
+- LSP bridge (Neovim / Emacs / Sublime via `deepcode-lsp`)
+- VS Code extension (skeleton; ships in v1.1)
+
+## Getting help
+
+- `deepcode doctor` — diagnostic dump
+- `deepcode --help` — flag reference
+- `~/.deepcode/sessions/<id>.jsonl` — transcript of every session
+- File issues at https://github.com/oratis/deepcode/issues

packages/core/package.json

@@ -16,6 +16,7 @@
   "files": [
     "dist/",
     "skills/",
+    "schemas/",
     "README.md"
   ],
   "scripts": {

packages/core/schemas/settings.schema.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://deepcode.dev/schemas/settings.schema.json",
+  "title": "DeepCode settings.json",
+  "description": "Per-user/project/local config. Three precedence layers: user (~/.deepcode/settings.json) < project (.deepcode/settings.json) < local (.deepcode/settings.local.json, gitignored).",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "model": {
+      "type": "string",
+      "enum": ["deepseek-chat", "deepseek-reasoner", "deepseek-v4-flash", "deepseek-v4-pro"],
+      "description": "Default model. deepseek-chat = fast general; deepseek-reasoner = multi-step reasoning."
+    },
+    "baseURL": {
+      "type": "string",
+      "format": "uri",
+      "description": "DeepSeek API base URL. Default: https://api.deepseek.com/v1."
+    },
+    "apiKeyHelper": {
+      "type": "string",
+      "description": "Path to an executable that prints the API key on stdout. Overrides credentials.json."
+    },
+    "effortLevel": {
+      "type": "string",
+      "enum": ["low", "medium", "high", "xhigh", "max"],
+      "description": "Default effort tier — affects maxTokens + temperature + multi-turn budget."
+    },
+    "permissions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "defaultMode": {
+          "type": "string",
+          "enum": ["default", "acceptEdits", "plan", "auto", "dontAsk", "bypassPermissions"]
+        },
+        "allow": { "type": "array", "items": { "type": "string" } },
+        "ask": { "type": "array", "items": { "type": "string" } },
+        "deny": { "type": "array", "items": { "type": "string" } },
+        "additionalDirectories": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "autoMode": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allow": { "type": "array", "items": { "type": "string" } },
+        "soft_deny": { "type": "array", "items": { "type": "string" } },
+        "hard_deny": { "type": "array", "items": { "type": "string" } },
+        "model": { "type": "string" },
+        "fallback": { "type": "string", "enum": ["ask", "deny"] }
+      }
+    },
+    "sandbox": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "filesystem": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allowWrite": { "type": "array", "items": { "type": "string" } },
+            "denyWrite": { "type": "array", "items": { "type": "string" } },
+            "allowRead": { "type": "array", "items": { "type": "string" } },
+            "denyRead": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "network": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "allowedDomains": { "type": "array", "items": { "type": "string" } },
+            "deniedDomains": { "type": "array", "items": { "type": "string" } },
+            "allowUnixSockets": { "type": "boolean" },
+            "allowLocalBinding": { "type": "boolean" }
+          }
+        },
+        "excludedCommands": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Whole-pipeline command names that bypass sandbox (e.g. 'git')."
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "PreToolUse": { "$ref": "#/definitions/HookMatcherList" },
+        "PostToolUse": { "$ref": "#/definitions/HookMatcherList" },
+        "Stop": { "$ref": "#/definitions/HookMatcherList" },
+        "SubagentStop": { "$ref": "#/definitions/HookMatcherList" },
+        "PreCompact": { "$ref": "#/definitions/HookMatcherList" },
+        "PostCompact": { "$ref": "#/definitions/HookMatcherList" },
+        "SessionStart": { "$ref": "#/definitions/HookMatcherList" },
+        "SessionEnd": { "$ref": "#/definitions/HookMatcherList" },
+        "UserPromptSubmit": { "$ref": "#/definitions/HookMatcherList" },
+        "Notification": { "$ref": "#/definitions/HookMatcherList" }
+      }
+    },
+    "allowedHttpHookUrls": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri" },
+      "description": "Whitelist of URL prefixes that 'http' hook handlers may POST to."
+    },
+    "disableAllHooks": { "type": "boolean" },
+    "memoryLoadCapKB": { "type": "integer", "minimum": 1, "maximum": 10000 },
+    "outputStyle": { "type": "string" },
+    "skillOverrides": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "mcpServers": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/definitions/McpServer" }
+    },
+    "enabledMcpjsonServers": { "type": "array", "items": { "type": "string" } },
+    "disabledMcpjsonServers": { "type": "array", "items": { "type": "string" } },
+    "disabledPlugins": { "type": "array", "items": { "type": "string" } },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "baseRef": { "type": "string" },
+        "symlinkDirectories": { "type": "array", "items": { "type": "string" } },
+        "sparsePaths": { "type": "array", "items": { "type": "string" } },
+        "bgIsolation": { "type": "boolean" }
+      }
+    },
+    "voice": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "type": "string", "enum": ["whisper.cpp", "stub"] },
+        "binPath": { "type": "string" },
+        "modelPath": { "type": "string" }
+      }
+    }
+  },
+  "definitions": {
+    "HookMatcherList": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "matcher": { "type": "string" },
+          "hooks": {
+            "type": "array",
+            "items": { "$ref": "#/definitions/HookHandler" }
+          }
+        }
+      }
+    },
+    "HookHandler": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["command", "http", "mcp_tool", "prompt", "agent"]
+        },
+        "command": { "type": "string" },
+        "url": { "type": "string", "format": "uri" },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "server": { "type": "string" },
+        "tool": { "type": "string" },
+        "prompt": { "type": "string" },
+        "agent": { "type": "string" },
+        "timeout": { "type": "integer", "minimum": 1, "maximum": 3600 },
+        "if": { "type": "string", "description": "Permission-rule-syntax filter." }
+      },
+      "required": ["type"]
+    },
+    "McpServer": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "command": { "type": "string" },
+        "args": { "type": "array", "items": { "type": "string" } },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "url": { "type": "string", "format": "uri" },
+        "transport": { "type": "string", "enum": ["stdio", "http", "sse"] },
+        "headers": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "headersHelper": { "type": "string" },
+        "alwaysLoad": { "type": "boolean" }
+      }
+    }
+  }
+}