> ## Documentation Index
> Fetch the complete documentation index at: https://cofounder.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> The collector → reasoner → actor pipeline.

Every co-founder run is three deterministic stages.

## 1. Collector

Pulls every relevant signal in parallel from your Appeeky data and your synced App Store Connect tables. The collector is **dumb on purpose** — it never decides anything, it just assembles a `CollectorPayload`.

What it pulls per run:

| Source               | Data                                                       | Cadence                    |
| -------------------- | ---------------------------------------------------------- | -------------------------- |
| Appeeky API          | ASO brief, visibility                                      | Weekly                     |
| Appeeky API          | Keyword movers (≥5 rank delta)                             | Daily                      |
| Appeeky API          | Tracked competitors                                        | Daily                      |
| Appeeky API          | Market chart movers                                        | Daily                      |
| App Store Connect    | Downloads / revenue / subs (30d)                           | Daily                      |
| App Store Connect    | Impressions / page views (7d, unique)                      | Daily                      |
| App Store Connect    | Reviews (since last run) + unanswered ones                 | Daily                      |
| App Store Connect    | Subscription business metrics (MRR, trials, churn)         | Daily                      |
| Apple Search Ads     | Campaign spend / CPI + wasteful search terms               | Every run (when connected) |
| RevenueCat           | Cross-platform revenue snapshot (MRR, actives, trials)     | Every run (when connected) |
| Web Supabase         | Tracked keywords + rank history                            | Daily                      |
| Forecasts            | Holt-Winters projections on downloads/revenue              | Every run                  |
| [Signals](./signals) | Open anomalies / forecast breaches that triggered this run | Signal-triggered runs      |
| `cofounder_*`        | Stale actions (≥2 days pending)                            | Every run                  |
| `cofounder_*`        | Past decisions + measured outcomes                         | Every run                  |
| `cofounder_*`        | Crisis baseline + competitor snapshots + metadata change   | Every run                  |

ASO brief is the only signal we **don't** refresh daily — it changes slowly and costs API credits, so we refresh it weekly.

***

## 2. Reasoner

Two-phase LLM pipeline using the [Vercel AI SDK](https://sdk.vercel.ai/):

### Phase 1 — Research (skipped in `quick` mode)

`generateText` with tools. The model can drill into specific keywords, competitors, or memory facts before producing the report. The agent autonomously decides what's worth investigating.

### Phase 2 — Synthesis

`generateObject` with a strict Zod schema (`DailyReportSchema`). The model receives:

* The full collector payload as text
* Phase-1 research findings
* Active memory facts ("this app is for X", "owner prefers concise output")
* Last 5 episodes (action → outcome pairs) for learning

Output is **always** schema-validated. If the model deviates, the run fails fast and the orchestrator retries.

### Specialist agents

Focused sub-agents (ads, ASO, product intelligence, release intelligence, social media) run their own internal reports when relevant, and the main reasoner folds their findings into the briefing. You'll see their conclusions cited in the report rather than raw data dumps.

### Which model runs

The model comes from your [LLM settings](./llm-settings) — pick a provider (OpenAI, Anthropic, Google, Kimi, DeepSeek), optionally bring your own API key, and choose research/synthesis models from the catalog. `analysisDepth` no longer selects the model; it controls how much investigation the agent is allowed to do:

| Depth      | Research phase | Tool-step budget | Self-critique pass |
| ---------- | -------------- | ---------------- | ------------------ |
| `quick`    | Skipped        | 3                | No                 |
| `standard` | Yes            | Moderate         | Yes                |
| `deep`     | Yes            | 12               | Yes                |

***

## 3. Actor

Reads `report.proposedExternalActions` and decides what to do per action:

```
┌─ slack_summary    → posts to your Slack channel/thread
├─ linear_issue     → creates a Linear ticket
├─ github_issue     → opens a GitHub issue
├─ asc_metadata_update → applies the change to App Store Connect
├─ asc_review_reply    → replies to a user review
├─ asc_version_create  → creates a new draft version
├─ webhook_post     → fires your outbound webhook
└─ notion_page      → creates a row in your Notion database
```

Plus **automatic deliveries** that don't need an LLM action — they happen every run if the integration is enabled:

| Auto-delivery                                                 | Trigger                          |
| ------------------------------------------------------------- | -------------------------------- |
| Slack daily summary                                           | Slack integration enabled        |
| Telegram briefing message                                     | Telegram paired                  |
| Telegram/Slack approval cards (one per proposed action)       | Write mode + integration enabled |
| Webhook: `report.created`                                     | Webhook integration enabled      |
| Notion DB row                                                 | Notion integration enabled       |
| Public Diary entry                                            | `publicDiaryEnabled=true`        |
| [Weekly portfolio digest](../capabilities/portfolio-briefing) | 2+ live apps + portfolio enabled |

### Read mode vs write mode

* **Read mode** (`agentMode: "read"`): only `slack_summary`, `webhook_post`, and `notion_page` are allowed. The agent can analyze and notify but never writes to ASC or opens issues.
* **Write mode** (`agentMode: "write"`): all action types allowed, but each one still requires either being in `autoApproveTypes` or human approval via the API/Slack buttons.

### Fingerprinting & dedup

Every action gets a `sha1(owner+app+type+subject)` fingerprint. If the same action shows up tomorrow, it's marked `superseded` instead of duplicated. This is why the agent can run twice a day without spamming you.

***

## Memory

All in Supabase, split between what the agent learned and what you told it:

* **Facts** (`cofounder_memory_facts`) — structured key/value the agent knows about you and your app. Set automatically (`owner_name`, `app_category`) or by you via the memory API.
* **Episodes** (`cofounder_memory_episodes`) — a record of every applied action with before/after metric snapshots. Drives the learning loop.
* **Company profile** (`cofounder_company_profile`, `cofounder_app_profile`) — what *you* tell the agent about the business: stage, ICP, positioning, brand voice, and hard rules like *"never recommend removing the free tier."* Drafted for you after onboarding, then yours to correct. Unlike facts it is never scored or evicted — everything you confirm reaches every run.
* **Documents** (`cofounder_documents`) — the prose half of the same idea. `business_context.md` is read on every briefing; the rest of the [Library](../capabilities/library) is retrieved when it matches the work at hand. The agent can propose edits to your context but never make them ([knowledge patches](../capabilities/knowledge-patches)).

Facts and episodes are embedded for **semantic search** — "did we already try X?" works in chat even when the wording doesn't match, with a recency fallback when embeddings are unavailable.

***

## Persistence

Every run writes to:

* `cofounder_runs` — orchestration row with cost, duration, status
* `cofounder_reports` — the structured `DailyReport` (full JSONB)
* `cofounder_actions` — every proposed/applied action with status timeline
* `cofounder_competitor_snapshots` — today's competitor metadata for tomorrow's diff
* `cofounder_metadata_snapshots` — today's *your* metadata (for A/B test memory)
* `cofounder_review_baselines` — rolling 30d sentiment baseline (for crisis mode)
* `cofounder_public_diary` — sanitized entry if public diary is enabled