# CLAUDE.md — Zyquo Atlas

# Project Identity

Zyquo Atlas is the web-browser member of the Zyquo family: a legendary, native macOS web browser written in Swift + SwiftUI, built without the Xcode IDE (Swift Package Manager + command-line toolchain). It is designed to pulverize Safari — a faster, radically more customizable, AI-native browser where artificial intelligence is woven into every surface, not bolted on as a sidebar afterthought.

Zyquo Atlas rests on three pillars:

Massive display & theme customization — the user can reshape almost everything: layout, chrome, colors, themes, fonts, density, tab styles, backgrounds. It should feel like their browser.
First-class favorites & history management — powerful, searchable, organizable, beautiful.
AI everywhere, done legendarily — summarize, chat-with-page, ask about selection, AI search, compose/rewrite in any text field, translate, extract, automate reading, and more — powered by the exact same providers and models as Zyquo Cloud (all of them).

Zyquo Atlas reuses Zyquo Cloud's provider/API layer and encrypted key vault, and must match the family's premium native design quality.

Naming conventions (use consistently everywhere):

Display name / product name: Zyquo Atlas
App bundle: Zyquo Atlas.app
Bundle identifier: com.zyquo.atlas
Executable / SPM target: ZyquoAtlas (no space)
Data folder: ~/Library/Application Support/ZyquoAtlas/
Profiles/browsing data: ~/Library/Application Support/ZyquoAtlas/Profiles/
Repo module prefix in file headers: Zyquo Atlas

# 📋 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:

swift

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

For shell scripts / Makefiles:

bash

#
#  <filename>
#  Zyquo Atlas
#
#  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 build AI features before a real tab can load and render a page, and do not write any code before Phase 0 research + Zyquo Cloud study are complete.

Working rules:

One phase at a time. At the start of each phase, write a checklist into docs/PLAN.md; check items off as you go. At the end of each phase, run a phase checkpoint: build (swift build), run what's runnable, fix all warnings/errors, write a 3–5 line phase summary in docs/PLAN.md before moving on.
Phase gates: Phase 0 is complete only when docs/AI-BROWSER-RESEARCH.md and docs/PROVIDER-REUSE.md are complete. Phase 2 is complete only when a WKWebView-based tab can navigate, show progress, handle back/forward, and the multi-tab model works. Phase 3 is complete only when page content can be reliably extracted and fed to a model, and one AI action (summarize page) works end-to-end with streaming. Phase 4 spec is the contract for all UI in Phase 6. Phase 7 is complete only when browser + AI verification passes with real keys. Phase 8 is complete only when spctl says "Notarized Developer ID".
Single source of truth, everywhere:
- Provider/model behavior → ported from Zyquo Cloud's client layer (Phase 0.B); never re-invent request formats. All Zyquo Cloud models are available in Atlas.
- Colors, fonts, spacing, radii → base values from ZyquoTheme tokens; user themes override via the theming engine (Phase 4). Zero raw hex values or magic numbers in views.
- Web engine, content extraction, and AI orchestration → live in the Browser/, Content/, and AI/ layers; never leak WKWebView or network guts into unrelated views.
- Product naming → per the conventions above. Never Zyquo alone, never ZyquoAtlas in user-facing text.
Coherence sweeps: after Phases 3, 6, and 8, do a consistency pass (uniform naming — always Tab, AIAction, PageContext, ProviderClient; no dead code; headers present; folders match Phase 2).
Compile early, compile often. Never accumulate more than one file of unbuilt changes.
Commit discipline: one logical unit per commit, phase-prefixed message. Never commit secrets or user browsing data.
Privacy is a design constraint, not a feature bullet: page content only leaves the machine when the user invokes an AI action (or has explicitly enabled an auto action), always to the user's chosen provider via their own key, never to Zyquo. This must hold from the first AI code written.

# ⚠️ PHASE 0 — MANDATORY RESEARCH + ZYQUO CLOUD STUDY (DO THIS FIRST, BEFORE ANY CODE)

Two mandatory research tracks, each producing a document. No Swift until both are done.

# 0.A — `docs/AI-BROWSER-RESEARCH.md` — how to integrate AI into a browser, legendarily (INTENSIVE WEB RESEARCH)

Do NOT rely on training data. Perform several intensive web research sessions studying how the best AI browsers and browser-AI products actually work, and synthesize a concrete, functional design. Research at minimum:

The landscape. Study current AI browsers and AI browsing features for patterns worth stealing and pitfalls to avoid: Arc / Arc Max & Dia (Browser Company), Perplexity Comet, Brave Leo, Microsoft Edge Copilot, Opera Aria, SigmaOS, and Chrome's built-in AI. Document what each does well: page summarization, chat-with-page, AI search/answers, tab organization, "ask about this", command bars, writing assistance, agentic browsing. Extract the functional interaction patterns, not marketing.
Page content extraction for LLMs. The hard part. Research how to reliably turn a live web page into clean, model-ready text: readability/DOM extraction (Mozilla Readability-style main-content extraction), stripping nav/ads/boilerplate, preserving structure/headings/links, handling article vs. app pages, extracting the user's current text selection, capturing visible viewport vs. full document, and handling very long pages (chunking + map-reduce summarization). Document how to inject JavaScript into WKWebView (WKUserScript, evaluateJavaScript) to get this content out.
Chunking, context, and long pages. How to summarize/answer over pages that exceed the context window: chunking strategies, map-reduce and refine summarization, embedding-free relevance selection (keyword/heuristic) vs. optional local embeddings, and citing which part of the page an answer came from.
AI surfaces & UX patterns. Where AI lives in a legendary browser: an AI command bar / omnibox (ask vs. navigate vs. search intent detection), a contextual sidebar chat bound to the current page/tab, inline selection actions (select text → floating "Ask / Explain / Translate / Rewrite"), AI-assisted writing in any web text field, AI search (answer + sources instead of just links), tab & session summarization, auto-summaries on hover/open, and lightweight agentic actions (e.g., "find and open the docs page for X"). Document keyboard-driven flows.
Streaming & responsiveness. How to stream AI output into browser UI without blocking navigation, run AI per-tab, cancel on navigation, and keep everything at 60fps.
Multi-tab / multi-page reasoning. Patterns for "summarize these 5 tabs", "compare these pages", chat that can reference multiple open tabs.
Safety/privacy & correctness. Clear consent before sending page data, on-screen indication when content leaves the device, avoiding hallucinated citations, and grounding answers in extracted content.

Write it into docs/AI-BROWSER-RESEARCH.md. Every AI feature in later phases must trace to a pattern documented here.

# 0.B — `docs/PROVIDER-REUSE.md` — study the Zyquo Cloud repo and reuse its providers

Before writing provider code, read and study the Zyquo Cloud repository (sibling project). Locate it on disk (check the user's projects folder; if not found, ask the user for its path). Document and reuse:

Exactly how each provider's API is called in Zyquo Cloud: base URLs, auth headers, request/response Codable models, the shared OpenAICompatibleClient, native AnthropicClient / GeminiClient, and the streaming (SSE) handling. Atlas must call models the exact same way — port or factor the code so it is identical to Cloud's.
The complete model catalog Zyquo Cloud ships (ModelCatalog / docs/PROVIDERS.md). Include ALL of these models in Zyquo Atlas — every provider, every model available in Cloud is available in Atlas. The user picks a default AI model for browsing and can override per feature (e.g., a fast cheap model for hover-summaries, a strong model for deep chat).
The secure key vault from Cloud (custom AES-256-GCM encryption, NO Keychain). Atlas reuses the same SecureKeyStore design and vault format.
Any provider-specific streaming quirks so Atlas handles all uniformly behind the ProviderClient protocol.

Outcome: Atlas's AI layer speaks to the identical providers/models as Zyquo Cloud, with the same keys and behavior.

# PHASE 1 — Project Setup (No Xcode IDE)

Toolchain: Swift Package Manager. Package.swift, executable target ZyquoAtlas. Build swift build -c release.
Web engine: WebKit / WKWebView (the system web engine) — the correct, supported path for a native macOS browser without bundling Chromium. Use WKWebViewConfiguration, WKUserContentController, WKWebsiteDataStore (persistent + non-persistent for private tabs), and process pooling for multi-tab.
App bundle: Makefile builds release, assembles Zyquo Atlas.app (Contents/MacOS/ZyquoAtlas, Info.plist, Resources/AppIcon.icns), signs (Phase 8; ad-hoc for make dev).
Info.plist: CFBundleDisplayName = Zyquo Atlas, bundle ID com.zyquo.atlas, LSMinimumSystemVersion (macOS 13.0+), NSHighResolutionCapable, LSApplicationCategoryType (public.app-category.productivity), and NSAppTransportSecurity configured appropriately for a browser loading arbitrary sites (a browser needs to load HTTP/arbitrary content — document the correct ATS posture; the WKWebView content itself is the exception surface, keep app's own API calls HTTPS-only). Register as a candidate default browser (CFBundleURLTypes for http/https, and handle NSUserActivityTypes/default-browser APIs). Universal (arm64 + x86_64) for release.
Entry point: @main SwiftUI App; proper activation from terminal launch.
Dependencies: Foundation + SwiftUI + WebKit + CryptoKit; Apple swift-markdown acceptable. Reuse Zyquo Cloud's URLSession networking — no external HTTP libs.

# PHASE 2 — Architecture + Browser Core

text

Sources/ZyquoAtlas/
├── App/                    # @main, window/scene, menu bar, default-browser handling
├── DesignSystem/           # ZyquoTheme tokens + ThemeEngine (user themes) 
├── Models/                 # Tab, TabGroup, Bookmark, HistoryEntry, Profile, AIAction, PageContext…
├── Browser/
│   ├── WebView.swift            # NSViewRepresentable wrapper over WKWebView
│   ├── TabManager.swift         # tabs, tab groups/spaces, ordering, suspension
│   ├── NavigationController.swift # url handling, back/forward, reload, progress
│   ├── ProfileStore.swift       # data stores, cookies, private/persistent
│   └── DownloadManager.swift    # file downloads
├── Content/
│   ├── ContentExtractor.swift   # injected JS → clean readable text, selection, metadata
│   ├── Readability.js           # bundled main-content extraction script
│   └── PageContext.swift        # normalized page representation for the model (title, url, text, selection, chunks)
├── AI/
│   ├── AIService.swift          # orchestrates provider calls for browser actions (streaming)
│   ├── AIActions.swift          # summarize, chat-with-page, ask-selection, translate, rewrite, AI-search, compare-tabs…
│   ├── Summarizer.swift         # chunking + map-reduce/refine for long pages
│   └── OmniIntent.swift         # omnibox intent: navigate vs. search vs. ask
├── Providers/               # PORTED FROM ZYQUO CLOUD (all models)
│   ├── ProviderProtocol.swift
│   ├── OpenAICompatibleClient.swift
│   ├── AnthropicClient.swift
│   └── GeminiClient.swift
├── Features/
│   ├── BookmarksService.swift   # favorites: folders, tags, search
│   ├── HistoryService.swift     # full-text searchable history
│   └── ReadingList.swift
├── Services/
│   ├── SecureKeyStore.swift     # reused from Zyquo Cloud (no Keychain)
│   └── PersistenceService.swift # SQLite or JSON for bookmarks/history/sessions
├── ViewModels/
└── Views/

Tabs: real multi-tab with process reuse, lazy loading, background-tab suspension to save memory, restore-on-launch, tab groups / "spaces". Each tab owns a WKWebView + navigation state + its own AI context.
PHASE GATE: a tab must navigate to a URL, show a determinate progress bar, support back/forward/reload/stop, open links in new tabs, and the omnibox must resolve URL vs. search — before any AI work.

# PHASE 3 — AI EVERYWHERE (THE DEFINING LAYER)

Build the content pipeline first, then the AI actions on top. PHASE GATE: "Summarize this page" works end-to-end with streaming, grounded in extracted content, on a long real article, using a Zyquo Cloud model.

# 3.A — Content extraction (`ContentExtractor` + `Readability.js`)

Inject JavaScript into the active WKWebView to extract: page title, URL, clean main-content text (Readability-style, boilerplate stripped), headings/structure, links, meta description, and the user's current selection. Handle article vs. app pages; fall back gracefully.
Produce a normalized PageContext; for long pages, chunk it (with overlap) for map-reduce summarization per the research. Cache per tab; invalidate on navigation.

# 3.B — AI actions (`AIService` + `AIActions`) — all streaming, all cancel-on-navigation

Implement, at minimum, these legendary, functional AI surfaces (from docs/AI-BROWSER-RESEARCH.md):

AI Command Bar / smart omnibox: typing detects intent — navigate (URL), search (web), or ask (AI answer with sources). Asking returns a streamed answer plus source links, without leaving the page.
Chat-with-page sidebar: a per-tab contextual chat bound to the current PageContext; ask follow-ups about the page; answers cite the section they came from; model picker in the sidebar (all Cloud models).
Selection actions: select text on any page → floating toolbar with Explain / Summarize / Translate / Rewrite / Ask; result appears in a popover or the sidebar.
Summarize page / TL;DR: one keystroke; long-page map-reduce; key points + optional full summary.
AI writing assist in web text fields: in any editable field (<textarea>, contenteditable), offer improve/rewrite/expand/shorten/fix-grammar/translate via a small inline affordance.
Translate page / selection to a chosen language.
Multi-tab reasoning: "summarize/compare these open tabs" — gather several tabs' PageContext and answer across them.
Optional auto-actions (opt-in): auto-summary on opening long articles, hover-preview summaries of links — always user-toggleable.
Privacy: before any page content is sent, respect the consent model (Phase 0.B / global privacy rule); show a clear indicator when content leaves the device; per-site and global toggles.

# 3.C — Orchestration

AIService routes each action to the chosen provider/model via the ported client layer, streams tokens into the relevant UI, cancels in-flight requests when the user navigates or hits Stop, and lets the user choose different default models per action class (fast/cheap for hovers, strong for deep chat).

# PHASE 4 — DESIGN SYSTEM, THEMING ENGINE & UI (LIGHT THEME + MASSIVE CUSTOMIZATION)

Two things at once: a flawless flagship light theme (family standard) AND a massive customization engine that lets users transform the browser. Build both properly.

# 4.1 — Base light theme (family standard, must be perfect)

Base tokens in ZyquoTheme — Atlas identity is a balanced teal-indigo "map/atlas" story (explorer, cartography):

Token	Value (light)	Usage
`background`	`#FAFBFC` (crisp cool off-white)	Chrome / canvas
`surface`	`#FFFFFF`	Toolbars, panels, cards
`surfaceSecondary`	`#F1F4F6`	Hover, inactive tabs
`accent`	`#1FA9A0` → paired with indigo `#4E63E0` (atlas teal-indigo)	Active tab, selection, AI actions, omnibox focus
`accentSubtle`	`#E6F5F3`	Active tab tint, selected rows
`textPrimary` `#1A1D22` · `textSecondary` `#6B7280` · `textTertiary` `#9CA3AF` · `border` `#E5E9EC`
`success`/`warning`/`danger`	`#2FA36B`/`#D9822B`/`#D64545`	Status

Family rules apply (no pure black on white, 0.5pt hairlines, ultra-soft shadows on floating panels only, dark theme derived, light theme is flagship). Typography/spacing/radii identical to the family (body 13.5pt/1.45; scale 4–32; radii 6/10/14). Chrome must be quiet and refined so web content is the star.

# 4.2 — THE THEMING & CUSTOMIZATION ENGINE (a headline feature)

Users can massively customize display and themes. Implement a real ThemeEngine where user settings override base tokens live:

Color themes: ship 8–12 gorgeous built-in themes (light & dark variants) + a custom theme editor (pick accent, background, chrome tint, toolbar color, active-tab color) with live preview; import/export themes as small JSON files.
Backgrounds: solid, gradient, or image/wallpaper behind the chrome / new-tab page; subtle translucency (NSVisualEffectView) toggles.
Layout & chrome: tab bar position (top horizontal OR left vertical sidebar like Arc), compact/comfortable density, show/hide toolbar elements, address bar centered vs. left, tab shape/rounding, separators on/off.
Typography & display: UI font choice and size; default web page zoom; per-site zoom memory; optional reader-mode typography controls (font, width, theme) for articles.
New Tab / Start page: fully customizable — background, greeting, favorites grid, quick AI ask box, recent history, widgets; user chooses what appears.
Spaces/profiles: multiple profiles (work/personal) each with their own theme, tabs, favorites, and data store. All customization is persisted per profile and applied without restart, at 60fps.

# 4.3 — Core browser UI (exact spec)

Window chrome: unified toolbar — back/forward, reload/stop, the AI omnibox (rounded, accent-focus ring; shows security indicator, reader-mode button, AI-ask button, and a page-AI status glyph), profile switcher, extensions/downloads, new-tab (+), and an AI panel toggle. Respects the tab-bar-position setting (top or left).
Tabs: smooth open/close/reorder animations; drag to reorder and into groups; hover previews; audible-tab indicator; pinned tabs; suspended-tab dimming; middle-click close; keyboard tab switching.
AI sidebar (right, collapsible ~360pt): the chat-with-page surface — model chip (all Cloud models), streamed answers with page-section citations, quick-action buttons (Summarize, Key points, Translate, Ask selection), and a history of AI interactions for this tab/session.
Selection floating toolbar: appears on text selection in-page (Explain/Summarize/Translate/Rewrite/Ask), positioned near the selection, dismisses on click-away.
Favorites (Bookmarks) manager: dedicated view — folders, tags, drag-and-drop organization, full-text search, favicon grid or list, edit title/url/notes, import/export (HTML bookmarks). Bookmarks bar (toggleable) under the toolbar.
History: full-text searchable history view grouped by day/site, with filters, delete-range, and "ask AI about my history" (e.g., "find that article about X I read last week"). Clear-data controls per profile.
Reading list & Reader mode: clean, themeable reader view with AI summary at the top.
Downloads: toolbar popover with progress, reveal, and open.
Empty/new-tab state: a stunning customizable start page with a prominent AI ask box.

# 4.4 — Motion & quality gate

Family motion standard (smooth streaming, 150ms fades, 80ms hovers, .snappy popovers, 60fps, lazy rendering). Browser-specific: buttery tab animations, no jank while a page loads AND AI streams simultaneously, theme changes apply instantly. Quality gate before done: review every screen and state (loading, error page, no-network, private mode, AI streaming, AI consent prompt, long-page summarizing, empty favorites/history, custom theme applied, vertical vs. top tabs). If it looks "developer-made", iterate.

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

Designed in SVG first (assets/icon/zyquo-atlas.svg) → .icns. Visual sibling of Cloud, Local & Agent: same squircle, same Z-monogram DNA, same premium quality — telling the browser / atlas / exploration story.

Creative direction — the Z that explores. Two directions (render both, keep the best):

Z-globe: the bold "Z" monogram integrated with a minimal globe / meridian motif — thin latitude/longitude arcs curving behind or through the Z, suggesting the web and cartography; the Z's diagonal reads like a route across the globe.
Z-compass: the Z centered within a refined compass / atlas mark — a subtle compass rose or orbiting ring, evoking navigation and discovery.

Canvas: Big Sur–style rounded squircle (Apple curvature).
Palette (mirrors the app): smooth vertical gradient blending teal into indigo (#22C3B8 → #1FA9A0 → #4E63E0 territory, tune for depth — an explorer's teal-to-deep-indigo, like sea into sky), the Z and globe lines in white to near-white with subtle inner luminosity and one soft top light. Distinct from Cloud's sky-blue, Local's silicon-green, and Agent's violet, while unmistakably the same family: same squircle, same Z, same lighting, same finish.
Precision & iteration: clean paths, viewBox="0 0 1024 1024", optical centering, thin arcs that survive downscaling (thicken or drop the finest meridians for 16/32px). Render 16→1024, inspect, refine.

Pipeline (Makefile): SVG → PNGs (16→1024 incl. @2x) via rsvg-convert or a CoreGraphics rasterizer → AppIcon.iconset → iconutil -c icns. SVG stays as source of truth. Derive the monochrome menu bar/toolbar template glyph and the in-app wordmark from the same SVG.

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

# Browser core

Fast multi-tab WKWebView browsing: tab groups/spaces, pinning, suspension, session restore, hover previews, drag-reorder
Smart AI omnibox (navigate / search / ask intent), security indicators, reader mode
Multiple profiles with isolated data, themes, favorites; private/incognito tabs (non-persistent data store)
Downloads, find-in-page, per-site zoom & settings, basic content-blocking hooks
Full favorites management (folders, tags, search, import/export, bookmarks bar) and full-text history (search, filters, ask-AI-about-history)

# AI everywhere (all models from Zyquo Cloud)

AI answers in the omnibox with sources; per-tab chat-with-page with section citations
Selection actions (Explain/Summarize/Translate/Rewrite/Ask) anywhere on a page
Summarize / TL;DR any page incl. long-page map-reduce; translate page or selection
AI writing assist in web text fields; multi-tab summarize/compare
Opt-in auto-summaries and link hover-summaries; per-action default model selection (fast vs. strong)
Reused encrypted key vault (no Keychain); clear privacy indicators when content leaves the device

# Massive customization (headline)

Theme engine: built-in themes + custom theme editor, backgrounds/wallpapers, translucency
Layout: top or left vertical tabs, density, chrome element toggles, tab shapes
Fully customizable new-tab/start page; UI font & size; per-profile persistence, live apply

# Native polish & shortcuts

⌘T new tab, ⌘W close tab, ⌘L focus omnibox, ⌘⇧A open AI sidebar, ⌘F find, ⌘D bookmark, ⌘Y history, ⌘⇧N private window, ⌘1–9 tab switch, ⌥Space Quick AI ask
Toggleable menu bar extra (quick AI ask / open Atlas); handoff as default browser

# PHASE 7 — VERIFICATION (MANDATORY)

The user will provide real API keys (same providers as Zyquo Cloud). You MUST:

Browser correctness: verify navigation, back/forward, tab lifecycle (open/suspend/restore/close), downloads, private-mode data isolation, profile switching, bookmark import/export, and full-text history search — on a set of real sites.
Content extraction quality: on a suite of varied real pages (news article, docs page, blog, JS-heavy app, very long article, page with a user selection), verify ContentExtractor returns clean, correct main-content text and correct selection; verify chunking on long pages.
AI verification across ALL Cloud models: for every provider/model in the shared catalog, run each core AI action (omnibox ask, summarize page, chat-with-page follow-up, selection explain/translate, rewrite in a text field, multi-tab compare) and confirm streaming works and answers are grounded in the extracted content. Produce a table: provider → model → action → ✅/❌ → notes. Fix every failure until green.
Privacy & cancellation: confirm page content is sent only on user-invoked AI actions (or opt-in autos), the on-screen "content leaving device" indicator fires correctly, and navigating/Stop cancels in-flight AI requests.
Never commit, log, or embed the user's keys or any browsing data; 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: