# 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:
1. **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.
2. **First-class favorites & history management** — powerful, searchable, organizable, beautiful.
3. **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:**

1. **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.
2. **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".
3. **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.
4. **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).
5. **Compile early, compile often.** Never accumulate more than one file of unbuilt changes.
6. **Commit discipline:** one logical unit per commit, phase-prefixed message. Never commit secrets or user browsing data.
7. **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:

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **Multi-tab / multi-page reasoning.** Patterns for "summarize these 5 tabs", "compare these pages", chat that can reference multiple open tabs.
7. **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:

1. **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.
2. **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).
3. **The secure key vault** from Cloud (custom AES-256-GCM encryption, **NO Keychain**). Atlas reuses the same `SecureKeyStore` design and vault format.
4. 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

```
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):
1. *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.
2. *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:

1. **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.
2. **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.
3. **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.
4. **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.
5. 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:**

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

Locate the **Developer ID Application identity name**, **Team ID**, **notarytool keychain profile (or Apple ID + app-specific password)**, entitlements, and any config there. **Reuse the exact same identity, Team ID, and notarytool credentials/profile for Zyquo Atlas.** Never invent placeholders, never print secrets, never commit them.

Then implement `make release`:
1. Build universal release (arm64 + x86_64, `lipo`), assemble `Zyquo Atlas.app`.
2. `entitlements.plist` with **Hardened Runtime**; include what a WebKit browser needs — network client, and (if you adopt App Sandbox for a browser) the appropriate network-client + files/downloads entitlements; WebKit uses XPC/child processes, so verify the correct posture and test. Prefer the **minimal** set that lets WKWebView, downloads, and the app's own HTTPS API calls work; document the choice.
3. `codesign --force --options runtime --timestamp --entitlements entitlements.plist --sign "Developer ID Application: <identity from zyquo-term>" "Zyquo Atlas.app"` — sign nested code (WebKit helper content, frameworks) first.
4. `ditto -c -k --keepParent` → `xcrun notarytool submit "Zyquo Atlas.zip" --keychain-profile "<profile from zyquo-term>" --wait`.
5. `xcrun stapler staple "Zyquo Atlas.app"`; verify `spctl -a -vv` = "accepted, source=Notarized Developer ID" and `stapler validate`.
6. Optional signed+stapled DMG (`hdiutil`).
7. On failure: `notarytool log`, fix (nested-code signing is the classic WebKit culprit), resubmit until it passes. Keep `make dev` (ad-hoc) for iteration.

---

## Engineering Standards

- Swift 5.9+ (Swift 6 mode if the toolchain allows); zero warnings
- `AIService` and network types as needed with structured concurrency; all provider and content types `Codable`
- WKWebView work correctly off/on the main actor as required; never block the main thread during load or AI streaming; cancel AI on navigation
- Robust, human-readable errors for every failure class (page failed to load, extraction failed on a hostile page, model/key missing, rate limited, network down); graceful error pages
- Provider layer identical to Zyquo Cloud with ALL models; base design tokens + user ThemeEngine overrides; UI strings centralized
- `README.md` (build) + `docs/` (AI-BROWSER-RESEARCH, PROVIDER-REUSE, PLAN); never commit secrets or browsing data
- Commit in logical, phase-prefixed increments

## Definition of Done

- `make release` produces a **Developer ID–signed, notarized, stapled** `Zyquo Atlas.app` (verified by `spctl`), built without the Xcode IDE
- A fast, stable multi-tab WKWebView browser with profiles, private mode, favorites, and full-text history — genuinely nicer to use than Safari
- **AI everywhere** works: omnibox ask-with-sources, chat-with-page with citations, selection actions, summarize/translate, writing assist, multi-tab reasoning — all streaming, all grounded in extracted content, using **every provider/model from Zyquo Cloud** (Phase 7 table green)
- The theming/customization engine delivers massive display & theme control (themes, backgrounds, top/left tabs, density, custom start page) applied live, per profile
- Privacy model holds: page content leaves the device only on user-invoked (or opt-in) AI actions, with a clear indicator; keys in the reused encrypted vault (no Keychain)
- The teal-indigo "atlas" SVG icon exists, is striking at all sizes, embedded as `.icns` + template glyph; clearly a sibling of the Cloud, Local, and Agent icons
- The light theme matches the Phase 4 base spec and passes the design quality gate; dark theme derived and correct
- Naming coherent everywhere: `Zyquo Atlas` user-facing, `com.zyquo.atlas`, `ZyquoAtlas` target/data folder
- **Every code file starts with the mandatory Author/Mail header** (verified by a repo-wide sweep)
- `docs/PLAN.md` shows every phase completed; `docs/AI-BROWSER-RESEARCH.md` and `docs/PROVIDER-REUSE.md` are complete and traceable to the implementation
- Zyquo Atlas feels like a polished, legendary, AI-native macOS browser — it pulverizes Safari