ai-partner: deep link into Partner tab with context

[CraigBuckmaster]

Parent epic: #1446 (Amicus — AI Study Partner v1)
Phase: 4 · Size: XS · Depends on: #1454 (Amicus tab), #1466 (home card)

Enable contextual handoffs into the Amicus tab that pre-seed a new thread with a starter query. Used by the home card (#1466), external deep-links (future), and potentially FAB escape routes.

---

Files to modify

• app/src/navigation/types.ts — ensure AmicusStackParamList.NewThread accepts seedQuery and seedChapterRef
• app/src/screens/AmicusThreadListScreen.tsx — handle NewThread navigation by creating a thread with seed and navigating onward
• app/src/navigation/RootNavigator.tsx — register deep-link config mapping URLs to Amicus routes

Files to create

• app/src/services/amicus/deepLink.ts — helper that constructs + dispatches seeded navigation actions
• app/src/services/amicus/__tests__/deepLink.test.ts

---

API surface

export interface AmicusSeed {
  query: string;
  chapterRef?: { book_id: string; chapter_num: number } | null;
}

export function navigateToAmicusWithSeed(
  navigation: NavigationProp<any>,
  seed: AmicusSeed
): void;

The function:

1. Calls navigation.navigate('AmicusTab', { screen: 'NewThread', params: { seedQuery: seed.query, seedChapterRef: formatChapterRef(seed.chapterRef) } })
2. Logs the event for analytics (ai-partner: aggregate privacy-safe analytics #1469)

NewThread route behavior

When navigated to with a seed:

1. Immediately create a new thread (via createAmicusThread from ai-partner: conversation persistence (user.db) #1457) with title generated from seed query
2. Append seed as the first user message
3. Trigger stream (via streamChat from ai-partner: streaming chat UI with citation pills #1455)
4. Replace nav stack so back button goes to previous screen (not NewThread → ThreadList which would feel broken)

Implementation note: NewThread doesn't need to be a rendered screen — it can be a "transition" route that redirects to Thread after setup. Use useEffect to perform the transition in the screen component, with a loading indicator shown for the ~100ms it takes.

External deep-link config

For future use (e.g., push notifications in Phase 5, widget taps in v2):

companionstudy://amicus/new?q=<url-encoded-query>&ch=<book:chapter>

Register in RootNavigator.tsx deep-link config. Not actively used in v1 but wired so tapping a notification or widget can open Amicus with seed.

Home card integration

AmicusHomeCard (#1466) calls navigateToAmicusWithSeed(navigation, { query: prompt.seed_query }) on tap.

---

Acceptance criteria

• navigateToAmicusWithSeed navigates to Amicus tab and creates thread with seed
• First user message = seed query; streaming begins automatically
• Back button returns to previous screen (not NewThread)
• Deep-link URL companionstudy://amicus/new?q=test routes correctly (spot-check; not required to fully test)
• Home card tap seeds correctly (verified against ai-partner: home screen card component #1466 integration)
• Unit tests cover: action construction, URL encoding, deep-link parsing
• No any types; lint clean

Out of scope

• Push notifications that deep-link → future Phase 5 or later
• Widget extensions → v2 or beyond