@prestyj/cli 5.30.0 → 5.30.2

package/README.md

@@ -1,7 +1,7 @@
 ![ezcoder](screenshots/ezcoder.png)
 
 <p align="center">
-  <strong>The fast, lean coding agent. Eight providers. Zero bloat.</strong>
+  <strong>The fast, lean coding agent. Twelve providers plus local models. Zero bloat.</strong>
 </p>
 
 <p align="center">
@@ -12,13 +12,13 @@
   <a href="https://github.com/Gahroot"><img src="https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="GitHub"></a>
 </p>
 
-A coding agent that ships only what the model needs to work — a tiny system prompt, one carefully-chosen MCP, and a focused tool set. Switch between Anthropic, OpenAI, GLM, Moonshot, MiniMax, Xiaomi, DeepSeek, and OpenRouter mid-conversation. Run it on its own, or let [`@prestyj/boss`](../ezboss/README.md) drive a fleet of `ezcoder` workers across many projects from a single chat.
+A coding agent that ships only what the model needs to work — a tiny system prompt, no bundled MCPs, and a focused tool set. Switch between Anthropic, OpenAI, Gemini, xAI, Moonshot, GLM, MiniMax, Xiaomi, DeepSeek, Sakana, OpenRouter, Hugging Face, and your own local models mid-conversation. Run it on its own, or let [`@prestyj/boss`](../ezboss/README.md) drive a fleet of `ezcoder` workers across many projects from a single chat.
 
 Built on [`@prestyj/ai`](../ai/README.md) and [`@prestyj/agent`](../agent/README.md). Part of the [EZCoder Framework](../../README.md) monorepo.
 
 ---
 
-## 🚀 Run It
+## Run It
 
 ```bash
 npm i -g @prestyj/cli
@@ -27,11 +27,11 @@ ezcoder login    # Pick provider, authenticate
 ezcoder          # Start coding
 ```
 
-OAuth for Anthropic and OpenAI (log in once, auto-refresh, no key to leak). API keys for the rest. Up and running in seconds either way. Auth lives in `~/.ezcoder/auth.json` and is shared with `ezboss`.
+OAuth for Anthropic, OpenAI, and Gemini; OAuth or an API key for xAI and Moonshot (log in once, auto-refresh, no key to leak). API keys for the rest. Up and running in seconds either way. Auth lives in `~/.ezcoder/auth.json` and is shared with `ezboss`.
 
 ---
 
-## 🪶 The system prompt problem
+## The system prompt problem
 
 Every token in the system prompt gets processed on **every single turn**. It's not a one-time cost. It's a tax on every request.
 
@@ -51,38 +51,43 @@ EZ Coder sends only what the model needs: how to work, what tools it has, and yo
 
 ---
 
-## 🧩 The MCP problem
+## The MCP problem
 
 Same philosophy applies to tools. People collect MCPs like Pokemon. Slack MCP, GitHub MCP, Notion MCP, five different file system MCPs. Every single one injects its tool descriptions into the context. The model now has to figure out which of 40+ tools to use for any given task.
 
 This doesn't help. It confuses the agent. More tool descriptions = more noise = worse tool selection. The model spends tokens reasoning about tools it will never call.
 
-EZ Coder ships with one MCP: [Grep](https://grep.dev). That's it. It lets the agent search across 1M+ public GitHub repos to verify implementations against real-world code. Correct API usage, library idioms, production patterns. One tool that actually makes the output better.
+EZ Coder ships with no MCPs by default. Checking work against real-world code is a native tool instead: `steroids` finds production repos similar to yours so the agent can confirm API usage, library idioms, and patterns. It loads only when the agent asks for it, so it costs nothing until it's used. (On GLM, the Z.AI MCP servers that come with your key are connected automatically.)
 
-You can still add your own MCPs if you need them. But start with less. You'll get better results.
+You can still add your own MCPs in `~/.ezcoder/mcp.json` or `.ezcoder/mcp.json`. But start with less. You'll get better results.
 
 ---
 
-## 🎛 Eight providers, one agent
+## Twelve providers, one agent
 
 Switch mid-conversation with `/model`. Not locked to anyone.
 
-
-| Provider          | Models                                                                       | Auth             |
-| ----------------- | ---------------------------------------------------------------------------- | ---------------- |
-| **Anthropic**     | Claude Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 4.5                             | OAuth            |
-| **OpenAI**        | GPT-6 Astra, GPT-6.1 Sol, GPT-6 Luna                                         | OAuth            |
-| **Moonshot**      | Kimi K3, Kimi K2.8 Preview, Kimi K2.7 Code                                    | OAuth or API key |
-| **Z.AI (GLM)**    | GLM-5.3, GLM-5.3-Flash (image)                                               | API key          |
-| **MiniMax**       | MiniMax M3 (image + video)                                                   | API key          |
-| **Xiaomi (MiMo)** | MiMo-V2.6-Pro + V2.6-Flash (image + video), V2.6-Pro-UltraSpeed              | API key          |
-| **DeepSeek**      | DeepSeek V4 Pro, V4.1 Flash (image)                                          | API key          |
-| **Sakana (Fugu)** | Fugu, Fugu Max, Fugu Ultra (image)                                           | API key          |
-| **OpenRouter**    | Qwen3.8 Max (image + video) + multi-provider gateway                        | API key          |
+| Provider          | Models                                                                                      | Auth             |
+| ----------------- | ------------------------------------------------------------------------------------------- | ---------------- |
+| **Anthropic**     | Claude Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5                                           | OAuth            |
+| **OpenAI**        | GPT-6 Astra, GPT-6.1 Sol, GPT-6 Luna                                                        | OAuth            |
+| **Gemini**        | Gemini 3.1 Pro (Preview), 3.8 Flash, 3.7 Flash, 3.5 Flash, 3.5 Flash Lite, 3.1 Flash Lite   | OAuth            |
+| **xAI (Grok)**    | Grok 4.7                                                                                    | OAuth or API key |
+| **Moonshot**      | Kimi K3, K2.8 Preview (Kimi sign-in), K2.7 Code, K2.7 Code HighSpeed                        | OAuth or API key |
+| **Z.AI (GLM)**    | GLM-5.3, GLM-5.3-Flash                                                                      | API key          |
+| **MiniMax**       | MiniMax M3                                                                                  | API key          |
+| **Xiaomi (MiMo)** | MiMo-V2.6-Pro, MiMo-V2.6-Flash, MiMo-V2.6-Pro-UltraSpeed                                    | API key          |
+| **DeepSeek**      | DeepSeek V4 Pro, V4.1 Flash                                                                 | API key          |
+| **Sakana (Fugu)** | Fugu, Fugu Max, Fugu Ultra                                                                  | API key          |
+| **OpenRouter**    | Qwen3.8 Max                                                                                 | API key          |
+| **Hugging Face**  | Kimi K2.7 Code, DeepSeek V4.1 Flash, GPT-OSS 120B (Inference Providers router)              | API key          |
+| **Local**         | Any model on an OpenAI-compatible server: Ollama, LM Studio, llama.cpp, vLLM                | None             |
+
+Every hosted model above except GLM-5.3, DeepSeek V4 Pro, and GPT-OSS 120B accepts images.
 
 The same conversation, the same tools, the same project context — only the model changes. Use a strong reasoning model when you need it, swap to a fast cheap one for grunt work, never restart your session.
 
-**Attachments.** Drag, paste, or type a path to attach images and video in the chat input. Video is sent natively to models that support it (Gemini 3.x, Kimi K3/K2.8 Preview/K2.7 Code, MiniMax M3, MiMo-V2.6, Qwen3.8 Max); for other models the video is saved to a temp file and the model is told to inspect it with ffmpeg or its own tools.
+**Attachments.** Drag, paste, or type a path to attach images and video in the chat input. Video is sent natively to models that support it (Gemini 3.x, every Moonshot Kimi model, MiniMax M3, MiMo-V2.6, Qwen3.8 Max); for other models the video is saved to a temp file and the model is told to inspect it with ffmpeg or its own tools.
 
 ---
 
@@ -118,7 +123,7 @@ Run `ezcoder` directly when you're heads-down on one project. Switch to `ezboss`
 
 ---
 
-## 💬 Slash commands
+## Slash commands
 
 Everything runs through slash commands inside the session. Not CLI flags.
 
@@ -131,7 +136,8 @@ Everything runs through slash commands inside the session. Not CLI flags.
 | `/branch` (`/b`)        | Branch the current conversation                            |
 | `/branches`             | List branches of the current session                       |
 | `/rewind`               | Restore files and/or conversation to an earlier checkpoint |
-| `/buddy`                | Spin up a second model to review the current chat          |
+| `/add-dir`              | Add another project folder to this workspace               |
+| `/remove-dir`           | Remove an added project folder from this workspace         |
 | `/settings` (`/config`) | Open settings                                              |
 | `/help` (`/h`, `/?`)    | Show all commands                                          |
 | `/quit` (`/q`, `/exit`) | Exit                                                       |
@@ -142,28 +148,37 @@ Plus built-in workflows that ship with the binary:
 /expand        # Compare against current alternatives and report gaps
 /raise-floor   # Audit existing features and make them just work
 /bullet-proof  # Run a defensive security review
-/init          # Generate CLAUDE.md for your project
+/init          # Generate or update AGENTS.md / CLAUDE.md for your project
 /setup-commit  # Generate a /commit command with quality checks
+/setup-ci      # Set up or harden CI for any stack
 /setup-skills  # Audit and recommend reusable skills
+/compare       # Compare your code against real-world code
+/steroids      # Index real repos like this project
 ```
 
 ---
 
-## 🛠 Tools
+## Tools
 
-EZ Coder comes with a focused set of tools. Each one is small, well-described, and earns its place in the prompt.
+EZ Coder comes with a focused set of tools. Only six core tools — `read`, `write`, `edit`, `bash`, `grep`, and `skill` — plus `tool_search` send their full schemas on every request. Everything else is listed as a one-line hint and loads the first time the agent needs it, so rarely used tools cost almost nothing.
 
 | Tool                              | What it does                                                                                           |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `bash`                            | Run shell commands                                                                                     |
+| `bash`                            | Run shell commands, in the foreground or background (`task_output` / `task_send` / `task_stop`)        |
 | `read`                            | Read file contents                                                                                     |
 | `write`                           | Write files                                                                                            |
 | `edit`                            | Surgical string replacements                                                                           |
 | `grep`                            | Search file contents (regex)                                                                           |
-| `find`                            | Find files by glob pattern                                                                             |
-| `ls`                              | List directory contents                                                                                |
-| `web_fetch`                       | Fetch URL content                                                                                      |
+| `skill`                           | Load a skill's instructions                                                                            |
+| `tool_search`                     | Load an on-demand tool by capability                                                                   |
+| `find` / `ls`                     | Find files by glob pattern / list a directory                                                          |
+| `code_search` / `code_nav`        | Find code by meaning / jump to exact definitions and callers                                           |
+| `web_fetch` / `web_search`        | Fetch a URL / search the web                                                                           |
+| `steroids`                        | Find real production repos similar to yours and read how they do it                                    |
+| `source_path`                     | Locate an installed dependency's source                                                                |
 | `screenshot`                      | Open a URL / dev server in a headless browser and capture a PNG so the agent can see the rendered page |
+| `debug`                           | Drive the Node debugger                                                                                |
+| `enter_plan` / `exit_plan`        | Plan before editing, then hand the plan back for approval                                              |
 | `subagent`                        | Run one blocking, isolated child task (backward-compatible)                                            |
 | `spawn_agent` / `wait_agent`      | Launch persistent child turns concurrently and collect results                                         |
 | `send_message` / `followup_task`  | Steer a running child or reuse an idle child's context                                                 |
@@ -171,7 +186,7 @@ EZ Coder comes with a focused set of tools. Each one is small, well-described, a
 
 The `screenshot` tool needs the optional `playwright` dependency plus a one-time `npx playwright install chromium`. Without it the tool returns an install hint instead of failing the turn. Captured images render inline in graphics-capable terminals (kitty, Ghostty, WezTerm, iTerm2); other terminals show a text line.
 
-Plus the [Grep MCP](https://grep.dev) for searching across 1M+ public GitHub repos. Add your own MCPs in settings if you need more — but start lean.
+Add your own MCPs in `~/.ezcoder/mcp.json` or `.ezcoder/mcp.json` if you need more — but start lean.
 
 ### Async subagent lifecycle
 
@@ -185,13 +200,13 @@ Parent cancellation interrupts active children. Session disposal shuts down ever
 
 ---
 
-## 🪄 Custom commands
+## Custom commands
 
 Drop a markdown file in `.ezcoder/commands/` and it becomes a slash command. Your React app gets `/deploy` and `/storybook`. Your API gets `/migrate` and `/seed`. Different projects, different commands.
 
 ---
 
-## ⏪ Checkpoints & `/rewind`
+## Checkpoints & `/rewind`
 
 Before every file the agent writes or edits, EZ Coder snapshots the prior on-disk content into a per-session checkpoint (stored under `~/.ezcoder/checkpoints/`, never in your repo). Run `/rewind` to pick an earlier checkpoint and restore **code only**, **conversation only**, or **both**.
 
@@ -199,7 +214,7 @@ Only edits made through ezcoder's `write`/`edit` tools are tracked — changes m
 
 ---
 
-## 🎒 Skills
+## Skills
 
 Reusable behaviors across projects. Drop `.md` files in:
 
@@ -226,22 +241,22 @@ Eleven ship built in, and route themselves when the work matches:
 
 ---
 
-## 📋 Project guidelines
+## Project guidelines
 
-Drop a `CLAUDE.md` or `AGENTS.md` in your repo root (or any parent directory). EZ Coder picks it up automatically.
+Drop an `AGENTS.md` or `CLAUDE.md` in your repo root (or any parent directory). EZ Coder picks it up automatically. One file per directory is loaded, first match wins: `AGENTS.override.md` > `AGENTS.md` > `CLAUDE.md` > `.cursorrules` > `CONVENTIONS.md`.
 
 Your rules. Your conventions. The agent follows them.
 
 ---
 
-## 👥 Community
+## Community
 
 - [Prestyj website](https://prestyj.com) — tutorials and updates
 - [GitHub @Gahroot](https://github.com/Gahroot)
 
 ---
 
-## 📄 License
+## License
 
 MIT
 

package/assets/skills/bulletproof/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bulletproof
-description: Use when writing or reviewing code an attacker can reach — auth, sessions, tokens, crypto; untrusted input (requests, files, archives, repo content, model/tool output); secrets; per-user or multi-tenant data access (incl. Supabase/Firebase RLS); dependencies, install scripts, CI/CD, publishing, signing, updates; shelling out, deserialization, dynamic loading; LLM/agent/MCP tools; and pre-ship "can this be hacked" reviews, hardening, or suspected compromise. Fires mid-build on adding a login, upload, webhook, dependency, or tool. Do NOT use for local CLIs/libraries/scripts with no auth, network, secrets or multi-user data, styling/copy/docs, or legal/privacy questions (compliance-guard).
+description: "Use for attacker-reachable code: auth, tokens, crypto, untrusted input, secrets, tenant data, CI, agent tools. Do NOT use for local scripts without auth or network."
 license: Apache-2.0. Content is defensive engineering guidance, not a security certification or a penetration test. See references/provenance.md.
 compatibility: Works offline from the bundled references, which are a snapshot dated 3 October 2026. Version numbers, CVEs, and incident details decay fast; re-verify date-sensitive claims with web access before stating them as current. Never certifies that software is secure.
 ---

package/assets/skills/clarify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clarify
-description: Use when requirements or a design are genuinely unsettled — the user asks to interrogate, sharpen, or stress-test a plan or spec before building, a new app or feature request leaves costly-to-reverse product decisions open, or mid-build discovery hits a decision that materially changes the result (scope, data model, UX, tradeoff). Settled terms and hard-to-reverse calls hand off to shared-language. Do NOT use for routine changes, clear bug reports (root-cause), reviewing finished work (code-review), or work whose requirements are already settled — bias to action there.
+description: Use when requirements are genuinely unsettled. Do NOT use for routine work.
 ---
 
 # Clarify

package/assets/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Use when the user asks to review written work — a diff, PR, branch, commit range, or agent-generated change — or says "review before merge", "is this really done?", "check what the agent did". Checks spec compliance and build quality separately, verifies PR/"done" claims against the diff, and reports file:line findings by severity. Do NOT use while still mid-build (finish and run checks instead), for a plain diff summary, or for security review (bulletproof), performance (lean), migrations/data loss (durable), or UI review (evidence-led-ui).
+description: Use when asked to review a diff, PR or finished work. Do NOT use mid-build.
 ---
 
 # Code Review

package/assets/skills/compliance-guard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compliance-guard
-description: Use when shipping something real users reach and the work carries legal exposure — pre-launch or "is this safe to ship" reviews; mid-build features adding personal data, pixels/cookies, payments or auto-renewal, uploads/UGC, email/SMS/push, AI chatbots, minors, biometrics, scraping; drafting privacy policies, terms, disclosures. Also when a feature may need a licence or be illegal: health, finance, money movement, crypto, gambling, adult content, background checks, automated hiring/lending/housing decisions. Do NOT use for local-only scripts, prototypes with no real users or data, or changes touching no data, money, users or public surface; security hardening is bulletproof's lane.
+description: Use when shipping to real users risks legal exposure (personal data, payments, minors). Do NOT use for local work.
 license: Apache-2.0. Content is engineering guidance, not legal advice. See references/provenance.md.
 compatibility: Static review works offline from the bundled references. Legal status changes constantly; date-sensitive claims must be re-verified with web access before being stated as current. Never certifies compliance.
 ---

package/assets/skills/durable/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: durable
-description: Use when user data must not be lost or corrupted — creating the first table/schema, writing or running migrations, backfills/imports, any destructive op (delete, drop, truncate, reset, overwrite), before the agent itself runs a command against a database that may hold real data, setting up backups/recovery, or moving data between systems; plus "is my data safe / back up my app" checks. Any store — SQL, document, serverless, files, queues. Do NOT use for query speed or pool sizing (that is lean), access control over data (that is bulletproof), or privacy/legal deletion regimes (that is compliance-guard).
+description: "Use when data could be lost: migrations, destructive ops, real databases. Do NOT use for query speed."
 license: Data-durability engineering guidance, not a DBA certification. Sources and snapshot date are recorded at the foot of each reference file.
 compatibility: Snapshot dated 3 October 2026. Version behaviours, provider retention defaults and tool flags decay — re-verify with web access before asserting them as current.
 ---

package/assets/skills/evidence-led-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: evidence-led-ui
-description: Use when building or changing web/mobile UI: net-new screens or pages, redesigns, design systems, visual polish, UI review, and mid-build edits touching colour, type, spacing, icons, focus/hover/selected states, borders, dropdown icons, motion, or UI copy layout. Also use when output looks generic or AI-made. Small styling fixes take the small-edit path. Do NOT use for behavior-only wiring with no visual state, copy-only text changes, database/API schemas, CLI output, or standalone image generation; speed/bundle work is lean, legal/privacy review of public pages is compliance-guard.
+description: Use when building or reviewing UI visuals. Do NOT use for behaviour-only changes.
 license: See LICENSES.md
 compatibility: Full review requires filesystem inspection and rendered screenshots (deferred `screenshot` tool); web research and device tooling are optional and unavailable checks must be reported as unverified.
 ---

package/assets/skills/lean/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lean
-description: Use when speed or resource use matters — while writing features that load, render lists, fetch, poll, spawn processes or cache (inline gate); on "slow / laggy / eating RAM / fans spinning", leaks, zombie or orphan processes, bundle bloat, dead code, Core Web Vitals; for a performance pass or pre-ship "will this run smoothly" check. Any stack — web, backend/API/CLI, desktop (Electron, Tauri), mobile, native, game, ML. Do NOT use for correctness bugs where speed is not the complaint, copy/docs-only changes, design or visual polish (evidence-led-ui), data-loss or migration safety (durable), or when the user explicitly deprioritizes performance.
+description: Use when speed or resource use matters. Do NOT use for correctness bugs.
 license: Performance engineering guidance, not a benchmark certification. Sources and snapshot date are recorded at the foot of each reference file.
 compatibility: Snapshot dated 3 October 2026. Thresholds, tool names, and defaults decay — re-verify with web access before asserting them as current. Claims sourced to that date carry a SNAPSHOT marker.
 ---

package/assets/skills/refactoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactoring
-description: Use for behavior-preserving restructuring: extract, move, split, deduplicate, plan a refactor, or migrate an implementation behind an unchanged contract. Baseline tests, small steps, revert-on-red. Do NOT use for requested behavior or API-contract changes (including new return/error semantics), even when called a "refactor"; use the normal implementation workflow with regression tests and update affected callers together. Also exclude bug fixes (root-cause when stubborn), performance work (lean), data migrations (durable), styling/copy, TDD's refactor step (tdd), and rewrites.
+description: Use for behaviour-preserving restructuring behind an unchanged contract. Do NOT use for renames, bug fixes or behaviour changes.
 license: Behavior-preservation methodology synthesized from public sources (Fowler's Refactoring catalog, Tidy First?, and community agent skills by bienhoang, wondelai, mattpocock, jeffallan, vasilyu1983), audited 2026-09-12.
 ---
 

package/assets/skills/root-cause/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: root-cause
-description: Use when a bug resists the obvious fix, behaviour makes no sense, a symptom keeps coming back, a test is flaky, something "worked last week", or the user asks why something happens and the answer is not on the surface — including mid-build when a second fix attempt fails. Do NOT use for bugs with a clear repro and an obvious cause (reproduce, fix, re-run directly), security incident triage (bulletproof), or reviewing a diff (code-review).
+description: Use when a bug resists the obvious fix or is flaky. Do NOT use when the cause is obvious.
 ---
 
 # Root-Cause

package/assets/skills/shared-language/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shared-language
-description: Use when a project's domain vocabulary is fuzzy or drifting (two names for one thing, one name for two), naming decisions keep recurring, or a hard-to-reverse architectural decision needs recording so it is not re-litigated or re-suggested — including mid-build when a term settles or a change contradicts an ADR. Do NOT use for throwaway scripts, projects too small to have recurring vocabulary, interviewing for requirements (clarify), or renames with no vocabulary decision (refactoring).
+description: Use when domain terms drift or a decision needs an ADR. Do NOT use for renames.
 ---
 
 # Shared Language

package/assets/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Use when the user asks for test-driven development, red-green-refactor, "write the test first", or wants a feature or bug fix built test-first — including mid-build when they ask to switch to test-first. Do NOT use when tests are a verification step after the build, the project has no suite and the user has not asked for one, the change is throwaway probe code, or the goal is restructuring without behaviour change (refactoring) or finding an unknown cause (root-cause).
+description: Use when asked for test-first development. Do NOT use for post-build tests.
 ---
 
 # TDD

package/dist/app-sidecar/app-settings.d.ts

@@ -0,0 +1,63 @@
+import type { Provider, ThinkingLevel } from "@prestyj/ai";
+import type { NolanModelPref } from "../core/nolan-model.js";
+export declare const ALL_PROVIDERS: Provider[];
+/** Per-project model + thinking preferences. Persisted so each window (one
+ *  project cwd) restores its OWN model across app restarts — instead of every
+ *  window reading the same single global slot that the last writer clobbered. */
+export interface ProjectModelPrefs {
+    provider: Provider;
+    model: string;
+    thinkingEnabled?: boolean;
+    thinkingLevel?: ThinkingLevel;
+}
+export interface AppSettings {
+    /** Folder new projects are created inside. Defaults to ~/ez-projects. */
+    projectsRoot: string;
+    /** Model + thinking prefs keyed by normalized project cwd. A window restores
+     *  its own entry on boot; absent → global settings.json → provider default. */
+    projectModels?: Record<string, ProjectModelPrefs>;
+    /** Autopilot (auto-review) on/off keyed by normalized project cwd. Per-window
+     *  (one window = one cwd); absent/false → off. Restored on boot. */
+    autopilot?: Record<string, boolean>;
+    /** Nolan model override keyed by normalized project cwd. */
+    nolanModels?: Record<string, NolanModelPref>;
+    /** Extra folders scanned for projects alongside `projectsRoot`. */
+    projectRoots?: string[];
+    /** Project paths dismissed from the picker, as normalized cwds. */
+    hiddenProjects?: string[];
+}
+export declare function stringArray(value: unknown): string[] | undefined;
+export declare function appSettingsFile(): string;
+export declare function defaultProjectsRoot(): string;
+/** Normalize a project cwd to a stable settings key so trailing slashes /
+ *  relative segments collapse — the same project always maps to one entry. */
+export declare function projectModelKey(cwd: string): string;
+export declare function loadAppSettings(): Promise<AppSettings>;
+export declare function saveAppSettings(settings: AppSettings): Promise<void>;
+/** Read this project's persisted model/thinking prefs, if any. */
+export declare function loadProjectModelPrefs(cwd: string): Promise<ProjectModelPrefs | undefined>;
+/** Persist this project's model/thinking prefs via read-modify-write so the rest
+ *  of the settings file (projectsRoot, other projects' entries) is preserved. */
+export declare function saveProjectModelPrefs(cwd: string, prefs: ProjectModelPrefs): Promise<void>;
+/** Read this project's persisted Nolan model override, if any. */
+export declare function loadNolanModelPref(cwd: string): Promise<NolanModelPref | undefined>;
+/** Persist (or with null, clear) this project's Nolan model override via
+ *  read-modify-write so the rest of the settings file is preserved. */
+export declare function saveNolanModelPref(cwd: string, pref: NolanModelPref | null): Promise<void>;
+/** Read this project's persisted autopilot flag (default off). */
+export declare function loadAutopilot(cwd: string): Promise<boolean>;
+/** Persist this project's autopilot flag via read-modify-write so the rest of
+ *  the settings file (projectsRoot, model map, other projects) is preserved. */
+export declare function saveAutopilot(cwd: string, enabled: boolean): Promise<void>;
+/**
+ * Persist the active model selection to ~/.ezcoder/settings.json so it survives app
+ * restarts. Mirrors the CLI's handleModelSelect persistence (App.tsx).
+ */
+export declare function persistModelSelection(settingsFile: string, provider: Provider, model: string): Promise<void>;
+/**
+ * Persist the thinking level to ~/.ezcoder/settings.json so it survives app restarts.
+ * Mirrors the CLI's handleToggleThinking persistence (App.tsx).
+ */
+export declare function persistThinkingLevel(settingsFile: string, level: ThinkingLevel | undefined): Promise<void>;
+/** Validate a project folder name: lowercase letters, digits, dashes only. */
+export declare function isValidProjectName(name: string): boolean;

package/dist/app-sidecar/app-settings.js

@@ -0,0 +1,147 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SettingsManager } from "../core/settings-manager.js";
+import { log } from "../core/logger.js";
+export const ALL_PROVIDERS = [
+    // US
+    "anthropic",
+    "openai",
+    "gemini",
+    "xai",
+    // China
+    "moonshot",
+    "glm",
+    "minimax",
+    "xiaomi",
+    "deepseek",
+    // Open-community gateway, before the provider-agnostic one
+    "huggingface",
+    // Japan, then provider-agnostic gateway last
+    "sakana",
+    "openrouter",
+];
+export function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value.filter((v) => typeof v === "string" && v.trim().length > 0);
+    return out.length > 0 ? out : undefined;
+}
+export function appSettingsFile() {
+    return path.join(os.homedir(), ".ezcoder", "ezcoder-app.json");
+}
+export function defaultProjectsRoot() {
+    return path.join(os.homedir(), "ez-projects");
+}
+/** Normalize a project cwd to a stable settings key so trailing slashes /
+ *  relative segments collapse — the same project always maps to one entry. */
+export function projectModelKey(cwd) {
+    return path.resolve(cwd);
+}
+export async function loadAppSettings() {
+    try {
+        const raw = JSON.parse(await fs.readFile(appSettingsFile(), "utf-8"));
+        return {
+            projectsRoot: typeof raw.projectsRoot === "string" && raw.projectsRoot.trim()
+                ? raw.projectsRoot
+                : defaultProjectsRoot(),
+            // Preserve the per-project map verbatim (validated + written by the
+            // model/thinking handlers below).
+            projectModels: raw.projectModels && typeof raw.projectModels === "object" ? raw.projectModels : undefined,
+            autopilot: raw.autopilot && typeof raw.autopilot === "object" ? raw.autopilot : undefined,
+            nolanModels: raw.nolanModels && typeof raw.nolanModels === "object" ? raw.nolanModels : undefined,
+            projectRoots: stringArray(raw.projectRoots),
+            hiddenProjects: stringArray(raw.hiddenProjects),
+        };
+    }
+    catch {
+        return { projectsRoot: defaultProjectsRoot() };
+    }
+}
+export async function saveAppSettings(settings) {
+    await fs.mkdir(path.dirname(appSettingsFile()), { recursive: true });
+    await fs.writeFile(appSettingsFile(), JSON.stringify(settings, null, 2), "utf-8");
+}
+/** Read this project's persisted model/thinking prefs, if any. */
+export async function loadProjectModelPrefs(cwd) {
+    const s = await loadAppSettings();
+    return s.projectModels?.[projectModelKey(cwd)];
+}
+/** Persist this project's model/thinking prefs via read-modify-write so the rest
+ *  of the settings file (projectsRoot, other projects' entries) is preserved. */
+export async function saveProjectModelPrefs(cwd, prefs) {
+    const s = await loadAppSettings();
+    const key = projectModelKey(cwd);
+    s.projectModels = { ...(s.projectModels ?? {}), [key]: prefs };
+    await saveAppSettings(s);
+}
+/** Read this project's persisted Nolan model override, if any. */
+export async function loadNolanModelPref(cwd) {
+    const s = await loadAppSettings();
+    return s.nolanModels?.[projectModelKey(cwd)];
+}
+/** Persist (or with null, clear) this project's Nolan model override via
+ *  read-modify-write so the rest of the settings file is preserved. */
+export async function saveNolanModelPref(cwd, pref) {
+    const s = await loadAppSettings();
+    const key = projectModelKey(cwd);
+    const next = { ...(s.nolanModels ?? {}) };
+    if (pref)
+        next[key] = pref;
+    else
+        delete next[key];
+    s.nolanModels = next;
+    await saveAppSettings(s);
+}
+/** Read this project's persisted autopilot flag (default off). */
+export async function loadAutopilot(cwd) {
+    const s = await loadAppSettings();
+    return s.autopilot?.[projectModelKey(cwd)] ?? false;
+}
+/** Persist this project's autopilot flag via read-modify-write so the rest of
+ *  the settings file (projectsRoot, model map, other projects) is preserved. */
+export async function saveAutopilot(cwd, enabled) {
+    const s = await loadAppSettings();
+    const key = projectModelKey(cwd);
+    s.autopilot = { ...(s.autopilot ?? {}), [key]: enabled };
+    await saveAppSettings(s);
+}
+/**
+ * Persist the active model selection to ~/.ezcoder/settings.json so it survives app
+ * restarts. Mirrors the CLI's handleModelSelect persistence (App.tsx).
+ */
+export async function persistModelSelection(settingsFile, provider, model) {
+    try {
+        const sm = new SettingsManager(settingsFile);
+        await sm.load();
+        await sm.set("defaultProvider", provider);
+        await sm.set("defaultModel", model);
+    }
+    catch (err) {
+        log("WARN", "app-sidecar", "failed to persist model selection", { err: String(err) });
+    }
+}
+/**
+ * Persist the thinking level to ~/.ezcoder/settings.json so it survives app restarts.
+ * Mirrors the CLI's handleToggleThinking persistence (App.tsx).
+ */
+export async function persistThinkingLevel(settingsFile, level) {
+    try {
+        const sm = new SettingsManager(settingsFile);
+        await sm.load();
+        await sm.set("thinkingEnabled", !!level);
+        if (level)
+            await sm.set("thinkingLevel", level);
+    }
+    catch (err) {
+        log("WARN", "app-sidecar", "failed to persist thinking level", { err: String(err) });
+    }
+}
+/** Validate a project folder name: lowercase letters, digits, dashes only. */
+export function isValidProjectName(name) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+// ── History reconstruction types ──────────────────────────
+// Mirrors HistoryEntry in ezcoder-app/src/agent.ts — the wire shape the webview
+// receives from GET /history. Fields beyond role/text carry the transcript
+//# sourceMappingURL=app-settings.js.map

package/dist/app-sidecar/app-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-settings.js","sourceRoot":"","sources":["../../src/app-sidecar/app-settings.ts"],"names":[],"mappings":"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"}

package/dist/app-sidecar/attachments.d.ts

@@ -0,0 +1,11 @@
+export interface AppAttachment {
+    kind: "image" | "video" | "file";
+    name: string;
+    mediaType: string;
+    /** base64 (no data: prefix). */
+    data: string;
+}
+export interface PreparedAttachment extends AppAttachment {
+    path?: string;
+}
+export declare function prepareAttachments(cwd: string, attachments: AppAttachment[]): Promise<PreparedAttachment[]>;

package/dist/app-sidecar/attachments.js

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { shrinkToFit, validateVisionImage } from "../utils/image.js";
+export async function prepareAttachments(cwd, attachments) {
+    const dir = path.join(cwd, ".ezcoder", "uploads");
+    await fs.mkdir(dir, { recursive: true }).catch(() => { });
+    const out = [];
+    for (const a of attachments) {
+        // Sanitize the filename and prefix with a short timestamp to avoid clobber.
+        const safe = a.name.replace(/[^\w.-]+/g, "_").slice(-80) || "file";
+        const fileName = `${Date.now().toString(36)}-${safe}`;
+        const filePath = path.join(dir, fileName);
+        const buf = Buffer.from(a.data, "base64");
+        // Validate and cap image attachments before they become native image content
+        // blocks. Anthropic applies a 2000 px per-dimension cap once conversation
+        // history contains more than 20 images, so every attachment must be safe for
+        // later turns too. Keep the original on disk, but send the resized bytes.
+        // Corrupt or unsupported images become plain files so they cannot reject the
+        // entire provider request.
+        let prepared = { ...a };
+        if (a.kind === "image") {
+            try {
+                const resized = await shrinkToFit(buf, a.mediaType);
+                const validatedType = await validateVisionImage(resized.buffer);
+                prepared = validatedType
+                    ? {
+                        ...a,
+                        mediaType: validatedType,
+                        data: resized.buffer.toString("base64"),
+                    }
+                    : { ...a, kind: "file" };
+            }
+            catch {
+                prepared = { ...a, kind: "file" };
+            }
+        }
+        try {
+            await fs.writeFile(filePath, buf);
+            out.push({ ...prepared, path: filePath });
+        }
+        catch {
+            out.push({ ...prepared });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=attachments.js.map