@chanlerdev/scorel 0.0.1 → 0.0.2

package/docs/spec/extensions.md

@@ -57,45 +57,42 @@ type ScorelEvent =
 
 ## 3. Extensions 系统
 
-### 3.1 接口
+S0083 后，已落地的 Extension 形态是 manifest-driven IM extension。它先服务 IM channel 接入，不把完整 plugin marketplace 一次性做完。
+
+### 3.1 Manifest
+
+每个 extension 目录包含：
+
+```text
+scorel.extension.json
+adapter.js
+skills/
+```
+
+最小 schema：
 
 ```typescript
-interface Extension {
+type ExtensionManifest = {
   id: string;
-  name: string;
-  version: string;
-
-  activate?(ctx: ExtensionContext): Promise<void>;
-  deactivate?(): Promise<void>;
-
-  tools?(): AgentTool[];                           // 追加工具
-  commands?(): Record<string, SlashCommand>;        // 追加斜杠命令
-  onEvent?(event: ScorelEvent, ctx: ExtensionContext): Promise<void>;
-  hooks?(): Partial<{
-    beforeToolCall: BeforeToolCallHook;
-    afterToolCall: AfterToolCallHook;
-    transformContext: TransformContextHook;
-  }>;
-}
-
-interface ExtensionContext {
-  readonly agent: Agent;
-  readonly session: SessionStore;
-  readonly config: Config;
-  readonly logger: Logger;
-}
+  kind: "im";
+  displayName: string;
+  adapter: string;
+  skills?: string[];
+  mcp?: unknown[];
+};
 ```
 
-Extension 可以注入四种能力：工具、斜杠命令、事件监听、原生 Hook。四种都不是必选，一个扩展可以只做最小的一件事。
+`mcp` 在 S0083 只解析保留，不启动 MCP server。
 
 ### 3.2 加载路径与时机
 
-```
-~/.scorel/extensions/    ← 全局
-.scorel/extensions/       ← 项目级
+```text
+extensions/builtin/       ← 内置，只读，随包发布
+~/.scorel/extensions/     ← 用户级
+.scorel/extensions/       ← 项目级，后续扩展
 ```
 
-启动时扫描 `.ts` / `.js`，动态 `import()`，调用 `activate()`。项目级覆盖全局。
+Host 启动时读取 config 中 enabled 的 extension，然后加载对应 manifest。V1 已实现 built-in/user root；项目级 root 仍是后续扩展点。
 
 ### 3.3 错误隔离
 
@@ -117,7 +114,7 @@ class ExtensionRunner {
 }
 ```
 
-**单个 Extension 挂掉绝不影响核心和其他 Extension。** 原生 Hook 的链式包装里同样有 try/catch 兜底，但拦截失败会直接跳过该层。
+**单个 Extension 挂掉绝不影响核心和其他 Extension。** IM adapter 启动失败只写 diagnostics 并跳过该 extension。
 
 ---
 
@@ -163,33 +160,104 @@ class PromptBuilder {
 
 环境变量不参与通用配置覆盖，只通过 `apiKeyEnv` 指向具体密钥。CLI 参数也不复制完整 config schema；只有明确属于交互控制的参数才进入 CLI。
 
-### 5.2 初期配置示例
+配置保存和配置展示只记录 / 返回 `apiKeyEnv`，不读取或保存 raw API key。缺少对应环境变量时，Settings 可以显示 credential missing 状态；真正创建 runtime 或调用 provider 时才把缺失 env 作为错误抛出。
+
+### 5.2 Provider / Model Profile 配置示例
+
+S0073 后，旧的单 `[model]` 配置被替换为 provider / provider models / available models / role profile 四层合同。
 
-pi-ai 已支持的内置 provider 使用 `type = "builtin"`，Scorel 只把 provider/model/api key 交给 pi-ai，不在本仓库重写 provider 协议：
+pi-ai 已支持的内置 provider 使用 `type = "builtin"`。Scorel 只把 provider/model/api key 交给 pi-ai，不在本仓库重写 provider 协议：
 
 ```toml
-[model]
+[providers.openai]
 type = "builtin"
 provider = "openai"
-id = "gpt-5.4-mini"
 apiKeyEnv = "SCOREL_API_KEY"
+
+[provider_models.openai_gpt_54_mini]
+provider = "openai"
+id = "gpt-5.4-mini"
+displayName = "GPT 5.4 Mini"
+
+[provider_models.openai_gpt_54_nano]
+provider = "openai"
+id = "gpt-5.4-nano"
+displayName = "GPT 5.4 Nano"
+
+[available_models.main]
+model = "openai_gpt_54_mini"
+displayName = "GPT 5.4 Mini"
+
+[available_models.aux]
+model = "openai_gpt_54_nano"
+displayName = "GPT 5.4 Nano"
+
+[model_profile.roles]
+primary = "main"
+standard = "main"
+auxiliary = "aux"
 ```
 
-自定义兼容 endpoint 使用 `type = "custom"`，并显式声明兼容协议。这个分支和 builtin provider 分开，避免把任意自定义 endpoint 混成 pi-ai 内置 provider：
+自定义兼容 endpoint 使用 `type = "custom"`，并显式声明兼容协议。这个分支和 builtin provider 分开，避免把任意自定义 endpoint 混成 pi-ai 内置 provider。Custom model 必须手动声明 context metadata，因为自定义 endpoint 不一定能可靠 discover model catalog：
 
 ```toml
-[model]
+[providers.chanleramp]
 type = "custom"
 api = "openai-completions"
 provider = "chanleramp"
-id = "gpt-5.4-mini"
 baseUrl = "https://amp.chanler.dev/v1"
 apiKeyEnv = "SCOREL_API_KEY"
+
+[provider_models.chanleramp_gpt_54_mini]
+provider = "chanleramp"
+id = "gpt-5.4-mini"
+displayName = "GPT 5.4 Mini"
 contextWindow = 400000
 maxTokens = 128000
 reasoning = true
+
+[provider_models.chanleramp_deepseek_v4_flash]
+provider = "chanleramp"
+id = "deepseek-v4-flash"
+displayName = "DeepSeek Flash"
+contextWindow = 128000
+maxTokens = 32000
+reasoning = false
+
+[available_models.main]
+model = "chanleramp_gpt_54_mini"
+displayName = "GPT 5.4 Mini"
+
+[available_models.aux]
+model = "chanleramp_deepseek_v4_flash"
+displayName = "DeepSeek Flash"
+
+[model_profile.roles]
+primary = "main"
+standard = "main"
+auxiliary = "aux"
 ```
 
+`providers.*` 是 LLM provider connection：供应商名称、协议/API shape、base URL 和 API key env var。一个 provider connection 可以对应多个 `provider_models.*`。
+
+`provider_models.*` 是 provider connection 下记录的候选模型。它描述真实 provider model id、展示名和自定义 endpoint 必需的 context metadata。
+
+`available_models.*` 是 Scorel 的 available model / use pool。它们从 `provider_models.*` 里引用少量真正允许 Scorel 使用的模型；Runtime、GUI composer 和未来 subagent selection 只能选择 pool 内模型，不能直接选择 provider catalog 或 provider model 里的任意条目。
+
+GUI 的 provider/model 写入必须 merge 到现有 `.scorel/config.toml`：同一 provider 下追加第二个 provider model，或把 provider model 加入 available models 时，不能删除已存在 provider、provider model、available model 或 role assignment，除非用户明确覆盖对应字段。
+
+Scorel 仍处在开发阶段，没有存量配置兼容要求。旧 `[models.*]` section 不再支持；遇到旧 section 必须按未知 section 报错。
+
+`model_profile.roles` 是 V1 的用途绑定：
+
+```text
+primary   -> 最强/最稳的主 agent 模型
+standard  -> 默认日常模型
+auxiliary -> 轻量辅助模型
+```
+
+这些 role 名是通用产品语义，不绑定 Opus / Sonnet / Haiku 这类具体供应商命名。
+
 `api` 初期只接受以下四个值：
 
 ```text
@@ -214,20 +282,24 @@ name = "github"
 transport = "stdio"
 command = "mcp-server-github"
 
-[extensions]
-disabled = ["experimental-memory"]
+[extensions.loopback]
+enabled = true
+kind = "im"
+
+[extensions.loopback.config]
+botTokenEnv = "SCOREL_LOOPBACK_TOKEN"
 ```
 
 ### 5.3 Schema 规则
 
 配置必须通过 `SCOREL_CONFIG_SCHEMA` 校验。未知 section 和未知 key 都应由通用 schema 校验拒绝，例如根级 `sessionsDir = "/tmp/nope"` 必须报 `Unsupported config key: sessionsDir`，不能为单个字段写特殊判断。
 
-当前已落地的稳定 section 只有 `[model]`。未来新增 `[tools]` / `[mcp]` / `[extensions]` 时，必须先把字段加入 schema，再接入加载逻辑和测试。
+当前已落地的稳定 section 是 `[providers.*]`、`[provider_models.*]`、`[available_models.*]`、`[model_profile.roles]`、`[memory]`、`[extensions.*]` 和 `[extensions.*.config]`。未来新增 `[tools]` / `[mcp]` 时，必须先把字段加入 schema，再接入加载逻辑和测试。
 
 ### 5.4 延后段落
 
 - `[permissions]` — 权限策略。初期工具默认全允许，权限审批整体后补
-- `[channels.telegram]` / `[channels.wechat]` — IM Channel 配置
+- 真实 IM 配置，例如 Telegram bot token env，由对应 extension spec 定义
 - `[mcp.servers.*.tier]` / `keywords` — MCP 分级加载配置
 
 这些段落的 schema 会在对应模块落地时补入，初期不预留任何半成品字段。
@@ -241,13 +313,13 @@ disabled = ["experimental-memory"]
 - 广播事件：`turn_finish` / `turn_error` / `rewind` / `compact`
 - Extension 加载 + 错误隔离（`tools` / `commands` / `onEvent`）
 - System Prompt 组装与预算
-- TOML 配置的核心段：`[model]`，并通过 `SCOREL_CONFIG_SCHEMA` 统一拒绝未知 section/key
+- TOML 配置的核心段：`[providers.*]` / `[provider_models.*]` / `[available_models.*]` / `[model_profile.roles]`，并通过 `SCOREL_CONFIG_SCHEMA` 统一拒绝未知 section/key
 
 **延后**
 - Extension 的沙箱与权限边界（现阶段信任本地扩展）
 - Prompt 的模板化与多语种切换
 - 热更新配置（初期启动时读一次即可）
-- `[tools]` / `[channels]` / `[mcp]` / `[extensions]` 的完整配置 schema
+- `[tools]` / `[mcp]` 的完整配置 schema
 - Skills 加载（`~/.scorel/skills/*/SKILL.md`）
 
 ---

package/docs/spec/ship/S0062-npm-package-and-release-workflow.md

@@ -115,6 +115,7 @@ publish: true | false
 The workflow must:
 
 - install pnpm from `packageManager`
+- install system tools required by the release check path, including `ripgrep` for the `Glob` and `Grep` coding-tool tests
 - run `pnpm install --frozen-lockfile`
 - run `pnpm release <bump> --dry-run` by default
 - require `NPM_TOKEN` only for a real publish
@@ -127,6 +128,7 @@ The workflow must:
 - `pnpm pack:smoke` packs and installs the tarball into a temporary project, then runs `scorel --help`.
 - `pnpm release patch --dry-run` runs the full dry-run path and exits 0.
 - `.github/workflows/release.yml` exists and manually triggers the same release command.
+- `.github/workflows/release.yml` installs `ripgrep` before running the release command, so the repo-level test suite matches the product's rg-backed coding tools.
 - `docs/ROADMAP.md` includes S0062 as Done only after verification.
 - `docs/CHANGELOG.md` records release infrastructure under Unreleased until the first release moves it to a version section.
 
@@ -163,4 +165,5 @@ git diff --check
 - Bundling can accidentally include development-only code. Keep `files` restricted to `dist`, README, and selected docs.
 - Publishing internal packages too early would create API stability pressure. Keep only root `@chanlerdev/scorel` public in S0062.
 - Real npm publish requires `chanlerdev` authentication locally or `NPM_TOKEN` in GitHub Actions.
+- GitHub hosted runners do not guarantee `rg` is available. Install `ripgrep` explicitly in release workflow setup instead of skipping the rg-backed tool tests.
 - A release script that mutates versions before verification can leave the repo dirty after failures. Run verification before mutation for normal release, and keep dry-run non-mutating.

package/docs/spec/ship/S0063-ai-release-notes.md

@@ -0,0 +1,129 @@
+# S0063: AI Release Notes
+
+## Goal
+
+Make every normal Scorel release produce transparent, user-readable changelog notes by default. The notes are generated from the commits since the previous `v*` release tag using DeepSeek V4 Flash, then inserted into `docs/CHANGELOG.md` before the release commit is created.
+
+## Scope
+
+- Add a release-notes generator that:
+  - finds commits in a supplied release range
+  - collects commit file names and diff stats before collecting patches
+  - skips generated files such as `dist/`, source maps, lockfiles, `.next/`, and `node_modules/` before reading patch content
+  - summarizes each commit as structured JSON evidence
+  - aggregates commit summaries into release-level structured JSON
+  - renders Markdown suitable for `docs/CHANGELOG.md`
+- Use DeepSeek official Chat Completions endpoint:
+  - default base URL: `https://api.deepseek.com/v1`
+  - default model: `deepseek-v4-flash`
+  - API key env: `DEEPSEEK_API_KEY`
+  - non-thinking request: `thinking: { "type": "disabled" }`
+  - JSON mode: `response_format: { "type": "json_object" }`
+- Treat `docs/spec/ship/S*.md` diffs as important product context in the system prompt, without parsing spec structure.
+- Make `pnpm release <patch|minor|major>` generate notes by default.
+- Add `--no-generate-notes` as the explicit release escape hatch.
+- Add a standalone preview/debug command:
+
+```bash
+pnpm release-notes --from v0.0.1 --to HEAD --version 0.0.2
+```
+
+- Update the manual GitHub Actions release workflow so CI releases use the same default notes behavior and can disable it explicitly.
+
+## Non-Goals
+
+- Do not build a full release management product.
+- Do not parse SHIP spec sections such as Goal, Scope, or Acceptance Criteria in S0063.
+- Do not publish GitHub Releases in S0063.
+- Do not require AI release notes when the operator explicitly passes `--no-generate-notes`.
+- Do not use mock provider behavior as proof for any real product path. Script unit tests may use injected fetch and git runners.
+
+## Contract
+
+### Default Release
+
+```bash
+pnpm release patch
+```
+
+must:
+
+- compute the next version from the current package version
+- find the previous `v*` tag for the release range
+- generate AI release notes before mutating versions
+- insert rendered notes under `## Unreleased` in `docs/CHANGELOG.md`
+- continue the existing verification, version bump, build, pack smoke, commit, tag, publish, and push path
+
+### Explicit Skip
+
+```bash
+pnpm release patch --no-generate-notes
+```
+
+must preserve the previous minimal changelog section behavior.
+
+### Dry Run
+
+```bash
+pnpm release patch --dry-run
+```
+
+must print the generated release notes preview when DeepSeek credentials are available. If credentials are missing or DeepSeek fails during dry run, the script may print a deterministic fallback preview and continue.
+
+### Standalone Preview
+
+```bash
+pnpm release-notes --from v0.0.1 --to HEAD --version 0.0.2
+```
+
+must print Markdown notes only. It must not bump versions, write files, create commits, tag, publish, or push.
+
+## Acceptance Criteria
+
+- `scripts/release-notes.mjs` exists and can be used as both an importable module and a CLI.
+- Root `package.json` includes `release-notes`.
+- Commit summary and release aggregation prompts require strict JSON output and mention SHIP specs as important context.
+- DeepSeek requests use `https://api.deepseek.com/v1` and `deepseek-v4-flash` by default, with large output token limits appropriate for a high-context release task.
+- Generated diffs are skipped before patch reads, so release-note collection does not depend on reading large bundled artifacts into a Node child-process buffer.
+- Oversized non-generated diffs are truncated before being sent to the model.
+- `scripts/release.mjs` generates notes by default and supports `--no-generate-notes`.
+- `.github/workflows/release.yml` exposes a `generate_notes` input that defaults to true and passes `DEEPSEEK_API_KEY` for release-note generation.
+- `docs/CHANGELOG.md` receives a full Markdown release section when notes generation is enabled.
+- `docs/ROADMAP.md` lists S0063 as Done after implementation and verification.
+
+## Test Requirements
+
+Run:
+
+```bash
+node --test scripts/release-notes.test.mjs
+pnpm release-notes --from v0.0.1 --to HEAD --version 0.0.2
+pnpm release patch --dry-run
+pnpm typecheck
+pnpm test
+git diff --check
+```
+
+The standalone `pnpm release-notes` command may require `DEEPSEEK_API_KEY` for the AI path. Tests must cover the deterministic collector, prompt payload, Markdown renderer, changelog insertion, and dry-run fallback behavior without calling the real API.
+
+Collector tests must cover a commit that changes generated files plus a real release script file, and assert that the collector never calls `git show --patch` for generated files or for the whole commit patch.
+
+## Affected Paths
+
+- `package.json`
+- `scripts/release.mjs`
+- `scripts/release-notes.mjs`
+- `scripts/release-notes.test.mjs`
+- `.github/workflows/release.yml`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+- `docs/CHANGELOG.md`
+- `docs/spec/ship/S0063-ai-release-notes.md`
+- `docs/superpowers/plans/2026-06-08-s0063-ai-release-notes.md`
+
+## Risks
+
+- AI may overstate work. Mitigate with commit-level evidence, strict JSON validation, conservative prompts, and explicit handling of SHIP specs as context rather than proof of shipped behavior.
+- Large diffs can exceed practical request size, and generated bundle diffs can exceed Node child-process output buffers before the model is called. Exclude generated files before patch reads, then truncate oversized non-generated patches while preserving file names and diff stats.
+- Release should not silently ship empty notes. Formal releases fail on AI generation errors unless `--no-generate-notes` is explicit; dry-run can fall back for preview.
+- DeepSeek API shape may drift. Keep base URL, model, and token limits configurable through environment variables.

package/docs/spec/ship/S0064-gui-product-intent-and-boundary.md

@@ -0,0 +1,79 @@
+# S0064: GUI Product Intent And Boundary
+
+## Goal
+
+Lock M9 GUI as a Project-first desktop app before implementation. The GUI should feel and behave like a Codex App-style workbench: local-first, project-centric, quiet, dense, and built for repeated engineering work.
+
+## Scope
+
+- Define GUI as an independent desktop app under `apps/gui`.
+- Use Electron for the first GUI implementation because the current Scorel runtime, Host, CLI, Relay client, and package graph are TypeScript / Node-first.
+- Keep the public `@chanlerdev/scorel` npm package focused on the CLI / Host / Relay operator surface; GUI distribution is separate.
+- Define GUI information architecture:
+  - Project-first main workspace.
+  - Settings manages Devices and connectors.
+  - Device identity is metadata and connection source, not the main navigation root.
+- Define local behavior:
+  - GUI main process uses embedded local Host.
+  - Local Host Registry projects are all visible in the GUI project list.
+- Define remote behavior:
+  - M9 remote scope is Relay-only.
+  - Settings can add Relay Devices.
+  - Remote Projects appear only after the user explicitly selects them in GUI.
+  - GUI must not auto-display the full remote Host Registry the way WebUI does.
+- Define design direction:
+  - Codex App is the primary product reference.
+  - Existing WebUI components and style rules may be reused where they match the GUI product model.
+
+## Non-Goals
+
+- Do not scaffold Electron in S0064.
+- Do not implement GUI screens.
+- Do not add SSH, direct WS + token, OAuth, account systems, or GUI auto-update.
+- Do not publish or package desktop installers.
+- Do not change the public npm CLI package surface.
+
+## Contract
+
+### Product Model
+
+WebUI and GUI intentionally differ:
+
+- WebUI is Device-first. After a Device is connected, WebUI shows the Device Host Registry's full Project list.
+- GUI is Project-first. Local Projects are shown in full, but remote Projects are curated by explicit user selection.
+
+### Desktop Boundary
+
+Electron main process may depend on Node-only Scorel packages and own local Host lifecycle. Electron renderer must remain an Entry UI: it may call GUI bridge APIs or `@scorel/client`, but it must not hold Runtime, write JSONL, or duplicate Host domain logic.
+
+### Remote Boundary
+
+M9 remote work uses Relay only. SSH Remote Device remains M10. Direct WS + token remains an advanced/non-M9 path.
+
+## Acceptance Criteria
+
+- `docs/ROADMAP.md` splits M9 into executable S specs.
+- `docs/spec/ship/S0064-gui-product-intent-and-boundary.md` records the GUI product boundary.
+- The spec clearly states Electron is a GUI app distribution choice, not a change to the public npm CLI package.
+- The spec clearly states remote Project visibility differs from WebUI.
+- The spec clearly states M9 remote scope is Relay-only.
+
+## Test Requirements
+
+Docs-only:
+
+```bash
+git diff --check
+```
+
+## Affected Paths
+
+- `docs/ROADMAP.md`
+- `docs/spec/ship/S0064-gui-product-intent-and-boundary.md`
+- `self/discussions/2026-06-08-repo-sync-and-m9-next-step.md`
+
+## Risks
+
+- Electron may inflate install size. This is acceptable for GUI distribution but must not leak into the CLI npm package.
+- Reusing WebUI too directly can accidentally preserve Device-first information architecture. S0064 locks Project-first as the GUI product rule.
+- Showing all remote Projects would expose too much remote workspace state and weaken the desktop curation model.

package/docs/spec/ship/S0065-gui-electron-shell-and-embedded-host.md

@@ -0,0 +1,73 @@
+# S0065: GUI Electron Shell And Embedded Host
+
+## Goal
+
+Create the first `apps/gui` Electron app shell and connect it to the local embedded Scorel Host. After this spec, opening the GUI should prove that desktop main process, renderer, and local Host lifecycle can cooperate without duplicating Runtime or Session ownership.
+
+## Scope
+
+- Add `apps/gui` workspace package.
+- Add Electron main process and renderer entry.
+- Add a small GUI bridge between renderer and main process.
+- Start or attach to an embedded local Host from the GUI main process.
+- Expose local Host connection state to the renderer.
+- List local Host Registry Projects through Host / client APIs.
+- Keep UI minimal: enough shell to show local connection and Project list placeholder.
+- Keep GUI distribution separate from `@chanlerdev/scorel` npm CLI package.
+
+## Non-Goals
+
+- Do not implement full chat UX.
+- Do not implement Relay Device settings.
+- Do not implement remote Project selection.
+- Do not package signed desktop installers.
+- Do not implement auto-start, tray behavior, or auto-update.
+- Do not add SSH or direct WS connector support.
+
+## Acceptance Criteria
+
+- `apps/gui` exists and is included in the workspace.
+- GUI can be launched in development from a root script or package script.
+- Electron main owns embedded local Host startup / connection.
+- Renderer can display local Host status and local Project list from the embedded Host.
+- Renderer does not import `@scorel/core` or directly write session JSONL.
+- Existing CLI release package does not include GUI files unless a later spec explicitly changes desktop distribution.
+
+## Test Requirements
+
+Run focused checks for the GUI package plus existing repo checks:
+
+```bash
+pnpm --filter @scorel/app-gui build
+pnpm --filter @scorel/app-gui typecheck
+pnpm --filter @scorel/app-gui test
+pnpm typecheck
+pnpm test
+pnpm pack:smoke
+git diff --check
+```
+
+GUI smoke command:
+
+```bash
+pnpm gui
+```
+
+If GUI smoke cannot run in the current environment, document the limitation in the final handoff.
+
+## Affected Paths
+
+- `package.json`
+- `pnpm-lock.yaml`
+- `pnpm-workspace.yaml`
+- `.gitignore`
+- `apps/gui/**`
+- `packages/client/**` if bridge/client APIs need small reuse adjustments
+- `docs/ROADMAP.md`
+- `docs/spec/ship/S0065-gui-electron-shell-and-embedded-host.md`
+
+## Risks
+
+- Electron dependency churn can bloat the monorepo. Keep GUI dependencies scoped to `apps/gui`.
+- Renderer/main boundaries can become leaky. Treat renderer as an Entry UI and keep Host ownership in main.
+- Embedded Host lifecycle may diverge from CLI `scorel` behavior. Reuse existing Host APIs where possible instead of creating GUI-only behavior.

package/docs/spec/ship/S0066-gui-local-project-workspace.md

@@ -0,0 +1,79 @@
+# S0066: GUI Local Project Workspace
+
+## Goal
+
+Make the GUI useful for local work: show all local Projects in a Project-first workspace, let the user create or open Sessions, and provide the first local chat surface over the embedded Host.
+
+## Scope
+
+- Build the Project-first main GUI layout:
+  - Project list as the primary navigation.
+  - Session list scoped to the selected Project.
+  - Chat / composer surface for the selected Session.
+- Show all Projects from the local Host Registry.
+- Add local Project through a desktop folder picker and `registerProject(workDir)`.
+- Create a new Session for a selected local Project.
+- Load existing Sessions via `listSessions({ projectId })`.
+- Send prompts through the same Host / DaemonClient path used by other entries.
+- Reuse WebUI rendering pieces only where they fit Codex App-style desktop UX.
+
+## Non-Goals
+
+- Do not add Relay Device settings.
+- Do not add remote Project selection.
+- Do not implement SSH or direct WS.
+- Do not implement advanced Codex App features such as diffs, file tree, approval UI, terminal panes, or task tabs.
+- Do not add model picker functionality unless it already exists as a shared product path.
+
+## Acceptance Criteria
+
+- GUI starts with local Projects visible without requiring Device selection.
+- Selecting a local Project shows its Sessions.
+- New Session creates a Session bound to the selected `projectId`.
+- Sending a prompt uses the embedded local Host and writes a real JSONL Session.
+- Local Project addition uses the system folder picker and Host `registerProject`.
+- Local Project list updates after registration.
+- UI is Project-first; Device is not the main navigation hierarchy.
+
+## Test Requirements
+
+Run:
+
+```bash
+pnpm --filter @scorel/app-gui build
+pnpm --filter @scorel/app-gui typecheck
+pnpm --filter @scorel/app-gui test
+pnpm typecheck
+pnpm test
+pnpm pack:smoke
+git diff --check
+```
+
+GUI smoke command:
+
+```bash
+pnpm gui
+```
+
+Manual smoke must use:
+
+- real local temporary Project directory
+- embedded local Host
+- real JSONL Session
+- real provider for at least one prompt if this spec wires chat sending end to end
+
+If provider credentials are unavailable, automated GUI tests must still cover the prompt-send path with a real `ScorelRuntime` and fake provider.
+
+## Affected Paths
+
+- `apps/gui/**`
+- `packages/client/**` if shared session projection needs extraction
+- `packages/daemon/**` only for reusable embedded Host API gaps
+- `docs/ROADMAP.md`
+- `docs/spec/ship/S0066-gui-local-project-workspace.md`
+
+## Risks
+
+- Over-copying WebUI can recreate Device-first navigation. Keep Project as the first-level object.
+- Local folder picker can tempt renderer-side filesystem access. Use main process bridge and Host APIs; renderer should not become the owner of Project canonicalization.
+- Chat surface scope can grow. Keep S0066 focused on local session creation, display, and prompt sending.