# okfsmith

> Python CLI that converts messy documents (PDFs, markdown, wiki dumps,
> Notion exports) into OKF v0.2 knowledge bundles. Apache-2.0. Python 3.10+.

## Docs

- [Documentation index](docs/index.md): map of all guides
- [Install](docs/install.md): PyPI, extras (office/mcp/ocr/test), pipx/uvx, shell completion, `okfsmith doctor`
- [Quickstart](docs/quickstart.md): init → ingest --no-llm → validate → graph --format html
- [Commands](docs/commands.md): full CLI reference. Bundle is always the first positional argument. Exit 0/1/2 contract; `error [CODE]:` messages; JSON modes.
- [Pipeline](docs/pipeline.md): ingest stages (collect → parse → section → extract → write → index/log); trust tiers (unverified / machine-confirmed / human-reviewed); SHA-256 dedup; provenance
- [Parsing](docs/parsing.md): LiteParse (PDF, offline), MarkItDown office extra, Docling OCR sidecar, Notion exports, ZipSlip-safe zip handling
- [LLM & no-LLM](docs/llm.md): --no-llm drafts; Ollama default; OKFSMITH_MODEL / OPENAI_API_KEY env vars; llm-unavailable behavior
- [Validation](docs/validation.md): OKF §11 rules E001–E004 (errors), W001–W015 (warnings), --strict, JSON report schema
- [MCP](docs/mcp.md): `okfsmith mcp BUNDLE` transports (stdio/sse/streamable-http); tools (index/list/search/get/neighbors); client configs for Claude/Cursor/VS Code/Gemini
- [Skill pack](docs/skill.md): skills/okfsmith-build/SKILL.md — scope and non-goals
- [Troubleshooting](docs/troubleshooting.md): slice-not-installed, llm-unavailable, not-a-bundle, E001/W001/W002 fixes
- [FAQ](docs/faq.md): OKF, offline guarantees, license, no-lock-in
- [Architecture overview](docs/OVERVIEW.md): eight-stage pipeline map

## Commands (grammar)

```
okfsmith init BUNDLE [--force] [--yes]
okfsmith ingest BUNDLE SOURCE... [--recursive] [--no-llm] [--model NAME] [--dry-run] [--quiet]
okfsmith validate BUNDLE [--format text|json] [--strict]
okfsmith list BUNDLE [--format text|json] [--tier unverified|machine-confirmed|human-reviewed]
okfsmith read BUNDLE CONCEPT_ID [--format text|json]
okfsmith graph BUNDLE [--format text|json|mermaid|html] [--output FILE]
okfsmith mcp BUNDLE [--transport stdio|sse|streamable-http]
okfsmith doctor
```

## Facts for agents

- A bundle is plain markdown + YAML frontmatter; concept id = path without `.md`.
- Only `type` is required in frontmatter (OKF §11.2).
- `validate` exit 0 = conformant; `--strict` turns warnings into failures.
- Sources under 1000 chars are skipped on ingest (stub prevention).
- Repos: https://github.com/Bilal-Junaid-Jiwani/okfsmith · PyPI: https://pypi.org/project/okfsmith/
- Spec: https://github.com/GoogleCloudPlatform/open-knowledge-format (OKF v0.2)
