<p align="center">
  <img src="https://raw.githubusercontent.com/weiiiii0622/llm-wiki-skills/main/media/icon.png" alt="llm-wiki-skills icon" width="144">
</p>

<h1 align="center">llm-wiki-skills</h1>

<p align="center">
  Local-first wiki skills for Codex and Claude Code.
  <br>
  Turn scattered project notes into a durable, source-grounded knowledge vault your agent can maintain and browse on the web.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/llm-wiki-skills"><img src="https://img.shields.io/npm/v/llm-wiki-skills?color=111827" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/llm-wiki-skills"><img src="https://img.shields.io/npm/dm/llm-wiki-skills?color=2563eb" alt="npm downloads"></a>
  <a href="https://github.com/weiiiii0622/llm-wiki-skills/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/weiiiii0622/llm-wiki-skills/release.yml?style=flat-square&logo=githubactions&label=release" alt="release status"></a>
  <img src="https://img.shields.io/node/v/llm-wiki-skills?style=flat-square&logo=nodedotjs" alt="Node.js version">
  <img src="https://img.shields.io/badge/Obsidian-compatible-7c3aed?style=flat-square&logo=obsidian" alt="Obsidian compatible">
  <img src="https://img.shields.io/badge/OKF-compatible-4285f4?style=flat-square&logo=google&logoColor=white" alt="OKF compatible">
  <a href="https://github.com/weiiiii0622/llm-wiki-skills/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/llm-wiki-skills?color=0f766e" alt="license"></a>
</p>

```sh
npx llm-wiki-skills init
```

## 🧠 Why This Exists

AI agents are useful until they forget the context you gave them last week. `llm-wiki-skills` gives them a local place to preserve what they learn:

| Before 😵 | After ✅ |
| --- | --- |
| Notes, PDFs, meeting docs, and decisions live in scattered files. | Sources stay in `raw/`, durable knowledge lands in `wiki/`, and agents know how to update it. |
| Every session starts with "read these files again." | Codex or Claude Code can ingest, query, and lint the same local vault. |
| Search depends on whatever the model happens to load. | Markdown stays canonical, with optional local qmd search acceleration. |

## ✨ Key Features

- 🤖 **Agent-native:** installs skills for Codex and Claude Code, not just docs for humans.
- 🏠 **Local-first:** no hosted memory service, no remote database, no required account.
- 📎 **Source-grounded:** raw evidence and synthesized wiki pages stay separate.
- 📦 **OKF-compatible:** new vaults are OKF v0.1 bundles with a root index, log, and concept-page metadata.
- 🧩 **Custom-format markdown conversion:** convert PDF, DOCX, PPTX, XLSX, XLS, HTML, HTM, EPUB, PNG, JPG, JPEG, WEBP, TIF, TIFF, and BMP files into markdown during ingest planning when Marker is installed.
- 🗂️ **Topic-aware:** choose a scaffold for research, product work, trips, investing, medical notes, legal/admin records, and more.
- 🌐 **Web-only graph atlas:** visualize, search, and read your wiki in a browser. Obsidian is optional, not required.
- 🚢 **Static deploy:** export the atlas as plain web assets for GitHub Pages, Netlify, Vercel, or any static host.
- 🔎 **QMD search:** optional `qmd` support adds local SQLite-backed hybrid search while markdown remains the source of truth.

## 🚀 Getting Started

### ⚡ 1. `npx` (Recommended)
Run the setup wizard in any repo or markdown workspace:

```sh
npx llm-wiki-skills init
```

The wizard asks which agent host to install, which topic scaffold to use, and whether to prepare the folder as an Obsidian vault.

For a non-interactive Codex setup:

```sh
npx llm-wiki-skills init --host codex --topic product-builder
```

Common flags:

| Flag | Use it when |
| --- | --- |
| `--host codex` | Install Codex repo skills under `.agents/skills/`. |
| `--host claude-code` | Install Claude Code project skills under `.claude/skills/`. |
| `--topic work-project` | Add topic directories and routing guidance. |
| `--obsidian` / `--no-obsidian` | Enable or skip Obsidian vault metadata. |
| `--qmd` | Add optional local qmd search support. |
| `--json` / `--quiet` | Use in scripts or CI. |

### 📦 2. Global `npm` install

```sh
npm install -g llm-wiki-skills
llm-wiki-skills init
```

Then check the install:

```sh
npx llm-wiki-skills status
```

<p align="center">
  <img src="https://raw.githubusercontent.com/weiiiii0622/llm-wiki-skills/main/media/llm-wiki-skills-installation.gif" alt="Installing llm-wiki-skills and creating a local wiki vault" width="720">
</p>

## 🛠️ Installation

Use it directly with `npx`:

```sh
npx llm-wiki-skills init
```

Or install it globally:

```sh
npm install -g llm-wiki-skills
llm-wiki-skills init
```

Requirements:

- Node.js 22 or newer.
- Codex or Claude Code if you want an agent to use the generated skills.
- Obsidian is optional. The web UI can visualize the wiki by itself.
- A project folder or markdown vault where local files can be created.

#### 🤖 Non-interactive installation supported

```sh
npx llm-wiki-skills init --host codex --topic product-builder
```

Common flags:

| Flag | Use it when |
| --- | --- |
| `--host codex` | Install Codex repo skills under `.agents/skills/`. |
| `--host claude-code` | Install Claude Code project skills under `.claude/skills/`. |
| `--topic work-project` | Add topic directories and routing guidance. |
| `--obsidian` / `--no-obsidian` | Enable or skip Obsidian vault metadata. |
| `--qmd` | Add optional local qmd search support. |
| `--json` / `--quiet` | Use in scripts or CI. |

## 🧭 Usage

### 🤖 Ask Your Agent to Use the Wiki

After setup, use the installed skills in your agent:

```text
Use the llm-wiki-ingest skill. Ingest raw/sources/customer-notes.md
into the wiki and update any overlapping pages.
```

```text
Use the llm-wiki-query skill. What do we know about onboarding friction?
Cite the wiki pages you used.
```

```text
Use the llm-wiki-lint skill. Find stale claims, contradictions,
or missing cross-references before handoff.
```

### 🌐 Open or Deploy the Web UI

The web UI is web-only: it lets you inspect the wiki graph in a browser and does not require Obsidian.

Run locally:

```sh
npx llm-wiki-skills web serve --root .
```

By default this serves the atlas at `http://127.0.0.1:3678/`. Assign a custom port when needed:

```sh
npx llm-wiki-skills web serve --root . --port 4000
```

Build for remote deploy:

```sh
npx llm-wiki-skills web build --root . --out dist/atlas
```

Then upload `dist/atlas` to any static web host. The export includes the graph, search index, page content, and diagnostics needed by the browser UI.

<p align="center">
  <img src="https://raw.githubusercontent.com/weiiiii0622/llm-wiki-skills/main/media/llm-wiki-skills-webui.png" alt="llm-wiki-skills web UI" width="720">
</p>

### 📋 Plan Larger Ingests

For bigger raw folders, create a batch plan first:

```sh
npx llm-wiki-skills ingest plan --raw raw/sources
npx llm-wiki-skills ingest converters status
npx llm-wiki-skills ingest status --plan PLAN_ID
npx llm-wiki-skills ingest validate --plan PLAN_ID
```

The ingest commands help track source files before your agent synthesizes them into wiki pages. PDF, DOCX, PPTX, and other Marker-supported raw files are converted to markdown by default when Marker is installed. Marker is an external Python/PyTorch tool and is not bundled with this MIT-licensed npm package; install it separately if you want multimedia conversion.

Ingest plans, converted markdown, and converted assets are written under `.llm-wiki-skills/ingest-plans/`, outside `wiki/` so the wiki stays focused on durable knowledge. Source summaries should read converted markdown when present, but still cite the original `raw/` path and SHA-256 from the plan.

When a source is marked `merged`, the CLI moves the raw file into `raw/archieved/` and keeps the original raw path plus SHA-256 in the ingest plan for provenance. Future ingest plans skip everything under `raw/archieved/`, including when scanning `--raw raw`.

For best results, ask your AI agent to handle this workflow. The installed skills tell the agent when to use these commands.

## 🔁 Example Workflow

```text
1. Drop source material into raw/sources/
2. Ask the agent to use llm-wiki-ingest
3. The agent handles the ingest workflow automatically
4. The agent writes source summaries and durable wiki pages
5. Ask questions with llm-wiki-query
6. Run llm-wiki-lint before important handoffs
```

A small demo vault is included at [`fixtures/demo-vault`](fixtures/demo-vault). Use it to inspect the expected shape before initializing your own workspace.

## 🗂️ Topic Vault Structure

Every vault starts with the same simple contract:

```text
raw/                         preserved source material
wiki/                        durable markdown knowledge
docs/llm-wiki-contract.md    local wiki rules
docs/llm-wiki-workflows.md   ingest/query/lint workflow reference
.obsidian/                   optional Obsidian vault settings
.llm-wiki-skills.json        install manifest for status checks
.llm-wiki-skills/            CLI-owned ingest plans and converted intermediates
```

Topic scaffolds add useful `wiki/` categories and a routing guide at `docs/llm-wiki-routing.md`.

| Topic 🗂️ | Best for | Example categories |
| --- | --- | --- |
| `general` | Mixed notes and broad research | projects, areas, resources, questions |
| `study-research` | Papers, courses, experiments | concepts, papers, methods, datasets |
| `work-project` | Delivery context and team knowledge | architecture, decisions, meetings, risks |
| `product-builder` | Customer evidence and product bets | personas, problems, competitors, metrics |
| `writing-content` | Essays, drafts, editorial research | audience, topics, claims, outlines |
| `trip-plan` | Travel planning and bookings | destinations, hotels, transport, itinerary |
| `investment` | Research, theses, watchlists | companies, valuation, catalysts, postmortems |
| `home-life` | Household systems and records | maintenance, purchases, utilities, documents |
| `medical` | Clinical study notes and references | conditions, diagnostics, drugs, guidelines |
| `legal-admin` | Contracts, deadlines, admin records | matters, obligations, agencies, contacts |
| `custom` | Anything else | starts from `general` plus your custom label |

Example:

```sh
npx llm-wiki-skills init --host codex --topic study-research
```

Creates a research-friendly vault like:

```text
wiki/
|-- concepts/
|-- papers/
|-- methods/
|-- datasets/
|-- claims-and-evidence/
`-- templates/
```

## 🔎 qmd Search Support

qmd is optional and off by default. Enable it when your wiki is large enough that local hybrid search is useful:

```sh
npx llm-wiki-skills init --host codex --qmd
npx llm-wiki-skills qmd status
npx llm-wiki-skills qmd reindex
```

Markdown under `wiki/` remains canonical. qmd is only used for local candidate discovery.

## ✅ What This Is / Is Not

| ✅ This is | 🚫 This is not |
| --- | --- |
| A local installer for agent wiki workflows. | A hosted memory service. |
| A way to keep raw evidence and durable knowledge organized. | A replacement for reviewing source material. |
| A bridge between markdown vaults, Codex, Claude Code, the web atlas, and optional Obsidian. | A full note-taking app or automatic importer. |
| Optional local search acceleration through qmd. | A required cloud search backend. |
