# Zyquo Cloud — Build Plan

## Phase 0 — Provider Research ✅ (completed 2026-07-30)

- [x] Live-probe `/models` endpoints of all 12 providers with real keys (authoritative current model IDs)
- [x] Live SSE streaming smoke test on all 12 providers (all HTTP 200)
- [x] Web research: official docs for each provider (auth, endpoints, schema, streaming, special params, rate limits, pricing)
- [x] Write `docs/PROVIDERS.md` covering all 12 providers × 8 research points
- [x] Phase checkpoint: PROVIDERS.md complete + summary

**Phase 0 checkpoint summary:** All 12 providers documented in `docs/PROVIDERS.md` (assembled from
per-provider files in `docs/research/`), each covering the 8 mandatory points, verified against live
probes with real keys — every key authenticated, every provider streamed successfully. Major catalog
churn found vs. training data: DeepSeek → v4-flash/v4-pro only; Mistral deprecates Magistral/Devstral/
Nemo 2026-07-31 (reasoning via `reasoning_effort`); xAI catalog now grok-4.5/4.3/4.20/build; Cerebras
down to 3 models; Perplexity has no `/models` (built-in catalog: sonar, sonar-pro, sonar-reasoning-pro,
sonar-deep-research). Items unverifiable from docs are flagged inline and queued for Phase 7.

## Phase 1 — Project Setup ✅ (completed 2026-07-30)

- [x] `Package.swift` — executable targets `ZyquoCloud` + `zyquo-verify`, test target, macOS 13+, swift-markdown dep
- [x] Minimal `@main` SwiftUI app that builds and launches (activation policy handled)
- [x] `Makefile`: `make dev` (release build + assemble `Zyquo Cloud.app` + ad-hoc sign), `make release`
      (universal + Developer ID + notarize skeleton, completed in Phase 8), `scripts/write-info-plist.sh`
- [x] Phase checkpoint: `swift build` clean (0 warnings), `make dev` assembles bundle, app launched via
      `open`, process verified, quit cleanly

**Phase 1 checkpoint summary:** SPM-only toolchain working on Swift 6.4. `make dev` produces an
ad-hoc-signed `dist/Zyquo Cloud.app` with correct Info.plist (`com.zyquo.cloud`, macOS 13+,
productivity category). Release/notarization targets stubbed to `scripts/notarize.sh` using the
verified zyquo-term identity + `MacLustr-Notarize` profile (implemented fully in Phase 8).

## Phase 2 — Architecture ✅ (completed 2026-07-30)

- [x] Models: `ProviderID`, `AIModel`, `ModelCapabilities`, `ModelPricing`, `ParameterSupport`, `Message`, `Conversation`, `Persona`, `PromptTemplate`, `ChatParameters`, `TokenUsage`
- [x] Providers: `ProviderProtocol` (`ChatRequest` → `AsyncThrowingStream<ChatEvent>`), `OpenAICompatibleClient` (11 providers incl. Gemini-compat + custom), `AnthropicClient` (native Messages API), `ProviderRegistry`
- [x] Services: `StreamingService` (SSE parser + URLSession streaming), `ModelCatalog` (+ seed `ModelCatalogData`, full data generated next), `PersistenceService` (JSON in Application Support)
- [x] ViewModels/Views skeleton folders
- [x] Phase checkpoint: builds clean (0 warnings), 10/10 unit tests pass (SSE parser incl. Anthropic
      named events / keep-alive comments / multi-line data; model JSON round-trip; error mapping)

**Phase 2 checkpoint summary:** Full provider abstraction in place — all quirks (auth headers,
stream_options, max_completion_tokens, enable_thinking, reasoning_content, citations, bare-array
/models) isolated in the two clients. Toolchain note: no Xcode on this machine (CLT only), so tests
use Swift Testing with `scripts/test.sh` wiring the CLT TestingMacros plugin + framework symlinks
(`make test`).

## Phase 3 — SecureKeyStore ✅ (completed 2026-07-30)

- [x] AES-256-GCM vault via CryptoKit at `~/Library/Application Support/ZyquoCloud/vault.zq`
- [x] HKDF master key: random salt + IOPlatformUUID (IOKit) + home path + obfuscated compiled-in pepper (XOR-assembled at runtime)
- [x] Vault format `[salt 32B][nonce+ciphertext+tag]`, plaintext JSON dict of provider→key, atomic writes, stable salt across saves
- [x] Round-trip encrypt/decrypt test (phase gate) + tamper test + machine-binding test + plaintext-leak test + no-Keychain sweep (clean)

**Phase 3 checkpoint summary:** Vault gate passed — 17/17 tests green including encrypt/decrypt
round-trip, GCM tamper detection, cross-machine rejection (injected entropy), salt stability, and
a scan proving no key material or field names appear in the vault file. Zero Keychain/SecItem usage
in the codebase. Keys redact to `••••` + last 4 via `SecureKeyStore.redacted`.

## Phase 4 — Design System & UI Spec ✅ (completed 2026-07-30)

- [x] `ZyquoTheme` tokens: full color spec (light flagship + night-sky dark derivation as dynamic
      NSColors), typography scale (title/body 13.5 lh 1.45/caption/code SF Mono), spacing 4–32,
      radii 6/10/14, soft shadow token, layout metrics (sidebar 260, header 52, column 760…), motion tokens
- [x] Reusable components: `ZyquoHairline` (0.5pt), `ZyquoBadge`, `StatusDot`, hover highlight (80ms),
      pressable style (0.97), provider glyphs
- [x] `AppearanceStore`: light/dark/system, 5 accent choices (sky-indigo default), chat font size 12–18 clamped, persisted
- [x] Phase checkpoint: builds clean; tokens are the only color/size source (raw-hex sweep of Views/ViewModels clean)

**Phase 4 checkpoint summary:** Design system complete per spec; the Phase 4.2 layout spec is the
contract for all Phase 6 UI and the 4.4 quality gate is re-checked before "done". Toolchain: builds
pinned to macOS 26 SDK (`SDKROOT` in Makefile/test.sh) because CLT lacks Xcode's SwiftUIMacros
plugin required by SDK 27's macro-based @State.

## Phase 5 — App Icon ✅ (completed 2026-07-30)

- [x] `assets/icon/zyquo-cloud.svg` — white geometric cloud + luminous-beam Z on a true superellipse
      squircle (n=4.6, computed path), sky gradient #82B4FF→#4E6AF0→#3A3F9E, soft top light, two
      distant parallax cloud layers; no SVG filters (CoreSVG-safe)
- [x] Rendered 16→1024 and visually inspected; iterated (lightened sky; small sizes were muddy →
      dedicated `zyquo-cloud-small.svg`: bigger cloud, 86px Z stroke, flat fills — used for 16/32 slots)
- [x] `scripts/generate-icon.sh` → iconset (small variant for ≤64px slots) → `Resources/AppIcon.icns`,
      embedded in the bundle by `make dev`/`release`; rasterizer: `scripts/rasterize-svg.swift` (AppKit)
- [x] Menu bar template glyph `zyquo-cloud-template.svg` (cloud silhouette, Z knocked out via mask) →
      `Resources/MenuBarIcon(@2x).png`; in-app wordmark/empty-state glyph will draw the same geometry
      as a SwiftUI Shape in Phase 6

**Phase 5 checkpoint summary:** Icon is crisp and on-identity at every size (verified visually at
1024/512/256/128/64/32/16). SVG sources are the single source of truth in `assets/icon/`.

## Phase 6 — Features ✅ (completed 2026-07-30; design gate re-checked before Done)

- [x] Core chat: sidebar (search ⌘F, pin, rename, delete, tags), streaming with stop (⌘.), model picker
      per conversation + per message, message actions (copy/edit&resend/regenerate/delete/quote),
      reasoning display (collapsible), Perplexity citations chips, per-message + per-conversation
      tokens & est. cost, system prompt per conversation + global default, gated parameters editor
- [x] Vision & attachments: image + text-file drag/drop + picker, 56pt thumbnails, dashed drop highlight
- [x] Productivity: 56-template prompt library + user templates ({{input}}), 8 personas + user personas,
      Quick Chat (⌥Space floating panel + "Continue in app"), compare mode (2–4 columns), export
      Markdown/PDF, full-text search, auto-titles via cheapest same-provider model
- [x] macOS polish: ⌘N/⌘K palette/⌘F/⌘↩/⌘⇧E/⌥Space/⌘., menu bar extra (template icon, toggleable),
      empty state per spec
- [x] Model management: 195-model built-in catalog, dynamic /models refresh + catalog diff in Settings,
      custom OpenAI-compatible models (ID + base URL), favorites
- [x] Markdown: full rendering (tables, quotes, lists, links, headings) + code blocks with copy button,
      language label, 11-language syntax highlighter; streaming-safe, memoized
- [x] Checkpoint: builds clean 0 warnings, 26 tests green, app launched + UI visually verified (dark)

**Phase 6 checkpoint summary:** All Phase 6 features implemented and wired. UI verified running;
light/dark render from the same tokens. End-to-end chat with live keys is exercised in Phase 7.

## Phase 7 — API Verification ✅ (completed 2026-07-30 — table fully green)

- [x] Verify harness: app binary gains `--verify` mode reusing the exact production provider clients;
      `zyquo-verify` target execs it (keys via env from .env.keys, never committed); `--load-vault` seeds the GUI vault
- [x] /models diff vs catalog per provider; "OK" completion on every catalog chat model;
      streaming test per provider; vision test per vision-capable provider
- [x] **Final result: 202/202 tests passed** (12 providers, 170 catalog models) — docs/VERIFICATION.md
- [x] Every failure across 3 sweeps fixed, PROVIDERS.md + catalog updated together

**Phase 7 checkpoint summary:** Live verification caught and fixed real bugs: SSE event separators
dropped by AsyncBytes.lines (all streams hung); async @main breaking GUI task scheduling; a --verify
MainActor deadlock; Together's completions-style `choices[].text` deltas; Mistral's high/none-only
reasoning_effort + ThinkChunk content arrays; Gemini's `models/` ID prefixes; deprecated models
(OpenAI chat-latest generations, Gemini 2.0/3-pro-preview, 18 Together dedicated-only, broken
DeepInfra gemma-4-31B) removed; streaming-only models flagged (`requiresStreaming`); 429/5xx
backoff added. End-to-end GUI chat verified live; auto-title now uses cheapest non-reasoning model.

## Phase 8 — Signing & Notarization ✅ (completed 2026-07-30)

- [x] `make release`: universal binary (arm64 + x86_64 via lipo; x86_64 needs `-U` for CLT's
      arm64-only swiftCompatibility56), Developer ID sign (hardened runtime, minimal entitlements),
      notarize app zip + DMG (`MacLustr-Notarize`, both **Accepted**), staple both
- [x] `spctl -a -vv` → **accepted, source=Notarized Developer ID** · `stapler validate` OK ·
      `lipo -archs` → x86_64 arm64 · notarized app launches and quits cleanly
- [x] Gotcha fixed: AMFI rejects XML comments inside the entitlements dict — plist is now comment-free

**Phase 8 checkpoint summary:** `dist/Zyquo Cloud.app` (signed, notarized, stapled, universal) and
`dist/ZyquoCloud.dmg` (notarized, stapled) ship-ready. Identity
"Developer ID Application: Simon-Pierre Boucher (3YM54G49SN)", profile MacLustr-Notarize.

---

## Definition of Done — final sweep (2026-07-30)

- [x] `make release` → Developer ID-signed, notarized, stapled `Zyquo Cloud.app` (spctl-verified), zero Xcode
- [x] Cloud SVG icon (+ small-size & template variants) striking at all sizes, embedded icns + menu bar template + in-app glyph/wordmark
- [x] Light theme per Phase 4 spec (visually verified), dark derived (visually verified)
- [x] Naming coherent: "Zyquo Cloud" UI, com.zyquo.cloud, ZyquoCloud target/data folder (sweeps clean)
- [x] 12 providers configured; custom AES-GCM vault, zero Keychain usage (sweep clean)
- [x] Verification harness: **202/202 green** across all providers/models with real keys (docs/VERIFICATION.md)
- [x] All Phase 6 features implemented and functional
- [x] Header audit: every code file carries the Author/Mail header (scripts/audit-headers.sh)
- [x] PROVIDERS.md ↔ ModelCatalog in sync (Phase 7 amendments recorded); 27/27 unit tests; zero compiler warnings
## Phase 2 — Architecture (pending)
## Phase 3 — SecureKeyStore (pending)
## Phase 4 — Design System (pending)
## Phase 5 — App Icon (pending)
## Phase 6 — Features (pending)
## Phase 7 — API Verification (pending)
## Phase 8 — Signing & Notarization (pending)