# GNKG — https://gnkg.vercel.app
> Gemini Notebook Knowledge Graph: a Chrome extension + local bridge that give people AND their agents full access to Gemini Notebook notebooks as mini knowledge graphs.

## For agents: install yourself
1. Ask the user to run the installer: Windows `irm https://gnkg.vercel.app/harness/install.ps1 | iex`, macOS/Linux `curl -fsSL https://gnkg.vercel.app/harness/install.sh | bash`. It loads the bridge, writes MCP configs for Claude Desktop / Claude Code / Cursor / Windsurf and installs the /gnkg skill. The user then adds the GNKG extension from the Chrome Web Store (link on https://gnkg.vercel.app/install) and signs in at notebook.google.com.
2. Connect: MCP stdio `npx -y @metaphyllc/gnkg-bridge`, or MCP over HTTP `http://127.0.0.1:7802/mcp`, or REST `http://127.0.0.1:7802/api/<tool>` (OpenAPI at https://gnkg.vercel.app/openapi.json). Cloud agents: see https://gnkg.vercel.app/harness/README.md (tunnel + token).
3. Read the live instructions from the bridge itself at http://127.0.0.1:7802/llms.txt — reproduced below.

## Pages
- https://gnkg.vercel.app/agents — the agent harness page
- https://gnkg.vercel.app/install — human install
- https://gnkg.vercel.app/harness/AGENT_CARD.md — system-prompt block
- https://gnkg.vercel.app/harness/SKILL.md — Claude Code skill

---

# GNKG Bridge — agent instructions
You are talking to a GNKG bridge (Gemini Notebook Knowledge Graph, v2.1.2). It controls the user's Gemini Notebook notebooks through a Chrome extension running in their signed-in browser. Every notebook is a mini knowledge graph: notebook › sources › bins › files › artifacts.

## How to connect (pick one)
- MCP (Streamable HTTP): POST JSON-RPC 2.0 to http://127.0.0.1:7802/mcp  (methods: initialize, tools/list, tools/call)
- MCP (stdio): command "npx", args ["-y","@metaphyllc/gnkg-bridge"]
- REST: POST http://127.0.0.1:7802/api/<tool_name> with a JSON body; schema at http://127.0.0.1:7802/openapi.json
- Auth: none required on localhost

## Workflow
1. gn_health — confirm the extension is connected and signed in.
2. gn_list_notebooks → pick a notebookId (or gn_create_notebook).
3. Add knowledge: gn_add_text_source / gn_add_url_source, or bifrost_push_bins for whole folders (weighted FFD bins of 450k words + Bin 0 master index).
4. Read: gn_get_notebook (sources + status), gn_graph (nlmkg/gnkg-graph-v1 JSON + Mermaid), gn_get_source (full text + AI guide).
5. Reason: gn_ask (grounded, citation-backed answer; optional sourceIds subset).
6. Produce: gn_create_artifact kind=audio|video|report|slide_deck|infographic|data_table|mind_map|flashcards|quiz (wait=true to poll), gn_download_artifact.
7. Long jobs return a jobId → poll gn_job; gn_events shows recent activity.

## Rules
- Never ask the user for cookies or tokens; the extension holds the session.
- Sources are capped at 500k words; prefer bifrost_push_bins for large corpora.
- Studio generation is quota-limited by Google; check status before retrying.
- Read-only fallback when RPC shapes drift: gn_dom_read.

## Tools
- gn_health: Extension/auth/transport health. Call first.
- gn_list_notebooks: List Gemini Notebook notebooks (most-recently-viewed first) with ids and source counts.
- gn_create_notebook: Create a notebook (a new mini knowledge graph).
- gn_delete_notebook: Delete a notebook permanently (irreversible). Only for notebooks the user asked to delete.
- gn_get_notebook: Get a notebook with its sources (id, title, kind, wordCount, status).
- gn_add_text_source: Add a text source (≤500k words). Use for bins, notes, transcripts.
- gn_add_url_source: Add a web page or YouTube URL as a source.
- gn_delete_source: Delete a source.
- gn_refresh_source: Re-sync a web/Drive source (the legacy B.I.F.R.O.S.T. feed trigger).
- gn_get_source: Read a source's indexed full text and AI summary.
- gn_ask: Ask the notebook a grounded question (uses Gemini Notebook's own retrieval). Optional sourceIds subset.
- gn_list_artifacts: List Studio artifacts (audio/video/report/slides/infographic/data table/mind map/quiz/flashcards) with status + media URLs.
- gn_create_artifact: Generate a Studio artifact remotely. kind: audio|video|report|slide_deck|infographic|data_table|mind_map|flashcards|quiz. wait=true polls until done (up to 15 min).
- gn_wait_artifact: Poll an artifact until completed/failed.
- gn_download_artifact: Download a completed artifact's media via Chrome downloads (TIWY handoff if enabled).
- gn_graph: Knowledge-graph view of a notebook (gnkg-graph-v1 JSON + Mermaid).
- bifrost_plan_bins: Plan B.I.F.R.O.S.T. bins locally: weighted FFD packing at 450k words, pre-chunk >400k, Bin 0 master index preview. files=[{name,text}].
- bifrost_push_bins: Pack files and push Bin 0 + bins into a notebook as text sources (waits for each to index). Returns jobId; poll with gn_job.
- gn_job: Get a background job (pushBins) with progress/steps/result.
- gn_events: Recent extension events (jobs, logs, downloads).
- gn_dom_read: Fallback: read the open Gemini Notebook tab's DOM (sources, artifacts, chat) when RPC drifts.
- gn_open_notebook: Open a notebook in a new Chrome tab.