# CLAUDE.md — Zyquo Cloud

# Project Identity

Zyquo Cloud is a legendary, native macOS AI chat client written in Swift + SwiftUI, built entirely without Xcode (Swift Package Manager + command-line toolchain only). It is inspired by MindMac but must significantly surpass it in features, polish, and provider coverage.

The name matters: Zyquo Cloud is the cloud edition of the Zyquo family — it connects exclusively to cloud AI model APIs. Users bring their own API keys for 12 different cloud AI providers and can chat with any model from any of them, switch models mid-conversation, and manage everything from a beautiful, fast, truly native macOS interface. The "Cloud" identity must be reflected everywhere: app name, bundle, wordmark, and above all the app icon. The visual design is a first-class deliverable: Zyquo Cloud must look like an app Apple would feature.

Naming conventions (use these consistently everywhere):

• Display name / product name: Zyquo Cloud
• App bundle: Zyquo Cloud.app
• Bundle identifier: com.zyquo.cloud
• Executable / SPM target: ZyquoCloud (no space)
• Data folder: ~/Library/Application Support/ZyquoCloud/
• Repo module prefix in file headers: Zyquo Cloud

# 📋 MANDATORY FILE HEADER — EVERY CODE FILE

Every single code file you write (all .swift files, plus Makefile, shell scripts, Package.swift, verification scripts — anything containing code) MUST begin with this header comment, adapted to the file's comment syntax:

//
//  <FileName>.swift
//  Zyquo Cloud
//
//  Author: Simon-Pierre Boucher
//  Mail: contact@spboucher.ai
//

For shell scripts / Makefiles:

#
#  <filename>
#  Zyquo Cloud
#
#  Author: Simon-Pierre Boucher
#  Mail: contact@spboucher.ai
#

No exceptions. If you ever create or refactor a file and the header is missing, add it. Before declaring the project done, run a sweep over the repository to verify every code file carries the header.

# 🧭 METHODOLOGY — WORK METHODICALLY, KEEP EVERYTHING COHERENT

You must execute this project strictly in phase order (0 → 8). Do not jump ahead, do not interleave phases, do not start the UI before the provider layer compiles, and do not write provider code before Phase 0 research is complete.

Working rules:

1. One phase at a time. At the start of each phase, write a short plan (checklist) into docs/PLAN.md; check items off as you complete them. At the end of each phase, perform a phase checkpoint: build the project (swift build), run what's runnable, fix all warnings/errors, and write a 3–5 line phase summary in docs/PLAN.md before moving on.
2. Phase gates: Phase 0 is complete only when docs/PROVIDERS.md covers all 12 providers with all 8 research points. Phase 3 is complete only when the vault encrypts/decrypts round-trip in a test. Phase 4 spec is the contract for all UI in Phase 6. Phase 7 is complete only when the results table is fully green. Phase 8 is complete only when spctl says "Notarized Developer ID".
3. Single source of truth, everywhere:
   • Model data → only from ModelCatalog (itself generated from docs/PROVIDERS.md). Never hardcode a model ID in a view or client.
   • Colors, fonts, spacing, radii → only from ZyquoTheme design tokens. Zero raw hex values or magic numbers in views.
   • Provider behavior differences (auth header, endpoint, params supported) → only in the provider client layer, never leaking into ViewModels or Views.
   • Product naming → only per the conventions above. Never Zyquo alone, never ZyquoCloud in user-facing text.
4. Coherence sweeps: after Phases 3, 6, and 8, do a dedicated consistency pass over the whole codebase: naming conventions uniform (types UpperCamelCase, one term per concept — e.g., always AIModel, never a mix of Model/LLM/AIModel), no dead code, no duplicated logic between provider clients (shared code lives in OpenAICompatibleClient), file headers present, folder structure matches Phase 2 exactly.
5. Compile early, compile often. Never accumulate more than one file of unbuilt changes. If the build breaks, fixing it is the immediate priority.
6. Commit discipline: one logical unit per commit, message prefixed by phase (e.g., phase4: add ZyquoTheme color tokens). Never commit secrets.
7. When research and reality disagree (e.g., a model in docs/PROVIDERS.md fails in Phase 7), update docs/PROVIDERS.md AND ModelCatalog together — the two must never drift apart.

# ⚠️ PHASE 0 — MANDATORY INTENSIVE WEB RESEARCH (DO THIS FIRST, BEFORE WRITING ANY CODE)

Before writing a single line of Swift, you MUST perform an intensive, exhaustive web research session to document every provider below. This research must be perfect and complete — the entire app depends on it. Do NOT rely on your training data: model catalogs, endpoints, and parameters change constantly. Search the official documentation of each provider.

For EACH of the 12 providers below, research and document in docs/PROVIDERS.md:

1. Base API URL and all relevant endpoints (chat completions, model listing, etc.)
2. Authentication method (header name, Bearer vs x-api-key, etc.)
3. The COMPLETE, CURRENT list of available models — exact model IDs as used in API calls, context window sizes, max output tokens, pricing if documented, and capabilities (vision, function calling, reasoning/thinking modes, streaming, JSON mode)
4. Request/response format — is it OpenAI-compatible? If not, document the exact schema (e.g., Anthropic's Messages API, Gemini's generateContent)
5. Streaming format (SSE structure, delta format, stop events)
6. Special parameters (e.g., reasoning_effort, thinking, Perplexity's search/citations, Qwen's enable_thinking, DeepSeek reasoner specifics)
7. Rate limits and error response formats
8. Whether a /models listing endpoint exists (so Zyquo Cloud can also fetch models dynamically at runtime)

# The 12 providers (all mandatory):

Research quality bar: For every provider, visit the OFFICIAL docs (platform.openai.com, docs.anthropic.com, docs.x.ai, docs.mistral.ai, ai.google.dev, DashScope docs, api-docs.deepseek.com, platform.moonshot.ai, docs.perplexity.ai, docs.together.ai, deepinfra.com/docs, inference-docs.cerebras.ai). Cross-check with each provider's /models endpoint spec. Write everything into docs/PROVIDERS.md before coding. This document is the single source of truth for the built-in model catalog shipped inside Zyquo Cloud.

# PHASE 1 — Project Setup (No Xcode)

• Toolchain: Swift Package Manager only. Package.swift with executable target ZyquoCloud. Build with swift build -c release.
• App bundle: Write a Makefile (or build.sh) that:
  1. Runs swift build -c release
  2. Assembles a proper Zyquo Cloud.app bundle (Contents/MacOS/ZyquoCloud, Contents/Info.plist, Contents/Resources/AppIcon.icns)
  3. Signs the app (see PHASE 8 — real Developer ID signing + notarization; ad-hoc only as a dev fallback)
• Info.plist must include: CFBundleName / CFBundleDisplayName = Zyquo Cloud, bundle ID com.zyquo.cloud, LSMinimumSystemVersion (macOS 13.0+), NSHighResolutionCapable, CFBundleIconFile, LSApplicationCategoryType (public.app-category.productivity), version/build numbers.
• Entry point: @main SwiftUI App struct. Ensure proper activation when launched outside Finder (NSApplication.shared.setActivationPolicy(.regular) + activate).
• No third-party dependencies unless truly necessary. Prefer Foundation + SwiftUI + CryptoKit. Apple's swift-markdown via SPM is acceptable for Markdown parsing.
• Minimum deployment: macOS 13 (Ventura). arm64 mandatory; universal binary (arm64 + x86_64 via lipo) is the target for release builds.

# PHASE 2 — Architecture

Sources/ZyquoCloud/
├── App/                 # @main, window setup, menu bar extra
├── DesignSystem/        # ZyquoTheme, colors, typography, spacing, reusable components
├── Models/              # Conversation, Message, Provider, AIModel, Persona, etc.
├── Providers/
│   ├── ProviderProtocol.swift
│   ├── OpenAICompatibleClient.swift   # OpenAI, xAI, Mistral, DashScope, DeepSeek, Kimi, Perplexity, Together, DeepInfra, Cerebras, Gemini-compat
│   ├── AnthropicClient.swift          # native Messages API
│   └── GeminiClient.swift             # native generateContent (if compat mode is insufficient)
├── Services/
│   ├── SecureKeyStore.swift           # custom encryption (Phase 3)
│   ├── PersistenceService.swift       # conversations as JSON in Application Support
│   ├── StreamingService.swift         # SSE parsing
│   └── ModelCatalog.swift             # built from PROVIDERS.md + dynamic /models fetch
├── ViewModels/
└── Views/

• All networking with URLSession (bytes(for:) for SSE streaming). No external HTTP libs.
• Concurrency: structured concurrency (async/await, AsyncSequence, @MainActor for UI state).
• Persistence: JSON files in ~/Library/Application Support/ZyquoCloud/.

# PHASE 3 — API Key Storage: CUSTOM ENCRYPTION (NO KEYCHAIN)

Explicit requirement: DO NOT use the macOS Keychain. Keys are encrypted by the app itself.

Implement SecureKeyStore:

1. Encryption: AES-256-GCM via CryptoKit.
2. Master key derivation: HKDF (CryptoKit) from:
   • A random 32-byte salt generated on first launch, stored alongside the vault
   • Machine-bound entropy: hardware UUID (IOPlatformUUID via IOKit) + user home path
   • A static app pepper compiled into the binary (obfuscated — assembled at runtime, never a plain string literal)
3. Vault file: single encrypted vault ~/Library/Application Support/ZyquoCloud/vault.zq — format [salt][nonce][ciphertext+tag]; plaintext is a JSON dictionary {"openai": "sk-...", "anthropic": "sk-ant-...", ...}.
4. Keys decrypted into memory only when needed, never logged, never written to disk in plaintext, redacted everywhere in the UI (show only the last 4 characters).
5. Settings UI: per-provider secure fields, a "Test" button per provider, masked display of saved keys, per-key delete.

# PHASE 4 — DESIGN SYSTEM & UI SPECIFICATION (LIGHT THEME, PIXEL-PERFECT)

Design is a hard requirement, not decoration. Zyquo Cloud ships with a flagship light theme that must be flawless. Build a real design system in Sources/ZyquoCloud/DesignSystem/ and use it everywhere — zero hardcoded colors or magic numbers in views.

# 4.1 — Light theme specification (the default, must be perfect)

Color tokens (define in ZyquoTheme, all as semantic tokens). The palette leans into the Cloud identity: airy off-white sky canvas, sky-to-indigo accent.

Rules: never pure black text on pure white; hairlines at 0.5pt; shadows extremely soft (black.opacity(0.06), radius 12, y 2) and used sparingly (floating panels, popovers only). Dark theme derives from the same tokens (define values too — a deep night-sky navy base, not flat gray), but the light theme is the flagship and gets first-class attention.

Typography (SF Pro system font, define as tokens):

• title 20pt semibold — window/section titles
• body 13.5pt regular, line-height 1.45 — messages (this generous line height is mandatory for readability)
• bodyEmphasis 13.5pt medium
• caption 11pt regular — timestamps, token counts
• code 12.5pt SF Mono — code blocks and inline code
• User can adjust chat font size (12–18pt) in Settings; everything scales cleanly.

Spacing scale: 4 / 8 / 12 / 16 / 20 / 24 / 32. Corner radii: 6 (small controls), 10 (bubbles, cards), 14 (floating panels). Standard content insets: 16pt. Max message column width: 760pt, centered — never full-bleed text on wide windows.

# 4.2 — Layout & screens (exact spec)

Main window — NavigationSplitView, min size 980×640, default 1240×800:

• Sidebar (260pt, translucent material): "Zyquo Cloud" wordmark top-left (wordmark uses the icon's cloud-Z glyph at 16pt beside the name); search field; "New Chat" prominent button; conversation list grouped by Pinned / Today / Yesterday / Previous 7 Days / Older; each row = title (1 line, truncated) + model badge + relative time; hover reveals pin/delete icons; selected row uses accentSubtle with 6pt radius; folders/tags section at bottom; footer with settings gear + usage summary.
• Chat area:
  • Header (52pt, hairline below): conversation title (inline-editable), centered model chip (provider logo glyph + model name, click → model picker popover), right side: compare-mode button, export, info popover (system prompt, parameters, total tokens & cost).
  • Transcript: user messages right-aligned in accentSubtle bubbles (radius 10); assistant messages left-aligned on surface with the provider glyph as avatar; 16pt vertical rhythm between turns; timestamps and per-message token/cost in caption appearing on hover; smooth auto-scroll during streaming with a "jump to bottom" pill when scrolled up; collapsible "Thinking…" section (chevron, textSecondary, monospaced) for reasoning models; Perplexity citations as numbered chips under the message.
  • Markdown rendering: full support — headings, tables (bordered, alternating row tint surfaceSecondary), blockquotes (3pt accent left bar), lists, links in accent; code blocks: surfaceSecondary background, 10pt radius, language label top-left, copy button top-right, SF Mono, native syntax highlighting via AttributedString (build a lightweight highlighter for Swift, Python, JS/TS, JSON, HTML/CSS, Bash, SQL, Go, Rust, C/C++).
  • Input bar: floating card docked at bottom (surface, radius 14, soft shadow, 12pt margin); multiline auto-growing text editor (max ~10 lines then scroll); left: attach button (images/files); right: parameter quick-toggle + circular accent send button (⌘↩); attached images shown as 56pt thumbnails above the field with remove buttons; drag-and-drop highlights the bar with a dashed accent border.
• Empty state: centered Zyquo Cloud icon, greeting, 4 suggested prompt cards, model chip — must look intentional and beautiful, never blank.

Settings window (Settings scene, native toolbar-style tabs, 720×520):

1. Providers & Keys — provider list with logo glyph, masked key, status dot (green verified / gray unset / red failed), inline "Test" button with spinner → ✅/❌ + latency
2. Models — catalog browser per provider: context window, capabilities badges (vision / reasoning / tools), pricing, favorite star, "Refresh from API" button, custom model/endpoint editor
3. Appearance — Light/Dark/System, accent color choices (sky-indigo default + graphite, teal, amber, rose), chat font size slider with live preview
4. Shortcuts — recordable key bindings
5. Advanced — streaming toggle, retry policy, default parameters, data folder reveal, export/import all data

Quick Chat panel (global hotkey ⌥Space): floating Spotlight-style panel, 640pt wide, radius 14, prominent shadow, single input + model chip; answers expand below; ESC dismisses; appears on the active screen, vertically at 30%.

Compare mode: 2–4 vertical columns, one model chip each, same prompt broadcast, independent streaming, per-column copy/regenerate.

# 4.3 — Motion & micro-interactions

• Streaming text appears smoothly (no jitter, no layout thrash); subtle blinking caret at the stream tail
• Message send: input clears instantly, user bubble animates in with a 150ms ease-out fade+rise
• Hover states on every interactive element (80ms ease); button presses scale to 0.97
• Model picker popover: springy but fast (.snappy)
• Never block the main thread; 60fps at all times, including during streaming into long conversations (use lazy rendering for transcripts)

# 4.4 — Design quality gate

Before declaring the project done, review every screen against this checklist: consistent token usage, aligned baselines, no clipped text, correct dark-mode derivation, clean scaling with the font slider, all states designed (empty, loading, error, streaming, disabled). If a screen looks "developer-made" rather than "designed", iterate until it doesn't.

# PHASE 5 — APP ICON: ULTRA-LEGENDARY "CLOUD" ICON, DESIGNED IN SVG

The icon is a deliverable of its own and it must embody the Cloud identity — this is Zyquo Cloud, the app that talks to cloud AI APIs. It must be designed in SVG first (assets/icon/zyquo-cloud.svg), then converted to .icns.

Creative direction — make it iconic:

• Concept: a fusion of the "Z" monogram and a cloud form. Two strong directions to explore (pick and refine the best after rendering both):
  1. Z-in-cloud: a sleek white cloud silhouette (soft, modern, geometric — not a cartoon puff) floating on the gradient canvas, with a bold accent-colored Z cut through or embossed into the cloud, its diagonal stroke rendered as a luminous beam crossing the cloud like light through sky.
  2. Cloud-built-Z: the Z itself constructed so its upper and lower horizontal strokes swell into subtle cloud-curved terminals, reading simultaneously as a letterform and a cloud — one shape, two meanings.
• Canvas: macOS Big Sur–style rounded squircle (Apple squircle curvature, not a plain rounded rect).
• Palette (sky story, coherent with the app's light theme): vertical gradient background from clear sky blue to deep indigo (#6FA8FF → #4E6AF0 → #3A3F9E territory — tune for richness and depth), cloud/monogram in white/near-white with a very subtle inner luminous gradient; one restrained highlight (soft top light, as if sunlit from above) for atmosphere and depth. Optionally a whisper of a second, distant cloud layer for parallax depth — only if it stays clean at small sizes. No gimmicks, no 10-color gradients, no bevel-heavy 2010 look — modern, airy, premium, unmistakably "cloud".
• Precision: clean paths, viewBox="0 0 1024 1024", optical (not mathematical) centering, stroke weights that survive downscaling.
• Iterate: render the SVG to PNG at 1024/512/256/128/64/32/16, LOOK at the results, and refine until it is crisp and striking at every size — especially 16px and 32px. If small sizes get muddy, bake a simplified small-size variant (e.g., drop the secondary cloud layer, thicken the Z) into the icns for 16/32px.

Pipeline (scripted in the Makefile):

1. zyquo-cloud.svg → PNGs at 16, 32, 64, 128, 256, 512, 1024 (use rsvg-convert, or a small Swift rasterizer with NSImage/CoreGraphics if librsvg is unavailable)
2. Assemble AppIcon.iconset (including @2x entries) → iconutil -c icns → Contents/Resources/AppIcon.icns
3. The SVG source stays in the repo as the single source of truth.

Also derive from the same SVG: a monochrome menu bar template icon (18×18pt, isTemplate = true — the cloud-Z silhouette works beautifully as a template glyph) and the in-app empty-state glyph and sidebar wordmark glyph.

# PHASE 6 — Features (This is where Zyquo Cloud becomes LEGENDARY)

# Core chat

• Multi-conversation sidebar with search, pin, rename, delete, folders/tags
• Full streaming with a stop button
• Model picker per conversation AND per message — switch provider/model mid-conversation
• Message actions: copy, edit & resend, regenerate (optionally with a different model), delete, quote-reply
• Reasoning/thinking display (DeepSeek Reasoner, Qwen thinking, Claude extended thinking, OpenAI reasoning summaries when available) in the collapsible section
• Perplexity citations as clickable numbered sources
• Token/usage per message and per conversation (from API usage), with estimated cost from Phase 0 pricing
• System prompt per conversation + global default
• Per-conversation parameters: temperature, top_p, max tokens, frequency/presence penalty — only show what the selected provider supports

# Vision & attachments

• Drag & drop or paste images for vision-capable models (base64 per provider format)
• Drag & drop text files (txt, md, code, csv, json) — contents injected into the message

# Productivity (surpassing MindMac)

• Prompt Library: ship ≥50 high-quality templates (writing, coding, analysis, translation…) + user templates with {{input}} variables
• Personas: system prompt + preferred model + parameters, selectable per conversation
• Quick Chat global panel (Phase 4.2)
• Compare mode (Phase 4.2)
• Export: conversation → Markdown, and → PDF (ImageRenderer/NSPrintOperation)
• Full-text search across all conversations
• Auto-generated conversation titles (cheap model from the same provider after the first exchange)

# macOS-native polish

• Shortcuts: ⌘N new chat, ⌘K model switcher/command palette, ⌘F search, ⌘↩ send, ⌘⇧E export, ⌥Space Quick Chat
• Menu bar extra (toggleable) using the template icon
• Launch fast, feel instant — no jank

# Model management

• Complete built-in catalog from Phase 0 (ModelCatalog)
• Dynamic model fetching from /models endpoints (refresh in Settings)
• Custom models (custom ID + base URL) → free support for any OpenAI-compatible cloud endpoint (OpenRouter, Groq, etc.)
• Favorite models pinned in the picker

# PHASE 7 — API VERIFICATION WITH REAL KEYS (MANDATORY)

The user will provide real API keys for all 12 providers. You MUST:

1. Build a verification harness (zyquo-verify CLI target or script) that, for every provider:
   • Lists models via /models where available and diffs against the built-in catalog
   • Sends a minimal chat completion ("Reply with exactly: OK") to every chat model in the catalog (skip embedding/audio/image-only models)
   • Tests streaming on at least one model per provider
   • Tests vision on one vision-capable model per provider that supports it
2. Produce a results table: provider → model → ✅/❌ → error message if failed.
3. Fix every failure (wrong ID, endpoint, header, schema) and iterate until everything that should work, works. Remove or flag genuinely deprecated models.
4. Never commit, log, or embed the user's keys anywhere. Keys live only in the encrypted vault or env vars during testing.

# PHASE 8 — SIGNING & NOTARIZATION (REAL, NOT AD-HOC)

The user has an existing, working signing/notarization setup for another project. Before doing anything, read and inspect the folder:

/Users/simon-pierreboucher/Desktop/other/OTHER/zyquo-term

In that folder, locate everything related to signing and notarization: build/notarization scripts, Makefile targets, the Developer ID Application certificate identity name, the Team ID, the Apple ID / app-specific password or stored notarytool keychain profile name, entitlements files, and any .env/config holding these values. Reuse the exact same identity, Team ID, and notarytool credentials/profile for Zyquo Cloud. Do not invent placeholder values — extract the real ones from that folder, and never print secrets into logs or commit them to the repo.

Then implement make release:

1. Build universal release binary (arm64 + x86_64, lipo), assemble Zyquo Cloud.app
2. Write entitlements.plist — Hardened Runtime enabled; only the entitlements actually needed (network client; no unnecessary exceptions). Base it on what zyquo-term uses if applicable.
3. codesign --force --options runtime --timestamp --entitlements entitlements.plist --sign "Developer ID Application: <identity from zyquo-term>" "Zyquo Cloud.app" (sign nested code first if any)
4. Zip with ditto -c -k --keepParent
5. xcrun notarytool submit "Zyquo Cloud.zip" --keychain-profile "<profile from zyquo-term>" --wait (or --apple-id/--team-id/--password if that's how zyquo-term does it)
6. On acceptance: xcrun stapler staple "Zyquo Cloud.app", then verify with spctl -a -vv "Zyquo Cloud.app" (must say "accepted, source=Notarized Developer ID") and stapler validate
7. Optionally produce a distributable DMG (hdiutil) with the app + Applications symlink, sign and staple the DMG too
8. If notarization fails, fetch the log (notarytool log), fix every issue (signature, entitlements, hardened runtime), and resubmit until it passes.

Keep a make dev target with ad-hoc signing for fast local iteration.

# Engineering Standards

• Swift 5.9+ (Swift 6 mode if the toolchain allows); zero compiler warnings
• Every provider request/response modeled with Codable structs — no dictionary spelunking
• Robust error handling: map HTTP + provider error bodies to clear human messages ("Invalid API key for Mistral", "Rate limited — retrying in 20s") with exponential backoff on 429/5xx
• Long read timeouts for streaming; cancellation everywhere
• All UI strings centralized (future localization-ready); design tokens only — no hardcoded colors/sizes in views
• README.md with build instructions (make → dev app, make release → notarized app)
• Commit in logical increments with clear messages

# Definition of Done

• make release produces a Developer ID–signed, notarized, stapled Zyquo Cloud.app (verified by spctl), built with zero Xcode
• The cloud-themed SVG icon exists, is genuinely striking at all sizes, and is embedded as .icns + menu bar template icon; the sidebar wordmark uses the same glyph
• The light theme matches the Phase 4 spec exactly and passes the design quality gate; dark theme derived and correct
• Naming is coherent everywhere: Zyquo Cloud in all user-facing text, com.zyquo.cloud bundle ID, ZyquoCloud target/data folder
• All 12 providers configured; keys encrypted with the custom vault (no Keychain anywhere in the codebase)
• The verification harness shows a green table across all providers/models with the user's real keys
• All features in Phase 6 implemented and functional
• Every code file starts with the mandatory Author/Mail header (verified by a repository-wide sweep)
• docs/PLAN.md shows every phase completed with its checkpoint summary; docs/PROVIDERS.md and ModelCatalog are in perfect sync
• Zyquo Cloud feels like a polished, legendary native Mac app — clearly better than MindMac