dominds 1.2.5 → 1.2.7

package/dist/cli/install.js

@@ -13,10 +13,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const installed_file_1 = require("../apps/installed-file");
+const app_lock_file_1 = require("../apps/app-lock-file");
+const assigned_port_1 = require("../apps/assigned-port");
+const resolution_file_1 = require("../apps/resolution-file");
 const run_app_json_1 = require("../apps/run-app-json");
-const runtime_port_1 = require("../apps/runtime-port");
-const time_1 = require("../shared/utils/time");
 function printHelp() {
     console.log(`Usage:
   dominds install <spec|path> [--local] [--id <appId>] [--enable] [--force]
@@ -28,7 +28,7 @@ Options:
   --force              Replace existing installed entry with the same id
 
 Notes:
-  - State is stored in ${installed_file_1.INSTALLED_APPS_REL_PATH} under the current rtws (process.cwd()).
+  - State is stored in ${resolution_file_1.APPS_RESOLUTION_REL_PATH} under the current rtws (process.cwd()).
   - dominds installs apps by running '<app> --json' via npx or local package bin.
 `);
 }
@@ -103,9 +103,9 @@ async function main() {
     }
     const localAbs = path_1.default.resolve(rtwsRootAbs, specOrPath);
     const shouldUseLocal = args.local || (await pathIsDirectory(localAbs));
-    const loadedInstalled = await (0, installed_file_1.loadInstalledAppsFile)({ rtwsRootAbs });
-    if (loadedInstalled.kind === 'error') {
-        console.error(`Error: failed to read ${installed_file_1.INSTALLED_APPS_REL_PATH}: ${loadedInstalled.errorText}`);
+    const loadedResolution = await (0, resolution_file_1.loadAppsResolutionFile)({ rtwsRootAbs });
+    if (loadedResolution.kind === 'error') {
+        console.error(`Error: failed to read ${resolution_file_1.APPS_RESOLUTION_REL_PATH}: ${loadedResolution.errorText}`);
         process.exit(1);
         return;
     }
@@ -117,33 +117,55 @@ async function main() {
         process.exit(1);
         return;
     }
-    const prev = loadedInstalled.file.apps.find((a) => a.id === installJson.appId) ?? null;
+    const prev = loadedResolution.file.apps.find((a) => a.id === installJson.appId) ?? null;
     if (prev && !args.force) {
         console.error(`Error: app '${installJson.appId}' already installed. Use 'dominds update ${installJson.appId}' or 'dominds install ... --force'.`);
         process.exit(1);
         return;
     }
-    const now = (0, time_1.formatUnifiedTimestamp)(new Date());
-    const enabled = args.enable || (prev ? prev.enabled : false);
-    const runtimePort = await (0, runtime_port_1.resolveStableAppRuntimePort)({
+    const userEnabled = args.enable || (prev ? prev.userEnabled : false);
+    const enabled = userEnabled;
+    const assignedPort = await (0, assigned_port_1.resolveStableAssignedPort)({
         appId: installJson.appId,
         installJson,
-        existingApps: loadedInstalled.file.apps,
-        existingRuntimePort: prev?.runtime.port ?? null,
+        existingApps: loadedResolution.file.apps,
+        existingAssignedPort: prev?.assignedPort ?? null,
     });
     const entry = {
         id: installJson.appId,
         enabled,
+        userEnabled,
         source: shouldUseLocal
             ? { kind: 'local', pathAbs: localAbs }
             : { kind: 'npx', spec: specOrPath },
-        runtime: { port: runtimePort },
+        assignedPort,
         installJson,
-        installedAt: prev ? prev.installedAt : now,
-        updatedAt: now,
     };
-    const nextFile = (0, installed_file_1.upsertInstalledApp)({ existing: loadedInstalled.file, next: entry });
-    await (0, installed_file_1.writeInstalledAppsFile)({ rtwsRootAbs, file: nextFile });
+    const nextFile = (0, resolution_file_1.upsertResolvedApp)({ existing: loadedResolution.file, next: entry });
+    await (0, resolution_file_1.writeAppsResolutionFile)({ rtwsRootAbs, file: nextFile });
+    try {
+        const loadedLock = await (0, app_lock_file_1.loadAppLockFile)({ rtwsRootAbs });
+        if (loadedLock.kind === 'error') {
+            console.error(`Warning: failed to read .minds/app-lock.yaml: ${loadedLock.errorText}`);
+        }
+        else {
+            const nextLock = (0, app_lock_file_1.upsertLockedApp)({
+                existing: loadedLock.file,
+                next: {
+                    id: entry.id,
+                    source: entry.source,
+                    package: {
+                        name: entry.installJson.package.name,
+                        version: entry.installJson.package.version,
+                    },
+                },
+            });
+            await (0, app_lock_file_1.writeAppLockFileIfChanged)({ rtwsRootAbs, file: nextLock });
+        }
+    }
+    catch (err) {
+        console.error(`Warning: failed to update .minds/app-lock.yaml: ${err instanceof Error ? err.message : String(err)}`);
+    }
     console.log(shouldUseLocal
         ? `Installed app '${entry.id}' from local package: ${localAbs}`
         : `Installed app '${entry.id}' via npx spec: ${specOrPath}`);

package/dist/cli/uninstall.js

@@ -13,7 +13,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const installed_file_1 = require("../apps/installed-file");
+const resolution_file_1 = require("../apps/resolution-file");
 function printHelp() {
     console.log(`Usage:
   dominds uninstall <appId> [--purge]
@@ -54,20 +54,20 @@ async function main() {
         return;
     }
     const rtwsRootAbs = process.cwd();
-    const loaded = await (0, installed_file_1.loadInstalledAppsFile)({ rtwsRootAbs });
+    const loaded = await (0, resolution_file_1.loadAppsResolutionFile)({ rtwsRootAbs });
     if (loaded.kind === 'error') {
-        console.error(`Error: failed to read ${installed_file_1.INSTALLED_APPS_REL_PATH}: ${loaded.errorText}`);
+        console.error(`Error: failed to read ${resolution_file_1.APPS_RESOLUTION_REL_PATH}: ${loaded.errorText}`);
         process.exit(1);
         return;
     }
-    const found = (0, installed_file_1.findInstalledApp)(loaded.file, args.appId);
+    const found = (0, resolution_file_1.findResolvedApp)(loaded.file, args.appId);
     if (!found) {
         console.error(`Error: app '${args.appId}' not installed`);
         process.exit(1);
         return;
     }
-    const next = (0, installed_file_1.removeInstalledApp)({ existing: loaded.file, appId: args.appId });
-    await (0, installed_file_1.writeInstalledAppsFile)({ rtwsRootAbs, file: next });
+    const next = (0, resolution_file_1.removeResolvedApp)({ existing: loaded.file, appId: args.appId });
+    await (0, resolution_file_1.writeAppsResolutionFile)({ rtwsRootAbs, file: next });
     if (args.purge) {
         const rtwsAppDirAbs = path_1.default.resolve(rtwsRootAbs, '.apps', args.appId);
         await promises_1.default.rm(rtwsAppDirAbs, { recursive: true, force: true });

package/dist/cli/update.js

@@ -12,10 +12,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const path_1 = __importDefault(require("path"));
-const installed_file_1 = require("../apps/installed-file");
+const app_lock_file_1 = require("../apps/app-lock-file");
+const assigned_port_1 = require("../apps/assigned-port");
+const resolution_file_1 = require("../apps/resolution-file");
 const run_app_json_1 = require("../apps/run-app-json");
-const runtime_port_1 = require("../apps/runtime-port");
-const time_1 = require("../shared/utils/time");
 function printHelp() {
     console.log(`Usage:
   dominds update [<appId>]
@@ -52,16 +52,22 @@ async function main() {
         return;
     }
     const rtwsRootAbs = process.cwd();
-    const loaded = await (0, installed_file_1.loadInstalledAppsFile)({ rtwsRootAbs });
+    const loaded = await (0, resolution_file_1.loadAppsResolutionFile)({ rtwsRootAbs });
     if (loaded.kind === 'error') {
-        console.error(`Error: failed to read ${installed_file_1.INSTALLED_APPS_REL_PATH}: ${loaded.errorText}`);
+        console.error(`Error: failed to read ${resolution_file_1.APPS_RESOLUTION_REL_PATH}: ${loaded.errorText}`);
         process.exit(1);
         return;
     }
+    const loadedLock = await (0, app_lock_file_1.loadAppLockFile)({ rtwsRootAbs });
+    const shouldUpdateLock = loadedLock.kind === 'ok';
+    if (loadedLock.kind === 'error') {
+        console.error(`Warning: failed to read .minds/app-lock.yaml: ${loadedLock.errorText}`);
+    }
+    let nextLock = loadedLock.kind === 'ok' ? loadedLock.file : null;
     const targets = args.appId === null
         ? [...loaded.file.apps]
         : (() => {
-            const found = (0, installed_file_1.findInstalledApp)(loaded.file, args.appId);
+            const found = (0, resolution_file_1.findResolvedApp)(loaded.file, args.appId);
             if (!found) {
                 console.error(`Error: app '${args.appId}' not installed`);
                 process.exit(1);
@@ -70,7 +76,6 @@ async function main() {
             return [found];
         })();
     let nextFile = loaded.file;
-    const now = (0, time_1.formatUnifiedTimestamp)(new Date());
     for (const entry of targets) {
         const installJson = entry.source.kind === 'npx'
             ? await (0, run_app_json_1.runDomindsAppJsonViaNpx)({ spec: entry.source.spec, cwdAbs: rtwsRootAbs })
@@ -80,22 +85,42 @@ async function main() {
         if (installJson.appId !== entry.id) {
             throw new Error(`Update failed: appId mismatch for '${entry.id}': got '${installJson.appId}' from --json handshake`);
         }
-        const runtimePort = await (0, runtime_port_1.resolveStableAppRuntimePort)({
+        const assignedPort = await (0, assigned_port_1.resolveStableAssignedPort)({
             appId: entry.id,
             installJson,
             existingApps: nextFile.apps,
-            existingRuntimePort: entry.runtime.port,
+            existingAssignedPort: entry.assignedPort,
         });
         const updated = {
             ...entry,
-            runtime: { port: runtimePort },
+            assignedPort,
             installJson,
-            updatedAt: now,
         };
-        nextFile = (0, installed_file_1.upsertInstalledApp)({ existing: nextFile, next: updated });
+        nextFile = (0, resolution_file_1.upsertResolvedApp)({ existing: nextFile, next: updated });
+        if (shouldUpdateLock && nextLock) {
+            nextLock = (0, app_lock_file_1.upsertLockedApp)({
+                existing: nextLock,
+                next: {
+                    id: updated.id,
+                    source: updated.source,
+                    package: {
+                        name: updated.installJson.package.name,
+                        version: updated.installJson.package.version,
+                    },
+                },
+            });
+        }
         console.log(`Updated app '${entry.id}'`);
     }
-    await (0, installed_file_1.writeInstalledAppsFile)({ rtwsRootAbs, file: nextFile });
+    await (0, resolution_file_1.writeAppsResolutionFile)({ rtwsRootAbs, file: nextFile });
+    if (shouldUpdateLock && nextLock) {
+        try {
+            await (0, app_lock_file_1.writeAppLockFileIfChanged)({ rtwsRootAbs, file: nextLock });
+        }
+        catch (err) {
+            console.error(`Warning: failed to update .minds/app-lock.yaml: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
 }
 if (require.main === module) {
     main().catch((err) => {

package/dist/dialog.js

@@ -514,6 +514,7 @@ class Dialog {
                 msgId: (0, id_1.generateShortId)(),
                 grammar: 'markdown',
                 userLanguageCode: this._lastUserLanguageCode,
+                origin: 'runtime',
             }
             : prompt;
         const trimmed = prepared.content.trim();
@@ -532,6 +533,7 @@ class Dialog {
             msgId: normalized.msgId,
             grammar: normalized.grammar,
             userLanguageCode: normalized.userLanguageCode,
+            origin: normalized.origin,
             q4hAnswerCallIds: normalized.q4hAnswerCallIds,
             runControl: undefined,
         };
@@ -550,6 +552,7 @@ class Dialog {
             msgId: options.msgId,
             grammar: options.grammar,
             userLanguageCode: options.userLanguageCode ?? this._lastUserLanguageCode,
+            origin: options.origin,
             q4hAnswerCallIds: options.q4hAnswerCallIds,
             runControl: options.runControl,
         };
@@ -560,6 +563,7 @@ class Dialog {
                 msgId: options.msgId,
                 grammar: options.grammar,
                 userLanguageCode: options.userLanguageCode ?? this._lastUserLanguageCode,
+                origin: options.origin,
                 q4hAnswerCallIds: options.q4hAnswerCallIds,
             },
             runControl: options.runControl,
@@ -622,6 +626,7 @@ class Dialog {
             msgId: (0, id_1.generateShortId)(),
             grammar: 'markdown',
             userLanguageCode: this._lastUserLanguageCode,
+            origin: 'runtime',
         };
         const runControlSpec = options?.runControl ?? this._activeRunControlSpec;
         let nextPrompt = basePrompt;

package/dist/docs/app-constitution.md

@@ -18,10 +18,60 @@ This document covers:
 - “Dev app” mode: allow an rtws to run _as_ a Dominds app during development, reusing the same directory structure/mechanisms.
 - Enhanced `.minds/team.yaml`: `use` / `import` to reference teammates provided by other apps, with clear execution context semantics.
 
-Relationship to `dominds/docs/kernel-app-architecture.md`:
+This document is the unified entry point for app-related semantics and mechanisms.
 
-- `kernel-app-architecture` focuses on runtime skeleton: registry, resolution, defunc semantics, IPC.
-- This doc focuses on: the app package + `.minds/**` asset contract, override mechanisms, and team composition semantics.
+## Roadmap: Phases A/B/C/D (MVP = phase)
+
+This document uses **A/B/C/D** to describe the evolution phases of this feature.
+
+- What “**MVP=C**” means: the acceptance gate for this stage is the **Phase C** checklist (i.e. only Phase C capabilities are required for this milestone; anything outside Phase C is not part of the gate even if implemented).
+- Phases are not a compatibility/stability promise: Dominds is still in a prototype/alpha iteration mode; phases are used to define **scope + acceptance focus** for this feature.
+
+> Note: This roadmap is an RFC-ish “scope definition”; it does not automatically imply everything is implemented today. The rest of this doc still marks items as “Current (implemented)” vs “Target (planned)”.
+
+### Phase A: Concepts and minimal skeleton (Foundations)
+
+Goal: make the kernel/app boundary and the minimal data flow runnable, so the install/resolve/boot path can be validated.
+
+- Key capabilities (at minimum):
+  - App install handshake (`<app> --json`) can be consumed by the kernel/CLI.
+  - App manifest (`.minds/app.yaml`) schema/loader is available.
+  - Basic local resolution strategy (`local`) works: discover local apps under `<rtws>/dominds-apps/<appId>/`.
+
+### Phase B: Team composition and cross-app references (Team Composition)
+
+Goal: allow app-provided teammates to participate in team composition, with explicit execution-context semantics for cross-app references.
+
+- Key capabilities (at minimum):
+  - Load enabled apps’ teammates YAML (with workspace overrides).
+  - Workspace `.minds/team.yaml` supports explicit cross-app referencing via `members.<id>.from + (use|import)`.
+  - Name collisions / reference failures are diagnosed and routed through Problems/defunc (retryable).
+
+### Phase C: MVP gate (deps/lock/override contract/port pinning/Problems)
+
+Goal: close the loop for “dependency resolution + observability + regressability”, so dogfooding is diagnosable and recoverable.
+
+- Key capabilities (must-pass):
+  - required/optional dependencies:
+    - optional missing/disabled: silently skipped (must not block startup; Problems not required; debug logs allowed).
+    - required missing/disabled: must not block startup; must be observable in WebUI Problems; related capability enters defunc/unavailable.
+  - required disable propagation:
+    - `<rtws>/.apps/resolution.yaml` must represent both user intent (explicit user disable) and the propagated effective state.
+    - when dependencies recover, propagated disables must auto-recover (without overriding explicit user disables).
+  - Override precedence (documented contract): `rtws override > app override > app defaults`.
+  - Lock semantics (design contract): `.minds/app-lock.yaml` freezes dependency versions only; enable/disable must not jitter the lock.
+  - assignedPort: once pinned, `assignedPort` must be non-zero; conflicts must be surfaced and re-assigned; uninstall naturally frees ports.
+  - Problems: Problems ids use a stable prefix (currently `apps/apps_resolution/`); after a fix, issues must reconcile/clear (no permanent residue).
+
+### Phase D: Integrator packaging and UX (Integration & UX)
+
+Goal: let an integrator app ship publishable default overrides for dependency apps, and polish the observability/Problems experience.
+
+- Key capabilities (target):
+  - app override: app packages may ship default overrides for dependency apps (publishable integration config), while rtws overrides still take precedence.
+  - Override surface expands to more `.minds/**` assets (persona/knowledge/lessons, memory, mcp, etc.).
+  - Problems mechanism enhancements: record and display “occurred at / resolved at / resolved state”, and allow “clear resolved” in UI.
+  - More complete error-path contracts (corrupt YAML, partial availability, recovery strategy) with regression coverage.
 
 ## Non-goals
 
@@ -29,6 +79,22 @@ Relationship to `dominds/docs/kernel-app-architecture.md`:
 - No sandbox/isolation definition (permissions/resource isolation is out of scope).
 - Not a full implementation plan; we keep implementation details as “anchors”.
 
+## Kernel-App Runtime Skeleton
+
+The following rules define the key runtime boundaries between kernel and apps:
+
+- Resolution order inside an app is fixed: `local(app) -> kernel`.
+- Override semantics: overrides happen at the **configuration layer**, not by “registering and overwriting” runtime objects:
+  - For a given app asset path `p`: `<rtws>/.apps/override/<app-id>/.minds/<p>` (rtws override) wins over the app package default.
+  - (Target: planned) an app integrator may ship _app overrides_ for its dependency apps (e.g. default overrides packaged with the app), but rtws overrides still take precedence.
+  - Shadowing kernel registry names is not a goal: name collisions should be diagnosed explicitly (and handled via defunc / Problems), not silently overwritten by last-writer-wins.
+- Conflict semantics: import name conflicts or unsatisfied dependencies put the app into defunc.
+- Registry boundary: app objects do not register into kernel registry; defunc does not require “removing app objects from kernel”.
+- Observability: defunc reasons should surface in Problems (at minimum with `appId`, reason kind, and suggested action).
+- Retry semantics: defunc is retryable by default (reload on a later refresh cycle once dependency/config issues are fixed).
+- Fixed tool contract: `app_integration_manual({ appId, language? })` failures should be observable but must not trigger defunc.
+- Typical load sequence: register toolsets first, then team/imports, apply overrides, validate, and finally register members; failures result in defunc.
+
 ## Core concepts
 
 ### Kernel
@@ -114,7 +180,14 @@ Recommended principles:
 (Current: implemented) existing anchors:
 
 - JSON schema: `dominds/main/apps/app-json.ts` (`DomindsAppInstallJsonV1`).
-- Installed apps file: `dominds/main/apps/installed-file.ts`.
+- Apps resolution file: `dominds/main/apps/resolution-file.ts`.
+
+(Current: implemented) the kernel treats `<rtws>/.apps/resolution.yaml` as **overlay + strategy**:
+
+- If the file exists: `apps[]` is the overlay (stores `enabled` / `assignedPort` / `source` / `installJson`), and `resolutionStrategy?` (if present) overrides the default strategy.
+- If the file is missing: the overlay is empty, and the strategy falls back to defaults (`order=['local']`, `localRoots=['dominds-apps']`).
+
+So even without `<rtws>/.apps/resolution.yaml`, as long as `.minds/app.yaml` declares dependencies, the kernel still resolves local apps via the default strategy; if the root manifest has no dependencies, the effective enabled apps set is empty.
 
 ## App-provided `.minds/**` assets
 
@@ -145,8 +218,9 @@ It describes:
 - how those members see each other and collaborate within the app.
 
 > Current prototype behavior: the kernel loads enabled app teammates YAML and **additively merges `members` into workspace `.minds/team.yaml`**.
-> The merge happens in `dominds/main/team.ts` and the loader is `dominds/main/apps/teammates.ts`.
-> This is not yet equivalent to “per-app team + `use/import` semantics”.
+> Current (v0): the kernel loads enabled app teammates YAML but does **not** flatten-merge their `members` into workspace `.minds/team.yaml`.
+> You must explicitly reference a dependency app teammate via `members.<id>.from + (use|import)` in workspace `.minds/team.yaml`.
+> Loader: `dominds/main/apps/teammates.ts`; resolver/execution: `dominds/main/team.ts`.
 
 ### `.minds/mcp.yaml`
 
@@ -166,14 +240,6 @@ Key semantics:
 
 ## `<rtws>/.apps/override/<app-id>/`: override layer
 
-### `.apps/installed.yaml`
-
-(Current: implemented) The kernel stores the installed/enabled apps list in `<rtws>/.apps/installed.yaml`.
-
-This file is a source of truth for enabled apps snapshot.
-
-(Target: planned) Replace the mixed responsibilities of `.apps/installed.yaml` with `.minds/app-lock.yaml` + `<rtws>/.apps/resolution.yaml`.
-
 ### Override root
 
 (Target: planned) The workspace override directory for an app is:
@@ -206,8 +272,7 @@ Suggested override resolution for any app asset path `p`:
 
 This naturally supports “override dependency apps”: once a dependency app is enabled in the same rtws, it can be overridden via its own `.apps/<dep-id>/...` directory.
 
-> Alignment note: `kernel-app-architecture` already sketches a `<rtws>/.apps/<app-id>/team.yaml` override DSL.
-> This document generalizes the idea to the broader `.minds/**` asset set (not only team).
+> This document also covers the `<rtws>/.apps/<app-id>/team.yaml` override DSL concept, and generalizes it to broader `.minds/**` assets (not only team).
 
 #### Override scope (recommended)
 
@@ -265,7 +330,9 @@ Constraints:
 
 ### Suggested YAML shape
 
-> Note: syntax below is a target design; the current `.minds/team.yaml` parser does not support it yet.
+> Current (v0): the `.minds/team.yaml` parser supports this syntax.
+> However, since app-context isolation/bridging is not implemented yet, `use` and `import` are runtime-equivalent for now.
+> Also: `from`-only is accepted but has no effect in v0 (it is treated as a local member definition).
 
 Example snippet:
 
@@ -359,7 +426,7 @@ This makes it possible that:
 ## Implementation anchors (current code)
 
 - install json schema: `dominds/main/apps/app-json.ts`
-- installed apps file: `dominds/main/apps/installed-file.ts`
+- apps resolution file: `dominds/main/apps/resolution-file.ts`
 - apps runtime (proxy tools): `dominds/main/apps/runtime.ts`
 - app teammates loader (prototype flat merge): `dominds/main/apps/teammates.ts`, `dominds/main/team.ts`
 - manifest parser: `dominds/main/apps/manifest.ts`

package/dist/docs/app-constitution.zh.md

@@ -17,10 +17,60 @@
 - “开发中 app（dev app）”模式：让一个 rtws 以一个 Dominds App 的身份运行，从而复用相同的目录结构与机制。
 - `.minds/team.yaml` 的增强语法：支持 `use`/`import` 引用其它 app 提供的 teammate，并定义运行上下文与诉请语义。
 
-本文与 `dominds/docs/kernel-app-architecture.zh.md` 的关系：
+本文作为 App 相关语义与机制的统一入口。
 
-- `kernel-app-architecture` 更关注“registry/解析/defunc/IPC”等运行时骨架。
-- 本文更关注“App 包与 `.minds/**` 资产的约定、覆盖机制、team 组装语义”。
+## 路线图：A/B/C/D 阶段（MVP=阶段）
+
+本文使用 **A/B/C/D** 表示该特性的演进阶段。
+
+- “**MVP=C**” 的含义：本阶段的验收口径以 **C 阶段**的清单为准（即：只要求达到 C 阶段所列能力；其它能力即使已实现，也不作为 C 阶段 gate）。
+- 阶段不等同于“兼容策略/稳定性承诺”：Dominds 仍处于原型期，阶段只用来定义**本特性**的可交付范围与验收重点。
+
+> 说明：本路线图是 RFC-ish 的“目标范围定义”，并不自动代表“当前实现已具备”。文中仍以“现状（已实现）/目标（拟实现）”分别标注。
+
+### 阶段 A：概念与最小骨架可跑（Foundations）
+
+目标：把 Kernel/App 的边界与最小数据流跑通，让“安装/解析/启动路径”可被验证。
+
+- 关键能力（至少）：
+  - App 的 install handshake（`<app> --json`）可被 Kernel/CLI 读取。
+  - App manifest（`.minds/app.yaml`）schema/loader 可用。
+  - 基本的本地解析策略（`local`）可工作：按 `<rtws>/dominds-apps/<appId>/` 发现本地 app。
+
+### 阶段 B：团队组装与跨 app 引用（Team Composition）
+
+目标：让 app 提供的 teammates 能参与 team 组装，并明确跨 app 引用的运行上下文语义。
+
+- 关键能力（至少）：
+  - 读取 enabled apps 的 teammates YAML（并支持 workspace override）。
+  - `.minds/team.yaml` 支持在 `members.<id>.from + (use|import)` 显式引用依赖 app 的 teammate。
+  - 同名冲突/引用失败可诊断，并进入 Problems/defunc 路径（可重试）。
+
+### 阶段 C：MVP gate（依赖/锁定/覆盖口径/端口固化/Problems）
+
+目标：把“依赖解析 + 可观测 + 可回归”的闭环打齐，确保 dogfooding 下可诊断、可恢复。
+
+- 关键能力（必过）：
+  - required/optional 依赖：
+    - optional 缺失/被 disable：静默跳过（不阻塞启动；不要求产生 Problems；允许 debug 日志）。
+    - required 缺失/被 disable：不阻塞启动；必须在 WebUI Problems 可观测；相关能力进入 defunc/不可用。
+  - disable 传导（required）：
+    - `<rtws>/.apps/resolution.yaml` 需要同时表达：用户意图（是否用户 disable）与被动传导后的有效状态。
+    - 依赖恢复后，能自动恢复被动传导导致的 disable（不覆盖用户显式 disable）。
+  - override 优先级（文档口径固定）：`rtws override > app override > app defaults`。
+  - lock 语义（设计口径）：`.minds/app-lock.yaml` 仅冻结依赖项版本；enable/disable 不应导致 lock 抖动。
+  - assignedPort：resolver 产出的 `assignedPort` 一旦固化必须为非 0；冲突时提示并重分配；卸载后自然回收。
+  - Problems：Problems id 使用稳定前缀（当前为 `apps/apps_resolution/`），修复后可 reconcile 清理（不应永久残留）。
+
+### 阶段 D：整合与体验完善（Integration & UX）
+
+目标：让 integrator app 能“可发布地整合”依赖 app 的默认覆盖，并完善 Problems/可观测性体验。
+
+- 关键能力（目标）：
+  - app override：app 包内可携带对依赖 app 的默认覆盖（作为 integrator 的可发布整合配置），且仍以 rtws override 为最高优先级。
+  - override 覆盖范围扩展到更多 `.minds/**` 资产（persona/knowledge/lessons、memory、mcp 等）。
+  - Problems 机制增强：记录并展示“发生时间/解决时间/已解决状态”，并支持“一键清理已解决项目”。
+  - 更完整的异常路径契约（损坏 YAML、部分可用、恢复策略）与回归覆盖。
 
 ## 非目标
 
@@ -28,6 +78,22 @@
 - 本文不定义 sandbox/隔离（例如权限隔离、资源隔离）。
 - 本文不把所有实现细节塞进来；实现锚点以“关键落点”形式列出。
 
+## Kernel–App 运行时骨架
+
+以下规则定义 Kernel 与 App 的关键运行时边界：
+
+- 解析顺序：app 内固定为 `local(app) -> kernel`。
+- 覆盖语义：覆盖按“配置层”发生，而不是按“对象注册”发生：
+  - 对同一 app 的资产路径 `p`：`<rtws>/.apps/override/<app-id>/.minds/<p>`（rtws override）优先于 app 包内默认值。
+  - （目标：拟实现）app 作为集成者可以为其依赖 app 提供 _app override_（例如随包发布的默认覆盖），但最终仍以 rtws override 为准。
+  - 对 kernel registry 的同名覆盖不是目标：同名冲突应被显式诊断（并按规则进入 defunc / Problems），而不是“后写覆盖前写”。
+- 冲突语义：import 引入同名冲突或依赖不满足时，app 进入 defunc。
+- registry 边界：app 对象不注册到 kernel registry；defunc 不涉及“从 kernel 移除 app 对象”。
+- 可观测性：defunc 原因应进入 Problems（至少可定位 `appId`、原因分类与建议动作）。
+- 重试语义：defunc 默认可重试（依赖或配置修复后，下一次刷新周期可重载）。
+- 固定工具契约：`app_integration_manual({ appId, language? })` 失败应可观测，但不触发 defunc。
+- 典型加载顺序：先解析并注册工具集，再读取 team 与 imports，应用 override，校验后注册成员；失败则 defunc。
+
 ## 核心概念
 
 ### Kernel
@@ -110,10 +176,17 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 - Install JSON 只承载“定位与缓存”所需的最小字段。
 - App 的能力清单（teammates/tools/web/seed 等）**只以 manifest 为准**，避免双写导致漂移。
 
-（现状：已实现）install json schema 与 installed apps 文件锚点仍可参考：
+（现状：已实现）install json schema 与 apps resolution 锚点仍可参考：
 
 - JSON schema：`dominds/main/apps/app-json.ts`（`DomindsAppInstallJsonV1`）。
-- `.apps/installed.yaml`：`dominds/main/apps/installed-file.ts`。
+- `.apps/resolution.yaml`：`dominds/main/apps/resolution-file.ts`。
+
+（现状：已实现）Kernel 的 app 解析以 `<rtws>/.apps/resolution.yaml` 提供 **overlay + strategy**：
+
+- 若文件存在：`apps[]` 作为 overlay（保存 `enabled` / `assignedPort` / `source` / `installJson`），`resolutionStrategy?`（若提供）覆盖默认策略。
+- 若文件不存在：overlay 视为空，strategy 使用默认值（`order=['local']`，`localRoots=['dominds-apps']`）。
+
+因此，即使缺少 `<rtws>/.apps/resolution.yaml`，只要 `.minds/app.yaml` 声明了依赖，Kernel 仍会按默认策略去解析本地 app；反之若根 manifest 没有依赖，则最终 enabled apps 为空。
 
 ## App 可提供的 `.minds/**` 资产
 
@@ -143,9 +216,9 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 - 这些 teammates 默认拥有哪些 toolsets/tools；
 - 这些 teammates 在 app 上下文里互相如何可见/可 tellask。
 
-> 现状：Kernel 目前已经支持“从 enabled apps 读取 teammates YAML 并把其 `members` 合并进 rtws 的 `.minds/team.yaml`”。
-> 该合并逻辑在 `dominds/main/team.ts`，读取逻辑在 `dominds/main/apps/teammates.ts`。
-> 但这仍是“原型期的扁平合并”，不等价于“每个 app 独立 team + use/import 语义”。
+> 现状（v0）：Kernel 会从 enabled apps 读取 teammates YAML，但**不会**把其 `members` 扁平合并进 rtws 的 `.minds/team.yaml`。
+> 你必须在 rtws 的 `.minds/team.yaml` 里通过 `members.<id>.from + (use|import)` 显式引用依赖 app 的 teammate。
+> 读取锚点：`dominds/main/apps/teammates.ts`；解析/落地锚点：`dominds/main/team.ts`。
 
 ### `.minds/mcp.yaml`
 
@@ -163,15 +236,7 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 - Kernel 不应自动把 `env.md` 写入 shell rc 或环境；它只提供可见性（文档/提示）。
 - 若 Kernel 提供“写入 rc managed block”的能力（例如 setup flow），也应基于明确的 UI/确认，而不是隐式执行。
 
-## `<rtws>/.apps/<app-id>/`：状态与覆盖层
-
-### `.apps/installed.yaml`
-
-（现状：已实现）Kernel 把“安装/启用的 apps 列表”写入 `<rtws>/.apps/installed.yaml`。
-
-它是 workspace 侧 app 系统的事实来源之一（至少用于 enabled apps snapshot）。
-
-（目标：拟实现）以 `.minds/app-lock.yaml` + `<rtws>/.apps/resolution.yaml` 替代 `.apps/installed.yaml` 的“混合职责”，将 enable/disable、来源解析、端口固化等收敛到 resolution 层。
+## `<rtws>/.apps/override/<app-id>/`：覆盖层
 
 ### 覆盖层目录（override root）
 
@@ -205,8 +270,7 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 
 这条规则天然支持“覆盖依赖 app”：只要某个依赖 app 在该 rtws 中被启用，workspace 就可以通过它自己的 `.apps/<dep-id>/...` 覆盖它。
 
-> 与 `kernel-app-architecture` 的对齐：该文档中已有 `<rtws>/.apps/<app-id>/team.yaml` override DSL 的构想；
-> 本文把“override”扩展到更通用的 `.minds/**` 资产（不仅限于 team）。
+> 本文同时覆盖 `<rtws>/.apps/<app-id>/team.yaml` override DSL 的构想，并扩展到更通用的 `.minds/**` 资产（不仅限于 team）。
 
 #### 覆盖范围（建议）
 
@@ -264,7 +328,8 @@ rtws 是一次运行的工作区根目录（`process.cwd()`）。Kernel 在其
 
 ### 建议的 YAML 形态
 
-> 注意：下述语法为目标设计；当前 `.minds/team.yaml` 的解析器尚未支持。
+> 现状（v0）：`.minds/team.yaml` 解析器已支持该语法。
+> 但由于 App 上下文隔离/桥接机制尚未完成，`use` 与 `import` 在运行时暂时等价（都会把来源 member 的配置导入为当前 team 的一个成员），差异仅作为未来语义的占位。
 
 示例（片段）：
 
@@ -358,7 +423,7 @@ Problem id 应体现“定义方 scope 的从属层级”，并保持短小稳
 ## 关键落点（现有实现锚点）
 
 - install json 解析：`dominds/main/apps/app-json.ts`
-- `.apps/installed.yaml`：`dominds/main/apps/installed-file.ts`
+- `.apps/resolution.yaml`：`dominds/main/apps/resolution-file.ts`
 - apps runtime（proxy tools）：`dominds/main/apps/runtime.ts`
 - app teammates loader（原型期扁平合并）：`dominds/main/apps/teammates.ts`、`dominds/main/team.ts`
 - manifest（`.minds/app.yaml`）解析：`dominds/main/apps/manifest.ts`

package/dist/docs/dialog-system.md

@@ -454,7 +454,7 @@ sequenceDiagram
 Q4H is raised when the `askHuman({ tellaskContent: "..." })` tellask function is invoked by ANY dialog (root or subdialog) on its own right:
 
 ```typescript
-// From main/llm/driver-v2/tellask-bridge.ts
+// From main/llm/kernel-driver/tellask-special.ts
 const isQ4H = callName === 'askHuman';
 ```
 

package/dist/docs/dialog-system.zh.md

@@ -445,7 +445,7 @@ sequenceDiagram
 当 `askHuman({ tellaskContent: "..." })` tellask 函数被任何对话（根或子对话）自行调用时，会提出 Q4H：
 
 ```typescript
-// 来自 main/llm/driver-v2/tellask-bridge.ts
+// 来自 main/llm/kernel-driver/tellask-special.ts
 const isQ4H = callName === 'askHuman';
 ```