jarvis/docs/KICKOFF_PROMPT.md

# Jarvis iOS — Claude Code Kickoff Prompt

Paste this entire prompt into Claude Code to begin.

---

## Prompt

You are building **Jarvis** — a SwiftUI iOS app that connects to a self-hosted RSS news correlation platform and displays stories ranked by signal score.

Read `CLAUDE.md` before writing a single line of code. It contains every architecture decision already made. Do not deviate from it.

---

## Your job

Build the remaining SwiftUI views. The networking layer, models, stores, and onboarding screen are already written. You are building the UI on top of them.

### Views to build

1. **SignalFeedView** — the home screen
   - Wordmark `Jarvis` with `J` in #FF5C00, rest white, weight 800, kerning -2
   - Live/Offline connection indicator (driven by `WebSocketManager.shared.connectionState`)
   - Sync bar: "Synced X min ago · N cached" when live, "Last synced X min ago" when offline
   - Topic filter pills: All · Finance · Tech · Politics · Africa (calls `store.setTopic()`)
   - Column headers: Story / Signal ↓
   - List of `StoryRowView` sorted by `signalScore` descending
   - Pull to refresh calls `store.loadStories(refresh: true)`
   - Infinite scroll: call `store.loadMore()` when last row appears
   - Tap row → navigate to `StoryDetailView`

2. **StoryRowView** — one row in the signal feed
   - Left edge stripe: 3pt wide, color opacity tied to signal score (97 = #FF5C00, fades to #1a1a1a at 0)
   - Story title, dimmed proportionally to score (97 = white, 20 = #444)
   - Signal score number, same fade behaviour
   - Source count, topic, time ago in monospaced font
   - Source chips (first 2 named, rest "+N")
   - Small green dot if story is fully cached offline

3. **StoryDetailView** — full story
   - Back button "Signal feed"
   - Category label + signal score pill (e.g. "Finance  · 97 signal")
   - Large headline, weight 800
   - Source chips
   - "All N articles cached · available offline" line if cached
   - Consensus block: orange left border, dark orange background
   - Conflicting block: dark red left border, dark red background (only if `conflict != nil`)
   - Coverage timeline: chronological list of `TimelineEntry`, first item has orange node
   - Tapping a timeline entry → navigate to `ArticleReaderView`

4. **ArticleReaderView** — full article
   - Back button showing parent story headline (truncated to 30 chars)
   - Source pill in #FF5C00, timestamp in monospaced
   - Cached badge inline (green, only if article is in SwiftData)
   - Large headline weight 800
   - Hero image placeholder (AsyncImage with grey fallback)
   - Body text, #4a4a4a, size 16, line spacing 1.65
   - Divider then "More from this cluster" section
   - 2–3 other articles from same story as tappable rows

5. **FeedManagerView** — feed health and management
   - Wordmark `Jarvis` header + "+ Add feed" button
   - Platform connection card: server URL, live/offline dot (from `WebSocketManager`)
   - Search bar to filter feed list
   - Two sections: "Healthy" and "Needs attention"
   - Each row: RSS icon, feed name, poll interval + article count, health dot
   - Health dot: green (#2a5a2a) = active, amber (#AA6600) = failing with retry countdown, red (#5a1a1a) = dead
   - Swipe to delete calls `APIClient.shared.deleteFeed(id:)`
   - "+ Add feed" sheet: URL input + name field + confirm button

---

## Design rules — non-negotiable

- Background: `Color.black` / `#000000` everywhere
- Accent: `Color("KisaniOrange")` = `#FF5C00`
- Surface cards: `#111111`, `#1A1A1A`
- All screens: `.preferredColorScheme(.dark)`
- Font weight: 800 for headlines, 700 for labels, 400 for body — never use 600
- Monospaced font for: timestamps, signal scores, server URLs, feed metadata
- No gradients. No shadows. Flat surfaces only.
- Minimum tap target: 44pt
- Signal score stripe and text both fade: score 80–100 = full orange, 50–79 = dimmed orange, 20–49 = dark brown, 0–19 = near invisible

---

## Data flow rules — non-negotiable

- Views never call `APIClient` directly — always go through `StoryStore` or a dedicated `@StateObject` ViewModel
- Signal scores are server-computed — never calculate or modify them in the UI
- WebSocket events trigger REST refetches — the store handles this already
- SwiftData (`CachedStory`, `CachedArticle`) is the offline source — query it when the server is unreachable
- Use `@EnvironmentObject var store: StoryStore` in views that need stories
- Use `@EnvironmentObject var ws: WebSocketManager` for connection state

---

## Xcode project setup

1. Create new Xcode project: iOS App, named **Jarvis**, Swift, SwiftUI
2. Set minimum deployment target: **iOS 17.0** (required for SwiftData)
3. Add all provided `.swift` files to the project
4. In `Assets.xcassets` add a new Color Set named `KisaniOrange`:
   - Any / Dark: `#FF5C00`
5. Add `Assets.xcassets` Color Set `AppBackground`: `#000000`
6. The SwiftData model container is already configured in `JarvisApp.swift`

---

## File structure to produce

```
Jarvis/
  Views/
    Home/
      SignalFeedView.swift
      StoryRowView.swift
    Story/
      StoryDetailView.swift
    Reader/
      ArticleReaderView.swift
    Feeds/
      FeedManagerView.swift
      AddFeedSheet.swift
    Shared/
      SignalStripe.swift       ← reusable 3pt stripe component
      SourceChips.swift        ← reusable chips row
      CachedBadge.swift        ← reusable green cached indicator
      ConnectionBanner.swift   ← offline warning banner
```

---

## Start here

1. Read `CLAUDE.md`
2. Create the Xcode project and add all existing files
3. Build `SignalStripe.swift`, `SourceChips.swift`, `CachedBadge.swift` — shared components used by multiple views
4. Build `StoryRowView.swift`
5. Build `SignalFeedView.swift`
6. Build `StoryDetailView.swift`
7. Build `ArticleReaderView.swift`
8. Build `FeedManagerView.swift` + `AddFeedSheet.swift`
9. Run on simulator, fix layout issues, verify dark mode renders correctly
10. Confirm WebSocket connection state drives the live/offline indicator on the home screen

Do not skip steps. Do not simplify the signal stripe fade logic. Do not use placeholder colours — every hex value is specified above.