Metadata-Version: 2.4
Name: llm-wiki-tools
Version: 0.3.0
Summary: CLI tools to read and manage LLM Wiki projects on GitHub
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markitdown>=0.1.0
Provides-Extra: vision
Requires-Dist: anthropic>=0.25.0; extra == "vision"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# wiki-tools

CLI tools to read and manage LLM Wiki projects on GitHub.

Two commands:
- **`wiki-read`** — read wiki pages from GitHub. Used by Claude Code agents during development.
- **`wiki-manage`** — generate, update, and lint the wiki. Used in the wiki repo.

**No MCP server. No extra infrastructure. Just Python + GitHub API.**

---

## How it works

```
local disk                        GitHub
──────────────────────────────    ──────────────────────
wiki-repo/
  raw/       ──── wiki-manage ──► wiki-repo/wiki/
  updates/        generate
                  update
                                  wiki-read ◄─── Claude Code
                                  (any project repo)
```

- `raw/` and `updates/` live **locally** — never pushed to GitHub
- `wiki/` lives **on GitHub** — the permanent, versioned knowledge base
- `wiki-read` reads from GitHub and is available in any project repo
- `wiki-manage` reads locally and writes to GitHub, used only in the wiki repo

---

## Install

```bash
pip install llm-wiki-tools
```

For image vision support (optional):

```bash
pip install "llm-wiki-tools[vision]"
```

Or directly from GitHub:

```bash
pip install git+https://github.com/YOUR_USERNAME/wiki-tools.git
```

---

## Requirements

**Python 3.10+**

**GitHub token** — create one at https://github.com/settings/tokens with `repo` scope, then add it to your shell profile:

```bash
# ~/.zshrc or ~/.bashrc
export GITHUB_TOKEN=ghp_yourtoken
```

---

## Repository structure

### Wiki repo — where the wiki lives

```
wiki-my-project/          ← cloned locally
  .project                ← includes wiki_local_path
  raw/                    ← original documents (local only, not on GitHub)
  updates/                ← new documents to ingest (local only, not on GitHub)
  CLAUDE.md
```

```
github: username/wiki-my-project
  wiki/                   ← generated markdown pages (GitHub only)
```

`.gitignore` in the wiki repo:
```
raw/
updates/
```

### Project repo — where you write code

```
my-project/
  .project                ← wiki_repo only, no wiki_local_path needed
  CLAUDE.md
  src/
```

---

## .project format

**In the wiki repo** — needs both `wiki_repo` and `wiki_local_path`:

```json
{
  "project_id": "my-project",
  "wiki_repo": "username/wiki-my-project",
  "wiki_local_path": "/Users/yourname/projects/wiki-my-project"
}
```

**In the project repo** — only needs `wiki_repo`:

```json
{
  "project_id": "my-project",
  "wiki_repo": "username/wiki-my-project"
}
```

The tools walk up from the current directory to find `.project`, so they work from any subdirectory.

---

## Commands

### wiki-read

```bash
wiki-read index              # read a page (with or without .md)
wiki-read architecture
wiki-read --list             # list all wiki pages
wiki-read --search "auth"   # full-text search across pages
wiki-read --info             # show current project, repo, and local path
```

Reads from GitHub. Works in any repo that has a `.project` file.

### wiki-manage

```bash
wiki-manage status             # show file counts for raw/ (local), updates/ (local), wiki/ (github)
wiki-manage generate           # read local raw/, generate wiki pages on GitHub
wiki-manage update             # read local updates/, update wiki on GitHub, move files to raw/
wiki-manage delete <page>      # delete a wiki page from GitHub
wiki-manage lint               # check for broken links, orphan pages, missing required pages
```

Reads from local disk, writes to GitHub. Requires `wiki_local_path` in `.project`.

> **Note on deletions:** updating a document in `updates/` automatically removes sections that no longer exist — Claude rewrites the affected pages based on the new content. Use `wiki-manage delete` only when an entire page becomes obsolete.

---

## Workflows

### Generate wiki from scratch

1. Put your documents in `raw/` locally
2. Open Claude Code in the wiki repo
3. Tell Claude: *"Generate the wiki from raw/ using wiki-manage generate"*

Claude runs `wiki-manage generate`, reads the raw files, generates wiki pages, and writes them to GitHub.

### Ingest new documents

1. Put new documents in `updates/` locally
2. Open Claude Code in the wiki repo
3. Tell Claude: *"Update the wiki with the new documents in updates/"*

Claude runs `wiki-manage update`, reads the updates, updates the relevant wiki pages on GitHub, updates `changelog.md`, then moves the files from `updates/` to `raw/` locally.

### Lint

Tell Claude: *"Run a lint on the wiki and fix any issues"*

Claude runs `wiki-manage lint` and fixes broken links, orphan pages, and missing required pages.

### Read wiki during development

In any project repo, Claude Code agents can read the wiki via `bash`:

```bash
wiki-read index
wiki-read decisions
wiki-read --search "payment"
```

---

## Required wiki pages

Only two pages are always required:

| Page | Content |
|---|---|
| `index.md` | Entry point — links to every other page |
| `changelog.md` | Chronological log of every wiki update |

All other pages are dynamic and determined by the project content. `index.md` is the source of truth for which pages exist.

---

## CLAUDE.md

Add this to the `CLAUDE.md` in every repo to tell Claude which tools are available and how to use them.

**Wiki repo:**

```markdown
## Wiki tools

Read the wiki:
  wiki-read <page>
  wiki-read --list
  wiki-read --search <query>

Manage the wiki (requires wiki_local_path in .project):
  wiki-manage status
  wiki-manage generate
  wiki-manage update
  wiki-manage lint

Always start with `wiki-read index` to orient yourself.
After every update, add an entry to changelog.md.
```

**Project repo:**

```markdown
## Wiki tools

Read the project wiki with:
  wiki-read <page>
  wiki-read --list
  wiki-read --search <query>

Always read `wiki-read index` at the start of every session.
```

---

## Publish a new version to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

Bump the version in `pyproject.toml` before each release.
