@miphamai/cli 0.24.2 → 0.24.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.24.2",
+  "version": "0.24.4",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/skills/standard/mipham-code-setup.SKILL.md

@@ -1,29 +1,114 @@
 ---
 name: mipham-code-setup
-description: Guide for installing, configuring, and troubleshooting Mipham Code — the multi-model open-core intelligent coding terminal
-version: 1.0.0
+description: Install, configure, diagnose, and troubleshoot Mipham Code — the multi-model open-core intelligent coding terminal. Covers setup wizard, API keys, providers, models, skills, permissions, workspace trust, shell/IDE integration, and first-run onboarding.
+version: 2.0.0
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Skill
 ---
 
-# Mipham Code Setup
+# Mipham Code Setup — Executable Setup Workflow
 
-Comprehensive setup and configuration guide for Mipham Code.
+**Type**: Rigid — follow the decision tree exactly. Don't skip diagnostic phases.
 
-## Installation
+**Purpose**: Guide users from zero to fully configured Mipham Code. This skill is BOTH:
 
-**Quick install (recommended):**
+1. A self-contained diagnostic + configuration workflow the AI can execute
+2. A reference for `/setup` command behavior and slash commands
+
+**Triggers**: "setup mipham", "configure mipham", "install mipham code", "mipham not working", "mipham setup", "first time using mipham", "help me set up", "getting started", `/setup`
+
+---
+
+## Phase 0: Environment Detection (ALWAYS RUN FIRST)
+
+Before doing anything, run these diagnostic checks. Report results in a status table.
+
+### 0.1 — Detect Installation
+
+```bash
+which mipham 2>/dev/null
+mipham --version 2>/dev/null
+bun --version 2>/dev/null
+node --version 2>/dev/null
+```
+
+### 0.2 — Detect Configuration
+
+```bash
+ls -la .mipham/config.yml 2>/dev/null
+ls -la ~/.mipham/config.yml 2>/dev/null
+ls -la MIPHAM.md 2>/dev/null
+ls -la CLAUDE.md 2>/dev/null
+```
+
+### 0.3 — Detect API Keys
+
+```bash
+env | grep -E 'ANTHROPIC_API_KEY|OPENAI_API_KEY|DEEPSEEK_API_KEY|QWEN_API_KEY|DOUBAO_API_KEY|HUNYUAN_API_KEY|GEMINI_API_KEY' | cut -d= -f1
+```
+
+### 0.4 — Detect Skills & Permissions
+
+```bash
+ls .mipham/skills/ 2>/dev/null
+cat .mipham/config.yml 2>/dev/null | grep -E 'permission|trust' || echo "no config"
+```
+
+### 0.5 — Detect Workspace Trust
+
+```bash
+cat ~/.mipham/trusted-workspaces.json 2>/dev/null || echo "no trust store"
+```
+
+### Status Report Format
+
+After detection, present results as:
+
+```
+── Mipham Code Status ──
+
+Installation:  [✅/⬜] mipham CLI  [✅/⬜] Bun  [✅/⬜] Node.js
+Project:       [✅/⬜] .mipham/  [✅/⬜] config.yml  [✅/⬜] MIPHAM.md
+User Config:   [✅/⬜] ~/.mipham/config.yml
+API Keys:      [N] set (list names or "none")
+Skills:        [N] installed
+Permissions:   [mode] (default/acceptEdits/plan/auto/dontAsk/bypass)
+Trust:         [✅/⬜] workspace trusted
+```
+
+Then proceed to ONLY the phases where something is missing. Don't re-run already-configured steps unless asked.
+
+---
+
+## Phase 1: Installation
+
+**Trigger**: `mipham --version` fails.
+
+### Option A: Quick Install (recommended)
 
 ```bash
 curl -fsSL https://mipham.ai/install.sh | bash
 ```
 
-**npm global install:**
+Then restart the shell or run:
+
+```bash
+export PATH="$HOME/.mipham/bin:$PATH"
+```
+
+### Option B: npm Global Install
 
 ```bash
 npm install -g @miphamai/cli
 mipham
 ```
 
-**From source:**
+### Option C: From Source (developers)
 
 ```bash
 git clone https://github.com/One-Mipham/mipham-code
@@ -31,25 +116,86 @@ cd mipham-code/apps/cli
 bun install && bun run bin/mipham
 ```
 
-## Configuration
+### ✅ Verification
 
-### 1. Create project config
+```bash
+mipham --version   # Should print version ≥ 0.24.0
+mipham --help      # Should print usage
+```
+
+---
+
+## Phase 2: Project Initialization
 
-Run `/setup` in Mipham Code for a guided 6-step wizard, or manually:
+**Trigger**: Missing `.mipham/` directory or `MIPHAM.md`.
+
+### 2.1 — Create .mipham/ directory
 
 ```bash
 mkdir -p .mipham
 ```
 
-`.mipham/config.yml`:
+### 2.2 — Create .mipham/config.yml
+
+Write a minimal config. Ask the user which provider they want to use first, or pick a sensible default:
 
 ```yaml
 defaultProvider: anthropic
 defaultModel: claude-sonnet-4-6
-permission: auto
+permission: default
 ```
 
-### 2. Set API Keys
+**Providers available** (alphabetical):
+
+| Provider  | Type          | Example Models                         |
+| --------- | ------------- | -------------------------------------- |
+| anthropic | Native SDK    | Claude Haiku 4.5, Sonnet 4.6, Opus 4.8 |
+| deepseek  | OpenAI Compat | V4 Flash, V4 Pro                       |
+| doubao    | OpenAI Compat | Seed 1.6, Seed 2.0                     |
+| gemini    | OpenAI Compat | 3.0 Flash, 3.0 Pro, 2.5 Pro            |
+| hunyuan   | OpenAI Compat | Lite, TurboS, 2.0, T1                  |
+| openai    | OpenAI Compat | GPT-5.4 Mini, GPT-5.4, GPT-5.5, Codex  |
+| qwen      | OpenAI Compat | Qwen Plus, Qwen Max                    |
+
+### 2.3 — Create MIPHAM.md (optional but recommended)
+
+Create `MIPHAM.md` in project root to define AI personality:
+
+```markdown
+# MIPHAM.md
+
+## Project Context
+
+- **Project**: [name]
+- **Language**: [zh-CN / en]
+- **Stack**: [TypeScript / Python / etc.]
+
+## Preferences
+
+- Code style: [e.g., functional, OOP]
+- Comment language: [e.g., English]
+- Test framework: [e.g., Vitest]
+```
+
+### ✅ Verification
+
+```bash
+ls -la .mipham/config.yml MIPHAM.md
+```
+
+---
+
+## Phase 3: API Key Configuration
+
+**Trigger**: Missing API keys in environment.
+
+### 3.1 — Identify Required Providers
+
+Ask the user which providers they plan to use. For each, set the env var.
+
+### 3.2 — Set API Keys
+
+**Recommended: Environment variables** (not in config files — avoids accidental commits):
 
 ```bash
 export ANTHROPIC_API_KEY="sk-ant-..."
@@ -61,53 +207,344 @@ export HUNYUAN_API_KEY="..."
 export GEMINI_API_KEY="..."
 ```
 
-Or add to `~/.mipham/config.yml`:
+Add these to `~/.zshrc` or `~/.bashrc` for persistence:
+
+```bash
+echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Alternative**: Store in `~/.mipham/config.yml`:
 
 ```yaml
 providers:
   - id: anthropic
     apiKey: $ANTHROPIC_API_KEY
+  - id: openai
+    apiKey: $OPENAI_API_KEY
+```
+
+### 3.3 — Verify Keys
+
+```bash
+env | grep API_KEY
+```
+
+### ❗Security Rules
+
+- NEVER hardcode API keys in project config files (`.mipham/config.yml` in project root should use `$ENV_VAR` references, not raw keys)
+- NEVER commit API keys to git
+- Add to `.gitignore`: `.mipham/config.yml` (if it contains keys), `.env`, `*.pem`
+
+---
+
+## Phase 4: Provider & Model Configuration
+
+**Trigger**: Need to set default or enable/disable providers.
+
+### 4.1 — Set Default Provider & Model
+
+In `.mipham/config.yml`:
+
+```yaml
+defaultProvider: anthropic
+defaultModel: claude-sonnet-4-6
 ```
 
-### 3. Project personality (MIPHAM.md)
+Or use slash commands:
+
+```
+/model          # Interactive model picker (Ctrl+P)
+/switch         # Switch provider
+/providers      # List all configured providers
+```
+
+### 4.2 — Enable/Disable Providers
+
+```yaml
+providers:
+  - id: anthropic
+    status: active
+  - id: openai
+    status: active
+  - id: deepseek
+    status: disabled
+```
+
+### ✅ Verification
+
+```
+/model    # Should show available models
+/providers # Should list active providers
+```
+
+---
+
+## Phase 5: Skills Installation
+
+**Trigger**: No or few skills installed.
+
+### 5.1 — Built-in Skills
 
-Create `MIPHAM.md` in project root to define AI interaction style:
+Mipham Code ships with 15 built-in skills loaded automatically:
 
-- Code preferences
-- Language (zh-CN / en)
-- Project-specific rules
+- **Standard (12)**: code-review, compassionate-communication, doc-generator, github-ops, memory, mipham-code-setup, security-review, self-review, superpower, tdd, web-access, web-search
+- **Mipham (3)**: om-artifact, om-model-optimize, om-security
 
-### 4. Verify installation
+### 5.2 — Community Skills
+
+Install from the community registry:
+
+```
+/setup 4     # Guided skill browser
+```
+
+Or directly:
+
+```bash
+# Skills are loaded from:
+# - apps/cli/skills/standard/     (built-in standard)
+# - apps/cli/skills/mipham/       (built-in mipham)
+# - ~/.mipham/skills/             (user-installed)
+# - .mipham/skills/               (project-local)
+```
+
+### 5.3 — Install Specific Skills
+
+```
+/skills install <name>    # Install from registry
+/skills list              # List available
+/skills search <query>    # Search registry
+```
+
+### ✅ Verification
+
+```
+/skills list   # Should show installed skills with counts
+```
+
+---
+
+## Phase 6: Permissions Configuration
+
+**Trigger**: Permission mode not configured or wrong for use case.
+
+### 6.1 — Permission Modes
+
+| Mode                | Behavior                        | Use Case                            |
+| ------------------- | ------------------------------- | ----------------------------------- |
+| `default`           | Prompt for each tool            | Normal development (recommended)    |
+| `acceptEdits`       | Auto-allow edits, prompt others | Active coding sessions              |
+| `plan`              | Plan-only, no tool execution    | Design & architecture work          |
+| `auto`              | Auto-allow all                  | Trusted, frequent use               |
+| `dontAsk`           | Never auto-allow                | CI/CD safety                        |
+| `bypassPermissions` | Skip all checks                 | ⚠️ Only for fully trusted codebases |
+
+### 6.2 — Configure
+
+In `.mipham/config.yml`:
+
+```yaml
+permission: auto
+```
+
+Or via slash command:
+
+```
+/permissions           # View current settings
+/setup 5               # Permission setup wizard
+```
+
+### 6.3 — CI/CD Safety
+
+For CI/CD environments, use `dontAsk` mode to prevent the AI from executing tools without explicit approval:
+
+```yaml
+permission: dontAsk
+```
+
+### ✅ Verification
+
+```
+/permissions   # Should show current mode
+```
+
+---
+
+## Phase 7: Workspace Trust
+
+**Trigger**: Untrusted workspace (prompted on startup in v0.24.3+).
+
+### 7.1 — Understanding Workspace Trust
+
+Workspace trust is a security mechanism that prevents AI from operating in untrusted directories. Trust is **hierarchical**: trusting `/Users/me/Projects` implicitly trusts all subdirectories.
+
+### 7.2 — Trust a Workspace
+
+**Interactive**: Accept the trust prompt when launching Mipham Code in a new directory.
+
+**Manual**:
+
+```
+/trust              # Show trust status
+/trust add <dir>    # Trust a directory
+/trust remove <dir> # Revoke trust
+```
+
+### 7.3 — Trust Store
+
+```
+~/.mipham/trusted-workspaces.json
+```
+
+### 7.4 — Auto-Trust for Worktrees
+
+When using git worktrees, Mipham Code automatically trusts worktree directories if the parent workspace is already trusted (via `EnterWorktree`).
+
+### ✅ Verification
+
+```
+/trust   # Should show "✅ Yes" for current directory
+```
+
+---
+
+## Phase 8: Shell & IDE Integration
+
+**Trigger**: Want terminal integration, aliases, or IDE plugins.
+
+### 8.1 — Shell Alias
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+alias mipham='cd ~/your-project && bun run ~/path/to/mipham-code/apps/cli/bin/mipham.ts'
+# Or if installed globally:
+alias mipham='mipham'
+```
+
+### 8.2 — VS Code Integration
+
+Run `/ide` to auto-generate `.vscode/` config files:
+
+- `settings.json` — terminal profile "mipham" using Bun
+- `keybindings.json` — Cmd+Esc to focus terminal, Cmd+Shift+M for new terminal
+- `extensions.json` — recommends `miphamai.mipham-code` extension
+
+To use after generation:
+
+1. Restart VS Code (or Cmd+Shift+P → Reload Window)
+2. Open terminal: Ctrl+` or Cmd+Esc
+3. Select "mipham" profile from terminal dropdown
+
+Install the VS Code extension:
+
+```bash
+code --install-extension miphamai.mipham-code
+```
+
+### 8.3 — JetBrains Integration
+
+Settings → Tools → Terminal → Shell path → `bun run mipham`
+
+### 8.4 — Terminal Setup
+
+```
+/terminal-setup    # Shell & terminal config wizard
+/setup 6           # Shell integration (part of full wizard)
+```
+
+### ✅ Verification
 
 ```bash
-mipham --version
-mipham --help
+which mipham       # Should resolve
+# In VS Code: Ctrl+` → select "mipham" profile
 ```
 
-Use `/doctor` in Mipham Code for system diagnostics.
+---
+
+## Phase 9: Full Verification
+
+Run after all configuration phases complete.
+
+### 9.1 — System Diagnostics
+
+```
+/doctor            # System diagnostics check
+```
 
-## Supported Providers
+### 9.2 — End-to-End Test
 
-| Provider      | Type          | Models                                 |
-| ------------- | ------------- | -------------------------------------- |
-| Anthropic     | Native SDK    | Claude Haiku 4.5, Sonnet 4.6, Opus 4.8 |
-| OpenAI        | OpenAI Compat | GPT-5.4 Mini, GPT-5.4, GPT-5.5, Codex  |
-| DeepSeek      | OpenAI Compat | V4 Flash, V4 Pro                       |
-| Google Gemini | OpenAI Compat | 3.0 Flash/Pro, 2.5 Pro                 |
-| Qwen          | OpenAI Compat | Qwen Plus, Qwen Max                    |
-| Doubao        | OpenAI Compat | Seed 1.6/2.0 series                    |
-| Hunyuan       | OpenAI Compat | Lite, TurboS, 2.0, T1                  |
+Start a conversation and verify:
 
-## Slash Commands (60 total)
+1. Model responds (not stuck on "connecting...")
+2. File tools work: "read CLAUDE.md"
+3. Bash works: "list files in current directory"
+4. Skills load: `/skills list`
+
+### 9.3 — Common Issues & Fixes
+
+| Symptom                   | Diagnosis                              | Fix                                              |
+| ------------------------- | -------------------------------------- | ------------------------------------------------ |
+| "Provider not registered" | Missing or invalid API key             | `env \| grep API_KEY`; check key format          |
+| "Model not found"         | Model ID mismatch or disabled provider | `/models` to list available; `/switch` to change |
+| Slow responses            | Large model, network, or context full  | `/fast on` or switch to Flash model; `/compact`  |
+| Context full              | Too many messages in history           | `/compact` to compress; `/clear` to reset        |
+| Permission denied         | Tool blocked by permission mode        | `/permissions` to check; adjust mode             |
+| "Workspace not trusted"   | New directory, not yet trusted         | Accept startup prompt or run `/trust`            |
+| MCP tools not available   | Server not connected                   | `/mcp connect <name>` or check config            |
+| Update not applying       | Cached binary                          | `mipham update --force` then restart             |
+| Config changes ignored    | YAML syntax error                      | Validate with `mipham --check-config`            |
+
+### 9.4 — Get Help
+
+```
+/help              # Full command reference
+/setup             # Re-run setup wizard
+/doctor            # Run diagnostics
+```
+
+Chat-based help: "help me configure X" or "why isn't Y working?"
+
+---
+
+## Quick Reference: Essential Slash Commands
+
+| Category      | Command           | Purpose                                                |
+| ------------- | ----------------- | ------------------------------------------------------ |
+| **Setup**     | `/setup`          | Full 6-step setup wizard                               |
+|               | `/setup 1`        | Initialize project (.mipham/ + MIPHAM.md + config.yml) |
+|               | `/setup 2`        | Configure providers & API keys                         |
+|               | `/setup 3`        | Choose default model                                   |
+|               | `/setup 4`        | Browse & install skills                                |
+|               | `/setup 5`        | Configure permissions                                  |
+|               | `/setup 6`        | Shell & IDE integration                                |
+| **Diagnosis** | `/doctor`         | System diagnostics                                     |
+|               | `/trust`          | Workspace trust status                                 |
+|               | `/permissions`    | Tool permission settings                               |
+| **Model**     | `/model`          | Interactive model picker (Ctrl+P)                      |
+|               | `/switch`         | Switch provider                                        |
+|               | `/models`         | List available models                                  |
+| **Session**   | `/clear`          | Reset conversation                                     |
+|               | `/compact`        | Compress context                                       |
+|               | `/rename`         | Rename session                                         |
+| **Workflow**  | `/plan`           | Enter plan mode                                        |
+|               | `/review`         | Code review                                            |
+|               | `/todos`          | Task list                                              |
+| **IDE**       | `/ide`            | Generate VS Code integration files                     |
+|               | `/terminal-setup` | Shell & terminal config                                |
+| **Skills**    | `/skills list`    | List installed skills                                  |
+|               | `/skills search`  | Search skill registry                                  |
+|               | `/skills install` | Install a skill                                        |
+
+---
 
-Essential: `/help`, `/switch`, `/model`, `/setup`, `/doctor`, `/mcp`
-Workflow: `/plan`, `/review`, `/diff`, `/todos`, `/tasks`
-Session: `/clear`, `/compact`, `/rename`, `/goal`, `/export`, `/resume`
+## Post-Setup: What to Do Next
 
-## Troubleshooting
+After configuration is verified:
 
-- **"Provider not registered"**: Check API key is set (`env | grep API_KEY`)
-- **"Model not found"**: Use `/models` to list available models
-- **Slow responses**: Toggle `/fast on` or switch to a Flash model
-- **Context full**: Use `/compact` to free token space
-- **Permission denied**: Use `/permissions` to check tool access settings
+1. **Initialize your project**: "help me understand this codebase"
+2. **Set up CLAUDE.md**: `/init` to generate project documentation for the AI
+3. **Install relevant skills**: `/setup 4` or `/skills search`
+4. **Configure MCP servers**: `/mcp connect` for external tool integration
+5. **Start coding**: Just start a conversation — the AI will use tools and skills automatically

package/src/agent/sub-agent.ts

@@ -8,6 +8,7 @@ import type { HookEngine } from '../core/hooks'
 import type { PermissionSystem } from '../core/permission'
 import { AgentExperience } from './agent-experience'
 import { PatternAnalyzer } from './pattern-analyzer.js'
+import { getWorkspaceTrust } from '../core/workspace-trust'
 import type { ExperienceRuleEngine } from '../core/rule-engine.js'
 
 // Singleton instances (created lazily)
@@ -200,6 +201,19 @@ export class SubAgent {
     // Resolve execution directory: worktree isolation or process cwd
     const execCwd = options.worktreePath || process.cwd()
 
+    // Check workspace trust for the execution directory.
+    // For worktree-isolated agents, auto-trust the worktree if the parent is trusted.
+    if (options.worktreePath) {
+      const trust = getWorkspaceTrust()
+      if (!trust.isTrusted(execCwd)) {
+        // Auto-trust worktree directories when the parent workspace is trusted
+        if (trust.isTrusted(process.cwd())) {
+          trust.trust(execCwd)
+        }
+        // Otherwise, proceed with a warning — don't block agent execution
+      }
+    }
+
     // Resolve system prompt: agentDef > options.systemPrompt > builtin type
     const systemPrompt =
       agentDef?.systemPrompt || options.systemPrompt || TYPE_SYSTEM_PROMPTS[agentType]

package/src/commands/project.ts

@@ -6,8 +6,18 @@
  * /security, /audit, /prompt-audit
  */
 import type { CommandHandler, CommandContext, CommandResult } from '../ui/commands.js'
-
-export { initCmd, permissionsCmd, recommendCmd, setupCmd, addDirCmd, promptAuditCmd, securityCmd }
+import { getWorkspaceTrust } from '../core/workspace-trust'
+
+export {
+  initCmd,
+  permissionsCmd,
+  recommendCmd,
+  setupCmd,
+  addDirCmd,
+  promptAuditCmd,
+  securityCmd,
+  trustCmd,
+}
 
 const initCmd: CommandHandler = async (ctx) => {
   const { existsSync, mkdirSync, writeFileSync } = await import('node:fs')
@@ -1004,3 +1014,35 @@ const securityCmd: CommandHandler = async () => {
 
   return { content: lines.join('\n') }
 }
+
+const trustCmd: CommandHandler = (ctx) => {
+  const trust = getWorkspaceTrust()
+  const cwd = process.cwd()
+  const trusted = trust.listTrusted()
+
+  const lines: string[] = [
+    '── Workspace Trust ──',
+    '',
+    `Current directory: ${cwd}`,
+    `Trusted: ${trust.isTrusted(cwd) ? '✅ Yes' : '⚠️  No (restart to trust)'}`,
+    `Trust store: ${trust.getStorePath()}`,
+    '',
+  ]
+
+  if (trusted.length === 0) {
+    lines.push('No trusted workspaces configured.')
+    lines.push('')
+    lines.push('Trust a workspace: restart Mipham Code in the directory')
+    lines.push('and accept the trust prompt.')
+  } else {
+    lines.push(`Trusted workspaces (${trusted.length}):`)
+    for (const dir of trusted) {
+      const marker = cwd.startsWith(dir) ? ' ← current' : ''
+      lines.push(`  • ${dir}${marker}`)
+    }
+    lines.push('')
+    lines.push('Remove a workspace: delete the directory entry from the trust store.')
+  }
+
+  return { content: lines.join('\n') }
+}

package/src/core/workspace-trust.ts

@@ -0,0 +1,144 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { homedir } from 'node:os'
+
+const MIPHAM_HOME = join(homedir(), '.mipham')
+const TRUST_STORE_PATH = join(MIPHAM_HOME, 'trusted-workspaces.json')
+
+export interface TrustedWorkspaces {
+  version: 1
+  directories: string[]
+  updatedAt: string
+}
+
+/**
+ * Resolves a directory to its real absolute path, following symlinks.
+ * Falls back to the resolved path if realpath fails.
+ */
+function realPath(dir: string): string {
+  try {
+    // Use resolve to normalize, but don't require the directory to exist yet
+    const resolved = resolve(dir)
+    return resolved
+  } catch {
+    return resolve(dir)
+  }
+}
+
+/**
+ * Manages the workspace trust store.
+ *
+ * Trust is hierarchical: a directory is trusted if it or any of its
+ * ancestor directories are in the trust store. This means trusting
+ * /Users/me/Projects implicitly trusts all subdirectories.
+ */
+export class WorkspaceTrust {
+  private store: TrustedWorkspaces
+
+  constructor() {
+    this.store = this.load()
+  }
+
+  /** Load the trust store from disk, or return a fresh default. */
+  private load(): TrustedWorkspaces {
+    try {
+      if (!existsSync(TRUST_STORE_PATH)) {
+        return { version: 1, directories: [], updatedAt: new Date().toISOString() }
+      }
+      const raw = readFileSync(TRUST_STORE_PATH, 'utf-8')
+      const parsed = JSON.parse(raw) as TrustedWorkspaces
+      if (parsed.version !== 1) {
+        // Unknown version — reset
+        return { version: 1, directories: [], updatedAt: new Date().toISOString() }
+      }
+      return parsed
+    } catch {
+      return { version: 1, directories: [], updatedAt: new Date().toISOString() }
+    }
+  }
+
+  /** Persist the trust store to disk. */
+  private save(): void {
+    try {
+      if (!existsSync(MIPHAM_HOME)) {
+        mkdirSync(MIPHAM_HOME, { recursive: true })
+      }
+      this.store.updatedAt = new Date().toISOString()
+      writeFileSync(TRUST_STORE_PATH, JSON.stringify(this.store, null, 2), 'utf-8')
+    } catch {
+      // Best-effort: don't crash if we can't save
+    }
+  }
+
+  /**
+   * Check whether a directory is trusted.
+   * A directory is trusted if it or any ancestor is in the trust list.
+   */
+  isTrusted(dir: string): boolean {
+    const resolved = realPath(dir)
+    const resolvedLower = resolved.toLowerCase()
+
+    for (const trusted of this.store.directories) {
+      const trustedLower = trusted.toLowerCase()
+      // Exact match
+      if (resolvedLower === trustedLower) return true
+      // Ancestor match: trusted dir is a parent of the target
+      if (resolvedLower.startsWith(trustedLower + '/')) return true
+    }
+
+    return false
+  }
+
+  /** Add a directory to the trust store. */
+  trust(dir: string): void {
+    const resolved = realPath(dir)
+    // Don't add duplicates
+    if (this.store.directories.includes(resolved)) return
+    // Don't add subdirectories of already-trusted paths
+    if (this.isTrusted(resolved)) return
+
+    this.store.directories.push(resolved)
+    // Sort for readability
+    this.store.directories.sort()
+    this.save()
+  }
+
+  /** Remove a directory from the trust store (and any subdirectories). */
+  untrust(dir: string): void {
+    const resolved = realPath(dir)
+    const resolvedLower = resolved.toLowerCase()
+
+    this.store.directories = this.store.directories.filter((d) => {
+      const lower = d.toLowerCase()
+      // Remove exact match and all subdirectories
+      return lower !== resolvedLower && !lower.startsWith(resolvedLower + '/')
+    })
+    this.save()
+  }
+
+  /** List all trusted directories. */
+  listTrusted(): string[] {
+    return [...this.store.directories]
+  }
+
+  /** Get the path to the trust store. */
+  getStorePath(): string {
+    return TRUST_STORE_PATH
+  }
+}
+
+// ── Singleton ──
+
+let _instance: WorkspaceTrust | null = null
+
+export function getWorkspaceTrust(): WorkspaceTrust {
+  if (!_instance) {
+    _instance = new WorkspaceTrust()
+  }
+  return _instance
+}
+
+/** Reset the singleton (for tests). */
+export function resetWorkspaceTrust(): void {
+  _instance = null
+}

package/src/index.tsx

@@ -1,7 +1,9 @@
 import React from 'react'
 import { join } from 'node:path'
+import { homedir } from 'node:os'
 import { existsSync } from 'node:fs'
 import { render } from 'ink'
+import * as readline from 'node:readline'
 import { App } from './ui/app'
 import {
   loadConfig,
@@ -33,6 +35,7 @@ import { AgentRegistry } from './agent/agent-registry'
 import { HookEngine } from './core/hooks'
 import { ArtifactServer } from './artifacts/server'
 import { getMetrics } from './core/metrics'
+import { getWorkspaceTrust } from './core/workspace-trust'
 import { ARTIFACTS_DIR, ARTIFACT_PORT, MIPHAM_DIR } from './shared/constants'
 import { AgentViewManager } from './agent-view/agent-view-manager'
 import { AgentViewDashboard } from './agent-view/dashboard'
@@ -52,10 +55,69 @@ interface RunOptions {
   version?: string
 }
 
+/**
+ * Check workspace trust before starting the session.
+ * If the cwd is not trusted, prompt the user via stdin.
+ * Exits the process if the user declines.
+ */
+async function checkWorkspaceTrust(): Promise<void> {
+  const cwd = process.cwd()
+  const trust = getWorkspaceTrust()
+
+  if (trust.isTrusted(cwd)) return
+
+  // Non-interactive mode (piped stdin, headless) — skip prompt, proceed
+  if (!process.stdin.isTTY) return
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr, // use stderr to avoid interfering with stdout rendering
+  })
+
+  const question = (prompt: string): Promise<string> =>
+    new Promise((resolve) => {
+      rl.question(prompt, (answer) => {
+        resolve(answer.trim().toLowerCase())
+      })
+    })
+
+  process.stderr.write('\n')
+  process.stderr.write('╔══════════════════════════════════════════════╗\n')
+  process.stderr.write('║  ⚠️  Workspace Trust                          ║\n')
+  process.stderr.write('╠══════════════════════════════════════════════╣\n')
+  process.stderr.write('║                                              ║\n')
+  process.stderr.write(`║  Directory not trusted:                      ║\n`)
+  process.stderr.write(`║  ${cwd.slice(0, 42).padEnd(42)}║\n`)
+  process.stderr.write('║                                              ║\n')
+  process.stderr.write('║  Trust this workspace?                       ║\n')
+  process.stderr.write('║  [Y] Trust and continue                      ║\n')
+  process.stderr.write('║  [N] Exit                                    ║\n')
+  process.stderr.write('║                                              ║\n')
+  process.stderr.write('╚══════════════════════════════════════════════╝\n')
+  process.stderr.write('\n')
+
+  try {
+    const answer = await question('Trust this workspace? [Y/N]: ')
+    if (answer === 'y' || answer === 'yes') {
+      trust.trust(cwd)
+      process.stderr.write(`✓ Workspace trusted: ${cwd}\n\n`)
+    } else {
+      process.stderr.write('✗ Workspace not trusted. Exiting.\n')
+      rl.close()
+      process.exit(1)
+    }
+  } finally {
+    rl.close()
+  }
+}
+
 export async function runApp(options: RunOptions): Promise<void> {
   // Metrics: count CLI invocation
   getMetrics().cliInvocations.inc()
 
+  // ── Workspace Trust Check ──
+  await checkWorkspaceTrust()
+
   // Handle `mipham agents` subcommand — launch standalone dashboard
   const args = process.argv.slice(2)
   if (args[0] === 'agents') {
@@ -202,6 +264,52 @@ export async function runApp(options: RunOptions): Promise<void> {
       prompt = `${prompt}\n\n<system-reminder name="key-expiry">\n${keyReminder}\n</system-reminder>`
     }
 
+    // First-run setup detection: inject mipham-code-setup guidance when
+    // no project or user config exists. This mirrors Claude Code's first-run
+    // onboarding flow — the AI proactively offers to help configure the tool.
+    const hasProjectConfig = existsSync(join(process.cwd(), '.mipham', 'config.yml'))
+    const hasUserConfig = existsSync(join(homedir(), '.mipham', 'config.yml'))
+    const hasMiphamMd = existsSync(join(process.cwd(), 'MIPHAM.md'))
+    if (!hasProjectConfig && !hasUserConfig) {
+      const setupReminder = [
+        '── First-Run Setup ──',
+        '',
+        `This appears to be a first run: no .mipham/config.yml found in project or ~/.mipham/.`,
+        '',
+        'Invoke the mipham-code-setup skill to guide the user through setup:',
+        '- Installation verification',
+        '- API key configuration',
+        '- Project initialization (.mipham/ + MIPHAM.md + config.yml)',
+        '- Provider & model selection',
+        '- Skills & permissions setup',
+        '- Workspace trust',
+        '- Shell & IDE integration',
+        '',
+        'The user may also run /setup for the guided 6-step wizard.',
+        'Be proactive: offer to help configure Mipham Code before diving into',
+        'their task. A properly configured environment makes everything smoother.',
+      ].join('\n')
+      prompt = `${prompt}\n\n<system-reminder name="first-run-setup">\n${setupReminder}\n</system-reminder>`
+    } else if (!hasMiphamMd) {
+      // Partial setup: has config but no MIPHAM.md
+      const partialReminder = [
+        '── Missing MIPHAM.md ──',
+        '',
+        'No MIPHAM.md found in project root. This file tells the AI about',
+        'project-specific preferences (language, code style, test framework).',
+        '',
+        'Suggest creating one: /setup 1 or "help me create a MIPHAM.md"',
+        '',
+        'A basic MIPHAM.md includes:',
+        '- Project name and description',
+        '- Primary language (zh-CN / en)',
+        '- Tech stack',
+        '- Code style preferences',
+        '- Test framework',
+      ].join('\n')
+      prompt = `${prompt}\n\n<system-reminder name="missing-mipham-md">\n${partialReminder}\n</system-reminder>`
+    }
+
     context.setSystemPrompt(prompt)
   }
 

package/src/skills/community-registry.json

@@ -52,6 +52,15 @@
     "author": "MiphamAI",
     "builtin": true
   },
+  {
+    "name": "mipham-code-setup",
+    "description": "Install, configure, diagnose, and troubleshoot Mipham Code — executable setup workflow with 9-phase decision tree covering installation, API keys, providers, models, skills, permissions, workspace trust, and shell/IDE integration",
+    "url": "https://github.com/One-Mipham/mipham-code",
+    "file": "mipham-code-setup.SKILL.md",
+    "category": "Setup",
+    "author": "MiphamAI",
+    "builtin": true
+  },
   {
     "name": "security-review",
     "description": "Security audit and vulnerability scanning for code changes — OWASP, secrets, supply chain",

package/src/ui/commands.ts

@@ -35,6 +35,7 @@ import {
   addDirCmd,
   securityCmd,
   promptAuditCmd,
+  trustCmd,
 } from '../commands/project.js'
 import { themeCmd, releaseNotesCmd, ideCmd, terminalSetupCmd } from '../commands/environment.js'
 import { commitCmd, pushCmd, prCmd, issueCmd } from '../commands/git.js'
@@ -3215,6 +3216,7 @@ const commandsListCmd: CommandHandler = () => {
     '/recommend': 'Project',
     '/security': 'Project',
     '/audit': 'Project',
+    '/trust': 'Project',
     '/prompt-audit': 'Code Quality',
     '/ide': 'Environment',
     '/terminal-setup': 'Environment',
@@ -3371,6 +3373,7 @@ registry.set('/permissions', permissionsCmd)
 registry.set('/add-dir', addDirCmd)
 registry.set('/security', securityCmd)
 registry.set('/audit', securityCmd)
+registry.set('/trust', trustCmd)
 registry.set('/prompt-audit', promptAuditCmd)
 
 // Environment
@@ -3513,6 +3516,7 @@ const COMMAND_DESCRIPTIONS: Record<string, string> = {
   '/recommend': 'Analyze project + recommend skills & setup',
   '/security': 'Security review checklist',
   '/audit': 'Same as /security',
+  '/trust': 'Show and manage trusted workspaces',
   '/prompt-audit': 'Audit prompts for modern model optimization',
   '/ide': 'IDE integration guide',
   '/terminal-setup': 'Shell & terminal config',