> ## 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.

# Growth Channels (Reddit lead-generation)

> Scan social platforms for high-intent posts about your app, score buying intent with AI, and draft replies you approve before posting.

The **Growth Channels** module turns Reddit (and, in future versions, HackerNews / X / ProductHunt) into a steady source of inbound leads for your app. It works on a three-step value loop:

```
1 reply you write =  customer today + Google ranking for years + AI answer recommendation
```

The same reply gets pulled into ChatGPT/Perplexity answers because Reddit content scores high on AI training and live web search. We track that cross-link automatically and surface it in your weekly briefing.

## How it works

The pipeline runs every 15 minutes (configurable per project):

```
fetch new posts → pre-filter → LLM intent scoring → if score ≥ threshold → LLM reply draft → lint → persist
       │                                                                                         │
       ▼                                                                                         ▼
seen_posts (Redis + Postgres dedupe)                              cofounder approval flow (Slack/Telegram)
```

Important constraints (V1):

* **No auto-posting.** The pipeline ONLY produces drafts. You manually paste-and-post on Reddit, then `mark-replied` the URL back to us.
* **Hard dedupe.** Every post is processed exactly once per project — `growth_seen_posts` is the truth source, Redis is the fast cache.
* **Per-project daily LLM budget.** If `daily_llm_budget_cents` is hit, the project auto-pauses for the day; you see the warning on the dashboard and raise the cap.
* **Reply linter** runs after every draft. Issues (`missing_disclosure`, `generic_opener`, `too_many_emojis`, …) are surfaced as warnings — drafts are never silently dropped.

## Intent scoring

Each post gets three sub-scores from the LLM. The final intent score is a weighted sum:

| Dimension               | Weight | What it captures                                         |
| ----------------------- | ------ | -------------------------------------------------------- |
| `problem_fit`           | 0.50   | Post describes a problem this product solves             |
| `buying_signal`         | 0.30   | User is actively shopping (not venting)                  |
| `reply_appropriateness` | 0.20   | Replying with our product would feel natural, not spammy |

Plus a `buyer_stage` classification:

* **awareness** → user describes a problem without naming a category. Reply with empathy + question. NO product mention.
* **consideration** → user is comparing options. Mention with disclosure if natural.
* **decision** → user has narrowed down. Direct mention with disclosure is fine.

The drafter respects `buyer_stage` and the subreddit's `promo_tolerance` profile (`strict`, `moderate`, `open`). Strict subs (e.g. r/Anxiety, r/Depression, r/meditation) never get product-mention drafts — only helpful advice.

## Onboarding (one input)

Paste an `appId` you've already connected to App Co-founder:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/growth/projects/bootstrap
{ "channel": "reddit", "appId": "1234567890" }
```

The bootstrap endpoint returns a fully-populated `GrowthProjectInput` draft with:

* `productDescription` + `targetAudience` + `antiPersona` (generated from App Store metadata)
* 5-10 suggested subreddits (LLM picks based on your audience)
* `competitorKeywords` (from your tracked competitors)
* `intentPatterns` (e.g. "looking for", "alternative to") — used as a cheap pre-filter
* Reasonable defaults for `minIntentScore` (60), `scanIntervalMin` (60), `dailyLlmBudgetCents` (500)

You review, edit, save with `POST /v1/growth/projects`. Project is created with `enabled: false` by default — flip to `true` when you're ready.

## State machine

```
pending  ──[user reviews]──┬──► approved  ──[user posts on reddit, pastes URL back]──► replied
                            └──► dismissed
                                             ──[60 days, untouched]──► expired
```

`replied` triggers an automatic write to `growth_tracked_citations`. From that point on, the AI Visibility scan worker checks every LLM answer it fetches for your reply URL and increments `ai_citations_count` on a hit. You see those citations in your weekly briefing.

## API endpoints

### Projects

| Method   | Path                                    | Purpose                                     |
| -------- | --------------------------------------- | ------------------------------------------- |
| `POST`   | `/v1/growth/projects/bootstrap`         | One-input → suggested draft                 |
| `POST`   | `/v1/growth/projects`                   | Create                                      |
| `GET`    | `/v1/growth/projects?channel=reddit`    | List                                        |
| `GET`    | `/v1/growth/projects/:id`               | Get one                                     |
| `PATCH`  | `/v1/growth/projects/:id`               | Update (subs, threshold, depth, enabled, …) |
| `DELETE` | `/v1/growth/projects/:id`               | Delete (cascades opportunities)             |
| `POST`   | `/v1/growth/projects/:id/scan`          | Manually trigger a scan                     |
| `GET`    | `/v1/growth/projects/:id/stats?days=30` | Funnel + per-grouping + budget              |

### Opportunities

| Method  | Path                                                         | Purpose                          |
| ------- | ------------------------------------------------------------ | -------------------------------- |
| `GET`   | `/v1/growth/opportunities?status=pending&urgency=must_reply` | List                             |
| `GET`   | `/v1/growth/opportunities/:id`                               | Get one (full draft + breakdown) |
| `PATCH` | `/v1/growth/opportunities/:id/review`                        | `{ decision, editedDraft? }`     |
| `POST`  | `/v1/growth/opportunities/:id/mark-replied`                  | `{ replyUrl }`                   |

### Channel registry

| Method | Path                  | Purpose                                      |
| ------ | --------------------- | -------------------------------------------- |
| `GET`  | `/v1/growth/channels` | Discover available channels + config schemas |

## Configuration

Per-project (editable on the dashboard):

* `productDescription` (required, 10+ chars)
* `targetAudience` (required)
* `antiPersona` (required) — *"NOT for: enterprise teams; users specifically asking for free open-source alternatives."* Drives down false positives more than any other field.
* `minIntentScore` (default 60)
* `scanIntervalMin` (default 60, range 15-1440)
* `analysisDepth` (`quick` / `standard` / `deep` — controls model selection)
* `dailyLlmBudgetCents` (default 500)
* `allowProductMentionGlobal` (master switch)
* `channelConfig` — Reddit shape: `{ subreddits: string[], competitorKeywords: string[], intentPatterns: string[] }`

Environment (see `.env.example`):

* `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET`, `REDDIT_USER_AGENT`
* Model overrides: `GROWTH_MODEL_STD_SCORER`, `GROWTH_MODEL_STD_DRAFTER`, …

## More channels are coming

Reddit is the first channel. The system is built so new sources (e.g. Hacker News) can be added over time — when they land, the same opportunities view simply starts showing them, filterable by channel.

## Safety guards (all on by default in V1)

1. **Pre-filter** — posts shorter than 50 chars without a question mark are skipped before the LLM.
2. **Cascade** — drafter only runs on posts that beat the project's intent threshold.
3. **Hard rules in prompt** — competitor requests, wrong platform, jokes, developers-building-it all cap scores.
4. **Author throttle** — V1.5: if an author has been replied to twice in the last 30 days, score cap = 50.
5. **Subreddit profile** — strict subs (r/Anxiety, r/Depression, r/meditation, …) never produce product-mention drafts.
6. **Daily cap per grouping** — `GROWTH_GROUPING_DAILY_CAP` (default 2) — V1.5 enforcement.
7. **Stale post filter** — posts older than `GROWTH_MAX_POST_AGE_DAYS` (default 7) are skipped.
8. **Reply linter** — disclosure, length, link, generic opener, emoji count, marketing language.
9. **Daily budget** — per project, in cents. Auto-pauses the project for the day when exceeded.
10. **No auto-post** — nothing ever goes to Reddit from the server. You always click and paste.

## Co-founder chat (read-only)

In **Ask** (web chat, Slack, Telegram), Co-founder can **read** Growth data but cannot post replies or create projects:

| Tool                                                     | What it does         |
| -------------------------------------------------------- | -------------------- |
| `growth_reddit_status`                                   | Is Reddit connected? |
| `growth_projects_list` / `growth_projects_get`           | Project configs      |
| `growth_projects_stats`                                  | Scan/reply stats     |
| `growth_opportunities_list` / `growth_opportunities_get` | Inbox + AI drafts    |
| `growth_scheduled_posts_list`                            | Scheduled queue      |

Writes (`growth_opportunities_post_reply`, `growth_projects_create`, `growth_scheduled_posts_create`, …) stay in the **Growth dashboard** or MCP — not in Co-founder chat. See [My Apps workspace](./my-apps-workspace).