lorewiki 0.2.2__tar.gz → 0.2.3__tar.gz

{lorewiki-0.2.2 → lorewiki-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lorewiki
-Version: 0.2.2
+Version: 0.2.3
 Summary: Local-first knowledge base for LLM-assisted coding, with hybrid retrieval (BM25 + hierarchy + optional vector) over SQLite FTS5.
 Project-URL: Documentation, https://github.com/JochenYang/Lore-wiki
 Project-URL: Source, https://github.com/JochenYang/Lore-wiki
@@ -105,50 +105,126 @@ it directly.
 
 ## Installation
 
+LoreWiki ships as a Python wheel on **PyPI** (canonical) with an
+**npm shim** that proxies to the same wheel. Pick one:
+
+### Python (recommended, full feature set)
+
+```bash
+# Install — isolated per-tool venv, the lorewiki.exe (Windows)
+# or lorewiki binary (macOS/Linux) is added to your PATH.
+uv tool install lorewiki
+
+# With the optional vector-retrieval extra (sqlite-vec + sentence-transformers):
+uv tool install 'lorewiki[vector]'
+
+# Upgrade:
+uv tool upgrade lorewiki
+
+# Uninstall (does NOT touch ~/.lorewiki/ — your data is yours):
+uv tool uninstall lorewiki
+```
+
+If you don't have `uv` yet:
+
 ```bash
-# Editable install (recommended for active development)
-uv tool install --editable .
+# macOS / Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell):
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Plain `pip` works too (the `lorewiki.exe` entry point is the same):
 
-# Or plain pip
-pip install -e .                 # core CLI
-pip install -e ".[dev]"          # add pytest / ruff / coverage
-pip install -e ".[vector]"       # opt-in: vector retrieval (sqlite-vec)
+```bash
+pip install lorewiki              # core CLI
+pip install 'lorewiki[vector]'    # opt-in: vector retrieval
 ```
 
-Python **3.10+** required. After install, `lorewiki --version`
-should print `LoreWiki 0.1.0`.
+> The `[rest]` and `[mcp]` extras from 0.1.x are gone as of 0.2.0.
+> The CLI + opencode skill replaced the FastAPI / MCP server surface.
+> The `[all]` extra is now an alias for `[vector]`.
 
-> Windows PowerShell users: if CJK characters show as `?` in
-> `lorewiki search --raw` output, prefix the command with
-> `chcp 65001 |` to force the shell code page to UTF-8, or upgrade
-> to v0.1.1+ which forces UTF-8 stdout automatically.
+### Node (npm shim, identical CLI)
+
+```bash
+npm install -g lorewiki           # postinstall calls `uv tool install lorewiki`
+npm install -g lorewiki@latest    # upgrade
+npm uninstall -g lorewiki         # also runs `uv tool uninstall lorewiki`
+```
+
+The npm package is a thin shim — it spawns the Python `lorewiki` that
+the postinstall hook installed. See [`README.npm.md`](README.npm.md)
+for the full story.
+
+### From source (for contributors)
+
+```bash
+git clone https://github.com/JochenYang/Lore-wiki
+cd Lore-wiki
+uv tool install --editable .              # dev install
+uv tool install --editable '.[dev]'       # + pytest / ruff / coverage
+```
+
+Python **3.10+** is required. After install, `lorewiki --version`
+should print a banner ending with `v0.2.x`.
+
+> **Windows PowerShell + CJK note**: starting with 0.2.0, LoreWiki
+> forces UTF-8 on stdout/stderr unconditionally — CJK characters
+> round-trip cleanly through the shell without `chcp 65001`. If you
+> hit garbled output on an older release, upgrade with
+> `uv tool upgrade lorewiki` or prefix the command with
+> `chcp 65001 |`.
+
+For deeper install info (PATH troubleshooting, where data lives,
+backups, common errors, how publishing works), see
+[`docs/install.md`](docs/install.md).
 
 ## Quickstart
 
 ```bash
-# 1. Create a wiki + config
+# 1. Create a wiki + sample Markdown
 lorewiki init --path ./my-wiki
 
-# 2. Author Markdown under ./my-wiki/, then index it
+# 2. Index the Markdown into SQLite + FTS5 (one-time, then incremental)
 lorewiki index --path ./my-wiki
 
-# 3. Search
+# 3. Search (default output is structured JSON for agents; --human for Rich Table)
 lorewiki search "用户登录接口" --path ./my-wiki --mode mix --top-k 5
+lorewiki search "用户登录接口" --path ./my-wiki --mode mix --top-k 5 --human
 
 # 4. Ask (LLM-assisted answer, gracefully falls back to top chunks)
 lorewiki ask "如何实现幂等重试" --path ./my-wiki
 
-# 5. Or author a note from the CLI (writes + re-indexes in one go)
-echo "Some deep details about Python design pattern." \
-  | lorewiki add --title "Python Design" --module "patterns" --tag python,design
+# 5. Author a note from the CLI (writes + re-indexes in one go)
+#    Three equivalent ways to provide the body:
+lorewiki add --title "Python Design" --module "patterns" --tag python,design \
+    --body "Some deep details about Python design patterns." \
+    --path ./my-wiki
+
+#    --file: read the body from a file
+lorewiki add --title "From File" --module "patterns" \
+    --file ./drafts/python-design.md --path ./my-wiki
 
-# 6. Browse the index status
+#    stdin pipe (any of these is fine on Windows + PowerShell, even
+#    with CJK content; 0.2.2+ scrubs UTF-16 surrogates automatically)
+echo "Some deep details about Python design patterns." \
+  | lorewiki add --title "From Pipe" --module "patterns" --path ./my-wiki
+
+# 6. Browse the index / hierarchy / status
 lorewiki status --path ./my-wiki
+lorewiki tree   --path ./my-wiki      # Rich-Tree view of the hierarchy
+lorewiki show   index.md --path ./my-wiki   # print a doc body (cleaned)
 ```
 
-The default config lives in `<wiki>/.lorewiki/config.toml`; user-wide
-overrides live in `~/.lorewiki/config.toml`; env vars `LOREWIKI_*` override
-both.
+**Config resolution** (later wins):
+
+1. `<wiki>/.lorewiki/config.toml` — per-wiki defaults
+2. `~/.lorewiki/config.toml` — user-wide overrides
+3. `LOREWIKI_*` env vars — shell-level overrides
+
+Edit any of these with `lorewiki config list / get / set` (TOML-aware,
+no hand-editing required).
 
 ## Topics — your second brain
 
@@ -336,7 +412,7 @@ See `docs/lorewiki dev document.md` for the full design plan and
 ```bash
 pip install -e ".[dev]"
 ruff check lorewiki skills tests  # lint
-pytest -q                        # 240 unit + integration tests
+pytest -q                        # 241 unit + integration tests
 pytest --cov=lorewiki            # coverage report
 ```
 

{lorewiki-0.2.2 → lorewiki-0.2.3}/README.md

@@ -61,50 +61,126 @@ it directly.
 
 ## Installation
 
+LoreWiki ships as a Python wheel on **PyPI** (canonical) with an
+**npm shim** that proxies to the same wheel. Pick one:
+
+### Python (recommended, full feature set)
+
+```bash
+# Install — isolated per-tool venv, the lorewiki.exe (Windows)
+# or lorewiki binary (macOS/Linux) is added to your PATH.
+uv tool install lorewiki
+
+# With the optional vector-retrieval extra (sqlite-vec + sentence-transformers):
+uv tool install 'lorewiki[vector]'
+
+# Upgrade:
+uv tool upgrade lorewiki
+
+# Uninstall (does NOT touch ~/.lorewiki/ — your data is yours):
+uv tool uninstall lorewiki
+```
+
+If you don't have `uv` yet:
+
 ```bash
-# Editable install (recommended for active development)
-uv tool install --editable .
+# macOS / Linux:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+# Windows (PowerShell):
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Plain `pip` works too (the `lorewiki.exe` entry point is the same):
 
-# Or plain pip
-pip install -e .                 # core CLI
-pip install -e ".[dev]"          # add pytest / ruff / coverage
-pip install -e ".[vector]"       # opt-in: vector retrieval (sqlite-vec)
+```bash
+pip install lorewiki              # core CLI
+pip install 'lorewiki[vector]'    # opt-in: vector retrieval
 ```
 
-Python **3.10+** required. After install, `lorewiki --version`
-should print `LoreWiki 0.1.0`.
+> The `[rest]` and `[mcp]` extras from 0.1.x are gone as of 0.2.0.
+> The CLI + opencode skill replaced the FastAPI / MCP server surface.
+> The `[all]` extra is now an alias for `[vector]`.
 
-> Windows PowerShell users: if CJK characters show as `?` in
-> `lorewiki search --raw` output, prefix the command with
-> `chcp 65001 |` to force the shell code page to UTF-8, or upgrade
-> to v0.1.1+ which forces UTF-8 stdout automatically.
+### Node (npm shim, identical CLI)
+
+```bash
+npm install -g lorewiki           # postinstall calls `uv tool install lorewiki`
+npm install -g lorewiki@latest    # upgrade
+npm uninstall -g lorewiki         # also runs `uv tool uninstall lorewiki`
+```
+
+The npm package is a thin shim — it spawns the Python `lorewiki` that
+the postinstall hook installed. See [`README.npm.md`](README.npm.md)
+for the full story.
+
+### From source (for contributors)
+
+```bash
+git clone https://github.com/JochenYang/Lore-wiki
+cd Lore-wiki
+uv tool install --editable .              # dev install
+uv tool install --editable '.[dev]'       # + pytest / ruff / coverage
+```
+
+Python **3.10+** is required. After install, `lorewiki --version`
+should print a banner ending with `v0.2.x`.
+
+> **Windows PowerShell + CJK note**: starting with 0.2.0, LoreWiki
+> forces UTF-8 on stdout/stderr unconditionally — CJK characters
+> round-trip cleanly through the shell without `chcp 65001`. If you
+> hit garbled output on an older release, upgrade with
+> `uv tool upgrade lorewiki` or prefix the command with
+> `chcp 65001 |`.
+
+For deeper install info (PATH troubleshooting, where data lives,
+backups, common errors, how publishing works), see
+[`docs/install.md`](docs/install.md).
 
 ## Quickstart
 
 ```bash
-# 1. Create a wiki + config
+# 1. Create a wiki + sample Markdown
 lorewiki init --path ./my-wiki
 
-# 2. Author Markdown under ./my-wiki/, then index it
+# 2. Index the Markdown into SQLite + FTS5 (one-time, then incremental)
 lorewiki index --path ./my-wiki
 
-# 3. Search
+# 3. Search (default output is structured JSON for agents; --human for Rich Table)
 lorewiki search "用户登录接口" --path ./my-wiki --mode mix --top-k 5
+lorewiki search "用户登录接口" --path ./my-wiki --mode mix --top-k 5 --human
 
 # 4. Ask (LLM-assisted answer, gracefully falls back to top chunks)
 lorewiki ask "如何实现幂等重试" --path ./my-wiki
 
-# 5. Or author a note from the CLI (writes + re-indexes in one go)
-echo "Some deep details about Python design pattern." \
-  | lorewiki add --title "Python Design" --module "patterns" --tag python,design
+# 5. Author a note from the CLI (writes + re-indexes in one go)
+#    Three equivalent ways to provide the body:
+lorewiki add --title "Python Design" --module "patterns" --tag python,design \
+    --body "Some deep details about Python design patterns." \
+    --path ./my-wiki
+
+#    --file: read the body from a file
+lorewiki add --title "From File" --module "patterns" \
+    --file ./drafts/python-design.md --path ./my-wiki
 
-# 6. Browse the index status
+#    stdin pipe (any of these is fine on Windows + PowerShell, even
+#    with CJK content; 0.2.2+ scrubs UTF-16 surrogates automatically)
+echo "Some deep details about Python design patterns." \
+  | lorewiki add --title "From Pipe" --module "patterns" --path ./my-wiki
+
+# 6. Browse the index / hierarchy / status
 lorewiki status --path ./my-wiki
+lorewiki tree   --path ./my-wiki      # Rich-Tree view of the hierarchy
+lorewiki show   index.md --path ./my-wiki   # print a doc body (cleaned)
 ```
 
-The default config lives in `<wiki>/.lorewiki/config.toml`; user-wide
-overrides live in `~/.lorewiki/config.toml`; env vars `LOREWIKI_*` override
-both.
+**Config resolution** (later wins):
+
+1. `<wiki>/.lorewiki/config.toml` — per-wiki defaults
+2. `~/.lorewiki/config.toml` — user-wide overrides
+3. `LOREWIKI_*` env vars — shell-level overrides
+
+Edit any of these with `lorewiki config list / get / set` (TOML-aware,
+no hand-editing required).
 
 ## Topics — your second brain
 
@@ -292,7 +368,7 @@ See `docs/lorewiki dev document.md` for the full design plan and
 ```bash
 pip install -e ".[dev]"
 ruff check lorewiki skills tests  # lint
-pytest -q                        # 240 unit + integration tests
+pytest -q                        # 241 unit + integration tests
 pytest --cov=lorewiki            # coverage report
 ```
 

{lorewiki-0.2.2 → lorewiki-0.2.3}/lorewiki/__init__.py

@@ -1,4 +1,4 @@
 """LoreWiki - Local-first knowledge base for LLM-assisted coding."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 __all__ = ["__version__"]

{lorewiki-0.2.2 → lorewiki-0.2.3}/lorewiki/cli/apps.py

@@ -150,9 +150,11 @@ def main(
             "--topic",
             "-t",
             help=(
-                "Active knowledge topic for this invocation. Overrides "
-                "LOREWIKI_TOPIC env and ~/lorewiki/current. Use `lorewiki "
-                "topic list` to see available topics."
+                "Active knowledge topic NAME for this invocation. Overrides "
+                "the LOREWIKI_TOPIC env var and ~/lorewiki/current. "
+                "Note: this is the OPTION form — to manage topics "
+                "(list / create / use / delete), use the `topic` subcommand. "
+                "Example: --topic react search 'useState closure'."
             ),
         ),
     ] = None,

{lorewiki-0.2.2 → lorewiki-0.2.3}/lorewiki/cli/commands.py

@@ -126,7 +126,14 @@ def index(
         typer.Option("--rebuild", help="Drop and rebuild the index from scratch."),
     ] = False,
 ) -> None:
-    """Index a directory of Markdown files into SQLite + FTS5."""
+    """Build or rebuild the SQLite + FTS5 index for a wiki directory.
+
+    Scans every ``.md`` file under the wiki, parses Markdown (with
+    frontmatter), and writes the index. By default this is incremental
+    — files whose content hash hasn't changed are skipped, so
+    re-running on a large wiki is fast. Pass ``--rebuild`` to wipe
+    the existing index and start from scratch.
+    """
     cfg = resolve_config(path)
     if not cfg.wiki_path.exists():
         console.print(
@@ -304,7 +311,13 @@ def update(
         typer.Option("--watch", help="Watch for file changes and re-index incrementally."),
     ] = False,
 ) -> None:
-    """Incrementally update the index."""
+    """Re-index only files that changed since the last index run.
+
+    Today ``update`` is functionally equivalent to ``index`` — the
+    indexer is already incremental. The split is kept so a future
+    watcher (phase 6) can plug into the same surface without a
+    breaking change.
+    """
     phase_pending("update", "phase 6 (incremental enhancements)")
 
 
@@ -332,10 +345,13 @@ def ask(
         typer.Option("--raw", help="Print the answer + hits as JSON."),
     ] = False,
 ) -> None:
-    """Retrieve relevant chunks and ask the LLM to compose an answer.
+    """Compose an answer from the top-k retrieved chunks.
 
-    Gracefully degrades to "show the top chunks" if the LLM is disabled or
-    unreachable, so the command always returns useful output.
+    Requires ``[llm]`` to be enabled and reachable in the wiki config
+    (``lorewiki config list`` to inspect). If the LLM is disabled or
+    the backend is unreachable, ``ask`` gracefully degrades to
+    printing the top chunks with a "degraded" notice — your workflow
+    never breaks because the model is down.
     """
     cfg = resolve_config(path)
     if cfg.db_path is None or not cfg.db_path.exists():

{lorewiki-0.2.2 → lorewiki-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lorewiki"
-version = "0.2.2"
+version = "0.2.3"
 description = "Local-first knowledge base for LLM-assisted coding, with hybrid retrieval (BM25 + hierarchy + optional vector) over SQLite FTS5."
 readme = "README.md"
 requires-python = ">=3.10"