Start with status, then repair deliberately.

Is Link Ready?

link status --validate
link doctor
link prompts

If link is not on your PATH, run from the source checkout with python3 link.py, or add ~/.local/bin to your shell path.

MCP Is Not Visible

link verify-mcp
python3 -m pip index versions link-mcp

Restart the MCP client after changing its config. If your installer printed a venv Python path, use that exact path in the MCP config.

Ingest Is Blocked

link ingest-status

Blocked ingest usually means a raw source has secret-looking values, cannot be read safely, or source representation counts may be incomplete. Redact or fix the local file, then ask the agent to ingest again.

Graph Is Stale

link rebuild-index
link rebuild-backlinks
link validate

Run this after manual Obsidian edits, hand-written wikilinks, or a failed ingest.

Demo Looks Stale

link-demo/ is generated local output and is ignored by git. If it was created with an older Link version, regenerate it:

python3 link.py demo link-demo --force
python3 link.py status link-demo --validate
python3 link.py query "why does Link help agents?" link-demo --budget small

The current generated demo should include three raw sources, source-backed wiki pages, one starter memory, one exploration, current backlinks, and schema v1.

The Wiki Feels Slow

link benchmark "agent memory"
link graph-summary "agent memory" --limit 40 --depth 1

Large graph views intentionally open bounded first. Use type filters, node search, depth controls, and explicit full-graph load only when you need everything.

pip Is Blocked By Homebrew Python

If pip reports externally-managed-environment, avoid forcing packages into Homebrew Python. Use a dedicated venv:

python3 -m venv ~/.link-mcp-venv
~/.link-mcp-venv/bin/python -m pip install --upgrade pip link-mcp

The current installers do this automatically when needed.