@miphamai/cli 0.82.0 → 0.84.0

package/package.json

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

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

@@ -77,7 +77,7 @@ 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/bypassPermissions)
+Permissions:   [mode] (default/acceptEdits/plan/auto/bypassPermissions)
 Trust:         [✅/⬜] workspace trusted
 ```
 
@@ -331,21 +331,43 @@ Or directly:
 
 ### 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          |
-| `bypassPermissions` | Skip all checks                 | ⚠️ Only for fully trusted codebases |
+| Mode                | Behavior                               | Use Case                                  |
+| ------------------- | -------------------------------------- | ----------------------------------------- |
+| `default`           | Ask-first tools are refused (see note) | Normal development (recommended)          |
+| `acceptEdits`       | Auto-allow edits, ask for other tools  | Active coding sessions                    |
+| `plan`              | Plan-only, no tool execution           | Design & architecture work                |
+| `auto`              | A classifier rules on every call       | Long unattended runs you still want gated |
+| `bypassPermissions` | Skip all checks                        | ⚠️ Only for fully trusted codebases       |
+
+**Note on `default`**: Mipham Code has no interactive approval prompt, so "ask"
+means the call is **refused** with a message naming the mode — it is not queued
+for your answer. That makes `default` the strictest _usable_ mode for Bash and
+file writes; `auto` is the mode that lets gated calls proceed without a human,
+by having a classifier rule on each one.
+
+**What `auto` actually gates.** Reads (Read/Grep/Glob) are never sent to the
+classifier — gating them would make `auto` the only mode in the ladder that cannot
+open a file without a round-trip to another model. Everything else that the static
+chain would refuse goes to the classifier, which can only **lift** a refusal: a
+deny rule or an `ask` rule is never overridden. If the classifier cannot be reached
+or answers unusably, the call is refused (fail-closed) with a message saying the
+refusal is _not_ a policy decision and can be retried.
 
 ### 6.2 — Configure
 
-In `.mipham/config.yml`:
+Press **Shift+Tab** to change the mode live; it cycles
+`default → acceptEdits → plan → auto` and lasts for the session only.
+`bypassPermissions` is a legal mode but is deliberately **not** on the wheel —
+it is reached by naming it in config, where the user has said what they mean.
+
+To persist a mode for a project, in `.mipham/config.yml`:
 
 ```yaml
 permission: default
 ```
 
+Any mode name from the table above is accepted, including `bypassPermissions`.
+
 Or via slash command:
 
 ```

package/src/agent/agent-context.ts

@@ -1,13 +1,14 @@
 // apps/cli/src/agent/agent-context.ts
 import { readdirSync, readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { ContextManager } from '../core/context'
 import type { ToolDefinition } from '../shared/index.ts'
 import type { AgentDefinition } from './types'
 import type { CrsiConfig } from '../shared/index.ts'
 import { AgentExperience } from './agent-experience'
 import { ExperienceRuleExtractor } from './experience-rules.js'
+import { miphamHome } from '../core/paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
 export interface AgentContextResult {
   context: ContextManager
@@ -26,17 +27,16 @@ function loadAgentMemory(
   crsiRuleInjection = true,
 ): string {
   let memoryDir: string
-  const home = homedir()
 
   switch (scope) {
     case 'user':
-      memoryDir = join(home, '.mipham', 'agent-memory', agentName)
+      memoryDir = miphamHome('agent-memory', agentName)
       break
     case 'project':
-      memoryDir = join(process.cwd(), '.mipham', 'agent-memory', agentName)
+      memoryDir = join(process.cwd(), MIPHAM_DIR, 'agent-memory', agentName)
       break
     case 'local':
-      memoryDir = join(process.cwd(), '.mipham', 'agent-memory-local', agentName)
+      memoryDir = join(process.cwd(), MIPHAM_DIR, 'agent-memory-local', agentName)
       break
   }
 

package/src/agent/agent-experience.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { ExperienceRuleExtractor, type ExperienceRule } from './experience-rules.js'
+import { miphamHome } from '../core/paths.ts'
 
 const MAX_EXPERIENCES = 20
 
@@ -11,7 +11,7 @@ export class AgentExperience {
 
   constructor(
     private readonly agentName: string,
-    baseDir: string = join(homedir(), '.mipham', 'agent-memory'),
+    baseDir: string = miphamHome('agent-memory'),
   ) {
     this.expDir = join(baseDir, agentName)
     this.expFile = join(this.expDir, 'experience.md')

package/src/agent/agent-registry.ts

@@ -1,8 +1,9 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { join, extname } from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import type { AgentDefinition, SubAgentType } from './types'
+import { miphamHome } from '../core/paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
 interface FrontmatterResult {
   data: Record<string, unknown>
@@ -91,13 +92,12 @@ export class AgentRegistry {
 
   /** Load project-level agents from .mipham/agents/ */
   loadProjectAgents(cwd: string): void {
-    this.loadDirectory(join(cwd, '.mipham', 'agents'), 'project')
+    this.loadDirectory(join(cwd, MIPHAM_DIR, 'agents'), 'project')
   }
 
   /** Load user-level agents from ~/.mipham/agents/ */
   loadUserAgents(): void {
-    const home = homedir()
-    this.loadDirectory(join(home, '.mipham', 'agents'), 'user')
+    this.loadDirectory(miphamHome('agents'), 'user')
   }
 
   /** Get a custom agent by name. Returns undefined for builtins. */

package/src/agent/cross-session/discovery.ts

@@ -8,10 +8,11 @@ import {
   statSync,
 } from 'node:fs'
 import { join, basename } from 'node:path'
-import { homedir, hostname } from 'node:os'
+import { hostname } from 'node:os'
 import type { SessionInfo, CrossSessionInbound } from '../../shared/types'
+import { miphamHome } from '../../core/paths.ts'
 
-const MIPHAM_HOME = join(homedir(), '.mipham')
+const MIPHAM_HOME = miphamHome()
 const ACTIVE_SESSIONS_DIR = join(MIPHAM_HOME, '.active-sessions')
 
 /** A session whose heartbeat file hasn't been touched in this long is dead. */

package/src/agent/cross-session/file-inbox.ts

@@ -9,12 +9,11 @@ import {
   lstatSync,
 } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
 import type { CrossSessionTransport } from './transport'
 import type { AgentMessage } from '../message-bus'
 import type { SessionInfo } from '../../shared/types'
 
-const MIPHAM_HOME = join(homedir(), '.mipham')
+const MIPHAM_HOME = miphamHome()
 const INBOX_DIR = join(MIPHAM_HOME, 'inbox')
 
 /** True if a path exists and is a symbolic link (symlink-attack guard). */
@@ -138,6 +137,7 @@ export class FileInboxTransport implements CrossSessionTransport {
 
 // Import discoverSessions lazily to avoid circular dependency
 import { discoverSessions } from './discovery'
+import { miphamHome } from '../../core/paths.ts'
 
 // ── Singleton ──
 

package/src/agent/effectiveness-tracker.ts

@@ -1,8 +1,8 @@
 import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import type { CrsiProvenanceBridge, CrsiVerdict } from './crsi-provenance-bridge.js'
 import { isRecoverableToolFailure } from './recoverable-failure.js'
+import { miphamHome } from '../core/paths.ts'
 
 export interface RuleEffectiveness {
   ruleId: string
@@ -32,7 +32,7 @@ export class EffectivenessTracker {
   private storePath: string
   private provenanceBridge?: CrsiProvenanceBridge
 
-  constructor(storeDir: string = join(homedir(), '.mipham', 'rule-engine')) {
+  constructor(storeDir: string = miphamHome('rule-engine')) {
     this.storePath = join(storeDir, STORE_FILE)
     this.data = new Map()
   }

package/src/agent/pattern-analyzer.ts

@@ -1,9 +1,8 @@
 import { readdirSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { homedir } from 'node:os'
 import { AgentExperience } from './agent-experience.js'
 import { parseFailureEntries, categorize, type ExperienceRule } from './experience-rules.js'
 import type { ToolRule } from '../core/rule-engine.js'
+import { miphamHome } from '../core/paths.ts'
 
 export interface Pattern {
   id: string
@@ -18,7 +17,7 @@ export interface Pattern {
 
 export class PatternAnalyzer {
   analyzeAgent(agentName: string, baseDir?: string): Pattern[] {
-    const dir = baseDir || join(homedir(), '.mipham', 'agent-memory')
+    const dir = baseDir || miphamHome('agent-memory')
     const exp = new AgentExperience(agentName, dir)
     const content = exp.getExperience()
     if (!content) return []
@@ -55,7 +54,7 @@ export class PatternAnalyzer {
   }
 
   analyzeAllAgents(baseDir?: string): Pattern[] {
-    const dir = baseDir || join(homedir(), '.mipham', 'agent-memory')
+    const dir = baseDir || miphamHome('agent-memory')
     if (!existsSync(dir)) return []
 
     let agents: string[]

package/src/agent/sub-agent.ts

@@ -498,12 +498,22 @@ export class SubAgent {
           // The gate is never absent: when nobody handed in a permission system, `gate` is
           // the CLI's default mode (see above), so this check always runs.
           // P0-3: Uses isolated subPermission (clamped by org restrictions) instead of parent's.
-          if (gate.needsApproval(tool, effectiveInput)) {
+          //
+          // `resolveApproval` replaces `needsApproval` here for the same reason as in
+          // `engine.ts`: in `auto` mode the static chain can only say `'ask'`, and the
+          // classifier is what turns that into a running call. `gate` only carries a
+          // classifier when the sub-agent's resolved mode is `auto` (see
+          // `createSubAgentPermission`), so the default sub-agent is unchanged.
+          const decision = await gate.resolveApproval(tool, effectiveInput, { signal })
+          if (decision.level === 'ask') {
             currentMessages.push({
               role: 'user' as const,
               content:
                 `Tool "${tu.name}" requires user approval (permission: ask). ` +
-                `Cannot execute in non-interactive sub-agent context.`,
+                `Cannot execute in non-interactive sub-agent context.` +
+                (decision.source === 'classifier' && decision.classifierReason
+                  ? ` Classifier: ${decision.classifierReason}`
+                  : ''),
             })
             continue
           }

package/src/agent/types.ts

@@ -10,7 +10,10 @@ export interface AgentFrontmatter {
   tools?: string // comma-separated allowlist
   disallowedTools?: string
   model?: string // 'sonnet' | 'opus' | 'haiku' | 'inherit' | full model ID
-  permissionMode?: 'default' | 'acceptEdits' | 'bypass' | 'plan' | 'bypassPermissions'
+  // Hand-written union rather than `PermissionMode`: it also admits the legacy
+  // `'bypass'` alias that `resolveAgentMode` normalizes. Adding a mode to
+  // `PermissionMode` does **not** fail to compile here — keep the two in step.
+  permissionMode?: 'default' | 'acceptEdits' | 'bypass' | 'plan' | 'auto' | 'bypassPermissions'
   maxTurns?: number
   skills?: string
   background?: boolean

package/src/commands/autoloop-journal.ts

@@ -1,8 +1,8 @@
 import { mkdirSync, readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { homedir } from 'node:os'
+import { miphamHome } from '../core/paths.ts'
 
-const AUTOLOOP_DIR = join(homedir(), '.mipham', 'autoloop')
+const AUTOLOOP_DIR = miphamHome('autoloop')
 
 function ensureDir(): void {
   if (!existsSync(AUTOLOOP_DIR)) mkdirSync(AUTOLOOP_DIR, { recursive: true })

package/src/commands/environment.ts

@@ -6,6 +6,7 @@
  */
 import type { CommandHandler } from '../ui/commands.js'
 import { NPM_INSTALL_COMMAND } from '../shared/index.ts'
+import { miphamHome } from '../core/paths.ts'
 
 export { themeCmd, releaseNotesCmd, ideCmd, terminalSetupCmd }
 
@@ -186,7 +187,7 @@ const terminalSetupCmd: CommandHandler = async () => {
   const lines: string[] = ['── Terminal Setup ──', '']
 
   // ── 1. Generate standalone shell setup script ──
-  const miphamDir = join(home, '.mipham')
+  const miphamDir = miphamHome()
   mkdirSync(miphamDir, { recursive: true })
 
   const shellScript = join(miphamDir, 'shell-setup.sh')

package/src/commands/loop-scaffold.ts

@@ -12,6 +12,7 @@
 import { mkdirSync, writeFileSync, existsSync, chmodSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { homedir } from 'node:os'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
 export interface ScaffoldResult {
   created: string[]
@@ -89,7 +90,7 @@ export function scaffoldLoopKit(basePath: string): ScaffoldResult {
   const skipped: string[] = []
 
   const resolved = resolve(basePath.replace(/^~/, homedir()))
-  const miphamDir = join(resolved, '.mipham')
+  const miphamDir = join(resolved, MIPHAM_DIR)
 
   // ── .mipham/ root ──
   ensureDir(miphamDir, created, skipped)

package/src/commands/project.ts

@@ -6,10 +6,14 @@
  * /security, /audit, /prompt-audit
  */
 import type { CommandHandler, CommandContext, CommandResult } from '../ui/commands.js'
+import type { PermissionMode } from '../shared/index.ts'
 import { getWorkspaceTrust } from '../core/workspace-trust'
 import { atomicWriteFileSync } from '../shared/atomic-write'
 import { CLOUD_PROVIDERS } from '../config/wizard-config'
+import { MODE_CYCLE, PERMISSION_MODE_HIERARCHY } from '../core/permission-config'
 import { homedir } from 'node:os'
+import { miphamHome } from '../core/paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
 export {
   initCmd,
@@ -22,6 +26,58 @@ export {
   trustCmd,
 }
 
+/**
+ * One description per mode — exhaustive by type, so adding a member to
+ * `PermissionMode` fails to compile until it is described here.
+ *
+ * `/permissions` and `/setup 5` both render from this single table. Each used to
+ * carry its own hand-written list, and they had already drifted: `/setup 5` was
+ * still listing the retired 3-level `auto`/`ask`/`bypass` spellings and telling
+ * the user to run `/config permission <level>` — a command that has never existed
+ * (`/config` takes no arguments). Descriptions state what the mode does **today**.
+ */
+const MODE_DESCRIPTIONS: Record<PermissionMode, string> = {
+  plan: 'reads only (Read/Grep/Glob); nothing writes or runs',
+  default: 'per-tool defaults (Bash/Write/Edit are refused, not queued)',
+  acceptEdits: 'reads + edits free; Bash auto-runs read/check commands',
+  auto: 'a classifier rules on each call that would otherwise be refused (reads are never gated)',
+  bypassPermissions: 'skip ALL permission checks (⚠️ use with caution)',
+}
+
+/**
+ * The mode table, in `PERMISSION_MODE_HIERARCHY` order — i.e. least → most
+ * permissive, which is what the heading above it claims. The order comes from the
+ * hierarchy array, never from this file, so it cannot disagree with the ranking
+ * `clampMode` actually walks.
+ */
+function renderModeTable(): string {
+  return PERMISSION_MODE_HIERARCHY.map((m) => `  ${m.padEnd(19)}— ${MODE_DESCRIPTIONS[m]}`).join(
+    '\n',
+  )
+}
+
+/**
+ * What Shift+Tab reaches, in the order the wheel visits it — derived from
+ * `MODE_CYCLE` rather than hand-written.
+ *
+ * Deliberately its **own line**, not the table above: the table is the
+ * permissiveness ladder (every legal mode, in `PERMISSION_MODE_HIERARCHY` order)
+ * while this is the cycle, and those two are *allowed* to differ — that is the
+ * entire reason `ALL_MODES` and `MODE_CYCLE` are separate arrays. Rendering one
+ * list as if it were the other is what the old copy did, and it is how a help
+ * screen comes to advertise a mode the wheel cannot reach.
+ *
+ * `src/ui/app.tsx` used to keep its own copy of this order (`PERMISSION_MODES`).
+ * The two happened to agree on the day each was written — which is the state that
+ * reads as safe and is not: the copy is what would have kept the footer saying
+ * `bypassPermissions` after the wheel moved to `auto`. It now imports `MODE_CYCLE`
+ * like this file does, so the help line and the footer are one list by
+ * construction.
+ */
+function renderCycleLine(): string {
+  return MODE_CYCLE.join(' → ')
+}
+
 /**
  * provider id → 环境变量名，例如 `minimax-global` → `MINIMAX_GLOBAL_API_KEY`。
  *
@@ -36,15 +92,12 @@ function envVarFor(providerId: string): string {
 
 const initCmd: CommandHandler = async (ctx) => {
   const { existsSync, mkdirSync } = await import('node:fs')
-  const { join } = await import('node:path')
-  const { homedir } = await import('node:os')
 
-  const home = homedir()
-  const userConfigPath = join(home, '.mipham', 'config.yml')
+  const userConfigPath = miphamHome('config.yml')
 
   // Generate user-friendly config if it doesn't exist yet
   if (!existsSync(userConfigPath)) {
-    mkdirSync(join(home, '.mipham'), { recursive: true })
+    mkdirSync(miphamHome(), { recursive: true })
 
     // 生成物必须来自随包发布的清单，不能来自 ctx.config —— 后者的 status 表达
     // 的是「用户停用了哪家」这个**运行时**状态，而 12 家里只有 mipham 声明了它
@@ -89,7 +142,7 @@ const initCmd: CommandHandler = async (ctx) => {
 # ── Defaults ──
 defaultProvider: ${ctx.providerId}
 defaultModel: ${ctx.modelId}
-permission: ask
+permission: default
 
 # ── Providers (${presetProviders.length} pre-configured — just add your API keys) ──
 providers:
@@ -186,11 +239,12 @@ Mode:       ${ctx.engine.getPermission().getMode()}
 Messages:   ${msgs.length} in context
 Tools:      ${ctx.engine.getTools().size} available
 
-Switch mode with Shift+Tab. Modes (least → most permissive):
-  default            — per-tool defaults (Bash/Write/Edit ask first)
-  acceptEdits        — reads + edits free; Bash auto-runs read/check commands
-  plan               — reads only (Read/Grep/Glob); nothing writes or runs
-  bypassPermissions  — skip ALL permission checks (⚠️ use with caution)
+Shift+Tab cycles: ${renderCycleLine()} (this session only).
+To persist a mode, set \`permission:\` in .mipham/config.yml — every mode below is
+accepted there.
+
+Modes (least → most permissive):
+${renderModeTable()}
 
 To let Bash run without asking: press Shift+Tab until the status line shows
 "acceptEdits", then send your message again.
@@ -338,7 +392,7 @@ const recommendCmd: CommandHandler = async (ctx) => {
   lines.push('── Configuration Tips ──')
   lines.push('')
 
-  const hasProjectMipham = existsSync(join(cwd, '.mipham'))
+  const hasProjectMipham = existsSync(join(cwd, MIPHAM_DIR))
   if (!hasProjectMipham) {
     lines.push('  /setup 1     Initialize .mipham/ + MIPHAM.md + config.yml')
   }
@@ -391,12 +445,11 @@ const setupCmd: CommandHandler = async (ctx, args) => {
   const { existsSync } = await import('node:fs')
   const { join } = await import('node:path')
   const cwd = process.cwd()
-  const home = homedir()
 
   const hasProjectMipham = existsSync(join(cwd, 'MIPHAM.md'))
-  const hasProjectConfig = existsSync(join(cwd, '.mipham', 'config.yml'))
-  const hasUserConfig = existsSync(join(home, '.mipham', 'config.yml'))
-  const hasMiphamDir = existsSync(join(cwd, '.mipham'))
+  const hasProjectConfig = existsSync(join(cwd, MIPHAM_DIR, 'config.yml'))
+  const hasUserConfig = existsSync(miphamHome('config.yml'))
+  const hasMiphamDir = existsSync(join(cwd, MIPHAM_DIR))
 
   const activeProviders = ctx.config.providers.filter((p) => p.status === 'active').length
   const totalProviders = ctx.config.providers.length
@@ -444,7 +497,7 @@ async function setupStep1(ctx: CommandContext): Promise<CommandResult> {
   const { join } = await import('node:path')
   const cwd = process.cwd()
 
-  const miphamDir = join(cwd, '.mipham')
+  const miphamDir = join(cwd, MIPHAM_DIR)
   const miphamPath = join(cwd, 'MIPHAM.md')
   const configPath = join(miphamDir, 'config.yml')
 
@@ -511,7 +564,7 @@ async function setupStep1(ctx: CommandContext): Promise<CommandResult> {
 # ── Defaults ──
 defaultProvider: ${ctx.providerId}
 defaultModel: ${ctx.modelId}
-permission: ask
+permission: default
 
 # ── Providers (${presetProviders.length} pre-configured — just add your API keys) ──
 providers:
@@ -687,14 +740,19 @@ async function setupStep5(ctx: CommandContext): Promise<CommandResult> {
   return {
     content: `── Step 5: Permissions Setup ──
 
-Current mode: ${ctx.config.permission}
+Current mode:  ${ctx.engine.getPermission().getMode()}
+config.yml:    ${ctx.config.permission}
 
-Permission levels:
-  auto    — Run tools automatically (suitable for sandboxed envs)
-  ask     — Prompt before each tool execution (default, recommended)
-  bypass  — Skip all checks (⚠ only for trusted codebases)
+Shift+Tab cycles: ${renderCycleLine()} (this session only).
 
-  Change with: /config permission <level>
+Modes (least → most permissive):
+${renderModeTable()}
+
+To persist one for a project, .mipham/config.yml:
+  permission: acceptEdits
+  permissionRules:
+    allow: ["Bash(npm test)"]     # or: /permissions allow "Bash(npm test)"
+    deny:  ["Bash(rm *)"]
 
 Available tools (${ctx.engine.getTools().size}):
   File:  read, write, edit, glob, grep
@@ -703,12 +761,6 @@ Available tools (${ctx.engine.getTools().size}):
   Net:   web-fetch, web-search
   Sys:   config, mcp
 
-Each tool category can be configured independently in .mipham/config.yml:
-  permissions:
-    file: ask
-    exec: ask
-    network: auto
-
 Next: /setup 6 for shell integration`,
   }
 }
@@ -784,7 +836,8 @@ To persist across sessions, add to .mipham/config.yml:
       - ${resolved}
 
 The AI can now access files in this directory.
-Permission level is controlled by /config permission <level>.`,
+Permission mode: Shift+Tab cycles ${renderCycleLine()} (this session);
+\`permission:\` in .mipham/config.yml persists one.`,
   }
 }
 
@@ -872,8 +925,8 @@ const promptAuditCmd: CommandHandler = async () => {
 
   // Files to scan
   const scanDirs = [
-    join(cwd, '.mipham', 'skills'),
-    join(cwd, '.mipham', 'rules'),
+    join(cwd, MIPHAM_DIR, 'skills'),
+    join(cwd, MIPHAM_DIR, 'rules'),
     join(cwd, '.claude'),
   ]
   const skillFiles: string[] = []

package/src/config/keys-manager.ts

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import { atomicWriteFileSync } from '../shared/atomic-write'
 import { saveProviderApiKey } from './loader'
+import { miphamHome } from '../core/paths.ts'
 
-const MIPHAM_HOME = join(homedir(), '.mipham')
+const MIPHAM_HOME = miphamHome()
 const KEYS_FILE = join(MIPHAM_HOME, 'keys.json')
 const EXPIRY_DAYS = 90
 

package/src/config/loader.ts

@@ -8,7 +8,6 @@ import {
   chmodSync,
 } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { homedir } from 'node:os'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { atomicWriteFileSync } from '../shared/atomic-write'
 import type {
@@ -29,8 +28,10 @@ import {
 } from './defaults'
 import { getCredentialKey, encryptApiKey, decryptApiKey, ENC_PREFIX } from './credential-crypto'
 import type { SettingsHooks } from '../core/hooks-config'
+import { miphamHome } from '../core/paths.ts'
+import { MIPHAM_DIR } from '../shared/constants.ts'
 
-const MIPHAM_HOME = join(homedir(), '.mipham')
+const MIPHAM_HOME = miphamHome()
 const BACKUP_PREFIX = 'config.backup-'
 
 /**
@@ -212,7 +213,7 @@ export function tryRestoreFromBackup(configPath: string): boolean {
 function loadMcpJson(cwd: string): McpServerConfig[] {
   const servers: McpServerConfig[] = []
   const searchPaths = [
-    join(cwd, '.mipham', 'mcp.json'),
+    join(cwd, MIPHAM_DIR, 'mcp.json'),
     join(cwd, '.mcp.json'),
     join(MIPHAM_HOME, 'mcp.json'),
   ]
@@ -294,7 +295,7 @@ export function loadSettingsJson(
 
   const searchPaths: Array<{ path: string; readHooks: boolean; isProject?: boolean }> = [
     {
-      path: join(cwd, '.mipham', 'settings.json'),
+      path: join(cwd, MIPHAM_DIR, 'settings.json'),
       readHooks: options.includeProjectHooks ?? false,
       isProject: true,
     },
@@ -366,7 +367,7 @@ export type SettingsScope = 'project' | 'user'
 export function settingsPathFor(scope: SettingsScope, cwd: string = process.cwd()): string {
   return scope === 'user'
     ? join(MIPHAM_HOME, 'settings.json')
-    : join(cwd, '.mipham', 'settings.json')
+    : join(cwd, MIPHAM_DIR, 'settings.json')
 }
 
 /**
@@ -442,7 +443,7 @@ export function removeSettingsRule(
 }
 
 export function loadConfig(cwd: string = process.cwd()): MiphamConfig {
-  const configPath = join(cwd, '.mipham', 'config.yml')
+  const configPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
 
   let config = { ...DEFAULT_CONFIG }
@@ -629,7 +630,7 @@ function mergeCredentialMaskingFile(
 export function loadCredentialMaskingConfig(cwd: string = process.cwd()): CredentialMaskingConfig {
   let merged = { ...DEFAULT_CREDENTIAL_MASKING_CONFIG }
   merged = mergeCredentialMaskingFile(merged, join(MIPHAM_HOME, 'config.yml'), true)
-  merged = mergeCredentialMaskingFile(merged, join(cwd, '.mipham', 'config.yml'), false)
+  merged = mergeCredentialMaskingFile(merged, join(cwd, MIPHAM_DIR, 'config.yml'), false)
   return merged
 }
 
@@ -655,7 +656,7 @@ export function loadUserCredentialMaskingConfig(): CredentialMaskingConfig {
  * Load background agent configuration from config sources.
  */
 export function loadBackgroundAgentConfig(cwd: string = process.cwd()): BackgroundAgentConfig {
-  const configPath = join(cwd, '.mipham', 'config.yml')
+  const configPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
 
   let merged = { ...DEFAULT_BACKGROUND_AGENT_CONFIG }
@@ -688,7 +689,7 @@ export function loadBackgroundAgentConfig(cwd: string = process.cwd()): Backgrou
  * Merges project-level over user-level. Returns defaults if no section present.
  */
 export function loadCrossSessionConfig(cwd: string = process.cwd()): CrossSessionConfig {
-  const configPath = join(cwd, '.mipham', 'config.yml')
+  const configPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
 
   let merged = { ...DEFAULT_CROSS_SESSION_CONFIG }
@@ -751,7 +752,7 @@ function decryptProviderApiKeys(providers: ProviderConfig[] | undefined): void {
  */
 export function getProviderApiKey(providerId: string, cwd: string = process.cwd()): string | null {
   const userConfigPath = join(MIPHAM_HOME, 'config.yml')
-  const projectConfigPath = join(cwd, '.mipham', 'config.yml')
+  const projectConfigPath = join(cwd, MIPHAM_DIR, 'config.yml')
   const configPath = existsSync(userConfigPath) ? userConfigPath : projectConfigPath
 
   try {