setup

Graphify Setup

Self-Evolving Skill: This skill improves through use. If the package name drifts, an install flag stops working, or a backend gotcha changes — fix this file (and references/backends.md) immediately, don't defer. Only update for real, reproducible issues.

Install the Graphify-Labs/graphify engine as an isolated uv tool and verify it works.

Naming gotcha: the PyPI package is graphifyy (double-y, temporary while the graphify name is reclaimed). The CLI binary is still graphify. Do not uv tool install graphify — wrong package.

Steps

1. Check current state

command -v graphify && graphify --version
uv tool list | grep -i graphifyy

If installed and healthy → report version and stop (idempotent).

2. Install (uv-first policy — never pip/pipx)

uv tool install "graphifyy[anthropic,gemini]"

Install WITH the LLM-backend extras — the bare package does AST-only extraction; semantic extraction of docs/images fails at runtime with "the 'anthropic'/'openai' package is required" (verified 2026-07-07). The [anthropic] extra enables --backend claude, [gemini] enables --backend gemini (uses the openai package under the hood).

Requires Python 3.10+; uv tool provisions its own interpreter, so the host repo's pinned Python is never touched (pin-wins rule unaffected).

Upgrade path:

uv tool upgrade graphifyy

3. Verify

graphify --version
graphify --help | head -20

Both must succeed. If graphify is not on PATH, run uv tool update-shell and re-source the shell profile.

4. Pick a backend (which LLM does extraction)

The engine needs an LLM for semantic extraction. Three are wired for this operator — full copy-paste env blocks in ../../references/backends.md:

• gemini-2.5-flash — bulk default (fast, no ban-risk); GEMINI_API_KEY already in env.
• fleet Opus 4.8 — "our LLM" via the dedicated graphify sub2api key (1Password 2eeg5h4n3st6kcmt3icjhfjiiy); needs GRAPHIFY_LLM_TEMPERATURE=omit.
• MiniMax-M3 — rich but slow; 1Password e54cb3ujopexslaq7loywpuycm.

All require unset HTTPS_PROXY HTTP_PROXY https_proxy http_proxy first. The claude backend is blocked (doorward 426) — use the fleet openai door.

5. Optional: register the Claude Code skill command

The engine ships its own /graphify skill installer:

graphify install

This writes ~/.claude/skills/graphify/SKILL.md. Skip by default — this plugin's build-graph skill already wraps the CLI; installing both creates two overlapping invocation paths. Only run it if the operator explicitly wants the upstream /graphify command too.

Failure modes

Symptom	Fix
uv: command not found	mise provides uv globally; run mise install or check ~/.zshrc mise activation
graphify not on PATH after install	uv tool update-shell, then restart shell
Installed graphify package by mistake	uv tool uninstall graphify && uv tool install "graphifyy[anthropic,gemini]"
"the 'anthropic'/'openai' package is required" at runtime	Extras missing: uv tool install "graphifyy[anthropic,gemini]" --force
--backend claude → HTTP 426 wrapper_version_too_old	This fleet routes ANTHROPIC_BASE_URL through doorward, which rejects direct SDK calls lacking the X-Ccmax-Wrapper-Version header. Use --backend gemini (GEMINI_API_KEY is in the env) — see build-graph skill

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing.
1. What failed? — Fix the instruction that caused it.
2. What worked better than expected? — Promote to recommended practice.
3. What drifted? — Fix any script, reference, or dependency (esp. references/backends.md) that no longer matches reality.
4. Log it. — Add a dated note to the plugin CLAUDE.md provenance with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.