VectifyAI
diff --git a/‎README.md‎
Lines changed: 23 additions & 155 deletions b/‎README.md‎
Lines changed: 23 additions & 155 deletions
diff --git a/‎examples/README.md‎
Lines changed: 44 additions & 0 deletions b/‎examples/README.md‎
Lines changed: 44 additions & 0 deletions
diff --git a/‎examples/chat/README.md‎
Lines changed: 92 additions & 0 deletions b/‎examples/chat/README.md‎
Lines changed: 92 additions & 0 deletions
@@ -97,8 +97,10 @@ openkb query "What are the main findings?"
 # 5. Or chat interactively
 openkb chat
 
-# (Optional) Distill a redistributable agent skill from your wiki
-openkb skill new my-expert "Reason like an expert on <your-topic>"
+# (Optional) Turn the wiki into other outputs
+openkb skill new my-expert "Reason like an expert on <your-topic>"   # a portable agent skill
+openkb visualize                                                     # an interactive knowledge graph
+openkb deck new my-deck "An intro deck on <your-topic>"              # slides — a single-file HTML deck
 ```
 
 ### Set up your LLM
@@ -171,7 +173,7 @@ A single source might touch 10--15 wiki pages. Knowledge accumulates: each docum
 
 # ⚙️ Usage
 
-OpenKB commands fall into two layers: the **wiki foundation** (compile + manage your knowledge) and **generators** (turn that wiki into useful output).
+OpenKB commands fall into two layers: the **wiki foundation** (compile + manage your knowledge) and **generators** (turn that wiki into useful output). Each links to a concrete walkthrough — a real artifact OpenKB generated from one sample paper (browse them all in [`examples/`](examples/)).
 
 ## Layer 1: 🧱 Wiki Foundation — compile and maintain
 
@@ -194,189 +196,53 @@ OpenKB commands fall into two layers: the **wiki foundation** (compile + manage
 | <code>openkb&nbsp;recompile&nbsp;[&lt;doc&gt;]&nbsp;[--all]</code> | Re-run the compile pipeline on already-indexed docs without re-indexing. Regenerates summaries and rewrites concept pages; manual edits are overwritten (`--dry-run` to preview, `--refresh-schema` to also update `wiki/AGENTS.md`) |
 | <code>openkb&nbsp;feedback&nbsp;["msg"]</code> | File feedback by opening a prefilled GitHub issue (`--type bug/feature/question` to tag it) |
 
-<!-- | `openkb lint --fix` | Auto-fix what it can | -->
-
 </details>
 
+→ **Example:** the everyday loop walked through end to end — [`examples/commands/`](examples/commands/).
+
 ## Layer 2: 💡 Generators — turn the wiki into output
 
 A "generator" reads from the compiled wiki and produces something usable: an answer, a conversation, a skill folder. The wiki is the substrate; generators are the surfaces.
 
-| Command | Output |
-|---|---|
-| <code>openkb&nbsp;query&nbsp;"question"</code> | A grounded answer with citations (`--save` to persist to `wiki/explorations/`) |
-| <code>openkb&nbsp;chat</code> | Interactive multi-turn session over the wiki (`--resume`, `--list`, `--delete` to manage sessions) |
-| <code>openkb&nbsp;visualize</code> | A self-contained interactive knowledge graph at `output/visualize/graph.html` — 3D, mind-map, and radial views |
-| | |
-| <code>openkb&nbsp;skill&nbsp;new&nbsp;&lt;skill-name&gt;&nbsp;"&lt;intent&gt;"</code> | Distill a redistributable agent skill from your wiki (see [Skill Factory](#-skill-factory--drop-in-a-book-out-comes-a-digital-expert) below) |
+| Command | Output | Example |
+|---|---|---|
+| <code>openkb&nbsp;query&nbsp;"question"</code> | A grounded answer with citations (`--save` to persist to `wiki/explorations/`) | [query & save](examples/commands/) |
+| <code>openkb&nbsp;chat</code> | Interactive multi-turn session over the wiki (`--resume`, `--list`, `--delete` to manage sessions) | [chat](examples/chat/) |
+| <code>openkb&nbsp;visualize</code> | A self-contained interactive knowledge graph at `output/visualize/graph.html` — 3D, mind-map, and radial views | [visualize](examples/visualize/) |
+| <code>openkb&nbsp;skill&nbsp;new&nbsp;&lt;skill-name&gt;&nbsp;"&lt;intent&gt;"</code> | Distill a redistributable agent skill from your wiki (see [Skill Factory](#skill-factory) below) | [skills](examples/skills/) |
+| <code>openkb&nbsp;deck&nbsp;new&nbsp;&lt;name&gt;&nbsp;"&lt;intent&gt;"</code> | Generate a single-file HTML slide deck (`--skill` picks a theme, `--critique` runs a quality pass) | [slides](examples/slides/) |
 
 <details>
 <summary><i>More skill commands:</i></summary>
 <br>
 
 | Command | Output |
 |---|---|
-| <code>openkb&nbsp;skill&nbsp;validate&nbsp;[name]</code> | Validate compiled skills (YAML frontmatter, file sizes, wikilinks, scripts). Auto-runs at end of `skill new` (`--strict` to treat warnings as failures) |
-| <code>openkb&nbsp;skill&nbsp;eval&nbsp;&lt;name&gt;</code> | Trigger-accuracy evaluation: does the `description:` field actually fire? LLM generates eval prompts; grader LLM scores activation (`--save` persists the eval set) |
-| <code>openkb&nbsp;skill&nbsp;history&nbsp;&lt;name&gt;</code> / <code>openkb&nbsp;skill&nbsp;rollback&nbsp;&lt;name&gt;</code> | Version history for skills. Each overwrite saves the previous version to `iteration-N/` with a diff; rollback restores any iteration |
-
-</details>
-
-### (i) 💬 Query & Chat — *ask the wiki*
-
-`openkb query "..."` answers a single question. `openkb chat` is interactive — each turn carries history, so you can dig into a topic without re-typing context. Both use the same underlying wiki and retrieval primitives.
-
-```bash
-openkb query "What does the literature say about attention scaling?"
-
-openkb chat                       # start a new session
-openkb chat --resume              # resume the most recent session
-openkb chat --resume 20260411     # resume by id (unique prefix works)
-openkb chat --list                # list all sessions
-openkb chat --delete <id>         # delete a session
-```
-
-Inside a chat, type `/` to access slash commands (Tab to complete).
-
-<details>
-<summary><i>More slash commands:</i></summary>
-<br>
-
-- `/help` — list available commands
-- `/status` — show knowledge base status
-- `/list` — list all documents
-- `/add <path>` — add a document or directory without leaving the chat
-- `/skill new <skill-name> "<intent>"` — compile a skill from this chat (see below)
-- `/save [name]` — export the transcript to `wiki/explorations/`
-- `/clear` — start a fresh session (the current one stays on disk)
-- `/lint` — run knowledge base lint
-- `/exit` — exit (Ctrl-D also works)
+| <code>openkb&nbsp;skill&nbsp;validate&nbsp;[name]</code> | Validate compiled skills (auto-runs after `skill new`) |
+| <code>openkb&nbsp;skill&nbsp;eval&nbsp;&lt;name&gt;</code> | Check the skill triggers on the right prompts |
+| <code>openkb&nbsp;skill&nbsp;history&nbsp;&lt;name&gt;</code> / <code>openkb&nbsp;skill&nbsp;rollback&nbsp;&lt;name&gt;</code> | Version history + rollback for skills |
 
 </details>
 
 <a id="skill-factory"></a>
 
-### (ii) 🛠 Skill Factory — *drop in a book; out comes a digital expert.*
-
-The newest generator. `openkb skill new` distills an [agent skill](https://docs.claude.com/en/docs/build-with-claude/skills) from any subset of your wiki, a portable folder that major agents (Claude Code, Codex, etc.) can install and load natively. Drop in a book's worth of papers; out comes a specialist that other agents can call on.
-
-```bash
-openkb skill new karpathy-thinking \
-  "Reason about transformers and attention in Karpathy's style"
-```
-
-<details>
-<summary><i>Output:</i></summary>
-<br>
-
-```
-<kb>/output/skills/karpathy-thinking/
-├── SKILL.md                   # YAML frontmatter + when-to-use + approach
-├── references/                # depth material the agent loads on demand
-│   ├── methodology.md
-│   └── key-quotes.md
-└── (scripts/)                 # optional, only if intent implies computation
-```
-
-Plus an auto-updated `<kb>/.claude-plugin/marketplace.json` so the whole KB is one-line installable.
-
-</details>
-
-<details>
-<summary><i>Install locally:</i></summary>
-<br>
-
-```bash
-cp -r output/skills/karpathy-thinking ~/.claude/skills/
-```
-
-</details>
-
-<details>
-<summary><i>Share with others:</i></summary>
-<br>
-
-Push your KB to GitHub, then anyone runs:
-
-```bash
-npx skills@latest add <your-org>/<your-repo>
-```
-
-</details>
-
-<details>
-<summary><i>Iterate from chat:</i></summary>
-<br>
-
-Compilation is one-shot, but follow-up edits don't have to be. Inside `openkb chat`, you can refine without re-running the whole pipeline:
+### 🛠 Skill Factory — *drop in a book; out comes a digital expert.*
 
-```
-/skill new karpathy-thinking "Reason about transformers like Karpathy"
-[generation streams]
-> description is too generic, make it about transformer implementations specifically
-[agent edits SKILL.md frontmatter in place]
-```
-
-</details>
-
-<details>
-<summary><i>Quality gates:</i></summary>
-<br>
-
-Structural validation, trigger-accuracy + body-coverage evaluation, and full history/rollback:
-
-```bash
-# Lint structure (auto-runs at end of `skill new`)
-openkb skill validate karpathy-thinking
-openkb skill validate --strict          # treat warnings as failures
-
-# Does the description actually fire when it should?
-openkb skill eval karpathy-thinking --save
-
-# History + rollback if a new iteration regresses
-openkb skill history karpathy-thinking
-openkb skill rollback karpathy-thinking --to 2
-```
-
-</details>
-
-### (iii) 🗺 Visualize — *see the shape of your knowledge*
-
-`openkb visualize` renders the wiki as a single self-contained, offline HTML page with three views of the same knowledge base — a **3D** force graph, an OpenKB-rooted **mind-map**, and a **radial** tree — coloured by type and linked by `[[wikilinks]]`.
-
-```bash
-openkb visualize            # build + open output/visualize/graph.html
-```
+The flagship generator: `openkb skill new` distills a portable [agent skill](https://docs.claude.com/en/docs/build-with-claude/skills) from your wiki that Claude Code, Codex, and Gemini can install and load natively. Drop in a book's worth of papers; out comes a specialist other agents can call on. → A real generated skill, plus install / share / `eval` / rollback, is walked through in **[`examples/skills/`](examples/skills/)**.
 
 # 🔧 Configuration
 
 ### Settings
 
-OpenKB settings are initialized by `openkb init` and stored in `.openkb/config.yaml`:
+`openkb init` writes `.openkb/config.yaml`:
 
 ```yaml
 model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 ```
 
-Model names use `provider/model` LiteLLM [format](https://docs.litellm.ai/docs/providers) (OpenAI models can omit the prefix):
-
-| Provider | Model example |
-|---|---|
-| OpenAI | `gpt-5.4` |
-| Anthropic | `anthropic/claude-sonnet-4-6` |
-| Gemini | `gemini/gemini-3.1-pro-preview` |
-
-<details>
-<summary><i>Advanced options (<code>entity_types</code>, OAuth):</i></summary>
-<br>
-
-`entity_types` (optional): a YAML list overriding the entity-type vocabulary used for entity pages; omit it to use the default `person`, `organization`, `place`, `product`, `work`, `event`, `other`.
-
-Subscription-based providers that authenticate via OAuth device flow (e.g. `chatgpt/*`, `github_copilot/*`) need no API key; OpenKB skips the missing-key warning for them.
-
-</details>
+The full settings reference — `entity_types`, OAuth providers (`chatgpt/*`, `github_copilot/*`), and LiteLLM tuning (timeouts for slow local runtimes like Ollama / LM Studio, `drop_params`, GitHub Copilot headers, install notes) — is in **[`examples/configuration/`](examples/configuration/)**.
 
 ### PageIndex Setup
 
@@ -398,6 +264,8 @@ Set `PAGEINDEX_API_KEY` in your `.env` to enable cloud features:
 PAGEINDEX_API_KEY=your_pageindex_api_key
 ```
 
+→ **Example:** local vs. cloud indexing, and importing a cloud-indexed doc — [`examples/pageindex-cloud/`](examples/pageindex-cloud/).
+
 ### AGENTS.md
 
 The `wiki/AGENTS.md` file defines wiki structure and conventions. It's the LLM's instruction manual for maintaining the wiki. Customize it to change how your wiki is organized.
 
@@ -0,0 +1,44 @@
+# OpenKB examples
+
+Hands-on, organized by use case. Each folder is one case — a short walkthrough
+plus the **real artifact** OpenKB produced for it (generated, not hand-written).
+
+> **Test inputs** live in [`docs/`](docs/) — the sample PDFs the cases ingest.
+> They're kept out of git on purpose (large / third-party files); drop your own
+> documents there to follow along.
+
+## Cases
+
+| Folder | What it shows | Real artifact inside |
+| --- | --- | --- |
+| [`configuration/`](configuration/) | `init`, `config.yaml`, API keys, LiteLLM tuning (Ollama, Copilot) | — |
+| [`commands/`](commands/) | the everyday loop: `add` · `query` · `remove` · `recompile` · `lint` · `list` · `status` | a compiled [`sample-wiki/`](commands/sample-wiki/) |
+| [`pageindex-cloud/`](pageindex-cloud/) | long documents: local vs. cloud indexing, and importing cloud-indexed docs | — |
+| [`chat/`](chat/) | the interactive REPL: persistent sessions + slash commands | — |
+| [`skills/`](skills/) | distill a redistributable agent skill from your wiki | [`transformer-attention/SKILL.md`](skills/transformer-attention/SKILL.md) |
+| [`slides/`](slides/) | generate a single-file HTML slide deck | [`attention-intro.html`](slides/attention-intro.html) |
+| [`visualize/`](visualize/) | render the wiki as an interactive knowledge graph | [`graph.html`](visualize/graph.html) |
+
+## It's all from one paper
+
+The compiled `sample-wiki/`, the skill, the deck, and the graph were **all**
+generated by running OpenKB over a single document —
+[`docs/attention-is-all-you-need.pdf`](docs/attention-is-all-you-need.pdf) — with
+`gpt-5.4`:
+
+```bash
+mkdir my-kb && cd my-kb
+openkb init --model gpt-5.4 --language en
+
+openkb add /path/to/examples/docs/attention-is-all-you-need.pdf   # → commands/sample-wiki/
+openkb query "How does attention replace recurrence?" --save      # → commands/sample-wiki/explorations/
+openkb skill new transformer-attention "Reason about the Transformer…"  # → skills/
+openkb deck new attention-intro "A short intro deck on the Transformer…" # → slides/
+openkb visualize                                                  # → visualize/
+```
+
+Your generated text will differ run to run (LLM output isn't deterministic) — the
+*structure* is what's stable.
+
+New to OpenKB? Read [`configuration/`](configuration/) first, then
+[`commands/`](commands/).
@@ -0,0 +1,92 @@
+# Chat TUI
+
+`openkb chat` is an interactive REPL over your wiki. Unlike `query` (one-shot), a
+chat session keeps context across turns, can edit the KB through slash commands,
+and is saved so you can resume it later.
+
+```bash
+openkb chat
+```
+
+```text
+OpenKB Chat
+~/research-kb · anthropic/claude-sonnet-4-6 · session 20260625-143022-a1x
+Type /help for commands, Ctrl-D to exit, Ctrl-C to abort the current response.
+
+>>> How do the two papers differ on their use of attention?
+Both rely on scaled dot-product attention, but…
+  · read_wiki_file(path="concepts/self-attention.md")
+  · read_wiki_file(path="summaries/deepseek-r1.md")
+
+>>> /save attention-comparison
+Saved to wiki/explorations/attention-comparison-20260625.md
+```
+
+Answers are grounded in your wiki: the agent reads `concepts/`, `summaries/`,
+`entities/`, and source files, and shows the tool calls it makes. Responses render
+as rich Markdown (headings, tables, code) in a terminal.
+
+---
+
+## Persistent sessions
+
+Every conversation is stored as JSON in `<kb>/.openkb/chats/`. Manage them with:
+
+```bash
+openkb chat --list              # table of sessions: id · turns · updated · title
+openkb chat --resume            # resume the most recent session
+openkb chat --resume 20260625   # resume by id or unique prefix
+openkb chat --delete 20260625   # delete a session
+```
+
+Resuming replays the last few turns so you have context:
+
+```text
+$ openkb chat --resume
+Resumed session · 4 turn(s)
+[3] >>> How do the two papers differ on their use of attention?
+[3]     Both rely on scaled dot-product attention, but…
+[4] >>> /save attention-comparison
+```
+
+---
+
+## Slash commands
+
+Inside the REPL, lines starting with `/` are commands rather than questions. Run
+`/help` to see the current set; the built-ins are:
+
+| Command | What it does |
+| --- | --- |
+| `/help` | List available commands |
+| `/exit`, `/quit` | Leave the REPL (Ctrl-D also works) |
+| `/clear` | Start a fresh session (the previous one is saved) |
+| `/save [name]` | Export the transcript to `wiki/explorations/<name>-<date>.md` |
+| `/status` | Show KB status without leaving chat |
+| `/list` | List documents in the KB |
+| `/lint` | Run the integrity + knowledge lint |
+| `/add <path>` | Ingest a file or directory (Tab-completes paths) |
+| `/skill new <name> "<intent>"` | Compile a skill from the wiki — see [`skills/`](../skills/) |
+| `/deck new [--critique] [--skill <name>] <name> "<intent>"` | Generate an HTML deck — see [`slides/`](../slides/) |
+| `/critique <path>` | Run the HTML critic over an existing deck/page |
+
+Slash commands run inline — errors are reported and the conversation continues;
+Ctrl-C aborts the running command without ending the session.
+
+### Why slash commands matter
+
+They turn chat into a workbench: ask a question, realize you're missing a source,
+`/add` it, and keep going — all in one session. Because the chat agent can write
+to `wiki/explorations/**` and `output/**`, asking it to "write that up as a note"
+or "turn this into a skill" produces real files you keep.
+
+---
+
+## Plain output for piping or logs
+
+```bash
+openkb chat --no-color     # disable colored output entirely
+openkb chat --raw          # show raw Markdown source, keep prompt/tool colors
+```
+
+`--no-color` also respects the `NO_COLOR` environment variable.