perplexity-notebooklm 0.2.0__tar.gz

perplexity_notebooklm-0.2.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv --version)",
+      "Bash(git --version)",
+      "Bash(claude --version)",
+      "Bash(pip show *)"
+    ]
+  }
+}

perplexity_notebooklm-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "perplexity-notebooklm-dev",
+  "description": "Marketplace de desenvolvimento para o plugin perplexity-notebooklm",
+  "owner": {
+    "name": "wgardim"
+  },
+  "plugins": [
+    {
+      "name": "perplexity-notebooklm",
+      "description": "Integração dual Perplexity <-> NotebookLM (conta Pro, sem API key)",
+      "version": "0.2.0",
+      "source": "./",
+      "author": {
+        "name": "wgardim"
+      }
+    }
+  ]
+}

perplexity_notebooklm-0.2.0/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "perplexity-notebooklm",
+  "version": "0.2.0",
+  "description": "Integração dual Perplexity <-> NotebookLM (conta Pro, sem API key): pesquisa citada vira fonte no notebook e vice-versa.",
+  "author": {
+    "name": "wgardim"
+  },
+  "homepage": "https://github.com/wgardim-hub/notebooklm2perplexity",
+  "repository": "https://github.com/wgardim-hub/notebooklm2perplexity",
+  "license": "MIT",
+  "keywords": ["perplexity", "notebooklm", "research", "mcp", "dual", "no-api-key"],
+  "mcpServers": {
+    "perplexity-pro": {
+      "command": "uv",
+      "args": ["run", "--directory", "${CLAUDE_PLUGIN_ROOT}", "perplexity-pro-mcp"]
+    }
+  }
+}

perplexity_notebooklm-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: publish
+
+# Publica no PyPI automaticamente quando uma Release é publicada (ou ao push de tag vX.Y.Z).
+# Usa PyPI Trusted Publishing (OIDC) — NÃO precisa de token/secret no repo.
+#
+# Setup (uma vez, no pypi.org → Account → Publishing → Add a pending publisher):
+#   PyPI project name: perplexity-notebooklm
+#   Owner: wgardim-hub   Repository: notebooklm2perplexity
+#   Workflow name: publish.yml   Environment: pypi
+# Depois: criar uma Release (ou `git tag vX.Y.Z && git push --tags`) → publica sozinho.
+
+on:
+  release:
+    types: [published]
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # exigido pelo Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build (sdist + wheel)
+        run: uv build
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

perplexity_notebooklm-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.env
+.claude.local.md
+.venv/
+dist/
+build/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+perplexity.log
+vendor/perplexity-ai/.git/
+node_modules/
+evals/results/

perplexity_notebooklm-0.2.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+Formato: [Keep a Changelog](https://keepachangelog.com). Versionamento semântico.
+
+## [0.2.0] — 2026-06-27
+
+### Mudado
+- **Publicável no PyPI / `uvx`**: removida a dependência do pacote `perplexity` (path-dep
+  vendorizado). O `cited_search.py` (curl_cffi, auto-contido) já move todos os modos, então
+  o backend não precisa mais do `Client` vendorizado. Deps agora: `curl_cffi`, `mcp`,
+  `python-dotenv`. Wheel verificado em env isolado (`uv build` + import isolado OK).
+
+### Adicionado (hardening de install — issue #1)
+- `uv run` no `plugin.json`/hook → **cross-SO** (Win/Mac/Linux) + **auto-bootstrap** do venv.
+- `perplexity-nlm-doctor` — valida deps/cookies/auth/Chrome/NotebookLM/driver.
+- `perplexity-nlm-auth` — login guiado: extrai cookies do Chrome logado → `.env` (Perplexity)
+  + `storage_state` (NotebookLM). Sem copiar cookie à mão.
+- `requires-python` travado `<3.14`; `docs/INSTALL.md` (caminho canônico único + FAQ).
+
+### Nota
+- Publicação no PyPI: `uv build` (feito) + `uv publish` (requer token do mantenedor) → `uvx perplexity-notebooklm`.
+
+## [0.1.1] — 2026-06-27
+
+### Adicionado
+- **Dedup semântico** (`notebooklm_write/embed.py`, model2vec local — sem API key/torch):
+  4ª camada de dedup por embeddings (cosseno). Pega reescritas que o MinHash perde
+  (ex.: cos=0.90 onde MinHash dava 0.28). Gracioso: ausente → cai pro MinHash.
+  Extra opcional `[semantic]`. Ativado via `check_duplicate(..., semantic=True)`.
+
+## [0.1.0] — 2026-06-27
+
+Primeira release: integração dual Perplexity ↔ NotebookLM, conta Pro, **sem API key**.
+
+### Adicionado
+- **MCP Perplexity** (`perplexity-pro`): tools `ask`/`search`/`reason`/`research`; backend
+  plugável (`adapter.py` + `backends/helallao.py`), auth por cookies da conta Pro.
+- **Citações** (`cited_search.py`): replica a recipe do pwm (warm GET + payload + double-parse SSE).
+- **NotebookLM HTTP/RPC** (`nlm_http.py`, notebooklm-py) via **cookie-bridge** de Chrome logado:
+  `add_text`/`add_url`/`add_file`, `list_notebooks`, `read_summary`, `list_source_ids`,
+  `generate_artifact` (audio/video/mind_map); fallback Selenium (`add_source.py`).
+- **Fluxo dual** (`dual_flow.py`): `research_to_notebook` (PPLX→NLM), `notebook_to_research`
+  (NLM→PPLX), `research_to_media` (research→fonte→artefato).
+- **Robustez/segurança**: `resilience.py` (retry+jitter, rate-limit, single-flight),
+  `security.py` (redação de logs + perms), `validate.py` (input nas tools).
+- **Verificação de citações** (`verify_citations.py`): heurística honesta + judge LLM opcional (adversarial).
+- **Dedup em 3 camadas** (`ledger.py`): por query (pula antes do Pro call), por conteúdo
+  exato, e near-verbatim (MinHash).
+- **Deep-research agêntico** (`agentic.py`): decompõe→multi-search→sintetiza, com cap de cota.
+- **Watcher bidirecional** (`watch.py`): vigia source-ids (sinal estável) com guards de ToS
+  (interval mín, dry-run, kill-switch interrompível, max-iter).
+- **RAG lexical cross-notebook** (`rag.py`): BM25 + cache auto-heal.
+- **Plugin Claude Code**: manifest, comandos `/dual-research` e `/notebook-enrich`, skill,
+  hook SessionStart (healthcheck de auth + lembrete Chrome :9222).
+- **Harness de eval** (`evals/`), **benchmark** do ecossistema (`docs/BENCHMARK.md`),
+  **roadmap** (`docs/INNOVATION.md`).
+
+### Notas
+- Sem API key paga: Perplexity por cookies da conta Pro; NotebookLM por cookie-bridge.
+- Validado ponta-a-ponta na conta real (dual flow, RAG 44 notebooks, dedup por query, watcher).
+
+### Limitações conhecidas
+- Dedup semântico real (embeddings) ainda não — camadas atuais pegam idêntico/near-verbatim/query.
+- Automação contínua (watcher/agêntico) tem risco inerente de ToS; usar com parcimônia.

perplexity_notebooklm-0.2.0/CLAUDE.md

@@ -0,0 +1,29 @@
+# MCP Perplexity ↔ NotebookLM
+
+Integração dual, SEM API key paga. Comandos via `.venv/Scripts/python.exe` (venv Python 3.13).
+
+## Arquitetura
+- **Perplexity**: backend `perplexity_mcp/backends/helallao.py` (plugável via `adapter.py`), auth por cookies no `.env` (`PERPLEXITY_COOKIES`). O motor é `cited_search.py` — AUTO-CONTIDO (curl_cffi, NÃO depende do pacote `perplexity`): replica a recipe pwm (warm GET + payload search_focus/send_back_text + double-parse do SSE) → resposta + citações. Sem dep externa de Perplexity → wheel publicável (`vendor/perplexity-ai` é legado, não usado). Robustez em `resilience.py`, segurança em `security.py`, validação em `validate.py`.
+- **NotebookLM**: `notebooklm_write/nlm_http.py` = HTTP/RPC (notebooklm-py), caminho preferido. `add_source.py` (Selenium) = fallback.
+- **Auth NotebookLM = cookie-bridge**: Google bloqueia login automatizado → abrir Chrome real logado: `chrome.exe --remote-debugging-port=9222 --user-data-dir="D:\nlm-chrome"`; nlm_http extrai cookies → storage_state (~/.notebooklm/).
+- **Inovações (v0.1.1)**: `dual_flow.py` (research_to_notebook/notebook_to_research/research_to_media), `verify_citations.py` (judge adversarial opcional), `ledger.py` (dedup 4 camadas), `agentic.py` (deep-research loop), `watch.py` (watcher), `rag.py` (BM25 cross-notebook). Plugin Claude Code em `.claude-plugin/`+`commands/`+`hooks/`.
+
+## Dedup + embeddings
+- `ledger.py` = 4 camadas: query (`_query_key` ORDENADO, não bag-of-words → evita falso-skip) → hash exato → MinHash near-verbatim → semântico.
+- Semântico = `embed.py`/model2vec LOCAL (extra `[semantic]`, sem API key/torch), lazy + GRACIOSO (ausente → cai pro MinHash). Reescrito cos~0.90 vs MinHash 0.28.
+
+## Gotchas NotebookLM (auth)
+- **watch vigia `list_source_ids` (ESTÁVEL), nunca `read_summary`**: `get_summary` REGENERA o texto a cada chamada → hash muda → falso-positivo de "mudança". Source-ids só mudam ao add/remove fonte.
+- Cookies obrigatórios do notebooklm-py: `SID` + `__Secure-1PSIDTS` (este ROTACIONA). Storage stale → `ValueError: Missing required cookies` → `nlm_http._needs_rebridge` reconhece "cookie"/"missing required" e re-bridge (não casa só "auth"/"expired").
+- Teste live de NotebookLM exige Chrome :9222 ABERTO e logado; senão `SessionNotCreatedException`.
+- notebooklm-py: accessors `client.sources/notebooks/artifacts`; `add_url` auto-detecta YouTube; `add_text/add_file/generate_artifact(audio|video|mind_map)`.
+
+## Comandos
+- Eval: `.venv/Scripts/python.exe evals/run.py`
+- Registrar MCP: `claude mcp add perplexity-pro --scope user -- ".venv/Scripts/perplexity-pro-mcp.exe"`
+- Dual: `dual_flow.research_to_notebook` (PPLX→NLM), `notebook_to_research` (NLM→PPLX)
+- Listar notebooks: `notebooklm_write.nlm_http.list_notebooks_sync()`
+
+## Convenções
+- Commits em português, sem emoji.
+- Segredos só no `.env` (gitignored). Nunca logar valores de cookie.

perplexity_notebooklm-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wgardim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

perplexity_notebooklm-0.2.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: perplexity-notebooklm
+Version: 0.2.0
+Summary: Integração dual NotebookLM <-> Perplexity (conta Pro, sem API key) via MCP + skill
+Project-URL: Homepage, https://github.com/wgardim-hub/notebooklm2perplexity
+Project-URL: Repository, https://github.com/wgardim-hub/notebooklm2perplexity
+Author: wgardim
+License: MIT
+License-File: LICENSE
+Keywords: mcp,no-api-key,notebooklm,perplexity,research
+Requires-Python: <3.14,>=3.10
+Requires-Dist: curl-cffi>=0.5.7
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: all
+Requires-Dist: model2vec>=0.8.0; extra == 'all'
+Requires-Dist: notebooklm-mcp>=2.0.11; extra == 'all'
+Requires-Dist: notebooklm-py>=0.7.2; extra == 'all'
+Requires-Dist: selenium>=4.0.0; extra == 'all'
+Provides-Extra: notebooklm
+Requires-Dist: notebooklm-mcp>=2.0.11; extra == 'notebooklm'
+Requires-Dist: notebooklm-py>=0.7.2; extra == 'notebooklm'
+Requires-Dist: selenium>=4.0.0; extra == 'notebooklm'
+Provides-Extra: semantic
+Requires-Dist: model2vec>=0.8.0; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="docs/assets/banner.svg" alt="Perplexity ⇄ NotebookLM" width="100%">
+
+**English** · [Português 🇧🇷](README.pt-BR.md)
+
+### The missing bridge between **Perplexity's** web intelligence and **NotebookLM's** knowledge base — driven by Claude Code, with **zero paid API keys.**
+
+[![version](https://img.shields.io/badge/version-0.2.0-blue)](https://github.com/wgardim-hub/notebooklm2perplexity/releases)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.13-3776ab)](pyproject.toml)
+[![no API key](https://img.shields.io/badge/API%20key-not%20required-success)]()
+[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-7c3aed)]()
+
+</div>
+
+---
+
+## Why this exists
+
+You research on **Perplexity**. You build knowledge on **NotebookLM**. Today they don't talk —
+you copy-paste between tabs, lose citations, and re-research the same topics.
+
+This project closes the loop. It's the **only** tool that wires Perplexity and NotebookLM
+**both ways**, using your **Pro accounts** (cookies) instead of paid API keys — so it costs
+you nothing beyond subscriptions you already pay for.
+
+```mermaid
+flowchart LR
+    subgraph PPLX["🔎 Perplexity Pro"]
+        S[search / reason / deep research<br/>+ citations]
+    end
+    subgraph NLM["📓 NotebookLM"]
+        N[sources · summaries · audio/video/mind-map]
+    end
+    S -- "research → source (verified, deduped)" --> N
+    N -- "summary → enrich / fact-check" --> S
+    C[/"Claude Code<br/>orchestrator"/] -.drives.- S
+    C -.drives.- N
+```
+
+---
+
+## What you get
+
+| | Capability |
+|---|---|
+| 🔁 | **Bidirectional dual flow** — research → notebook source, *and* notebook → enriched research. Nobody else does both. |
+| 🔑 | **No paid API keys** — Perplexity via account cookies; NotebookLM via a one-time cookie-bridge. |
+| 📎 | **Citations preserved** — replicates the SSE recipe that surfaces real web sources. |
+| 🧹 | **4-layer dedup** — never ingest the same thing twice (query → exact → near-verbatim → **semantic embeddings**, all local). |
+| 🛡️ | **Adversarial citation verification** — drops hallucinated/dead sources before they reach your notebook. |
+| 🤖 | **Agentic deep-research** — decomposes a question, searches each angle, synthesizes a cited report. |
+| 🎧 | **Media pipeline** — turn research into a NotebookLM audio overview, video, or mind-map in one call. |
+| 👁️ | **Continuous watcher** — monitors notebooks for real changes (stable source-id signal) with hard ToS guards. |
+| 🔌 | **Ships as a Claude Code plugin** — `/dual-research`, `/notebook-enrich`, MCP server, session hook. |
+
+---
+
+## Quickstart
+
+> Prereqs: **[uv](https://docs.astral.sh/uv/)** on PATH + **Python 3.12/3.13** (not 3.14). uv handles the venv & deps. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
+
+```bash
+# 1. Install as a Claude Code plugin (brings MCP + commands + skill + hook).
+#    uv run auto-creates the venv on first launch — cross-OS, no hardcoded paths.
+/plugin marketplace add wgardim-hub/notebooklm2perplexity
+/plugin install perplexity-notebooklm@perplexity-notebooklm-dev   # restart Claude Code
+
+# 2. Guided login (pulls cookies from a logged-in Chrome — no manual paste).
+#    Open once: chrome --remote-debugging-port=9222 --user-data-dir="<profile>"
+#    logged into perplexity.ai AND NotebookLM, then:
+uv run --directory <repo> perplexity-nlm-auth
+
+# 3. Verify everything ("did I configure it right?")
+uv run --directory <repo> perplexity-nlm-doctor
+```
+
+> One canonical path. **Don't** also copy the skill into `~/.claude/skills/` — the plugin ships it.
+> The package is self-contained (no vendored deps) — once published to PyPI, the MCP runs via
+> `uvx perplexity-notebooklm`. Manual install & `python -m perplexity_mcp.server`: see [`docs/INSTALL.md`](docs/INSTALL.md).
+
+---
+
+## The two flows
+
+```python
+from dual_flow import research_to_notebook, notebook_to_research, research_to_media
+
+# Perplexity → NotebookLM  (research becomes a verified, deduped source)
+research_to_notebook("State of commercial fusion in 2026", NB, tool="research",
+                     verify=True, dedup=True)
+
+# NotebookLM → Perplexity  (read the notebook, fact-check & update against the live web)
+notebook_to_research(NB, tool="search")
+
+# Research → media  (source + audio / video / mind-map in one call)
+research_to_media("AI in real estate 2026", NB, kind="mind_map")
+```
+
+> **NotebookLM auth:** Google blocks automated logins, so the first run needs a real
+> Chrome you control:
+> `chrome.exe --remote-debugging-port=9222 --user-data-dir="D:\nlm-chrome"` (log in once).
+> After that it's pure HTTP with automatic cookie re-bridge.
+
+---
+
+## Architecture
+
+```
+perplexity_mcp/      MCP server · pluggable backend (helallao) · cited_search
+                     resilience (retry/jitter/rate-limit) · security · validate
+                     verify_citations (adversarial) · agentic (deep-research)
+notebooklm_write/    nlm_http (notebooklm-py HTTP/RPC + cookie-bridge) · add_source (Selenium fallback)
+                     ledger (4-layer dedup) · embed (local model2vec)
+dual_flow.py         the bidirectional orchestration
+rag.py · watch.py    cross-notebook BM25 retrieval · change watcher
+evals/ · skills/     regression harness · Claude Code skill
+.claude-plugin/      plugin manifest · commands · hooks
+```
+
+**Design principles:** small, single-purpose modules · pluggable Perplexity backend
+(swap providers without touching callers) · graceful degradation everywhere (no Chrome →
+clean error; no embedder → falls back to MinHash; stale cookie → auto re-bridge) ·
+eval harness as a regression gate · honest about limits.
+
+### Dedup, in 4 layers (cheapest first)
+
+| Layer | Catches | Cost |
+|-------|---------|------|
+| **Query** | re-researching the same topic | free (skips *before* the Pro call) |
+| **Exact hash** | identical content | free |
+| **MinHash** | near-verbatim edits | free |
+| **Semantic** | reworded / paraphrased (cosine ≈ 0.90) | local embedding, no API |
+
+---
+
+## Reliability & safety
+
+- **Resilience:** exponential backoff + full jitter, rate limiting, single-flight auth refresh.
+- **Your accounts, your cookies:** every user authenticates with **their own** Perplexity/NotebookLM. Credentials live only in your local `.env` + `~/.notebooklm/` (git-ignored, never committed, never shipped in the package). Nothing personal is bundled — a fresh install has zero cookies; you run `perplexity-nlm-auth` to pull your own.
+- **Security:** secrets only in `.env` (git-ignored); cookie values never logged (redaction); file perms hardened.
+- **ToS-aware automation:** the watcher defaults to dry-run, enforces a ≥10-min poll floor, an interruptible kill-switch, and writes only through an explicit callback with a human checkpoint.
+- **Tested:** eval harness (`evals/run.py`) + end-to-end validation on real accounts (dual flow, 44-notebook RAG, dedup, watcher).
+
+---
+
+## Honest limitations
+
+A senior project says what it *doesn't* do:
+
+- Built on **unofficial** Perplexity/NotebookLM interfaces — they can change; expect occasional maintenance.
+- Continuous automation against your accounts carries inherent **ToS risk** — use sparingly.
+- Semantic dedup needs the optional local model; without it, dedup falls back to lexical.
+- NotebookLM write/read needs a logged-in Chrome on the debug port (Google blocks headless login).
+
+---
+
+## Roadmap
+
+See [`docs/INNOVATION.md`](docs/INNOVATION.md) for the full ranked roadmap, and
+[`docs/BENCHMARK.md`](docs/BENCHMARK.md) for how this compares against 7 ecosystem projects.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Not affiliated with Perplexity AI or Google.

perplexity_notebooklm-0.2.0/README.md

@@ -0,0 +1,166 @@
+<div align="center">
+
+<img src="docs/assets/banner.svg" alt="Perplexity ⇄ NotebookLM" width="100%">
+
+**English** · [Português 🇧🇷](README.pt-BR.md)
+
+### The missing bridge between **Perplexity's** web intelligence and **NotebookLM's** knowledge base — driven by Claude Code, with **zero paid API keys.**
+
+[![version](https://img.shields.io/badge/version-0.2.0-blue)](https://github.com/wgardim-hub/notebooklm2perplexity/releases)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.13-3776ab)](pyproject.toml)
+[![no API key](https://img.shields.io/badge/API%20key-not%20required-success)]()
+[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-7c3aed)]()
+
+</div>
+
+---
+
+## Why this exists
+
+You research on **Perplexity**. You build knowledge on **NotebookLM**. Today they don't talk —
+you copy-paste between tabs, lose citations, and re-research the same topics.
+
+This project closes the loop. It's the **only** tool that wires Perplexity and NotebookLM
+**both ways**, using your **Pro accounts** (cookies) instead of paid API keys — so it costs
+you nothing beyond subscriptions you already pay for.
+
+```mermaid
+flowchart LR
+    subgraph PPLX["🔎 Perplexity Pro"]
+        S[search / reason / deep research<br/>+ citations]
+    end
+    subgraph NLM["📓 NotebookLM"]
+        N[sources · summaries · audio/video/mind-map]
+    end
+    S -- "research → source (verified, deduped)" --> N
+    N -- "summary → enrich / fact-check" --> S
+    C[/"Claude Code<br/>orchestrator"/] -.drives.- S
+    C -.drives.- N
+```
+
+---
+
+## What you get
+
+| | Capability |
+|---|---|
+| 🔁 | **Bidirectional dual flow** — research → notebook source, *and* notebook → enriched research. Nobody else does both. |
+| 🔑 | **No paid API keys** — Perplexity via account cookies; NotebookLM via a one-time cookie-bridge. |
+| 📎 | **Citations preserved** — replicates the SSE recipe that surfaces real web sources. |
+| 🧹 | **4-layer dedup** — never ingest the same thing twice (query → exact → near-verbatim → **semantic embeddings**, all local). |
+| 🛡️ | **Adversarial citation verification** — drops hallucinated/dead sources before they reach your notebook. |
+| 🤖 | **Agentic deep-research** — decomposes a question, searches each angle, synthesizes a cited report. |
+| 🎧 | **Media pipeline** — turn research into a NotebookLM audio overview, video, or mind-map in one call. |
+| 👁️ | **Continuous watcher** — monitors notebooks for real changes (stable source-id signal) with hard ToS guards. |
+| 🔌 | **Ships as a Claude Code plugin** — `/dual-research`, `/notebook-enrich`, MCP server, session hook. |
+
+---
+
+## Quickstart
+
+> Prereqs: **[uv](https://docs.astral.sh/uv/)** on PATH + **Python 3.12/3.13** (not 3.14). uv handles the venv & deps. Full guide: [`docs/INSTALL.md`](docs/INSTALL.md).
+
+```bash
+# 1. Install as a Claude Code plugin (brings MCP + commands + skill + hook).
+#    uv run auto-creates the venv on first launch — cross-OS, no hardcoded paths.
+/plugin marketplace add wgardim-hub/notebooklm2perplexity
+/plugin install perplexity-notebooklm@perplexity-notebooklm-dev   # restart Claude Code
+
+# 2. Guided login (pulls cookies from a logged-in Chrome — no manual paste).
+#    Open once: chrome --remote-debugging-port=9222 --user-data-dir="<profile>"
+#    logged into perplexity.ai AND NotebookLM, then:
+uv run --directory <repo> perplexity-nlm-auth
+
+# 3. Verify everything ("did I configure it right?")
+uv run --directory <repo> perplexity-nlm-doctor
+```
+
+> One canonical path. **Don't** also copy the skill into `~/.claude/skills/` — the plugin ships it.
+> The package is self-contained (no vendored deps) — once published to PyPI, the MCP runs via
+> `uvx perplexity-notebooklm`. Manual install & `python -m perplexity_mcp.server`: see [`docs/INSTALL.md`](docs/INSTALL.md).
+
+---
+
+## The two flows
+
+```python
+from dual_flow import research_to_notebook, notebook_to_research, research_to_media
+
+# Perplexity → NotebookLM  (research becomes a verified, deduped source)
+research_to_notebook("State of commercial fusion in 2026", NB, tool="research",
+                     verify=True, dedup=True)
+
+# NotebookLM → Perplexity  (read the notebook, fact-check & update against the live web)
+notebook_to_research(NB, tool="search")
+
+# Research → media  (source + audio / video / mind-map in one call)
+research_to_media("AI in real estate 2026", NB, kind="mind_map")
+```
+
+> **NotebookLM auth:** Google blocks automated logins, so the first run needs a real
+> Chrome you control:
+> `chrome.exe --remote-debugging-port=9222 --user-data-dir="D:\nlm-chrome"` (log in once).
+> After that it's pure HTTP with automatic cookie re-bridge.
+
+---
+
+## Architecture
+
+```
+perplexity_mcp/      MCP server · pluggable backend (helallao) · cited_search
+                     resilience (retry/jitter/rate-limit) · security · validate
+                     verify_citations (adversarial) · agentic (deep-research)
+notebooklm_write/    nlm_http (notebooklm-py HTTP/RPC + cookie-bridge) · add_source (Selenium fallback)
+                     ledger (4-layer dedup) · embed (local model2vec)
+dual_flow.py         the bidirectional orchestration
+rag.py · watch.py    cross-notebook BM25 retrieval · change watcher
+evals/ · skills/     regression harness · Claude Code skill
+.claude-plugin/      plugin manifest · commands · hooks
+```
+
+**Design principles:** small, single-purpose modules · pluggable Perplexity backend
+(swap providers without touching callers) · graceful degradation everywhere (no Chrome →
+clean error; no embedder → falls back to MinHash; stale cookie → auto re-bridge) ·
+eval harness as a regression gate · honest about limits.
+
+### Dedup, in 4 layers (cheapest first)
+
+| Layer | Catches | Cost |
+|-------|---------|------|
+| **Query** | re-researching the same topic | free (skips *before* the Pro call) |
+| **Exact hash** | identical content | free |
+| **MinHash** | near-verbatim edits | free |
+| **Semantic** | reworded / paraphrased (cosine ≈ 0.90) | local embedding, no API |
+
+---
+
+## Reliability & safety
+
+- **Resilience:** exponential backoff + full jitter, rate limiting, single-flight auth refresh.
+- **Your accounts, your cookies:** every user authenticates with **their own** Perplexity/NotebookLM. Credentials live only in your local `.env` + `~/.notebooklm/` (git-ignored, never committed, never shipped in the package). Nothing personal is bundled — a fresh install has zero cookies; you run `perplexity-nlm-auth` to pull your own.
+- **Security:** secrets only in `.env` (git-ignored); cookie values never logged (redaction); file perms hardened.
+- **ToS-aware automation:** the watcher defaults to dry-run, enforces a ≥10-min poll floor, an interruptible kill-switch, and writes only through an explicit callback with a human checkpoint.
+- **Tested:** eval harness (`evals/run.py`) + end-to-end validation on real accounts (dual flow, 44-notebook RAG, dedup, watcher).
+
+---
+
+## Honest limitations
+
+A senior project says what it *doesn't* do:
+
+- Built on **unofficial** Perplexity/NotebookLM interfaces — they can change; expect occasional maintenance.
+- Continuous automation against your accounts carries inherent **ToS risk** — use sparingly.
+- Semantic dedup needs the optional local model; without it, dedup falls back to lexical.
+- NotebookLM write/read needs a logged-in Chrome on the debug port (Google blocks headless login).
+
+---
+
+## Roadmap
+
+See [`docs/INNOVATION.md`](docs/INNOVATION.md) for the full ranked roadmap, and
+[`docs/BENCHMARK.md`](docs/BENCHMARK.md) for how this compares against 7 ecosystem projects.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Not affiliated with Perplexity AI or Google.