Metadata-Version: 2.4
Name: llm-wiki-installer
Version: 0.1.7
Summary: Installer for LLM-native Obsidian Markdown knowledge vaults.
Author: llm-wiki contributors
Maintainer: llm-wiki-installer maintainers
License-Expression: MIT
Project-URL: Homepage, https://github.com/exhank/llm-wiki-installer
Project-URL: Repository, https://github.com/exhank/llm-wiki-installer
Project-URL: Issues, https://github.com/exhank/llm-wiki-installer/issues
Project-URL: Documentation, https://github.com/exhank/llm-wiki-installer/tree/main/docs
Project-URL: Changelog, https://github.com/exhank/llm-wiki-installer/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/exhank/llm-wiki-installer/security/policy
Keywords: agent,llm,markdown,obsidian,knowledge-base,installer,wiki
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# llm-wiki-installer

[![CI](https://github.com/exhank/llm-wiki-installer/actions/workflows/ci.yml/badge.svg)](https://github.com/exhank/llm-wiki-installer/actions/workflows/ci.yml)
[![Release](https://github.com/exhank/llm-wiki-installer/actions/workflows/release.yml/badge.svg)](https://github.com/exhank/llm-wiki-installer/actions/workflows/release.yml)
[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](pyproject.toml)
[![PyPI](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fllm-wiki-installer%2F0.1.7%2Fjson&query=%24.info.version&label=PyPI&prefix=v)](https://pypi.org/project/llm-wiki-installer/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

`llm-wiki-installer` generates a Git-auditable, agent-friendly Obsidian
Markdown knowledge vault from one command.

It turns an empty folder into a durable Markdown knowledge system with clear
evidence boundaries, agent policy, helper scripts, and selected upstream
Skills. The generated vault is designed for a simple loop: collect
approved sources, compile them into `wiki/`, retrieve from the wiki first, and
review every change through Git.

It is not itself an initialized vault. This repository builds the generator; the
generated vault lives in a separate target repository.

## Quick Start

From the empty directory you want to turn into an `llm-wiki` vault, run:

```bash
curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | /bin/bash
```

The default flow is interactive. It shows selectors for dependency tools and
upstream Skills, with all options selected by default. When no target path is
provided, the installer writes the vault into the current directory.

If you use `uv`, the package is also published on PyPI as
[`llm-wiki-installer`](https://pypi.org/project/llm-wiki-installer/):

```bash
uvx llm-wiki-installer
```

For pinned automation, include the package version you want to reproduce:

```bash
uvx llm-wiki-installer==<version> --no-interactive /path/to/knowledge-vault
```

## Why This Exists

Most AI note workflows stop at chat answers or ad hoc generated notes. This
project sets up a stricter vault contract:

- `raw/` keeps user-approved source evidence.
- `wiki/` keeps compiled long-term Markdown knowledge.
- `wiki/index.md` and `wiki/maps/` provide stable retrieval entry points.
- `wiki/tags.md` keeps the flat kebab-case tag registry.
- `wiki/log.jsonl`, Git diff, and generated scripts make changes auditable.
- Upstream Skills are copied as third-party artifacts from pinned sources.

## Features

- One-command local or streamed installer.
- Python installer package with no runtime third-party dependencies.
- Interactive default-all selectors for dependency tools and upstream Skill
  sources.
- Generated AGENTS policy, README, scripts, Codex config, index, log, and
  stable Obsidian settings.
- Generated stable Obsidian settings with bundled Things theme and obsidian-git
  plugin assets.
- Pinned upstream Skill commits for reproducible generated vaults.
- Safety checks that refuse to generate into this generator repository.
- Unit, shell integration, type, lint, coverage, and package checks.

## What It Generates

`llm-wiki-installer` turns an empty target repository into a working vault
contract:

```text
knowledge-vault/
+-- raw/                 # user-approved source evidence
+-- attachments/         # Obsidian default attachment folder
+-- wiki/                # durable compiled knowledge
|   +-- index.md         # retrieval entry point
|   +-- tags.md          # flat kebab-case tag registry
|   +-- log.jsonl        # JSONL change log
|   +-- maps/            # topic maps for navigation
+-- outputs/             # generated reports and exports
+-- inbox/               # incoming material awaiting review
+-- archives/             # retired material
+-- schema/              # schema and policy documents
+-- AGENTS.md            # runtime policy for agents
+-- .agents/
|   +-- skills/          # flattened pinned third-party Skill artifacts
+-- .codex/
|   +-- config.toml      # Codex project config
|   +-- hooks.json       # Codex project hook config
+-- .scripts/            # verification helpers
+-- .obsidian/           # stable Obsidian settings, theme, and pinned plugin assets
```

The operating model is intentionally file-first:

```text
approved sources -> raw/ -> wiki pages -> wiki/index.md + wiki/maps/
                         \-> wiki/log.jsonl -> Git diff review

agents read AGENTS.md -> retrieve with rg/fzf -> verify against raw/
```

## Generate A Vault

Install with the published PyPI package:

```bash
uvx llm-wiki-installer /path/to/knowledge-vault
```

Pin the package version for repeatable automation:

```bash
uvx llm-wiki-installer==<version> /path/to/knowledge-vault
```

Install into the current directory with the streamed shell bootstrap:

```bash
curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | /bin/bash
```

Pass installer options through the same pattern:

```bash
curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | /bin/bash -s -- --force
```

The streamed launcher resolves
[GitHub Releases latest](https://github.com/exhank/llm-wiki-installer/releases/latest)
internally when `LLM_WIKI_INSTALLER_REF` is not set. Set
`LLM_WIKI_INSTALLER_REF` only when intentionally testing or pinning another ref:

```bash
curl -fsSL https://raw.githubusercontent.com/exhank/llm-wiki-installer/main/install.sh | LLM_WIKI_INSTALLER_REF=<tag-or-commit> /bin/bash
```

The `uvx` entry point uses the PyPI package and runs the same installer CLI as
`llm-wiki-install`. It is the preferred path for automation because JSON output
comes directly from the Python CLI. The streamed one-line command remains useful
on machines that do not already use `uv`.

Install from a local checkout into the current directory:

```bash
bash /path/to/llm-wiki-installer/install.sh
```

Install into a specific directory:

```bash
bash install.sh /path/to/knowledge-vault
```

Use `--force` with a specific directory only when you intentionally want to
overwrite generated files in the target vault:

```bash
bash install.sh --force /path/to/knowledge-vault
```

Preview an install plan:

```bash
bash install.sh --dry-run /path/to/knowledge-vault
bash install.sh --dry-run --json /path/to/knowledge-vault
```

Select tools and upstream Skills explicitly:

```bash
bash install.sh --tools rg --skills kepano /path/to/knowledge-vault
bash install.sh --tools none --skills none /path/to/knowledge-vault
```

Run without network bootstrap operations:

```bash
bash install.sh --offline --tools rg --skills none /path/to/knowledge-vault
```

Run without automatically installing missing selectable tools:

```bash
bash install.sh --no-install-tools --tools rg /path/to/knowledge-vault
```

When run from an interactive terminal, the installer shows two onboarding
selectors before generating files:

- dependency tools: `rg` and `fzf`
- upstream Skill sources: `Ar9av/obsidian-wiki` and `kepano/obsidian-skills`

Both selectors default to all options selected. Use Up/Down to move, Space to
toggle an option, and Enter to continue. Non-interactive runs, including
scripted installs with redirected output, use the all-selected default. To force
that behavior from a terminal, pass:

```bash
bash install.sh --no-interactive /path/to/knowledge-vault
```

The installer refuses to use a checked-out generator repository, or any path
inside one, as the target. If you run `bash install.sh` from this repository, it
exits instead of writing vault files here.

## Generated Target Layout

The target vault receives:

```text
inbox/
raw/
attachments/
wiki/
outputs/
archives/
AGENTS.md
README.md
.agents/skills/
.codex/config.toml
.codex/hooks.json
.scripts/postrun.sh
.scripts/check-index-log.sh
.obsidian/
.gitignore
```

Selected upstream Skills are installed into `.agents/skills/`, flattened by
skill directory name. Stable Obsidian settings, the Things theme, and pinned
obsidian-git plugin assets are generated under `.obsidian/`; volatile workspace
state is not generated.

## Requirements

- Python 3.13+
- Git
- `rg` when selected
- `fzf` when selected
- Network access to PyPI for `uvx`, GitHub for streamed installs and upstream
  Skills

Pass `--no-install-tools` to require preinstalled tools instead. Pass
`--offline` to disable upstream Skill cloning; when `--offline` is used without
`--skills`, upstream Skills default to `none`.

## CLI Options

```text
--force              overwrite generated files in the target vault
--no-interactive     use default all-selected prompts without asking
--yes                alias for --no-interactive
--tools LIST         rg,fzf, all, or none
--skills LIST        Ar9av,kepano, all, or none
--no-install-tools   fail if a selected missing tool would need installation
--offline            do not run network bootstrap operations
--dry-run            print the install plan without writing files
--json               print dry-run or final install summaries as JSON
```

## Failure Handling

Installer failures are intended to be actionable. Common fixes:

- Missing Python: install Python 3.13+ or use `uvx --python 3.13`.
- Missing Git: install Git and rerun the same command.
- Missing `rg` or `fzf`: install the selected tool or rerun with `--tools`
  excluding it.
- Network unavailable: use `--offline --skills none`; selected upstream Skills
  require GitHub access.

## Privacy And Network Boundaries

The installer does not include telemetry. It writes only under the target vault
root after rejecting the generator repository itself and child paths. Network
access is limited to documented bootstrap operations: fetching the published
package from PyPI when using `uvx`, cloning this installer for streamed
installs, and cloning selected pinned upstream Skill sources. Use `--dry-run`
to inspect the plan first, and `--offline` to disable installer-managed network
bootstrap operations after the package or launcher has already started.

## Develop

```bash
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pip install --no-build-isolation --no-deps -e .
```

Useful development checks:

```bash
make format        # apply isort and Black to src/ and tests/
make format-check  # verify isort and Black without changing files
make lint          # run format checks and Pylint
make typecheck     # run mypy
make test          # run pytest
make coverage      # run pytest with coverage
make shell-test    # run the stubbed shell integration harness
make package-check # build sdist/wheel and run twine check
make verify        # run the full local verification stack
```

Optional local Git hook setup:

```bash
.venv/bin/pre-commit install
```

## Project Map

- `install.sh` is the small compatibility launcher.
- `src/llm_wiki_installer/` contains the Python installer package.
- `src/llm_wiki_installer/templates/` contains generated vault file bodies.
- `docs/technical-design.md` is the architecture source of truth.
- `docs/llm-wiki-generation-guide.md` is the generation contract.
- `docs/security-model.md` describes trust boundaries, network access, command
  execution, and supply-chain controls.
- `tests/test_installer.py` covers installer behavior and generated contracts.
- `tests/install_test.sh` is the shell integration harness with stubbed tools.

## Contributing And Security

Contributions should keep the generator and generated vault contracts aligned:
when generated behavior changes, update the relevant template, docs, and tests
in the same patch. See `CONTRIBUTING.md` for the local workflow,
`docs/security-model.md` for the security model, and `SECURITY.md` for
vulnerability reporting.

## Credits

This project is inspired by Andrej Karpathy's LLM Wiki methodology: compile
approved source material into a long-lived Markdown wiki, retrieve from the wiki
first, and keep changes reviewable through files and Git.

The installer can copy upstream Skills from these projects as third-party
artifacts:

- `Ar9av/obsidian-wiki`
- `kepano/obsidian-skills`

Thanks to the authors and maintainers of the tools and ecosystems this project
builds on:

- [Obsidian](https://obsidian.md/) for the local-first Markdown knowledge base
  model this installer targets.
- [ripgrep](https://github.com/BurntSushi/ripgrep) and
  [fzf](https://github.com/junegunn/fzf) for fast local search and selection.
- [Git](https://git-scm.com/), [Python](https://www.python.org/), and
  related tooling for the portable installer and verification toolchain.

These acknowledgements do not imply endorsement by those projects. They are
included to make the dependencies and inspiration behind `llm-wiki-installer`
clear.

## License

MIT. See `LICENSE`.
