teft-leads 0.1.0__tar.gz

teft_leads-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/michaelwilhelmsen/.claude/commands/**)",
+      "Read(//Users/michaelwilhelmsen/.claude/skills/**)",
+      "Read(//Users/michaelwilhelmsen/.claude/**)",
+      "Read(//Users/michaelwilhelmsen/.claude/plugins/**)",
+      "Read(//Users/michaelwilhelmsen/.agents/skills/wayfinder/**)",
+      "Bash(gh issue *)",
+      "Bash(git ls-tree *)",
+      "Bash(git ls-remote *)",
+      "Bash(gh label *)",
+      "Bash(echo \"=== setup-matt-pocock-skills ===\" && cat ~/.claude/skills/setup-matt-pocock-skills/SKILL.md 2>/dev/null | head -60; echo \"=== search for a github tracker doc anywhere in ~/.claude/skills ===\" && grep -rl -i \"wayfinding operations\" ~/.claude/skills 2>/dev/null | head; grep -rl -i \"wayfinder:map\" ~/.claude 2>/dev/null | grep -iE 'tracker|github' | head)",
+      "Bash(gh api graphql -f 'query= *)",
+      "Bash(gh api *)"
+    ]
+  }
+}

teft_leads-0.1.0/.env.example

@@ -0,0 +1,35 @@
+# Copy to `.env` (git-ignored) and fill in. Never commit real values.
+
+# --- LLM provider (the `rank` command / M3) ----------------------------------
+# Default provider is Anthropic, model Sonnet 5 (cost-efficient; SKIP-rule calibration
+# re-checked equivalent to Opus on the #4 fixtures). Set the key you use below.
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+
+# Optional: switch the LLM. TEFT_LLM = anthropic (default) | openai.
+# TEFT_MODEL overrides the per-provider default model id.
+#   anthropic default: claude-sonnet-5   (claude-opus-4-8 for the frontier tier)
+#   openai   default: gpt-5.6-terra      (gpt-5.6-luna cheaper, gpt-5.6-sol frontier)
+# Re-run the fixtures before trusting a new provider — see VALIDATE.md.
+# TEFT_LLM=openai
+# TEFT_MODEL=gpt-5.6-terra
+
+# --- Candidate source (the `scrape` step) ------------------------------------
+# TEFT_SOURCE = browser (default) | apify
+#   browser: drives YOUR logged-in session (needs LI_AT below); $0, no external service.
+#   apify:   a no-cookies Apify post-search actor scrapes on their infra — faster, and
+#            ban risk is off your account. Needs APIFY_TOKEN (apify.com free tier).
+# TEFT_SOURCE=apify
+# APIFY_TOKEN=
+# TEFT_APIFY_ACTOR=harvestapi/linkedin-post-search           # content-search (posts)
+# TEFT_APIFY_PEOPLE_ACTOR=harvestapi/linkedin-profile-search # people-search (by title)
+
+# --- Search tuning -----------------------------------------------------------
+# How many candidates to pull per query before ranking (default 25).
+# TEFT_MAX_CANDIDATES=25
+
+# --- LinkedIn session (browser source only) ----------------------------------
+# Your LinkedIn `li_at` session cookie — reused so teft drives YOUR logged-in
+# session instead of automating a login. See SESSION_BOOTSTRAP.md for how to grab it.
+# Optional: if the browser profile already holds a valid session you can leave this blank.
+LI_AT=

teft_leads-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# teft runtime data — NEVER commit session cookies or scraped people
+.teft/
+browser-profile/
+candidates.json
+shortlist-*.md
+
+# secrets
+.env
+.env.*
+!.env.example

teft_leads-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

teft_leads-0.1.0/CLAUDE.md

@@ -0,0 +1,101 @@
+# teft — project guide
+
+`teft` is a personal, local-first LinkedIn intent-signal lead-finder. It finds people posting
+buyer-intent signals, runs each through a "why now" prompt (with a load-bearing SKIP rule), and
+returns a ranked shortlist. No SaaS, no hosting. Candidate source is pluggable (`TEFT_SOURCE`):
+`browser` (default — drives Michael's *own* logged-in session via Patchright + `li_at` reuse, $0,
+no external service) or `apify` (a no-cookies Apify post-search actor scrapes on their infra —
+faster, ban risk off the account, opt-in external service). Planning lives in GitHub Issues (map
+#1, build plan #6, impl map #7).
+
+## Commands
+
+```bash
+uv run teft run          # guided: config → product/brief/phrases → scrape → rank → view
+uv run teft view         # local results dashboard (reads latest ~/.teft/shortlist-*.json)
+uv run teft serve        # FastAPI web app: BYOK settings, search/re-rank, results, history
+uv run teft scrape -p "phrase" [-p …] [-t "job title" …] [--discover-only] [--dump] [--emails]
+#   -p → content-search (signal leads);  -t → people-search (role-fit leads, apify only)
+uv run teft rank --brief brief.txt     # candidates.json → why-now → shortlist-<date>.{md,json}
+uv run teft bootstrap    # verify the logged-in LinkedIn session
+uv run teft version
+```
+
+Pipeline: `scrape` (content-search → per-candidate enrich → `~/.teft/candidates.json`) → `rank`
+(→ `shortlist-<date>.{md,json}`) → `view`. `teft run` chains all three. The scrape/rank split is
+deliberate: scrape once, re-run/tune `rank` for free.
+
+## Config (env, auto-loaded from `.env` — no manual `source`)
+
+- `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` — key for the chosen provider (`rank`).
+- `TEFT_SOURCE` — `browser` (default) | `apify`. `apify` needs `APIFY_TOKEN`; `browser` needs `LI_AT`.
+- `APIFY_TOKEN` — Apify API token (free tier) for `TEFT_SOURCE=apify`.
+- `TEFT_APIFY_ACTOR` — post-search actor id (default `harvestapi/linkedin-post-search`).
+- `TEFT_APIFY_PEOPLE_ACTOR` — people-search actor id (default `harvestapi/linkedin-profile-search`).
+- `LI_AT` — LinkedIn session cookie for `browser` source (or sign in once in the persistent profile).
+- `TEFT_LLM` — `anthropic` (default, `claude-sonnet-5`) | `openai` (`gpt-5.6-terra`).
+- `TEFT_MODEL` — override the model id (e.g. `claude-opus-4-8`, `gpt-5.6-sol`, `gpt-5.6-luna`).
+- `TEFT_HEADLESS=1` — invisible/faster browser (default headful is stealthier).
+- `TEFT_MIN_DELAY` / `TEFT_MAX_DELAY` — pacing between candidates (speed vs ban-safety).
+- `TEFT_MAX_CANDIDATES` — int cap per query (default 25 → `Config.max_candidates_per_query`).
+- `TEFT_DATA_DIR` — data dir (default `~/.teft`).
+
+`teft run` prompts for and persists any missing key/cookie to `.env` (git-ignored). Data dir holds
+`candidates.json`, `shortlist-*.{md,json}`, `actions.json` (contacted+notes), `campaign.json`,
+`browser-profile/`.
+
+## Dev
+
+```bash
+uv sync
+uv run pyright      # type check (must be clean)
+uv run pytest -q    # tests
+uv run ruff check . # lint
+```
+
+Stack: Python 3.12, `uv`, `typer`, `pydantic`, `patchright`, `anthropic`, `openai`, `httpx`. `src/teft/`:
+`config` · `models` · `session` (Patchright) · `search` (M1) · `enrich` (M2) · `apify` (post- +
+profile-search sources) · `source` (browser/apify × content/people dispatch) · `rank` (M3, provider
+seam; **two prompts** — signal why-now for content-search, softer role-fit for people-search, keyed
+on `Candidate.source`) · `view` (stdlib server + dashboard) · `serve/` (FastAPI web app: `app`
+routes · `web` inline UI · `runs` engine · `settings` BYOK · `history` records/compare) · `wizard`
+(`teft run`) · `cli`.
+
+## Gotchas / non-obvious facts
+
+- **LinkedIn DOM (verified live):** profile pages have **no `<h1>`/og: tags** — name comes from the
+  page `<title>` (`name_from_title` handles both profile and activity title shapes, language-agnostic).
+  Activity page is stable: post = `.update-components-text`, headline =
+  `.update-components-actor__description` (NOT `__title`, which is the name), date =
+  `.update-components-actor__sub-description`, post urn from `[data-urn^="urn:li:activity"]`.
+- **Enrichment is one nav/candidate** (activity page only); email is opt-in (`--emails`, extra nav,
+  usually empty for cold leads).
+- **Never use `networkidle` waits** — LinkedIn never idles; wait for the specific selector instead.
+- **SKIP-rule calibration** validated on Opus (#4); re-checked equivalent on **Sonnet 5** (now the
+  default) via `tests/fixtures/` on 2026-07-16. Re-run the fixtures before trusting any new provider/
+  tier. Prompt is ported verbatim from the `prototype/why-now-prompt` branch.
+- Keep Patchright (stealth, #2) for the `browser` source — don't swap to plain Playwright.
+- **Apify source is defensive/unvalidated:** `candidate_from_post_item` probes many field-name
+  variants because actor output schemas differ; the exact mapping + the actor input (`keywords`,
+  `maxItems`) are unverified against a live token — tune from a `--dump` (`~/.teft/dump/apify-*.json`).
+- Avatars are initials (LinkedIn photo URLs are session-gated, don't render externally).
+- `teft view` is localhost-only, single-user, no auth — don't expose the port.
+- Pure logic (URL/email/name/title parsing, prompt plumbing, actions) is unit-tested; DOM selectors
+  are the thin live layer, tunable from `--dump` captures.
+
+## Agent skills
+
+### Issue tracker
+
+GitHub Issues via the `gh` CLI (repo `michaelwilhelmsen/linkedin-lead-finder`); this is also where the
+wayfinder maps live (#1, #6, #7). See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical roles, label strings unchanged (`needs-triage`, `needs-info`, `ready-for-agent`,
+`ready-for-human`, `wontfix`) — distinct from the `wayfinder:*` labels. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` + `docs/adr/` at the repo root (created lazily by `/domain-modeling`, not
+scaffolded upfront). See `docs/agents/domain.md`.

teft_leads-0.1.0/CONCEPT.md

@@ -0,0 +1,132 @@
+# LinkedIn Lead Finder — Concept Seed
+
+> **This document is the seed input for a follow-up wayfinder session in this directory.** It captures the reference product, why we're building our own instead of using theirs, sample output shape, and the open questions wayfinder should help answer. Don't treat this as a spec — treat it as the raw brief.
+
+---
+
+## The core idea (one paragraph)
+
+Build a tool that takes a description of a product (what it does, who it's for, the pain it solves) and returns a ranked list of high-intent LinkedIn prospects — not scraped-database contacts, but people whose *recent posts, role changes, and public activity* signal they are actively in-market. Each prospect comes with a fit score and a plain-English "why this person, right now" explanation that a human could actually use as the opening line of an outreach message. The angle is "real signals, not stored databases" — surface intent from live public activity rather than filtering a static contact list on firmographics.
+
+---
+
+## Reference: what SeedOps.co does
+
+SeedOps (seedops.co) is the tool the Reddit DM was pitching. It's an early-stage AI lead-gen product with a clear positioning hook that's worth stealing conceptually even if we don't copy the implementation.
+
+**Pitch:** "Find and outreach high-intent leads with AI. Real signals, not stored databases."
+
+**How it works (from their homepage):**
+- User creates a "campaign" and describes their ideal lead in natural language (e.g. "decision-makers actively frustrated with their current vendor and looking to buy a replacement in the last 30 days")
+- SeedOps runs the campaign as a persistent "signal" — it monitors public activity 24/7 and surfaces matches
+- Each match gets a fit score (0–100%) and a short LLM-generated explanation of *why* this person fits *this* campaign *right now*
+- Results are shown in a table: `# | Prospect | Signal | Signal Date | Fit | Found Date`
+- Export to CSV, then plug into any outreach tool (they don't do automated outreach themselves — their words: "for this early stage, no. The only option is to export them and use any outreach tool")
+
+**Signal types they surface** (from their landing page examples):
+- **Buying signal** — "Our lead research is still painfully manual. Looking for a tool that surfaces genuinely high-intent prospects..."
+- **Competitor signal** — "Finally switched off our old CRM. The reporting was a nightmare..."
+- **Hiring signal** — "Scaling the team fast this quarter — six open roles..."
+- **Fundraising signal** — "Thrilled to share we just closed our seed round..."
+- **Investment signal** — "We are already backing some incredible companies... Seed-stage founders, my DMs are open."
+- **Expansion signal** — "We're opening our first office in Dubai..."
+
+**Pricing (for reference):**
+- Free: 500 credits one-time, 1 running signal, 30 rows/table
+- Pro: $89/mo, 6,000 credits, 5 running signals, unlimited rows
+- Enterprise: custom
+
+**Positioning vs. incumbents** (from their compare table):
+- Apollo & lemlist = stored database + cold leads
+- SeedOps = real-time data + real intent signals + AI-powered leads
+
+---
+
+## Sample output (from the Reddit DM screenshots)
+
+The redditor shared a live campaign called **"Meeting Management for Agencies an..."** (truncated in the screenshot) with the subtitle *"Creative and sales agencies looking for meeting workflow tools"* — 35 results, targeting a product called **Humla** (a meeting/notes/workflow product). This is the concrete output shape wayfinder should aim to match or improve on:
+
+**Table columns:** `# | Prospect (name + LinkedIn headline) | Signal (link to source post) | Signal Date | Fit % | Found Date`
+
+**Actual "Fit" explanations from the screenshots** (verbatim, so wayfinder has a concrete target for the LLM output quality):
+
+> **Antony Puttick — Group Creative Director | Drummer | Relentlessly Curious — 85% fit — Jul 14, 2026**
+> "Antony is ideal for Humla because he has spent a year building an automated micro-agency workflow specifically triggered by meeting notes, and this means he is currently in the active stage of optimizing the bridge between client recordings and collaborative project management."
+
+> **Miladys Cruz-Fisher — Principal & Creative AI Strategist — 85% fit — Jul 2, 2026**
+> "Miladys is ideal for Humla because she has officially relaunched her agency as an AI strategy firm, and this means she is currently building her new internal stack and client service workflows while facing immediate pressure to implement the very AI tools she advocates for."
+
+> **Kyle — 85% fit — Jun 19, 2026**
+> "Kyle is ideal for Humla because he is currently expanding his sales team at an AI company, and this means he has a fresh mandate to establish scalable meeting workflows and ensure client records are collaborative as new hires onboard."
+
+> **Gillian — 82% fit — Jul 9, 2026**
+> "Gillian is ideal for Humla because she explicitly calls out a capturing problem where valuable insights are lost in meeting notes and siloed updates, and this means her team lacks the collaborative workflow tools needed to surface and centralize client stories."
+
+> **Ian — 82% fit — Jul 14, 2026**
+> "Ian is ideal for Humla because he just transitioned to a Director leadership role focused on coaching and empowering a larger [team]... he now faces a fresh mandate to implement scalable [workflows]..."
+
+**What's notable about the output quality:**
+- Each explanation follows a `[Person] is ideal for [Product] because [observed fact], and this means [inferred current need]` structure — the "and this means" bridge is the money shot; it's what turns a post into a buying signal.
+- Fit is expressed as a % with a colored dot, not a category. Feels precise even though it's clearly LLM-scored.
+- Signal date and Found date are separate columns — implying the system stores *when* the intent post happened vs. *when* the tool surfaced it.
+- All fits in the shown sample sit in the 82–85% band. Either the threshold is high or the calibration is loose — worth investigating.
+
+---
+
+## Why build our own instead of using SeedOps
+
+This is a three-birds-one-stone move for Michael, not a straight "cheaper clone" play:
+
+1. **Own the tool at Screenpartner.** The agency is chronically fighting for larger projects and haggled-down estimates. A working intent-signal engine plugged into Screenpartner's own outbound (marketing agencies, WordPress-shaped businesses, integrations pain-points) could directly move the needle on landing 1M+ NOK projects. That's the "1-2M NOK annual surplus in 5 years" company goal.
+
+2. **Learn the mechanics.** LLM-driven scoring + signal extraction from unstructured web/LinkedIn data is a stack Michael's weakest in (Python, data pipelines, DevOps). Building this is a legitimate skills investment, not a distraction. AI has "removed the barrier of entry for unfamiliar frameworks" per Michael's own notes.
+
+3. **Potential side-product / recurring revenue.** Fits Michael's stated dream (passive/recurring revenue alongside agency salary). Killer hook is already validated by the reddit DM: the pitch worked well enough on Michael that he wants to build it. The seedops founder even admits their own ICP is "so wide" — meaning there's room for a *narrower*, better-positioned tool (e.g. "for agencies selling into agencies", "for WordPress consultancies", etc.).
+
+The trap to avoid: this becomes yet another abandoned side project (woodworking app, quotes app, git-timetrack). Wayfinder should push hard on scope. A weekend-shippable v0 that Michael actually uses for Screenpartner outbound is worth 10× a beautiful spec that never gets built.
+
+---
+
+## Open questions (this is the wayfinder agenda)
+
+**Product shape**
+- Is this a personal tool for Screenpartner first, or a SaaS from day one? (The answer changes everything about auth, billing, multi-tenancy.)
+- Lead list only, or automated outreach too? SeedOps punted on outreach — is that a real gap or a smart focus?
+- LinkedIn-only or multi-source (Twitter/X, Reddit, HN, company blogs, hiring pages, press releases)?
+
+**Input shape**
+- Freeform natural-language campaign brief (SeedOps' approach) vs. structured form (product name, ICP, pain points, competitor list)? A hybrid?
+- Does the user upload their own product one-pager / website URL and we extract positioning automatically?
+
+**Data sources & the LinkedIn problem**
+- LinkedIn actively blocks scraping. What's the legal/practical path? Options include: (a) LinkedIn Sales Navigator API + partner status (hard), (b) third-party providers who resell LinkedIn data (Apollo, Proxycurl, Nubela, RocketReach — but these are "stored database"), (c) user-brings-their-own-LinkedIn-session via a browser extension (grey area but scrappy), (d) non-LinkedIn signals only (Twitter, GitHub, personal blogs, company news).
+- What does "real-time" actually mean in practice? Polling frequency vs. cost.
+
+**Scoring & LLM prompt design**
+- The "and this means…" template in SeedOps' output is a specific prompt engineering pattern. Reverse-engineering that prompt is probably 30 minutes of work and gets us 70% of the output quality.
+- How is Fit % computed? LLM self-rating (unreliable), embedding similarity to ICP description (calibratable), or a hybrid?
+
+**Enrichment**
+- How much per-lead enrichment do we do (email finding, company data, mutual connections)? Each layer adds cost.
+
+**Tech stack**
+- Michael's strengths: WordPress/PHP/ACF, JS, CSS. Intermediate: Python, Next.js, React. Weakest: DevOps.
+- Realistic stack candidates: Next.js + Vercel + Supabase + OpenAI/Anthropic API + a scraping/signal-fetch layer (Apify, Bright Data, or custom). Or, for a "start ugly and ship" v0: a Python script + Postgres + a plain HTML dashboard.
+- Cron/queue for signal-polling: Vercel Cron? Trigger.dev? A tiny VPS with systemd?
+
+**Cost model (self-imposed constraint)**
+- What's the per-lead cost ceiling before the economics don't work? SeedOps sells 6,000 credits for $89 — that's ~1.5 cents per credit. If a "credit" = one lead surfaced, that's very tight margin unless data-source costs are negligible.
+
+**Time budget (self-imposed constraint)**
+- Michael has 1–2 hours on weekday evenings, 8–11 PM. First useful version should exist within 2–3 weeks of evenings, not months. What's the smallest slice that produces one usable Screenpartner lead?
+
+---
+
+## What wayfinder should NOT do in the next session
+
+- Don't spec out architecture in detail.
+- Don't write code.
+- Don't pick a name (`linkedin-lead-finder` is a placeholder directory name — the name comes later).
+- Don't attempt to solve the LinkedIn scraping question definitively; just enumerate the realistic paths.
+
+The next session's job is: **narrow the shape.** Personal tool vs. SaaS. LinkedIn-only vs. multi-source. Freeform vs. structured input. Lead list vs. outreach. Get to a one-paragraph "here's the v0 we're building and here's what it does" — then the session after that can plan the build.

teft_leads-0.1.0/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Michael Wilhelmsen / Screenpartner. All rights reserved.
+
+No permission is granted to any person to use, copy, modify, or distribute this
+software, in whole or in part, in source or binary form, without the prior
+written consent of the copyright holder.

teft_leads-0.1.0/NOTICE

@@ -0,0 +1,14 @@
+teft
+Copyright 2026 Michael Wilhelmsen
+
+This product includes software adapted from:
+
+  linkedin-mcp-server
+  https://github.com/stickerdaniel/linkedin-mcp-server
+  Copyright (c) Daniel Sticker and contributors
+  Licensed under the Apache License, Version 2.0.
+
+Specifically, teft's LinkedIn URL normalization and person-link classification
+(src/teft/linkedin_urls.py) are adapted from that project's
+`linkedin_mcp_server/scraping/link_metadata.py`. A copy of the Apache-2.0
+license is available at http://www.apache.org/licenses/LICENSE-2.0.

teft_leads-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: teft-leads
+Version: 0.1.0
+Summary: Local-first LinkedIn intent-signal lead-finder with a local web app — real signals, not stored databases.
+Project-URL: Repository, https://github.com/michaelwilhelmsen/linkedin-lead-finder
+Author-email: Michael Wilhelmsen <michael@screenpartner.no>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.12
+Requires-Dist: anthropic>=0.40
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=2.0
+Requires-Dist: patchright>=1.40
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# teft
+
+> **teft** *(Norwegian: the instinctive nose for a lead — a scent for who's in-market right now).*
+> Repo slug is still `linkedin-lead-finder`; the tool is named `teft`.
+
+A personal, local-first tool that turns a freeform brief into a ranked, explained
+shortlist of high-intent LinkedIn prospects — "real signals, not stored databases."
+
+## For colleagues — try it in 2 minutes
+
+Nothing to clone. It runs entirely on your own machine (the web app is `127.0.0.1`-only).
+
+1. **Install uv:** `curl -LsSf https://astral.sh/uv/install.sh | sh` (Windows: see [docs.astral.sh/uv](https://docs.astral.sh/uv))
+2. **Run:** `uvx teft-leads serve` — your browser opens the app. (PyPI name is `teft-leads`; the command you type once installed is still `teft`.)
+3. **In the app:** Settings → paste your keys → Search → run it.
+
+That's it. The rest of this page is for people building on `teft`.
+
+## About / planning
+
+Planned with the **wayfinder** workflow; the plan lives as **GitHub Issues**. Two maps:
+
+- [**Planning map (#1)**](../../issues/1) — *complete.* Destination reached: the locked v0 definition.
+- [**Build plan (#6)**](../../issues/6) — stack, LLM, architecture, name, milestones.
+- [**Implementation map (#7)**](../../issues/7) — **active.** v0 as five `wayfinder:task` milestones (M0→M4);
+  the **frontier** (open, unblocked, unassigned) is the work takeable now — currently
+  [**M0 (#8)**](../../issues/8).
+
+See [`CONCEPT.md`](CONCEPT.md) for the original seed brief.
+
+## v0 at a glance
+
+Python CLI on your Mac, over your *own* logged-in LinkedIn session (Patchright, `li_at` cookie reuse).
+
+**Guided:** `teft run` — one command walks you through config (prompts + saves any missing key/cookie),
+then *product → brief → buyer-intent phrases* (or reuse the last campaign), scrapes, ranks, and opens the
+results UI. Defaults to headless/fast.
+
+**Or step by step:**
+- **`teft scrape -p "phrase" …`** — content-search → per-candidate activity/profile → `candidates.json`.
+- **`teft rank --brief brief.txt`** — each candidate → the "why now" prompt, SKIP filter → ranked
+  `shortlist-<date>.{md,json}`.
+- **`teft view`** — a local, zero-dependency results UI: lead cards, expandable post, Open profile / Open
+  post / copy email, and contacted + notes saved to `~/.teft/actions.json`.
+
+No Fit %, no monitoring, no outreach, no external services. `.env` is auto-loaded (no manual `source`).
+Speed/stealth knobs: `TEFT_HEADLESS=1`, `TEFT_MIN_DELAY` / `TEFT_MAX_DELAY`, `TEFT_MAX_CANDIDATES` (cap per query, default 25).
+
+## LLM provider
+
+`rank` is provider-pluggable. Default is `claude-opus-4-8` (the tier the "why now" prompt's SKIP-rule
+calibration was validated on). To use GPT-5.6 instead, set `TEFT_LLM=openai` (defaults to `gpt-5.6-terra`;
+override with `TEFT_MODEL`, e.g. `gpt-5.6-sol` / `gpt-5.6-luna`) and `OPENAI_API_KEY`. **The SKIP calibration
+is only proven on Claude — re-run the fixtures on a new provider before trusting it** (see [VALIDATE.md](VALIDATE.md)).

teft_leads-0.1.0/README.md

@@ -0,0 +1,54 @@
+# teft
+
+> **teft** *(Norwegian: the instinctive nose for a lead — a scent for who's in-market right now).*
+> Repo slug is still `linkedin-lead-finder`; the tool is named `teft`.
+
+A personal, local-first tool that turns a freeform brief into a ranked, explained
+shortlist of high-intent LinkedIn prospects — "real signals, not stored databases."
+
+## For colleagues — try it in 2 minutes
+
+Nothing to clone. It runs entirely on your own machine (the web app is `127.0.0.1`-only).
+
+1. **Install uv:** `curl -LsSf https://astral.sh/uv/install.sh | sh` (Windows: see [docs.astral.sh/uv](https://docs.astral.sh/uv))
+2. **Run:** `uvx teft-leads serve` — your browser opens the app. (PyPI name is `teft-leads`; the command you type once installed is still `teft`.)
+3. **In the app:** Settings → paste your keys → Search → run it.
+
+That's it. The rest of this page is for people building on `teft`.
+
+## About / planning
+
+Planned with the **wayfinder** workflow; the plan lives as **GitHub Issues**. Two maps:
+
+- [**Planning map (#1)**](../../issues/1) — *complete.* Destination reached: the locked v0 definition.
+- [**Build plan (#6)**](../../issues/6) — stack, LLM, architecture, name, milestones.
+- [**Implementation map (#7)**](../../issues/7) — **active.** v0 as five `wayfinder:task` milestones (M0→M4);
+  the **frontier** (open, unblocked, unassigned) is the work takeable now — currently
+  [**M0 (#8)**](../../issues/8).
+
+See [`CONCEPT.md`](CONCEPT.md) for the original seed brief.
+
+## v0 at a glance
+
+Python CLI on your Mac, over your *own* logged-in LinkedIn session (Patchright, `li_at` cookie reuse).
+
+**Guided:** `teft run` — one command walks you through config (prompts + saves any missing key/cookie),
+then *product → brief → buyer-intent phrases* (or reuse the last campaign), scrapes, ranks, and opens the
+results UI. Defaults to headless/fast.
+
+**Or step by step:**
+- **`teft scrape -p "phrase" …`** — content-search → per-candidate activity/profile → `candidates.json`.
+- **`teft rank --brief brief.txt`** — each candidate → the "why now" prompt, SKIP filter → ranked
+  `shortlist-<date>.{md,json}`.
+- **`teft view`** — a local, zero-dependency results UI: lead cards, expandable post, Open profile / Open
+  post / copy email, and contacted + notes saved to `~/.teft/actions.json`.
+
+No Fit %, no monitoring, no outreach, no external services. `.env` is auto-loaded (no manual `source`).
+Speed/stealth knobs: `TEFT_HEADLESS=1`, `TEFT_MIN_DELAY` / `TEFT_MAX_DELAY`, `TEFT_MAX_CANDIDATES` (cap per query, default 25).
+
+## LLM provider
+
+`rank` is provider-pluggable. Default is `claude-opus-4-8` (the tier the "why now" prompt's SKIP-rule
+calibration was validated on). To use GPT-5.6 instead, set `TEFT_LLM=openai` (defaults to `gpt-5.6-terra`;
+override with `TEFT_MODEL`, e.g. `gpt-5.6-sol` / `gpt-5.6-luna`) and `OPENAI_API_KEY`. **The SKIP calibration
+is only proven on Claude — re-run the fixtures on a new provider before trusting it** (see [VALIDATE.md](VALIDATE.md)).

teft_leads-0.1.0/SESSION_BOOTSTRAP.md

@@ -0,0 +1,55 @@
+# M0 — session bootstrap + content-search go/no-go (you run this)
+
+The scaffold is built. These last two steps touch your **personal LinkedIn account**
+(cookie + live queries, with real ban risk), so they're yours to run — not automated.
+This is the go/no-go for the whole v0 slice.
+
+## 0. Install (one time)
+
+```bash
+uv sync                        # installs deps into .venv
+uv run patchright install chrome   # downloads the browser Patchright drives
+```
+
+## 1. Grab your `li_at` cookie
+
+1. Log in to LinkedIn in your normal browser.
+2. DevTools → Application → Cookies → `https://www.linkedin.com` → copy the **`li_at`** value.
+3. `cp .env.example .env`, paste it as `LI_AT=...`, add your `ANTHROPIC_API_KEY` (for later, M3).
+
+`.env` is git-ignored — never commit it. Treat `li_at` like a password.
+
+## 2. Verify the session
+
+```bash
+set -a && source .env && set +a
+uv run teft bootstrap
+```
+
+Expect `✓ Authenticated — your session works.` A headful Chrome opens as you. If it
+fails, sign in once inside the window; the persistent profile keeps the session so you
+can leave `LI_AT` blank afterward.
+
+## 3. The content-search go/no-go (the load-bearing risk)
+
+Manually — before we build M1 — confirm LinkedIn **content search** returns usable
+recent posts from strangers via your session. In the Chrome that `bootstrap` opened, or
+by hand:
+
+1. Visit `https://www.linkedin.com/search/results/content/?keywords=<a Humla buyer-intent phrase>`
+   (e.g. *"lost in meeting notes"*, *"client follow-up"*, *"onboarding new AEs"*).
+2. Eyeball ~10–20 results. For each, can you see: **author**, **post text**, **date**, and
+   click through to a profile?
+3. Try 2–3 phrases. Note roughly how many results feel like real intent vs. noise, and
+   whether you hit a search-limit wall.
+
+## 4. Record the decision on the ticket
+
+Comment on **[M0 (#8)](../../issues/8)** with one of:
+
+- **GO** — content-search returns usable posts. → unblocks M1 (#9); we build `content_search`.
+- **NO-GO** — too gated/thin. → we re-scope the smallest slice to **filtered people-search**
+  and update the map (#7) before building further. (This is a fine outcome — it's exactly
+  what M0 exists to find out cheaply.)
+
+Then close #8. M1 is blocked-by #8, so it stays off the frontier until you do.

teft_leads-0.1.0/VALIDATE.md

@@ -0,0 +1,64 @@
+# Afternoon validation — the batched live session
+
+All four milestones' **code** is on `main`. The offline half (M3 rank) is tested and
+its prompt is proven (#4). What's left is the **live half** — validating the two
+LinkedIn-driving steps against your own session — plus one end-to-end judgment.
+Do these in order; each unblocks the next. One session, ~30–45 min.
+
+Prereq: `uv sync && uv run patchright install chrome`, and `.env` filled
+(`LI_AT`, `ANTHROPIC_API_KEY`) — see [SESSION_BOOTSTRAP.md](SESSION_BOOTSTRAP.md).
+
+```bash
+set -a && source .env && set +a
+```
+
+## 1. Session (M0 recap)
+```bash
+uv run teft bootstrap        # expect ✓ Authenticated
+```
+
+## 2. M1 — content-search discovery  → closes #9
+```bash
+uv run teft scrape --discover-only --dump -p "lost in meeting notes" -p "client follow-up"
+```
+- Expect a list of `/in/...` candidate URLs.
+- **Good** → comment on #9, close it.
+- **Empty/junk** → open `~/.teft/dump/anchors-*.json`; if the profile links are there
+  but under a different structure, the fix is the `main a[href]` scope / scroll in
+  `src/teft/search.py`. Paste me a dump and I'll adjust.
+
+## 3. M2 — enrichment  → closes #10
+```bash
+uv run teft scrape --dump -p "lost in meeting notes" -p "client follow-up"   # writes ~/.teft/candidates.json
+```
+- Open `~/.teft/candidates.json`: are `name`, `headline`, `signal_post_text`
+  populated? `email`/`company` are best-effort (often empty for cold leads — fine).
+- The **live selectors in `enrich.py` (`_scrape_one`) are guesses.** If fields are
+  blank, `~/.teft/dump/profile-*.json` has the raw captures — send me one and I'll
+  fix the `_NAME_JS` / `_HEADLINE_JS` / `_ACTIVITY_JS` selectors. This is the step
+  most likely to need a tuning round.
+
+## 4. M3 + M4 — rank end-to-end  → closes #11, #12 (the v0 done-condition)
+```bash
+uv run teft rank --brief tests/fixtures/humla_brief.txt   # or your own brief file
+```
+- Reads `~/.teft/candidates.json`, writes `~/.teft/shortlist-<date>.md`.
+- **The v0 bar:** is ≥1 entry send-worthy *unedited*? If yes → close #11 and #12; v0 is shipped.
+- Tune loop is cheap: re-run `rank` freely (no re-scrape); only re-`scrape` for fresh candidates.
+
+## Optional — validate the GPT-5.6 provider before trusting it
+
+The SKIP-rule calibration is only proven on Claude (#4). To check GPT-5.6 gives the same
+quality (Sara + Marcus surface, Tom's marathon SKIPs) before using it on real runs:
+```bash
+cp tests/fixtures/candidates.json ~/.teft/candidates.json
+export OPENAI_API_KEY=...
+TEFT_LLM=openai TEFT_MODEL=gpt-5.6-terra uv run teft rank --brief tests/fixtures/humla_brief.txt
+```
+Compare against the same run with the default (Claude). If GPT holds calibration, switch for real by
+setting `TEFT_LLM=openai` in `.env`; if it force-fits or over-SKIPs, stay on Claude or try `gpt-5.6-sol`.
+
+## If you'd rather I keep going now
+Reply with a pasted dump file (anchors or profile JSON) and I'll tune selectors
+blind against real DOM — that's the one thing that still needs your data, not your
+presence.

teft_leads-0.1.0/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_