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: 5c61110f465cc4172f712ad435c06041c0aed1ec
- 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.