ckgraphify 0.1.0__tar.gz

ckgraphify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Safi Shamsi
+
+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.

ckgraphify-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+exclude .DS_Store
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+prune .pytest_cache
+prune .venv-release
+prune build
+prune cgraph.egg-info
+prune dist
+prune graphify-out
+prune tests

ckgraphify-0.1.0/PKG-INFO

@@ -0,0 +1,608 @@
+Metadata-Version: 2.4
+Name: ckgraphify
+Version: 0.1.0
+Summary: AI coding assistant skill for Claude Code and Codex - graph-main boundary graphs, multi-repo call chains, business-map concepts, and business search
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/safishamsi/graphify
+Project-URL: Repository, https://github.com/safishamsi/graphify
+Project-URL: Issues, https://github.com/safishamsi/graphify/issues
+Keywords: claude,claude-code,codex,knowledge-graph,graph-main,business-map,multi-repo,hsf,mtop,rag,graphrag,tree-sitter,llm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx
+Requires-Dist: datasketch
+Requires-Dist: rapidfuzz
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: tree-sitter-python
+Requires-Dist: tree-sitter-javascript
+Requires-Dist: tree-sitter-typescript
+Requires-Dist: tree-sitter-go
+Requires-Dist: tree-sitter-rust
+Requires-Dist: tree-sitter-java
+Requires-Dist: tree-sitter-groovy
+Requires-Dist: tree-sitter-c
+Requires-Dist: tree-sitter-cpp
+Requires-Dist: tree-sitter-ruby
+Requires-Dist: tree-sitter-c-sharp
+Requires-Dist: tree-sitter-kotlin
+Requires-Dist: tree-sitter-scala
+Requires-Dist: tree-sitter-php
+Requires-Dist: tree-sitter-swift
+Requires-Dist: tree-sitter-lua
+Requires-Dist: tree-sitter-zig
+Requires-Dist: tree-sitter-powershell
+Requires-Dist: tree-sitter-elixir
+Requires-Dist: tree-sitter-objc
+Requires-Dist: tree-sitter-julia
+Requires-Dist: tree-sitter-verilog
+Requires-Dist: tree-sitter-fortran
+Provides-Extra: mcp
+Requires-Dist: mcp; extra == "mcp"
+Provides-Extra: neo4j
+Requires-Dist: neo4j; extra == "neo4j"
+Provides-Extra: pdf
+Requires-Dist: pypdf; extra == "pdf"
+Requires-Dist: markdownify; extra == "pdf"
+Provides-Extra: watch
+Requires-Dist: watchdog; extra == "watch"
+Provides-Extra: svg
+Requires-Dist: matplotlib; extra == "svg"
+Provides-Extra: leiden
+Requires-Dist: graspologic; python_version < "3.13" and extra == "leiden"
+Provides-Extra: office
+Requires-Dist: python-docx; extra == "office"
+Requires-Dist: openpyxl; extra == "office"
+Provides-Extra: google
+Requires-Dist: openpyxl; extra == "google"
+Provides-Extra: video
+Requires-Dist: faster-whisper; extra == "video"
+Requires-Dist: yt-dlp; extra == "video"
+Provides-Extra: kimi
+Requires-Dist: openai; extra == "kimi"
+Requires-Dist: tiktoken; extra == "kimi"
+Provides-Extra: ollama
+Requires-Dist: openai; extra == "ollama"
+Provides-Extra: bedrock
+Requires-Dist: boto3; extra == "bedrock"
+Provides-Extra: gemini
+Requires-Dist: openai; extra == "gemini"
+Requires-Dist: tiktoken; extra == "gemini"
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Requires-Dist: tiktoken; extra == "openai"
+Provides-Extra: sql
+Requires-Dist: tree-sitter-sql; extra == "sql"
+Provides-Extra: all
+Requires-Dist: mcp; extra == "all"
+Requires-Dist: neo4j; extra == "all"
+Requires-Dist: pypdf; extra == "all"
+Requires-Dist: markdownify; extra == "all"
+Requires-Dist: watchdog; extra == "all"
+Requires-Dist: graspologic; python_version < "3.13" and extra == "all"
+Requires-Dist: python-docx; extra == "all"
+Requires-Dist: openpyxl; extra == "all"
+Requires-Dist: faster-whisper; extra == "all"
+Requires-Dist: yt-dlp; extra == "all"
+Requires-Dist: matplotlib; extra == "all"
+Requires-Dist: openai; extra == "all"
+Requires-Dist: tiktoken; extra == "all"
+Requires-Dist: boto3; extra == "all"
+Requires-Dist: tree-sitter-sql; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <a href="https://graphifylabs.ai"><img src="https://raw.githubusercontent.com/safishamsi/graphify/v4/docs/logo-text.svg" width="260" height="64" alt="Graphify"/></a>
+</p>
+
+<p align="center">
+  🇺🇸 <a href="README.md">English</a> | 🇨🇳 <a href="docs/translations/README.zh-CN.md">简体中文</a> | 🇯🇵 <a href="docs/translations/README.ja-JP.md">日本語</a> | 🇰🇷 <a href="docs/translations/README.ko-KR.md">한국어</a> | 🇩🇪 <a href="docs/translations/README.de-DE.md">Deutsch</a> | 🇫🇷 <a href="docs/translations/README.fr-FR.md">Français</a> | 🇪🇸 <a href="docs/translations/README.es-ES.md">Español</a> | 🇮🇳 <a href="docs/translations/README.hi-IN.md">हिन्दी</a> | 🇧🇷 <a href="docs/translations/README.pt-BR.md">Português</a> | 🇷🇺 <a href="docs/translations/README.ru-RU.md">Русский</a> | 🇸🇦 <a href="docs/translations/README.ar-SA.md">العربية</a> | 🇮🇹 <a href="docs/translations/README.it-IT.md">Italiano</a> | 🇵🇱 <a href="docs/translations/README.pl-PL.md">Polski</a> | 🇳🇱 <a href="docs/translations/README.nl-NL.md">Nederlands</a> | 🇹🇷 <a href="docs/translations/README.tr-TR.md">Türkçe</a> | 🇺🇦 <a href="docs/translations/README.uk-UA.md">Українська</a> | 🇻🇳 <a href="docs/translations/README.vi-VN.md">Tiếng Việt</a> | 🇮🇩 <a href="docs/translations/README.id-ID.md">Bahasa Indonesia</a> | 🇸🇪 <a href="docs/translations/README.sv-SE.md">Svenska</a> | 🇬🇷 <a href="docs/translations/README.el-GR.md">Ελληνικά</a> | 🇷🇴 <a href="docs/translations/README.ro-RO.md">Română</a> | 🇨🇿 <a href="docs/translations/README.cs-CZ.md">Čeština</a> | 🇫🇮 <a href="docs/translations/README.fi-FI.md">Suomi</a> | 🇩🇰 <a href="docs/translations/README.da-DK.md">Dansk</a> | 🇳🇴 <a href="docs/translations/README.no-NO.md">Norsk</a> | 🇭🇺 <a href="docs/translations/README.hu-HU.md">Magyar</a> | 🇹🇭 <a href="docs/translations/README.th-TH.md">ภาษาไทย</a> | 🇹🇼 <a href="docs/translations/README.zh-TW.md">繁體中文</a>
+</p>
+
+<p align="center">
+  <a href="https://safishamsi.gumroad.com/l/qetvlo"><img src="https://img.shields.io/badge/Book-The%20Memory%20Layer-2ea44f?style=flat&logo=gitbook&logoColor=white" alt="The Memory Layer"/></a>
+  <a href="https://github.com/safishamsi/graphify/actions/workflows/ci.yml"><img src="https://github.com/safishamsi/graphify/actions/workflows/ci.yml/badge.svg?branch=v7" alt="CI"/></a>
+  <a href="https://pypi.org/project/ckgraphify/"><img src="https://img.shields.io/pypi/v/ckgraphify" alt="PyPI"/></a>
+  <a href="https://clickpy.clickhouse.com/dashboard/ckgraphify"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsql-clickhouse.clickhouse.com%2F%3Fquery%3DSELECT%2520concat%2528toString%2528round%2528sum%2528count%2529%2F1000%2529%2529%2C%2520%2527k%2527%2529%2520AS%2520c%2520FROM%2520pypi.pypi_downloads%2520WHERE%2520project%253D%2527ckgraphify%2527%2520FORMAT%2520JSON%26user%3Ddemo&query=%24.data%5B0%5D.c&label=downloads&color=blue" alt="Downloads"/></a>
+  <a href="https://github.com/sponsors/safishamsi"><img src="https://img.shields.io/badge/sponsor-safishamsi-ea4aaa?logo=github-sponsors" alt="Sponsor"/></a>
+  <a href="https://www.linkedin.com/in/safi-shamsi"><img src="https://img.shields.io/badge/LinkedIn-Safi%20Shamsi-0077B5?logo=linkedin" alt="LinkedIn"/></a>
+  <a href="https://x.com/cgraph"><img src="https://img.shields.io/badge/X-cgraph-000000?logo=x&logoColor=white" alt="X"/></a>
+</p>
+
+<p align="center">
+  <a href="https://star-history.com/#safishamsi/graphify&Date">
+    <img src="https://api.star-history.com/svg?repos=safishamsi/graphify&type=Date" alt="Star History Chart" width="370"/>
+  </a>
+</p>
+
+Type `/cgraph` in Claude Code or use the installed Codex skill to work with graph-main boundary graphs, multi-repo call chains, business-map concepts, and business search.
+
+Supported assistant channels are Claude Code and Codex.
+
+```
+/cgraph .
+```
+
+That's it. You get three files:
+
+```
+graphify-out/
+├── graph.html       open in any browser — click nodes, filter, search
+├── GRAPH_REPORT.md  the highlights: key concepts, surprising connections, suggested questions
+└── graph.json       the full graph — query it anytime without re-reading your files
+```
+
+For a readable architecture page with Mermaid call-flow diagrams, run:
+
+```bash
+graphify export callflow-html
+```
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum | Check | Install |
+|---|---|---|---|
+| Python | 3.10+ | `python --version` | [python.org](https://www.python.org/downloads/) |
+| uv *(recommended)* | any | `uv --version` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| pipx *(alternative)* | any | `pipx --version` | `pip install pipx` |
+
+**macOS quick install (Homebrew):**
+```bash
+brew install python@3.12 uv
+```
+
+**Windows quick install:**
+```powershell
+winget install astral-sh.uv
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install python3.12 python3-pip pipx
+# or install uv:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+---
+
+## Install
+
+> **Official package:** The PyPI package is `ckgraphify`. The CLI command is still `graphify`.
+
+**Step 1 — install the package:**
+
+```bash
+# Recommended (uv puts graphify on PATH automatically):
+uv tool install ckgraphify
+
+# Alternatives:
+pipx install ckgraphify
+pip install ckgraphify
+```
+
+**Step 2 — register the skill with your AI assistant:**
+
+```bash
+graphify install
+```
+
+That's it. Open your AI assistant and type `/cgraph .`
+
+> **PowerShell note:** Use `graphify .` not `/cgraph .` — the leading slash is a path separator in PowerShell.
+
+> **`graphify: command not found`?** Use `uv tool install ckgraphify` or `pipx install ckgraphify` — both put the CLI on PATH automatically. With plain `pip`, add `~/.local/bin` (Linux) or `~/Library/Python/3.x/bin` (Mac) to your PATH, or run `python -m graphify`.
+
+### Pick your platform
+
+| Platform | Install command |
+|----------|----------------|
+| Claude Code | `graphify install` |
+| Codex | `graphify install --platform codex` |
+
+> Codex users: also add `multi_agent = true` under `[features]` in `~/.codex/config.toml`.
+> Codex uses `$cgraph` instead of `/cgraph`.
+
+### Optional extras
+
+Install only what you need:
+
+| Extra | What it adds | Install |
+|---|---|---|
+| `pdf` | PDF extraction | `pip install "ckgraphify[pdf]"` |
+| `office` | `.docx` and `.xlsx` support | `pip install "ckgraphify[office]"` |
+| `google` | Google Sheets rendering | `pip install "ckgraphify[google]"` |
+| `video` | Video/audio transcription (faster-whisper + yt-dlp) | `pip install "ckgraphify[video]"` |
+| `mcp` | MCP stdio server | `pip install "ckgraphify[mcp]"` |
+| `neo4j` | Neo4j push support | `pip install "ckgraphify[neo4j]"` |
+| `svg` | SVG graph export | `pip install "ckgraphify[svg]"` |
+| `leiden` | Leiden community detection (Python < 3.13 only) | `pip install "ckgraphify[leiden]"` |
+| `ollama` | Ollama local inference | `pip install "ckgraphify[ollama]"` |
+| `openai` | OpenAI / OpenAI-compatible APIs | `pip install "ckgraphify[openai]"` |
+| `gemini` | Google Gemini API | `pip install "ckgraphify[gemini]"` |
+| `bedrock` | AWS Bedrock (uses IAM, no API key) | `pip install "ckgraphify[bedrock]"` |
+| `sql` | SQL schema extraction | `pip install "ckgraphify[sql]"` |
+| `all` | Everything above | `pip install "ckgraphify[all]"` |
+
+---
+
+## Make your assistant always use the graph
+
+Run this once in your project after building a graph:
+
+| Platform | Command |
+|----------|---------|
+| Claude Code | `graphify claude install` |
+| Codex | `graphify codex install` |
+
+This writes a small config file that tells your assistant to read `GRAPH_REPORT.md` before answering questions about your codebase. Claude Code and Codex can also register hooks so the assistant checks the graph before file reads.
+
+To remove cgraph from supported assistant configs: `graphify uninstall` (add `--purge` to also delete `graphify-out/`). Or use `graphify claude uninstall` / `graphify codex uninstall`.
+
+---
+
+## What's in the report
+
+- **God nodes** — the most-connected concepts in your project. Everything flows through these.
+- **Surprising connections** — links between things that live in different files or modules. Ranked by how unexpected they are.
+- **The "why"** — inline comments (`# NOTE:`, `# WHY:`, `# HACK:`), docstrings, and design rationale from docs are extracted as separate nodes linked to the code they explain.
+- **Suggested questions** — 4–5 questions the graph is uniquely positioned to answer.
+- **Confidence tags** — every inferred relationship is marked `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`. You always know what was found vs guessed.
+
+---
+
+## What files it handles
+
+| Type | Extensions |
+|------|-----------|
+| Code (29 languages) | `.py .ts .js .jsx .tsx .mjs .go .rs .java .c .cpp .h .hpp .rb .cs .kt .scala .php .swift .lua .luau .zig .ps1 .ex .exs .m .mm .jl .vue .svelte .groovy .gradle .dart .v .sv .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk` |
+| Docs | `.md .mdx .qmd .html .txt .rst .yaml .yml` |
+| Office | `.docx .xlsx` (requires `pip install ckgraphify[office]`) |
+| Google Workspace | `.gdoc .gsheet .gslides` (opt-in; requires `gws` auth and `--google-workspace`; Sheets need `pip install ckgraphify[google]`) |
+| PDFs | `.pdf` |
+| Images | `.png .jpg .webp .gif` |
+| Video / Audio | `.mp4 .mov .mp3 .wav` and more (requires `pip install ckgraphify[video]`) |
+| YouTube / URLs | any video URL (requires `pip install ckgraphify[video]`) |
+
+Code is extracted locally with no API calls (AST via tree-sitter). Everything else goes through your AI assistant's model API.
+
+Google Drive for desktop `.gdoc`, `.gsheet`, and `.gslides` files are shortcut
+pointers, not document content. To include native Google Docs, Sheets, and Slides
+in a headless extraction, install and authenticate the
+[`gws` CLI](https://github.com/googleworkspace/cli), then run:
+
+```bash
+pip install "ckgraphify[google]"  # needed for Google Sheets table rendering
+gws auth login -s drive
+graphify extract ./docs --google-workspace
+```
+
+You can also set `GRAPHIFY_GOOGLE_WORKSPACE=1`. Graphify exports shortcuts into
+`graphify-out/converted/` as Markdown sidecars, then extracts those files.
+
+---
+
+## Common commands
+
+```bash
+/cgraph .                        # build graph for current folder
+/cgraph ./docs --update          # re-extract only changed files
+/cgraph . --cluster-only         # rerun clustering without re-extracting
+/cgraph . --no-viz               # skip the HTML, just the report + JSON
+/cgraph . --wiki                 # build a markdown wiki from the graph
+graphify export callflow-html      # architecture/call-flow HTML from graphify-out/
+
+/cgraph query "what connects auth to the database?"
+/cgraph path "UserService" "DatabasePool"
+/cgraph explain "RateLimiter"
+
+/cgraph add https://arxiv.org/abs/1706.03762   # fetch a paper and add it
+/cgraph add <youtube-url>                       # transcribe and add a video
+
+graphify hook install              # auto-rebuild on git commit
+graphify merge-graphs a.json b.json              # combine two graphs
+```
+
+See the [full command reference](#full-command-reference) below.
+
+---
+
+## Ignoring files
+
+Create a `.graphifyignore` in your project root — same syntax as `.gitignore`, including `!` negation:
+
+```
+# .graphifyignore
+node_modules/
+dist/
+*.generated.py
+
+# only index src/, ignore everything else
+*
+!src/
+!src/**
+```
+
+---
+
+## Team setup
+
+`graphify-out/` is meant to be committed to git so everyone on the team starts with a map.
+
+**Recommended `.gitignore` additions:**
+```
+graphify-out/manifest.json    # mtime-based, breaks after git clone
+graphify-out/cost.json        # local only
+# graphify-out/cache/         # optional: commit for speed, skip to keep repo small
+```
+
+**Workflow:**
+1. One person runs `/cgraph .` and commits `graphify-out/`.
+2. Everyone pulls — their assistant reads the graph immediately.
+3. Run `graphify hook install` to auto-rebuild after each commit (AST only, no API cost). This also sets up a git merge driver so `graph.json` is never left with conflict markers — two devs committing in parallel get their graphs union-merged automatically.
+4. When docs or papers change, run `/cgraph --update` to refresh those nodes.
+
+---
+
+## Using the graph directly
+
+```bash
+# query the graph from the terminal
+graphify query "show the auth flow"
+graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json
+
+# expose the graph as an MCP server (for repeated tool-call access)
+python -m graphify.serve graphify-out/graph.json
+
+# register with Kimi Code:
+kimi mcp add --transport stdio graphify -- python -m graphify.serve graphify-out/graph.json
+```
+
+The MCP server gives your assistant structured access: `query_graph`, `get_node`, `get_neighbors`, `shortest_path`.
+
+> **WSL / Linux note:** Ubuntu ships `python3`, not `python`. Use a venv to avoid conflicts:
+> ```bash
+> python3 -m venv .venv && .venv/bin/pip install "ckgraphify[mcp]"
+> ```
+
+---
+
+## Environment variables
+
+These are only needed for **headless / CI extraction** (`graphify extract`). When running via the `/cgraph` skill inside your IDE, the model API is provided by your IDE session — no extra keys needed.
+
+| Variable | Used for | When required |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | Claude (Anthropic) backend | `--backend claude` |
+| `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Google Gemini backend | `--backend gemini` |
+| `OPENAI_API_KEY` | OpenAI or OpenAI-compatible APIs | `--backend openai` |
+| `MOONSHOT_API_KEY` | Kimi Code backend | `--backend kimi` |
+| `OLLAMA_BASE_URL` | Ollama local inference URL | `--backend ollama` (default: `http://localhost:11434`) |
+| `OLLAMA_MODEL` | Ollama model name | `--backend ollama` (default: auto-detect) |
+| `GRAPHIFY_OLLAMA_NUM_CTX` | Override Ollama KV-cache window size | optional — auto-sized by default |
+| `GRAPHIFY_OLLAMA_KEEP_ALIVE` | Minutes to keep Ollama model loaded | optional — set `0` to unload after each chunk |
+| `AWS_*` / `~/.aws/credentials` | AWS Bedrock — standard credential chain | `--backend bedrock` (no API key, uses IAM) |
+| `GRAPHIFY_MAX_WORKERS` | AST parallelism thread count | optional — also `--max-workers` flag |
+| `GRAPHIFY_MAX_OUTPUT_TOKENS` | Raise output cap for dense corpora | optional — e.g. `32768` for large files |
+| `GRAPHIFY_API_TIMEOUT` | HTTP timeout in seconds (default: 600) | optional — also `--api-timeout` flag |
+| `GRAPHIFY_FORCE` | Force graph rebuild even with fewer nodes | optional — also `--force` flag |
+| `GRAPHIFY_GOOGLE_WORKSPACE` | Auto-enable Google Workspace export | optional — set to `1` |
+
+---
+
+## Privacy
+
+- **Code files** — processed locally via tree-sitter. Nothing leaves your machine.
+- **Video / audio** — transcribed locally with faster-whisper. Nothing leaves your machine.
+- **Docs, PDFs, images** — sent to your AI assistant for semantic extraction (via the `/cgraph` skill, using whatever model your IDE session runs). Headless `graphify extract` requires `GEMINI_API_KEY` / `GOOGLE_API_KEY` (Gemini), `MOONSHOT_API_KEY` (Kimi), `ANTHROPIC_API_KEY` (Claude), `OPENAI_API_KEY` (OpenAI), a running Ollama instance (`OLLAMA_BASE_URL`), AWS credentials via the standard provider chain (Bedrock - no API key needed, uses IAM), or the `claude` CLI binary (Claude Code - no API key needed, uses your Claude subscription). The `--dedup-llm` flag uses the same key.
+- No telemetry, no usage tracking, no analytics.
+
+---
+
+## Troubleshooting
+
+**`graphify: command not found` after `pip install ckgraphify`**
+pip installs scripts to a user bin directory that may not be on your PATH. Fix:
+- macOS: add `~/Library/Python/3.x/bin` to your PATH in `~/.zshrc`
+- Linux: add `~/.local/bin` to your PATH in `~/.bashrc`
+- Or use `uv tool install ckgraphify` / `pipx install ckgraphify` — both manage PATH automatically.
+
+**`python -m graphify` works but `graphify` command doesn't**
+Your shell's PATH doesn't include the Python scripts directory. Use `uv` or `pipx` instead of plain `pip`.
+
+**`/cgraph .` causes "path not recognized" in PowerShell**
+PowerShell treats a leading `/` as a path separator. Use `graphify .` (no slash) on Windows.
+
+**Graph has fewer nodes after `--update` or rebuild**
+If a refactor deleted files, the old nodes linger. Pass `--force` (or set `GRAPHIFY_FORCE=1`) to overwrite even when the rebuild has fewer nodes.
+
+**Graph has duplicate nodes for the same entity (ghost duplicates)**
+This happens when semantic and AST extraction disagreed on the node ID format. Run a full re-extract to clean up:
+```bash
+graphify extract . --force
+```
+
+**Ollama runs out of VRAM / context window exceeded**
+The KV-cache window is auto-sized but may be too large for your GPU. Reduce it:
+```bash
+GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000
+```
+
+**Graph HTML is too large to open in a browser (>5000 nodes)**
+Skip HTML generation and use the JSON directly:
+```bash
+graphify cluster-only ./my-project --no-viz
+graphify query "..."
+```
+
+**`graph.json` has conflict markers after two devs commit at once**
+Run `graphify hook install` — it sets up a git merge driver that union-merges `graph.json` automatically so conflicts never happen.
+
+**Extraction returns empty nodes/edges for docs or PDFs**
+Docs and PDFs require an LLM call. Check that your API key is set and the backend is correct:
+```bash
+ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude
+```
+
+**Skill version mismatch warning in your IDE**
+Your installed cgraph version is different from the skill file. Update:
+```bash
+uv tool upgrade ckgraphify
+graphify install  # overwrites the skill file
+```
+
+---
+
+## Full command reference
+
+```
+/cgraph                          # run on current directory
+/cgraph ./raw                    # run on a specific folder
+/cgraph ./raw --mode deep        # more aggressive relationship extraction
+/cgraph ./raw --update           # re-extract only changed files
+/cgraph ./raw --directed         # preserve edge direction
+/cgraph ./raw --cluster-only     # rerun clustering on existing graph
+/cgraph ./raw --no-viz           # skip HTML visualization
+/cgraph ./raw --obsidian         # generate Obsidian vault
+/cgraph ./raw --wiki             # build agent-crawlable markdown wiki
+/cgraph ./raw --svg              # export graph.svg
+/cgraph ./raw --graphml          # export for Gephi / yEd
+/cgraph ./raw --neo4j            # generate cypher.txt for Neo4j
+/cgraph ./raw --neo4j-push bolt://localhost:7687
+/cgraph ./raw --watch            # auto-sync as files change
+/cgraph ./raw --mcp              # start MCP stdio server
+
+/cgraph add https://arxiv.org/abs/1706.03762
+/cgraph add <video-url>
+/cgraph add https://... --author "Name" --contributor "Name"
+
+/cgraph query "what connects attention to the optimizer?"
+/cgraph query "..." --dfs --budget 1500
+/cgraph path "DigestAuth" "Response"
+/cgraph explain "SwinTransformer"
+
+graphify uninstall                 # remove from Claude Code and Codex configs
+graphify uninstall --purge         # also delete graphify-out/
+
+graphify hook install              # post-commit + post-checkout hooks
+graphify hook uninstall
+graphify hook status
+
+graphify claude install / uninstall
+graphify codex install / uninstall
+
+graphify extract ./docs                        # headless LLM extraction for CI (no IDE needed)
+graphify extract ./docs --backend gemini       # explicit backend: gemini, kimi, claude, openai, ollama, bedrock, or claude-cli
+graphify extract ./docs --backend gemini --model gemini-3.1-pro-preview
+graphify extract ./docs --backend ollama       # local Ollama (set OLLAMA_BASE_URL / OLLAMA_MODEL) - no API key needed for loopback
+GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama   # override KV-cache window (auto-sized by default)
+GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama    # unload model after each chunk (saves VRAM on small GPUs)
+graphify extract ./docs --backend bedrock      # AWS Bedrock via IAM - no API key, uses AWS credential chain
+graphify extract ./docs --backend claude-cli   # route through Claude Code CLI - no API key, uses your Claude subscription
+graphify extract ./docs --max-workers 16       # AST parallelism (also GRAPHIFY_MAX_WORKERS)
+graphify extract ./docs --token-budget 30000   # smaller semantic chunks for local/small models
+graphify extract ./docs --max-concurrency 2    # fewer parallel LLM calls (useful for local inference)
+graphify extract ./docs --api-timeout 900      # longer HTTP timeout for slow local models (default 600s)
+graphify extract ./docs --google-workspace     # export .gdoc/.gsheet/.gslides via gws before extraction
+graphify extract ./docs --no-cluster           # raw extraction only, skip clustering
+graphify extract ./docs --force                # overwrite graph.json even if new graph has fewer nodes (use after refactors or to clear ghost duplicates)
+graphify extract ./docs --dedup-llm            # LLM tiebreaker for ambiguous entity pairs (uses same API key)
+graphify extract ./docs --global --as myrepo   # extract and register into the cross-project global graph
+GRAPHIFY_MAX_OUTPUT_TOKENS=32768 graphify extract ./docs --backend claude  # raise output cap for dense corpora
+
+graphify export callflow-html                       # graphify-out/<project>-callflow.html
+graphify export callflow-html --max-sections 8      # cap generated architecture sections
+graphify export callflow-html --output docs/arch.html
+graphify export callflow-html ./some-repo/graphify-out
+
+graphify global add graphify-out/graph.json myrepo   # register a project graph into ~/.graphify/global.json
+graphify global remove myrepo                         # remove a project from the global graph
+graphify global list                                  # show all registered repos + node/edge counts
+graphify global path                                  # print path to the global graph file
+
+graphify clone https://github.com/karpathy/nanoGPT
+graphify merge-graphs a.json b.json --out merged.json
+graphify --version                                    # print installed version
+graphify watch ./src
+graphify check-update ./src
+graphify update ./src
+graphify update ./src --no-cluster  # skip reclustering, write raw AST graph only
+graphify update ./src --force       # overwrite even if new graph has fewer nodes
+graphify cluster-only ./my-project
+graphify cluster-only ./my-project --graph path/to/graph.json  # custom graph location
+```
+
+---
+
+## Learn more
+
+- [How it works](docs/how-it-works.md) — the extraction pipeline, community detection, confidence scoring, benchmarks
+- [ARCHITECTURE.md](ARCHITECTURE.md) — module breakdown, how to add a language
+- [Optional integrations](docs/docker-mcp-sqlite.md) — Docker MCP Toolkit + SQLite
+
+---
+
+## Built on graphify — Penpax
+
+[**Penpax**](https://graphifylabs.ai) is the always-on layer built on top of graphify — it applies the same graph approach to your entire working life: meetings, browser history, emails, files, and code, updating continuously in the background.
+
+Built for people whose work lives across hundreds of conversations and documents they can never fully reconstruct. No cloud, fully on-device.
+
+**Free trial launching soon.** [Join the waitlist →](https://graphifylabs.ai)
+
+---
+
+<details>
+<summary>Contributing</summary>
+
+### Development setup
+
+Clone the repo and install in editable mode:
+
+```bash
+git clone https://github.com/safishamsi/graphify.git
+cd graphify
+git checkout v7                        # active development branch
+
+# Create a virtual environment (Python 3.10+ required):
+python3 -m venv .venv
+source .venv/bin/activate              # Windows: .venv\Scripts\activate
+
+# Install in editable mode with all optional extras:
+pip install -e ".[all]"
+```
+
+Verify the editable install:
+```bash
+graphify --version
+python -c "import graphify; print(graphify.__file__)"
+```
+
+### Running tests
+
+```bash
+pip install pytest
+pytest tests/ -q                       # run the full suite
+pytest tests/test_extract.py -q        # one module
+pytest tests/ -q -k "python"           # filter by name
+```
+
+> macOS note: the test suite includes both `sample.f90` and `sample.F90` fixtures. These collide on case-insensitive HFS+ / APFS file systems. Run on Linux or in a Docker container if you need to test both Fortran variants simultaneously.
+
+### Git workflow
+
+- Active development happens on the `v7` branch.
+- Commit style: `fix: <description>` / `feat: <description>` / `docs: <description>`
+- Before opening a PR, run `pytest tests/ -q` and confirm it passes.
+- Add a fixture file to `tests/fixtures/` and tests to `tests/test_languages.py` for any new language extractor.
+
+### What to contribute
+
+**Worked examples** are the most useful contribution. Run `/cgraph` on a real corpus, save the output to `worked/{slug}/`, write an honest `review.md` covering what the graph got right and wrong, and open a PR.
+
+**Extraction bugs** — open an issue with the input file, the cache entry (`graphify-out/cache/`), and what was missed or wrong.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for module responsibilities and how to add a language.
+
+</details>