# Task: Discuss guided agent UX for beginners and children

## Identity

- Task ID: 20260914-agent-ux-discussion-930b45dd
- Mode: Feature
- Branch: codex/20260914-agent-ux-discussion-930b45dd-agent-ux-discussion
- Worktree: D:\Datas\OthersProjects\.codex-worktrees\makelore\20260914-agent-ux-discussion-930b45dd
- Base commit: 1d00ba39bd598e2f2ea26cc867d82afc2bdba3ee
- Owner: codex
- Status: Ready for Integration

## Scope

- Personal cloud Agents creation, requirements editing, model selection guidance, preview transitions/examples/comparison, readable execution confirmation, private-use handoff and desktop UI polish.
- Related unit tests, Electron interaction spec and README. Earlier discussion and interactive mockup led to the user accepting implementation in the same task.
- No changes to Main, cloud contracts, billing, auth, teacher/student permissions, knowledge processing, channel routing or scheduling semantics.

## Intent And Constraints

- Confirmed audience: ages 8–15, teacher guidance followed by independent use; nonprofessional adults also matter.
- Confirmed objective: independently create, test and improve a first helper. User accepted the short guide and editable requirements/preview sketch, then approved implementation.
- Concurrent and Planning Gates Passed through the loaded maintain-project-docs bundled check/start/status and required project-memory reads. Same-task feature owner, branch, base and isolated worktree match the identity above.
- Integrated project context remains unchanged. Other historical placeholder task records represent unknown coordination state; no concrete dependency blocks these Renderer edits. Active peer 20260914-cloud-reconnect-5ad71e6c owns Main session time validation and has no semantic overlap.
- Preserve saved/preview/published separation, recovery identities, creator payment and Main-owned backend access. No subagents, live paid requests, real account publication, merge, push or deployment.
- Keep system_prompt as the sole saved instruction source. Style choices add/remove exact plain-language instruction lines; editing other fields preserves arbitrary instructions verbatim.
- The catalog has no recommendation marker. Newly created assistants select the first actual available model, visibly editable; existing assistants never receive an automatic model change.

## Outcome

- Creation occupies a focused content area: choose one of four editable purpose starters or a custom idea, enter name/purpose/answer style/special requirements, then save and try the real assistant. Creation and uncertain retries retain the existing operation identity.
- Empty/list states use understandable wording and reflect disabled/archived status. Step navigation and leave protection preserve partial requirements, including when name and purpose remain empty.
- Requirements use three optional answer-style buttons plus free text. Advanced capability, knowledge and limit controls remain available behind an explicit toggle; their state and independent budget saves are preserved.
- Model selection is visible with explanations and loading-error retry. Only a fresh creation preselects an actual catalog model once. Missing models remain explicit; no fake recommendation or model capability is inferred.
- Example questions only fill the composer. Explicit save-and-retrial waits for a successful save, uses its returned revision, preserves existing typed text or reuses the last question without sending, and retains the previous trial for comparison.
- Current runs, queued work, approvals, attachments and uncertain operations block the replacement-trial action. Save-only and tab switching preserve the current trial. Prior-trial downloads continue to use that trial's own thread.
- Approval UI shows actual description/name and arguments with readable known labels, retaining complete technical details and unchanged batch decision/retry identities.
- First private-use confirmation shows availability and creator billing without unrelated sharing/API setup. It uses the existing publish operation, then opens a separate normal conversation. Subsequent sharing, applications, linked channels and version management remain available.
- Buttons in the editor have a minimum 40 px height; existing light theme and split layout remain. Headings/body wrap naturally; small-window panels and initial trial activation remain usable.
- README documents the resulting behavior. The WeChat status unit assertion now waits for the actual asynchronously loaded status rather than merely the presence of the initial placeholder.

## Verification

- pnpm 10.33.4 verified against packageManager; install --frozen-lockfile passed.
- Typecheck passed. lint:check passed with 8 pre-existing warnings (CloudChat/CloudCosts generation refs, existing mixed component exports and Home dependency).
- Relevant 4-file regression run: 55 tests passed. Final focused cloud-agents-page run: 18 tests passed, including one additional disabled/archived availability-label test (56 relevant tests across the final checked files).
- Production build:vite passed, including Renderer, Main, Preload and utility bundles. Existing chunk-size/mixed-import warnings remain.
- Electron cloud-agents.spec.ts passed with the real desktop shell and a test-owned Host API fixture. Covers guided creation, model selection, leave protection, save/start, fill-only examples, editing, Ctrl+S, history comparison, combined save/retrial, private-use handoff and the existing knowledge/budget/schedule path.
- Electron checked 1366×768 and 980×680 windows, 125%/150% zoom, fixed composer position, independent scroll, drag/keyboard divider and F6/Escape focus behavior. Inspected creation, requirements, wide/narrow editor and private-use screenshots; corrected creation's excessive vertical offset.
- Full pnpm test first stage: 236 files passed, 1 failed; 2069 tests passed, 1 failed, 2 skipped. Failure: tests/unit/pi-managed-worker-opener.test.ts:292 expects makelore-runtime-v6.mjs while the runtime generates v7. Both the v6 expectation and extension version 7 already exist at base 1d00ba39, and neither source was changed here. The release-proof summary also still names v6. This unrelated baseline inconsistency is recorded, not hidden by changing Pi in a UI task.
- The pressure test skipped by pnpm test's failing && chain was run separately: 1 test passed.
- No live cloud/model quality or student usability study; UI tests use fixture responses. The earlier mockup uses explicitly labeled sample answers and remains outside the repository.
- Final typecheck and production build passed after the creation-layout/status changes. Documentation drift and whitespace checks passed; task result is ready for local commit and registry completion. Generated reports, fixtures, logs and screenshots remain untracked/ignored or outside the repository.

## Follow-ups

- Integrate the completed UI branch through the project's normal integration workflow.
- Align the stale Pi managed-worker/release-proof version expectations with the authoritative extension version in a separate runtime task.
- Validate independent first creation and revision with younger and older students; no measured usability improvement is claimed.
- Knowledge/file simplification and teacher templates remain later work. No classroom role model has been introduced.

## Promotion Candidates

- Target: personal cloud Agent ADR/product positioning during Integration Gate. Proposal: record the confirmed ages 8–15, teacher-guided introduction and independent first-helper creation/testing/improvement objective. Evidence: explicit audience clarification and accepted sketch/implementation. Future impact: default UI prioritizes the creation/use loop. Semantic conflict: none with the personal-creator boundary. Human confirmation: objective and implementation direction accepted; no new teacher/student access model is authorized.
- Target: personal cloud Agent architecture/current state. Proposal: document guided Renderer requirements over the existing system_prompt and create/save/publish APIs, explicit save-and-retrial, and single-use model preselection only on fresh creation. Evidence: implementation, focused tests and Electron fixture checks above. Future impact: preserve cloud authority and existing recovery semantics in future UX work. Semantic conflicts: no cloud contract changes. Human confirmation: ordinary integration review.