fix: bug fixes and README revamp

Author: rejojer

README.md

@@ -1,36 +1,40 @@
 <div align="center">
 
-# OpenKB
+<a href="https://openkb.ai">
+  <img src="https://docs.pageindex.ai/images/general/openkb.png" alt="OpenKB (by PageIndex)" />
+</a>
 
-### Karpathy's LLM Knowledge Base — as a CLI
+# OpenKB (Open Knowledge Base)
 
-**Drop documents in. Get an auto-maintained, cross-linked wiki out.**
+<h3 align="center">LLM-Powered Wiki Knowledge Base</h3>
 
-[Getting Started](#getting-started) · [How It Works](#how-it-works) · [Commands](#commands) · [Configuration](#configuration)
+<p align="center"><i>Scale to long documents&nbsp; ◦ &nbsp;Reasoning-based retrieval&nbsp; ◦ &nbsp;Native multimodality support&nbsp; ◦ &nbsp;No Vector DB</i></p>
 
 </div>
 
 ---
 
+# 📑 Introduction to OpenKB
+
 Andrej Karpathy [described](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) a workflow where LLMs compile raw documents into a structured, interlinked markdown wiki — summaries, concept pages, cross-references — all maintained automatically. Knowledge compounds over time instead of being re-derived on every query.
 
-**OpenKB** is an open-source CLI that implements this workflow, powered by [PageIndex](https://github.com/VectifyAI/PageIndex) for long document understanding and [markitdown](https://github.com/microsoft/markitdown) for broad format support.
+**OpenKB** (Open Knowledge Base) is an open-source CLI that implements this workflow, powered by [PageIndex](https://github.com/VectifyAI/PageIndex) for long document understanding and [markitdown](https://github.com/microsoft/markitdown) for broad format support.
 
 ### Why not just RAG?
 
 RAG rediscovers knowledge from scratch on every query. Nothing accumulates. OpenKB compiles knowledge once into a persistent wiki, then keeps it current. Cross-references already exist. Contradictions are flagged. Synthesis reflects everything consumed.
 
-## Features
+### Features
 
-- **Any format** — PDF, Word, PowerPoint, Excel, HTML, Markdown, and more via markitdown
+- **Any format** — PDF, Word, PowerPoint, Excel, HTML, Markdown, text, CSV, and more via markitdown
 - **Long documents** — Books and reports that exceed LLM context windows are handled via [PageIndex](https://github.com/VectifyAI/PageIndex) tree indexing
 - **Auto wiki** — LLM generates summaries, concept pages, and cross-links. You curate sources; the LLM does the rest
 - **Query** — Ask questions against your wiki. The LLM navigates your compiled knowledge to answer
 - **Lint** — Health checks find contradictions, gaps, orphans, and stale content
 - **Watch mode** — Drop files into `raw/`, wiki updates automatically
 - **Obsidian compatible** — Wiki is plain `.md` files with `[[wikilinks]]`. Open in Obsidian for graph view and browsing
 
-## Getting Started
+# 🚀 Getting Started
 
 ### Install
 
@@ -67,7 +71,7 @@ OPENAI_API_KEY=sk-...
 
 OpenKB uses [LiteLLM](https://docs.litellm.ai/docs/providers) — any provider works. Set the model during `okb init` or edit `.okb/config.yaml`.
 
-## How It Works
+# 🧩 How It Works
 
 ```
 raw/                              You drop files here
@@ -116,7 +120,9 @@ When you add a document, the LLM:
 
 A single source might touch 10-15 wiki pages. Knowledge accumulates — each document enriches the existing wiki rather than sitting in isolation.
 
-## Commands
+# 📦 Usage
+
+### Commands
 
 | Command | Description |
 |---|---|
@@ -126,11 +132,11 @@ A single source might touch 10-15 wiki pages. Knowledge accumulates — each doc
 | `okb query "question" --save` | Ask and save the answer to `wiki/explorations/` |
 | `okb watch` | Watch `raw/` and auto-compile new files |
 | `okb lint` | Run structural + knowledge health checks |
-| `okb lint --fix` | Auto-fix what it can |
+<!-- | `okb lint --fix` | Auto-fix what it can | -->
 | `okb list` | List indexed documents and concepts |
 | `okb status` | Show knowledge base stats |
 
-## Configuration
+### Configuration
 
 Generated by `okb init`, stored in `.okb/config.yaml`:
 
@@ -148,7 +154,7 @@ The `wiki/AGENTS.md` file defines wiki structure and conventions. It's the LLM's
 
 At runtime, the LLM reads `AGENTS.md` from disk — your edits take effect immediately.
 
-## Using with Obsidian
+### Using with Obsidian
 
 OpenKB's wiki is a directory of Markdown files with `[[wikilinks]]` — Obsidian renders it natively.
 
@@ -157,18 +163,20 @@ OpenKB's wiki is a directory of Markdown files with `[[wikilinks]]` — Obsidian
 3. Use graph view to see knowledge connections
 4. Use Obsidian Web Clipper to add web articles to `raw/`
 
-## Compared to Karpathy's Approach
+# 🔗 Learn More
+
+### Compared to Karpathy's Approach
 
 | | Karpathy's workflow | OpenKB |
 |---|---|---|
 | Short documents | LLM reads directly | markitdown → LLM reads |
 | Long documents | Doesn't fit in context | PageIndex tree index |
-| Supported formats | Web clipper → .md | PDF, Word, PPT, Excel, HTML, audio, .md |
+| Supported formats | Web clipper → .md | PDF, Word, PPT, Excel, HTML, text, CSV, .md |
 | Wiki compilation | LLM agent | LLM agent (same) |
 | Q&A | Query over wiki | Wiki + PageIndex retrieval |
 | Open source | No | Yes |
 
-## Tech Stack
+### Tech Stack
 
 - [PageIndex](https://github.com/VectifyAI/PageIndex) — Vectorless, reasoning-based document indexing
 - [markitdown](https://github.com/microsoft/markitdown) — Universal file-to-markdown conversion
@@ -177,10 +185,10 @@ OpenKB's wiki is a directory of Markdown files with `[[wikilinks]]` — Obsidian
 - [Click](https://click.palletsprojects.com/) — CLI framework
 - [watchdog](https://github.com/gorakhargosh/watchdog) — Filesystem monitoring
 
-## License
+### License
 
 Apache 2.0 — see [LICENSE](LICENSE)
 
-## Acknowledgments
+### Acknowledgments
 
 Inspired by [Andrej Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Powered by [PageIndex](https://pageindex.ai/).

…ples/docs/attention is all your need.pdf …mples/docs/attention-is-all-you-need.pdfexamples/docs/attention is all your need.pdf renamed to examples/docs/attention-is-all-you-need.pdf examples/docs/attention is all your need.pdf renamed to examples/docs/attention-is-all-you-need.pdf

@@ -20,7 +20,10 @@ def list_wiki_files(directory: str, wiki_root: str) -> str:
         Newline-separated list of ``.md`` filenames found in *directory*,
         or ``"No files found."`` if the directory is empty or does not exist.
     """
-    target = Path(wiki_root) / directory
+    root = Path(wiki_root).resolve()
+    target = (root / directory).resolve()
+    if not target.is_relative_to(root):
+        return "Access denied: path escapes wiki root."
     if not target.exists() or not target.is_dir():
         return "No files found."
 
@@ -40,7 +43,10 @@ def read_wiki_file(path: str, wiki_root: str) -> str:
     Returns:
         File contents as a string, or ``"File not found: {path}"`` if missing.
     """
-    full_path = Path(wiki_root) / path
+    root = Path(wiki_root).resolve()
+    full_path = (root / path).resolve()
+    if not full_path.is_relative_to(root):
+        return "Access denied: path escapes wiki root."
     if not full_path.exists():
         return f"File not found: {path}"
     return full_path.read_text(encoding="utf-8")
@@ -59,7 +65,10 @@ def write_wiki_file(path: str, content: str, wiki_root: str) -> str:
     Returns:
         ``"Written: {path}"`` on success.
     """
-    full_path = Path(wiki_root) / path
+    root = Path(wiki_root).resolve()
+    full_path = (root / path).resolve()
+    if not full_path.is_relative_to(root):
+        return "Access denied: path escapes wiki root."
     full_path.parent.mkdir(parents=True, exist_ok=True)
     full_path.write_text(content, encoding="utf-8")
     return f"Written: {path}"

openkb/agent/tools.py

@@ -280,14 +280,21 @@ def watch():
 
     def on_new_files(paths):
         for p in paths:
-            _add_single_file(Path(p), kb_dir)
+            fp = Path(p)
+            if fp.suffix.lower() not in SUPPORTED_EXTENSIONS:
+                click.echo(
+                    f"Skipping unsupported file type: {fp.suffix}. "
+                    f"Supported: {', '.join(sorted(SUPPORTED_EXTENSIONS))}"
+                )
+                continue
+            _add_single_file(fp, kb_dir)
 
     click.echo(f"Watching {raw_dir} for new documents. Press Ctrl+C to stop.")
     watch_directory(raw_dir, on_new_files)
 
 
 @cli.command()
-@click.option("--fix", is_flag=True, default=False, help="Automatically fix lint issues.")
+@click.option("--fix", is_flag=True, default=False, help="Automatically fix lint issues.")  # TODO: --fix not yet implemented
 def lint(fix):
     """Lint the knowledge base for structural and semantic inconsistencies."""
     kb_dir = _find_kb_dir()

openkb/cli.py

@@ -66,7 +66,7 @@ def convert_document(src: Path, kb_dir: Path) -> ConvertResult:
     raw_dir = kb_dir / "raw"
     raw_dir.mkdir(parents=True, exist_ok=True)
     raw_dest = raw_dir / src.name
-    if raw_dest != src:
+    if raw_dest.resolve() != src.resolve():
         shutil.copy2(src, raw_dest)
 
     # ------------------------------------------------------------------

openkb/converter.py

@@ -30,7 +30,7 @@
 - Explorations: name, one-liner description
 
 ## Log Format
-Each log entry: `## [YYYY-MM-DD] operation | description`
+Each log entry: `## [YYYY-MM-DD HH:MM:SS] operation | description`
 Operations: ingest, query, lint
 
 ## Format