[Spec] Phase 13: Guided onboarding, manual sharing, and self-contained macOS App

[Nowhitestar]

Phase closed under the accepted scope — September 29, 2026

Implementation and stable publication are complete under the September 15 scope in #170. The migration defect #200 is resolved, and the committed migration journal remains byte-for-byte preserved. #171 records completed v0.23.0 publication and closes the obsolete exact RC21-to-stable transition without claiming it was replayed.

The September 28 whole-App update to local build 0.26.0-local.20260928.1 / 1694 passed signed-bundle, App-owned Host/Capture, native-input readiness, database/configuration preservation and native icon-control checks. September 29 Host/database readback remains healthy. The waived fresh-install/legacy-upgrade and other historical journeys retain their explicit limitations; this closure does not mark them as new passes. Public reconciliation: #228.

Historical issue record

Current closeout checkpoint — 2026-09-15

Phase 13 implementation and stable publication are complete under the owner's explicitly accepted reduced validation scope. Only the ordinary final installed update remains deferred while the App is busy; #171 retains that unchecked outcome. Do not restart historical acceptance matrices.

• [P13-25] Complete consolidated public-install acceptance #170 is closed with the exact public RC21 and physical-Mac evidence, version-scoped reuse and explicit unperformed-journey risks.
• Stable v0.23.0 is published from accepted RC21 source ef9828a3d241acde0d05c8908e1d7b4023878760, build 1667. Publisher 34943140833 and independent public downloads, signatures, notarization, provenance and signed stable-feed verification pass.
• PR docs(release): close v0.23.0 stable guidance #218 publishes final release/README/version-maintenance guidance; website PR Nowhitestar/tingfengji#10 publishes the stable download entry. The Release body, main tree and actual production page are read back and match.
• Final-public fresh-local-runtime installation/full v0.22.2 upgrade and additional cloud/lifecycle/rollback repetitions are explicitly accepted risks, not new passes. The VM stays stopped. No OAuth, model or Notion-write repetition is needed.
• Remaining: allow the running App to become idle, complete the single ordinary RC21-to-stable whole-App update, verify service/data preservation, then close [P13-26] Promote the accepted source commit to v0.23.0 #171/[Spec] Phase 13: Guided onboarding, manual sharing, and self-contained macOS App #145 and the goal. Do not interrupt an active recording or claim that this deferred outcome passed.

Historical September 15 checkpoint — superseded above

Current closeout checkpoint — 2026-09-15

Phase 13 is still open. Use #170 for the remaining installed-candidate acceptance and #171 for conditional same-source stable publication; the original test matrix and dated checkpoints below are not a new execution queue.

• The consolidated RC21 is published from ef9828a3d241acde0d05c8908e1d7b4023878760, build 1666. Official publisher 34931133893 passed. Independent public-download digests/provenance, DMG/App signatures/notarization/staples, update signatures and unchanged stable feed are verified.
• The local Runtime Pack fixes (fix(audio): validate runtime packs without developer tools #212), installation-entry corrections (docs: distinguish DMG controls from legacy CLI #214), same-source promotion boundary (chore(release): prepare repaired RC21 promotion boundary #215) and legacy menu-bar retirement repair (fix(migration): retire legacy menu bar owner during upgrade #216) are merged. Source CI passed, and installed internal-App/component evidence is retained with its exact scope; it is not relabeled as final public-RC21 installed acceptance.
• Existing real recording, committed transcript/summary and verified manual-sharing evidence is retained. Do not repeat completed external writes. Sharing remains exclusively manual.
• Current English/Chinese README and issue-template guidance are published through docs: point install guidance to published RC21 #217. The landing-page RC21 link and footer are deployed through Nowhitestar/tingfengji#9 and anonymously read back. These documentation changes do not create another RC or change the candidate source.
• Remaining: finish the affected public local-runtime installation and automatic whole-App upgrade from the genuine v0.22.2 baseline, with preserved data and no duplicate owners. Reconcile applicable existing lifecycle/rollback evidence, then publish stable from that exact accepted RC21 source and verify the RC-to-stable whole-App update. Stable is not published.
• A new Grok OAuth login and fresh guest cloud-summary repetition are explicitly waived, not newly passing tests. Do not request them again. Do not inspect password stores, copy credentials, reset permissions, patch signed Apps, switch providers silently or create another VM.

Historical closeout checkpoint — 2026-09-11

The business requirements below remain in force, but their original baseline and RC4 reference are historical. Use docs/phase13-closeout.md, #209 and #170/#171 for current closure, not a fresh execution of the original plan.

Migration attempt 7 is committed on the physical Mac. Complete local dev8 has ready Host/Capture and passed installed Sharing discovery plus the separate read-only connector probe. Earlier dev6 passed a real synthetic recording through committed transcript/summary with zero automatic sharing. Its success is not current xAI readiness: the saved xAI grant is temporarily unreadable. The newer late-startup shell fix passed CI and is awaiting the consolidated whole-App validation artifact.

The user has declined password access. Do not inspect password applications/stores or credential material, alter access controls, or retry local signing. The current batch uses existing CI signing to produce one internal whole-App validation artifact; it creates no public RC, Release or update feed. Verify accounts only through normal product UI. Positive Test Share/manual Share readback awaits a designated test parent.

Consolidate the observed defects, verify the changed paths proportionately, preserve applicable completed evidence, then publish one consolidated candidate. No VM per candidate; use an existing isolated environment only if a final clean-state requirement actually needs it. #145/#170/#171 stay open until their actual remaining outcomes are verified. Public RC19 is not accepted for stable promotion.

Problem Statement

Yulu can record, transcribe, and summarize conversations, but obtaining a reliable
first successful note still requires users to understand installation scripts,
background processes, provider-specific settings, optional command-line Agents,
calendar tools, and sharing configuration. The product lacks one state-aware
Onboarding journey that distinguishes durable adoption from current readiness and
that explains how to recover when macOS permissions, an Agent, a provider, or a
background service is unavailable.

The current release shape is also not a normal Mac application. It depends on a
repository-shaped runtime, host Node and Python installations, package-manager
steps, and absolute LaunchAgent paths. It cannot yet satisfy the promised
drag-to-Applications experience or prove a safe upgrade from the current stable
release. Separately, sharing is split across incompatible legacy and newer paths:
an old setting can automatically send summaries through Hermes while the manual
path can be disabled or impossible to configure. That violates user intent and
can leave an external write with an Unknown Outcome.

Solution

Phase 13 delivers a unified, resumable Onboarding Home and a self-contained,
Developer ID-signed Apple Silicon Yulu.app. Fresh users can drag a notarized DMG
into Applications, launch without Homebrew or language runtimes, complete one real
recording through saved transcript and summary, then choose or defer optional
Conversation, Calendar, Agent Connector, and Sharing capabilities. Existing users
receive a non-blocking entry and a transactional migration that preserves their
data, permission identity where macOS permits it, and a rollback path.

Provider and connector setup becomes explicit and capability-specific. xAI can
transcribe, summarize, and converse using the Grok CLI-compatible OAuth path, with
an API key only when the user explicitly selects it. Supported local Agents use
their own native authorization; Yulu never reads or persists their OAuth tokens and
does not depend on CLIProxyAPI. Calendar Source readiness and Agent Calendar
Connector readiness remain separate.

Recording Processing ends after transcript and summary are saved. Sharing is
manual-only: a user configures and proves an explicit destination with a Test
Share, then initiates every production Share Action from the recording detail
surface, confirms its immutable snapshot, and receives a verified receipt,
failure, or fenced Unknown Outcome. Legacy automatic sharing is retired without
replaying uncertain external writes.

The release is distributed only as a signed, notarized, and stapled DMG. The App
contains its core arm64 runtimes and helpers, registers background work with
SMAppService only from /Applications, stores mutable state in standard user
locations, updates as one signed unit through Sparkle 2, and is accepted on both a
clean Apple Silicon Mac and a real v0.22.2 upgrade before the same source commit
is promoted from the final consolidated candidate accepted under #170 to v0.23.0.

User Stories

1. As a new Mac user, I want to install Yulu by dragging one App into Applications, so that I do not need Terminal or a package manager.
2. As a new Mac user, I want Yulu to open without host Node, Python, Homebrew, npm, pip, or Xcode, so that installation is predictable.
3. As a user launching Yulu from its mounted DMG, I want clear drag-to-Applications guidance, so that services are not registered from a temporary path.
4. As a user, I want one visible Yulu application, so that I do not have to manage separate product apps even though Yulu isolates internal work.
5. As a user, I want Yulu to explain background-item approval status, so that a registration request is not mistaken for a running service.
6. As a user, I want a named Activation Blocker with retry or exact remediation instead of an endless starting state, so that I can recover without guessing.
7. As a user, I want microphone and related permissions requested in context and verified by a real capability, so that an OS prompt is not mistaken for success.
8. As an upgrading user, I want Yulu to resume the same step after macOS requires permission again, so that an unavoidable reauthorization does not strand me.
9. As a fresh user, I want Onboarding to open automatically after the App is healthy, so that I know how to obtain my first complete note.
10. As an existing user, I want Onboarding to remain non-blocking, so that an upgrade does not take over my normal workflow.
11. As a user, I want one Onboarding Home that links to authoritative configuration surfaces, so that setup state is not duplicated across screens.
12. As a user, I want the Activation Journey to resume after I leave or restart Yulu, so that completed progress is not lost.
13. As a user, I want to defer an incomplete Activation Journey, so that I can use the rest of Yulu without repeated forced entry.
14. As a user, I want Core Activation established only by a real production recording, so that a synthetic probe cannot claim the product works.
15. As a user, I want Core Activation to require saved audio, transcript, and a current summary from my selected provider, so that the milestone represents actual value.
16. As a user, I want Core Activation Evidence to remain durable after the source recording is deleted, so that onboarding does not reset unexpectedly.
17. As a user, I want optional capabilities to be adopted or explicitly deferred, so that they do not block the core product.
18. As a returning user, I want later readiness loss shown separately from my durable onboarding outcome, so that a temporary outage does not erase setup history.
19. As a returning user, I want newly introduced capabilities shown as new without revoking Onboarding Completion, so that upgrades remain respectful.
20. As an existing user, I want only legacy evidence that satisfies the new contract migrated as adopted, so that stale configuration is not promoted to readiness.
21. As an xAI user, I want one OAuth path that can authorize realtime transcription, Grok summaries, and conversation, so that I do not configure each capability separately.
22. As an xAI user with Grok CLI access, I want Yulu to use the compatible OAuth authorization path, so that I can use entitled xAI models without CLIProxyAPI.
23. As an xAI user who cannot use OAuth, I want to explicitly select and store an API key in Keychain, so that I have a deliberate alternative.
24. As an xAI user, I want OAuth to remain primary when selected, so that a refresh failure cannot silently spend an API key.
25. As a privacy-conscious user, I want a versioned Data Path Disclosure before cloud transcription or summary, so that authorization is not mistaken for consent.
26. As a local-Agent user, I want Yulu to detect supported candidates without selecting one for me, so that discovery does not change provider authority.
27. As a local-Agent user, I want to install or locate an Agent, complete its native login, return to Yulu, and run a real capability probe, so that readiness is proven.
28. As a Codex, Claude Code, Hermes, or OpenClaw user, I want the runtime to own its OAuth tokens, so that Yulu never copies or stores them.
29. As a user, I want Summary and Conversation capability probes to be independent, so that one working capability does not imply another.
30. As a user, I want my selected provider and model pinned to each recording or conversation, so that Yulu never silently changes authority or falls back.
31. As a Claude Code user, I want an unsupported or blocked runtime state reported exactly, so that other working Agent choices remain available.
32. As a Mac user, I want macOS Calendar to be the recommended meeting source, so that scheduled capture works without installing another tool.
33. As a Google Calendar power user, I want gog OAuth available as an advanced source, so that I can choose it explicitly without making it a startup dependency.
34. As a calendar user with no upcoming events, I want successful access and enumeration to count as ready, so that an empty calendar is not reported as broken.
35. As an Agent calendar user, I want Agent Calendar Connector readiness separate from Yulu's meeting Calendar Source, so that the two permissions are not conflated.
36. As a user finishing a recording, I want automatic processing to stop after transcript and summary, so that no external destination receives content without my action.
37. As an upgrading user with legacy automatic sharing enabled, I want the setting retired without creating new writes, so that old consent is not reused.
38. As a user with a pending legacy task whose delivery never began, I want its transcript and summary to finish without sharing, so that useful processing is preserved safely.
39. As a user with an already started or uncertain legacy delivery, I want its audit state preserved and fenced, so that Yulu cannot duplicate an external write.
40. As a user configuring Sharing, I want to select a ready Agent Connection, prove its Connector, choose an explicit target, and read it back, so that a default string is not called configured.
41. As a user configuring Sharing, I want to send a meeting-free Test Share and verify its receipt, so that I prove write access before exposing meeting content.
42. As a user, I want actual recording content shareable only from its detail surface, so that configuration and external writes are visibly separate.
43. As a user, I want every Share Action to show and confirm the selected summary, Agent, and destination snapshot, so that I know exactly what will be written where.
44. As a user cancelling a share confirmation, I want zero external calls, so that dismissal has no side effect.
45. As a user confirming a share, I want exactly one external attempt and a durable receipt or outcome, so that I can audit the result.
46. As a user sharing an already delivered summary, I want a duplicate warning but the option to create a new explicit action, so that I can intentionally send it elsewhere or again.
47. As a user whose Share Action has an Unknown Outcome, I want ordinary retry disabled and reconciliation choices shown, so that I do not create duplicate pages or messages.
48. As an upgrading user, I want configuration, databases, onboarding state, models, logs, and IPC migrated into standard user locations transactionally, so that App replacement never risks my data.
49. As an upgrading user, I want recordings to stay in my selected Media Library, so that an application update does not silently move user-visible files.
50. As an upgrading user, I want the old runtime and data roots retained read-only for one release cycle, so that a failed migration can be rolled back.
51. As a user, I want migration and update blocked while recording, so that capture and durable data cannot be interrupted mid-write.
52. As a user, I want Yulu to prove there is exactly one Host, Capture helper, and IPC owner after upgrade, so that old and new installations cannot run concurrently.
53. As a user, I want the App to keep the existing Capture helper identity where possible, so that microphone permission continuity has the best chance of surviving upgrade.
54. As a user, I want optional large models downloaded as integrity-checked Runtime Packs, so that the initial App stays practical without weakening core startup.
55. As a user, I want Sparkle to update the entire signed App and validate its helpers and data after relaunch, so that partial runtime patching cannot corrupt installation.
56. As a user, I want a failed update health gate to offer a return to the previous App, so that an update cannot leave Yulu unusable.
57. As a prospective user, I want README, website, GitHub About, and release guidance to describe the current product, so that onboarding starts before installation with accurate expectations.
58. As a release owner, I want only the notarized DMG presented as the binary installation artifact, so that all users follow one accepted installation path.
59. As a release owner, I want the public RC tested from a quarantined download on a clean Apple Silicon Mac, so that CI packaging success is not confused with user acceptance.
60. As an existing stable user, I want a real v0.22.2 upgrade acceptance test with data and services, so that migration claims are based on the supported path.
61. As a release owner, I want v0.23.0 promoted from the same source commit as the final consolidated candidate accepted under [P13-25] Complete consolidated public-install acceptance #170, so that stable introduces no untested code.

Implementation Decisions

• The project glossary and ADRs are the semantic authority. Onboarding surfaces must use Core Activation, Optional Capability Outcome, current Readiness, Agent Connection, Calendar Source, Agent Connector, Share Destination, Share Action, and Unknown Outcome consistently.
• Check changed behavior and relevant regressions; reuse applicable passing evidence. Obsolete assertions about legacy delivery states must be corrected without weakening durable outcome guarantees.
• /onboarding is a resumable progress home and orchestrator, not a duplicate settings system or forced linear wizard. Fresh healthy installations open it automatically; upgrades and returning users receive a non-blocking entry that respects prior deferral.
• Core Activation reuses the production recording pipeline. A Qualifying Recording contains non-empty saved audio, transcript, and current summary with provider provenance. External delivery is never part of qualification.
• Versioned Onboarding persistence stores Core Activation Evidence and one adopted-or-deferred Optional Capability Outcome per optional step. Current readiness is queried separately and never rewrites durable completion.
• Existing users receive adopted outcomes only when existing evidence satisfies the exact new contract. Weak configuration, old share activity, or historical Hermes delivery does not qualify automatically.
• Agent Connection Center remains the single authority for supported runtime discovery, native authorization guidance, capability selection, real probes, and repair. Detection creates candidates only; users make every selection.
• Codex, Claude Code, Hermes, and OpenClaw authorization remains runtime-owned. Yulu stores non-secret connection metadata and Runtime Evidence, but never reads, copies, imports, or persists their OAuth tokens.
• xAI supports Transcription, Summary, and Conversation through the Grok CLI-compatible OAuth client and endpoints. API-key use is an explicit selected Credential Source stored in Keychain, never an automatic fallback. CLIProxyAPI is not installed, integrated, or required.
• Summary Provider and Conversation Provider remain independent, explicit selections. A provider/model is pinned per recording or Native Session Reference and cannot change by implicit priority or fallback.
• macOS Calendar is the primary Calendar Source. gog Google OAuth remains an advanced, optional Calendar Source. Calendar Source Readiness requires access and enumeration, not a non-empty event result.
• Agent Calendar Connector is a separate capability with its own bounded, read-only readiness probe. Calendar Source state cannot establish Connector Readiness and vice versa.
• Recording Processing ends after transcript and summary commit. New completion commands, events, task records, Activation Attempts, and replay paths cannot carry an automatic delivery authorization.
• Retire agent_pipeline.auto_send_notion. Migration treats any saved true value as disabled. Unstarted legacy delivery intent is cleared while processing continues; started, Unknown Outcome, and completed delivery audits remain intact and never auto-retry.
• Real recording content is shared only from the recording or summary detail surface. Agent Console no longer sends meeting content. Agent Connection Center owns runtime and Connector readiness; Settings and Onboarding reuse one Sharing destination and Test Share surface.
• Sharing Readiness requires an explicit selected Agent Connection, a real Connector probe, an explicit destination persisted and read back, and a verified Test Share. Discovered candidates and suggested default text are not configured state.
• Every production Share Action is protected by the process-local UI mutation bearer, captures an immutable summary/connection/destination snapshot, requires a fresh confirmation, and creates exactly one attempt. Verified duplicates warn but remain possible through a new action; Unknown Outcome remains fenced.
• The public product is one visible /Applications/Yulu.app containing separately signed and restartable product shell, Host, and Capture processes. Capture retains the existing bundle identity and signing team to maximize TCC continuity.
• The immutable App bundles exact arm64 Node, Python, ffmpeg, production JavaScript and Python dependencies, native Node addons, built Web UI, and Swift helpers. It runs no npm, pip, Homebrew, compilation, or bundle mutation after signing.
• Large local models may remain versioned, integrity-checked Optional Runtime Packs outside the App. Missing optional packs do not prevent the App from opening or offering another explicit capability.
• Background services register with SMAppService using bundle-relative components only after the App is running from /Applications. System approval state is reported separately from registration success.
• Mutable configuration, databases, onboarding state, the file-backed MCP token, models, caches, IPC, and logs move to standard per-user Library locations. Keychain remains Keychain; recordings remain in the configured Media Library, defaulting to ~/Movies/Yulu; legacy dictation media moves to ~/Movies/Yulu/Dictation.
• Application Migration uses a recording guard, one migration lock, durable journal, SQLite-safe checkpoints, legacy job snapshot, service takeover, and post-migration health gate. It commits only after proving one active owner and otherwise restores legacy jobs and paths.
• Database changes remain additive and backward-readable for the one-release rollback window. Old roots remain read-only during that window.
• Sparkle 2 replaces the whole App. Updates defer during recording, checkpoint operational data before the new Host starts, reconcile services, and require App, helper, database, and IPC health after relaunch before success.
• Distribution remains outside the Mac App Store under Developer ID without App Sandbox for this release. The App and final DMG are signed, notarized, and stapled in the correct nested-code order.
• A launch from the mounted DMG or any non-Applications path displays install guidance and performs no persistent service or update registration.
• The signed, notarized, stapled DMG is the only user-facing binary release artifact; ZIP installation artifacts are retired.
• v0.23.0 is cut from the same source commit as the final consolidated candidate accepted under [P13-25] Complete consolidated public-install acceptance #170. Current Release Please metadata must be corrected to that release line before stable publication.
• README, website, GitHub About, social preview, and release notes are release-gated product surfaces and require live read-back before stable publication.

Testing Decisions

• Tests assert externally observable behavior and durable state, not internal call order or private implementation structure. Existing seams are preferred over adding new test-only interfaces.
• The first seam is the user journey: existing Playwright and React route tests cover Onboarding, authoritative configuration navigation, Activation recovery, Sharing destination setup, confirmations, cancellation, and visible blockers.
• The second seam is Host behavior: existing tRPC caller, server, Recording Pipeline, provider-adapter, and durable-store tests run complete state transitions with controlled adapters. They prove transcript and summary commit, zero automatic external writes, safe legacy migration, capability-specific readiness, share snapshots, receipts, Unknown Outcome fences, and bearer protection.
• The third seam is the public DMG: packaging and migration harnesses accept the same signed artifact as users. Automated checks cover bundle inventory, arm64 architecture, deployment target, nested signatures, notarization/stapling, absence of host-runtime dependencies, standard paths, migration rollback, service uniqueness, update deferral, and bundle immutability.
• A final real-machine acceptance run starts from a quarantined public DMG on an Apple Silicon Mac without Homebrew, Node, Python, npm, pip, or Xcode. It covers drag-to-Applications, Gatekeeper, background approval, permission recovery, Onboarding, recording, transcription, xAI summary, restart/login, supported Agent OAuth, Calendar, Test Share, manual production Share, and no automatic external write.
• A separate real upgrade acceptance starts from v0.22.2 with representative configuration, databases, recordings, Keychain items, TCC state, and legacy jobs. It proves transactional migration, no duplicate owner, preserved Media Library, rollback, and a subsequent RC-to-stable whole-App update.
• macOS 13 arm64 remains a declared deployment target check but is not an acceptance environment for this release.
• Historical delivery receipt, audit, and reconciliation tests remain even after automatic sharing is removed, because legacy started and Unknown Outcome records must stay safe.

Out of Scope

• Mac App Store distribution or enabling App Sandbox.
• Intel/x86_64 builds.
• macOS 13 arm64 as a release-acceptance environment.
• Installing or managing OAuth tokens for Codex, Claude Code, Hermes, OpenClaw, gog, or any other external runtime.
• Installing, embedding, or depending on CLIProxyAPI.
• Any automatic or scheduled external sharing.
• Treating Hermes as a required runtime or preserving its automatic Notion delivery exception.
• New production sharing destinations beyond the already selected Notion and Zulip scope.
• Moving a user's configured Media Library without an explicit user action.
• Replacing external Agent CLIs or calendar tools with bundled copies.
• Claiming Claude Code readiness while its exact supported invocation remains blocked.
• Treating unit, packaging, development-install, or current-machine success as Release Candidate Acceptance.

Original pre-Phase-13 baseline notes (historical, not current status)

• Current code has two incompatible sharing paths: completion events can persist an automatic Notion intent that bypasses the general Agent enablement state, while the manual path uses that disabled legacy state. The destination configuration modal also exists without a reachable UI entry, and suggested target text can be misreported as configured.
• The most recent inspected local task successfully committed transcript and xAI summary before an automatic Hermes delivery ended with an Unknown Outcome. That historical attempt must remain fenced because Yulu cannot prove whether Notion received it.
• The current signed/notarized ZIP pipeline and installer tests are useful prior art, but the release architecture must change from a repository-shaped runtime to one immutable App and DMG.
• Phase 12 remains the authority for Agent Runtime and Gateway connection semantics. Phase 13 consumes those explicit readiness contracts for Onboarding, Conversation, Calendar Connector, and Sharing rather than redefining token custody or fallback behavior.