makelore/.project-docs/30-worklog/tasks/20260906-project-setup-ux-90fe6cf2.md

Task: Review new project setup UX

Identity

• Task ID: 20260906-project-setup-ux-90fe6cf2
• Mode: Feature
• Branch: codex/20260906-project-setup-ux-90fe6cf2-project-setup-ux
• Worktree: D:\Datas\OthersProjects.codex-worktrees\makelore\20260906-project-setup-ux-90fe6cf2
• Base commit: 5c61110f46
• Owner: codex
• Status: Ready for Integration

Scope

• Review the new-project transition from Project Configuration to the first Coding Conversation, with particular attention to the zero-Agent state and the discoverability of the return/continue action.
• Verify the persisted readiness rule, route behavior, empty states, model prerequisite, and current product terminology before recommending an interaction change.
• Implement the accepted interaction direction with one shared Conversation-readiness rule, a strong first-Agent setup path, deterministic navigation, and a recoverable zero-Agent Conversation state.
• Add focused unit and Electron E2E coverage while keeping persistence, Pi runtime, Provider, Plugin, and Main/Renderer contracts unchanged.

Intent And Constraints

• Preserve the explicit product decision that new projects have no default project Agent and that the user chooses the Agent identity, model, responsibility, and Skills.
• Keep project-owned parent Agents distinct from short-lived runtime child Agents; do not describe the Project Configuration entity as a child Agent.
• Preserve Pi 0.84.2, .makelore ownership, the single light visual system, and the current Main/Renderer boundary.
• Prefer one explicit first-run completion path over a forced tutorial, compatibility layer, new state machine, or automatically fabricated default Agent.

Outcome

• Confirmed that the screenshot's “项目智能体” is the persisted project-owned parent Agent, not an ephemeral runtime child Agent, and retained that terminology throughout.
• Added one shared Conversation-readiness rule: initialized must be true and the project must contain at least one enabled, unarchived Agent with a non-empty name, avatar, role, responsibility, and resolved model. Project list entry, direct /chat resolution, the programming-module gate, and Coding chat now use the same rule instead of trusting initialized alone.
• Reworked the zero-ready-Agent configuration state into a prominent required-step card. With no model it offers “先配置模型” and a direct model-settings action; otherwise it creates the first Agent or resumes an enabled incomplete Agent. Disabled-only state intentionally offers a new Agent because the edit dialog has no enable control.
• The first Agent is persisted immediately and then navigates to /chat. Later Agent additions and edits retain the existing page-draft plus explicit-save behavior.
• Replaced history-relative back navigation with labelled, deterministic “返回对话” or “稍后设置” destinations. Unsaved Agent changes are confirmed before any page exit, including the model-settings prerequisite path.
• Archiving the last ready Agent now explains that saving will return the project to a pending state; saving that state clears initialized and leaves the unusable chat route.
• Added a full Coding chat recovery state with a direct project-configuration action and no Composer or Conversation/runtime creation when no usable Agent exists.
• Updated README with the accepted readiness and onboarding behavior.

Verification

• Focused Vitest: 5 files, 63 tests passed, covering readiness, App routing, MainLayout gating, Project Configuration onboarding/navigation, and Coding chat recovery.
• Full pnpm test: 230 files / 1928 tests passed with 2 skipped, followed by the isolated pressure test passing 1/1.
• pnpm run typecheck: passed after the final interaction changes.
• pnpm run lint:check: passed with 0 errors; it retained 5 pre-existing warnings in src/pages/Home/index.tsx and src/pages/Makelore/index.tsx.
• pnpm run build:vite: passed after the final interaction changes; only the repository's existing Browserslist, dynamic-import, and chunk-size warnings were emitted.
• Electron E2E project-configuration-skills.spec.ts: passed 1/1, including zero-model guidance, legacy initialized: true plus zero-Agent recovery, and labelled return to chat.
• Playwright trace inspection showed an initial E2E failure was caused by that spec's later restrictive Host API stub, not product navigation; the navigation assertion now runs before the stub and passes.
• Independent read-only review found the disabled-only recovery loop; after the targeted correction and test, the reviewer returned PASS.
• git diff --check: passed.
• With explicit human approval, rebuilt the unpushed main merge from a safety checkpoint and adopted the exact unchanged state of .project-docs/30-worklog/tasks/20260906-agent-browser-failure-a7c91e4d.md; the rebuilt feature tree matches the checkpoint tree exactly.
• check_project_docs.py and check_doc_drift.py --task-id 20260906-project-setup-ux-90fe6cf2 both passed after recovery.

Follow-ups

• No required implementation follow-up remains.

Promotion Candidates

• Target: .project-docs/30-worklog/current-state.md. Proposal: record that Coding Conversation readiness requires both persisted initialization and at least one enabled, unarchived, fully configured project Agent; all project-entry and chat-recovery surfaces share this invariant, and the first Agent setup is the explicit completion path. Evidence: shared readiness tests, Project Configuration onboarding tests, App/MainLayout route tests, Coding chat recovery tests, Electron E2E, successful full unit suite, typecheck, lint, production build, and independent review. Future impact: future project-entry, archival, or Agent-edit work must reuse the shared predicate rather than treating initialized as sufficient on its own. Semantic conflicts: none known; the rule preserves the existing no-default-Agent and project-owned Agent decisions. Human confirmation required: no, unless integration discovers a conflicting accepted product decision.