okfsmith logo okfsmith Docs EN Open okfsmith
On this page

Troubleshooting

Changelog

[0.5.2] — 2026-09-29

Fixed

  • Dashboard frontend missing from the PyPI wheel — the 0.5.1 wheel shipped only the dashboard's Python files, so a pip-installed okfsmith dashboard showed the "frontend bundle has not been built yet" placeholder instead of the SPA. The okfsmith/dashboard/static/* bundle now ships in wheels and sdists, guarded by regression tests.

[0.5.1] — 2026-09-28

Fixed

  • Knowledge-graph edge resolution for section concepts — when a document is split into per-section concepts (id doc/section), markdown links in those concepts are relative to the source document, but the resolver treated the id as a file path, so the Explore graph silently dropped edges for interlinked documents. Links now resolve to the target document's primary section concept; genuinely broken links are still marked dead.

[0.5.0] — 2026-09-28

Added

  • Web dashboard (okfsmith dashboard) — a local-first web UI covering all ten product areas: Overview, Ingest (drag-and-drop with live parse → chunk → embed → validate → index progress), Explore (interactive knowledge graph), Temporal, Chat (grounded, with clickable citations), Validate, MCP, Eval, Doctor, and Settings. Binds only to 127.0.0.1, per-launch token auth, default port 8931 with free-port fallback, fully offline packaged assets (no CDN). The knowledge graph renders ECharts-style: solid cluster-colored circles with labels inside, degree-scaled hubs, edge-to-edge arrows, and a cluster legend. See Web dashboard.

[0.4.0] — 2026-09-28

Added

  • okfsmith sync — incremental sync of a bundle with its sources: SHA-256 change detection, added / updated / renamed / removed handling (renames detected by content hash, updates replace under the same ids — never name-2 duplicates), atomic resumable state, --watch polling, --dry-run, --format json. See Syncing sources.
  • Temporal knowledge model — concepts carry valid_from / valid_until validity windows, supersedes replacement chains, and last_verified freshness; retrieval ranks by currency, and --as-of <date> on search / eval replays any instant. Superseded concepts are hidden by default, never deleted. See Temporal model.
  • MCP expansion — four new read tools: traverse (BFS link-graph expansion, depth ≤ 3, cycle-safe), provenance (concept → sources → ingest manifest), diff (bundle vs bundle or vs sync snapshot), plus evidence budgets on every tool (max_chunks, max_tokens, continuation_token) for bounded agent context. See MCP server.
  • okfsmith eval — golden Q&A eval harness: scores golden sets on the RAG Triad (context relevancy / faithfulness / answer relevancy), diagnoses failures as retrieval vs generation, runs heuristic (keyless) or LLM-judge, and gates CI with --fail-under. See Evaluating bundles.
  • Governed MCP write-back — four new tools (preview_write_concept, write_concept, update_concept, audit_log) let agents contribute under code-enforced governance: writes always land at the unverified trust tier, human-reviewed concepts need explicit downgrade_trust, validator-gated, atomic, append-only audited. See MCP server.

[0.3.0] — 2026-09-26

Added

  • Interactive chat REPL (okfsmith chat) — ask questions over your bundle in natural language, Claude-Code style: citations, slash commands (/search, /read, /validate, /graph, /doctor, …), extractive fallback when no LLM is reachable, and generative answers via Ollama or any OpenAI-compatible provider. See Interactive chat.
  • Any-model provider system — 15 --provider presets (ollama, lmstudio, openai, groq, mistral, deepseek, openrouter, together, fireworks, deepinfra, anyscale, perplexity, xai, gemini, agentrouter), plus --api-base / OKFSMITH_API_BASE for any other OpenAI-compatible endpoint. Keys are never displayed, logged, or saved to disk. See Providers & API keys.
  • Chat startup UI — Qwen/Claude/Antigravity-style makeover: gradient ASCII OKFSMITH banner, bundle-aware kb › prompt, and ✦ answer markers. Piped and NO_COLOR output stays plain.
  • This documentation website — the Claude-Code-style docs you are reading, now live at bilal-junaid-jiwani.github.io/okfsmith via GitHub Pages.

[0.2.0] — 2026-09-26

Added

  • okfsmith doctor — environment check covering dependencies, optional extras, Ollama reachability, and API-key status (keys are always reported as set (hidden), never echoed).
  • --format json output for list, read, validate, and graph for scripting and CI.
  • --dry-run for ingest — parse and plan without writing anything.
  • Shell completion via okfsmith --install-completion / --show-completion, plus a man page.
  • Progress bars for long ingests.

Fixed

  • Graph viewer (viz.html) pointer-event bug — click and drag now work in the interactive visualization.
  • README/CLI help-text mismatches — documented commands and flags now match the real CLI exactly.

Security

  • Link containment in ingested content.
  • Zip-bomb guards on archive inputs.
  • Symlink skipping during directory ingestion.
  • Fixed a HIGH-severity CVE in the MarkItDown dependency.

Upgrade notes

Upgrade with pip install --upgrade okfsmith. No bundle migration is needed — bundles created by earlier versions validate unchanged. okfsmith search, okfsmith get, and okfsmith completions were never CLI commands (search/get are MCP tools and chat slash commands; completion uses --install-completion).