lorewiki 0.3.0__tar.gz → 0.3.2__tar.gz

{lorewiki-0.3.0 → lorewiki-0.3.2}/.gitignore

@@ -57,3 +57,7 @@ uv.lock
 !.env.example
 *.local.toml
 
+# Sharing scratch — written for copy-paste to community channels,
+# never intended to be part of the repo.
+SHARE.md
+

{lorewiki-0.3.0 → lorewiki-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lorewiki
-Version: 0.3.0
+Version: 0.3.2
 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

{lorewiki-0.3.0 → lorewiki-0.3.2}/lorewiki/__init__.py

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

{lorewiki-0.3.0 → lorewiki-0.3.2}/lorewiki/data/skill_template/SKILL.md

@@ -145,6 +145,47 @@ descriptions, the command exits with code 1 and prints a panel that
 tells the user to name the topic by hand. The agent should fall
 back to asking the user explicitly in that case.
 
+### Topic Selection Before Writing (the "ask, don't surprise" rule)
+
+If the user says "save this to my wiki" / "记到 wiki 里" / "メモして"
+**without naming a topic**, the LLM must **not** auto-create a topic
+on the user's behalf. The wiki is a long-lived knowledge asset —
+silently dropping a doc into a freshly-invented `general` vault is
+surprising and pollutes the user's mental model.
+
+Follow this tree strictly, and **ask the user at the leaves**:
+
+```text
+User: "save X to my wiki"  (no topic named)
+  │
+  ├── 1. Is there an active topic?  (~/lorewiki/current exists)
+  │     ├── YES → use it. No question needed.
+  │     └── NO  → go to step 2.
+  │
+  ├── 2. How many topics exist?  (lorewiki topic list --raw)
+  │     ├── 1 → "I see one topic '<name>'. Use it?" (one confirmation)
+  │     ├── 2-3 → list them, ask "which one?" (free text or pick)
+  │     └── 4+ → ask "which one?" (don't auto-pick)
+  │
+  └── 3. Zero topics exist
+        ├── Run `lorewiki topic suggest "<X summary>"` for English
+        │   descriptions, OR have the LLM propose 1-3 names itself
+        │   for CJK descriptions.
+        └── Show candidates to the user:
+              "I can create topic 'wechat-mp', 'wechat-miniprogram',
+              or 'mp'. Which? (Or pick your own — lowercase, digits,
+              hyphens, 1-64 chars.)"
+            User picks → lorewiki topic create <name>
+            User rejects all → ask for a name by hand.
+```
+
+**Why this matters**: a user who has spent a year curating
+`~/lorewiki/topics/react/`, `~/lorewiki/topics/api/`, etc., does
+**not** want their work silently merged into a `general` vault just
+because they said "wiki" without naming a topic. The cost of asking
+once is one round-trip; the cost of surprising the user is having
+to undo the merger later.
+
 **Path resolution priority** (later wins):
 1. `--topic` flag
 2. `LOREWIKI_TOPIC` env var
@@ -546,7 +587,9 @@ lorewiki clean    --path "<WIKI>" [--dry-run] [--no-backup]
 | "what's in the wiki / what modules exist"               | `lorewiki tree`                                               |
 | "does the wiki explain how X is implemented?"             | `lorewiki ask "how is X implemented?" --raw`                  |
 | "what modules does the wiki have?"                      | `lorewiki tree --depth 2`                                     |
-| "remember this / save this / take a note about X"       | `lorewiki add --title "X" --body "..."`                       |
+| "remember this / save this / take a note about X" (topic named)  | `lorewiki topic use <name> && lorewiki add --title "X" --body "..."` |
+| "remember this / save this to my wiki" (no topic)               | Follow the **Topic Selection Tree** (see "ask, don't surprise")     |
+| "save this URL / doc to my wiki"                                 | Fetch content (webfetch / Read tool) → `lorewiki add --title X --body "<fetched>"` |
 | "store these N pages / scrape this site"                | Drop the dir under the topic, then `lorewiki index`           |
 | "import my entire <some-tool> docs folder"              | `lorewiki topic create <name> --source <docs-folder>`          |
 | "why does this query return no results?"                 | Re-run with `--mode bm25` to inspect scores                   |

{lorewiki-0.3.0 → lorewiki-0.3.2}/lorewiki/utils/skill_installer.py

@@ -29,6 +29,7 @@ Differences from ``skills/install.py``:
 """
 from __future__ import annotations
 
+import contextlib
 import os
 import re
 import sys
@@ -120,35 +121,35 @@ TOOLS: Final[tuple[Tool, ...]] = (
     Tool(
         id="opencode",
         label="opencode",
-        primary="$XDG_CONFIG_HOME/opencode/skills/<name>",
+        primary="$XDG_CONFIG_HOME/opencode/skills/<name>/SKILL.md",
     ),
     Tool(
         id="claude",
         label="Claude Code",
-        primary="~/.claude/skills/<name>",
+        primary="~/.claude/skills/<name>/SKILL.md",
     ),
     Tool(
         id="codex",
         label="Codex CLI",
-        primary="$CODEX_HOME/skills/<name>",
+        primary="$CODEX_HOME/skills/<name>/SKILL.md",
     ),
     Tool(
         id="cursor",
         label="Cursor",
-        primary="~/.cursor/skills/<name>",
+        primary="~/.cursor/skills/<name>/SKILL.md",
         # Cursor also auto-discovers ~/.agents/skills/ (interop path).
-        aliases=("~/.agents/skills/<name>",),
+        aliases=("~/.agents/skills/<name>/SKILL.md",),
     ),
     Tool(
         id="gemini",
         label="Gemini CLI",
-        primary="$GEMINI_HOME/skills/<name>",
-        aliases=("~/.agents/skills/<name>",),
+        primary="$GEMINI_HOME/skills/<name>/SKILL.md",
+        aliases=("~/.agents/skills/<name>/SKILL.md",),
     ),
     Tool(
         id="antigravity",
         label="Google Antigravity",
-        primary="~/.gemini/antigravity/skills/<name>",
+        primary="~/.gemini/antigravity/skills/<name>/SKILL.md",
     ),
 )
 
@@ -159,15 +160,15 @@ TOOLS: Final[tuple[Tool, ...]] = (
 
 
 def _parent_exists(path: Path) -> bool:
-    """True if the tool's *config root* exists (two levels above the skill dir).
+    """True if the tool's *config root* exists (three levels above the SKILL.md).
 
-    For ``~/.config/opencode/skills/lorewiki`` we check
+    For ``~/.config/opencode/skills/lorewiki/SKILL.md`` we check
     ``~/.config/opencode/`` — the directory the tool itself creates
     on first launch. Going further up would land on ``$HOME`` /
     ``C:\\`` which always exist and would mark every tool as
     installed.
     """
-    return path.parent.parent.exists()
+    return path.parent.parent.parent.exists()
 
 
 def detect_installed_tools() -> list[Tool]:
@@ -278,6 +279,18 @@ def install_skill(
     ``write_text``. We don't want one locked path to abort the
     rest of the install — we surface the failure as a ``[skip]``
     line and move on.
+
+    The install target is the file ``<root>/<name>/SKILL.md``
+    (not the directory itself). The path templates in :data:`TOOLS`
+    already include the ``/SKILL.md`` suffix. An earlier version
+    of this function wrote to the directory path, which on Windows
+    surfaces as ``PermissionError`` when the dir already exists,
+    and on POSIX silently creates a *file* at the dir path —
+    leaving an orphan single-file ``~/.agents/skills/<name>``
+    (31821 bytes) instead of the expected ``<root>/<name>/SKILL.md``
+    file. The current implementation also cleans up the orphan
+    single-file layout (a file where the dir should be) at the
+    alias path so the new ``mkdir`` doesn't fail.
     """
     if skill_text is None:
         skill_text = _read_skill_template()
@@ -299,6 +312,21 @@ def install_skill(
         alias = tool.resolve(alias_tmpl)
         if alias == primary:
             continue
+        # Clean up the legacy single-file layout (e.g.
+        # ``~/.agents/skills/lorewiki`` as a file, not a dir) so
+        # the new ``mkdir`` doesn't fail because a parent path
+        # component is a file.
+        if alias.parent.exists() and not alias.parent.is_dir():
+            try:
+                alias.parent.unlink()
+                actions.append(
+                    f"[rm]   {alias.parent} (legacy single-file layout)"
+                )
+            except OSError as exc:
+                actions.append(
+                    f"[skip] {alias.parent} (legacy unlink failed: {exc})"
+                )
+                continue
         alias.parent.mkdir(parents=True, exist_ok=True)
         if alias.exists() and not overwrite:
             actions.append(
@@ -322,19 +350,27 @@ def uninstall_skill(tool: Tool) -> list[str]:
     Each target is wrapped in its own ``try/except OSError`` for the
     same reason as :func:`install_skill`: a locked directory or
     read-only mount should not abort the rest of the uninstall.
+
+    Also handles the legacy single-file layout (e.g. an alias at
+    ``~/.agents/skills/<name>`` written as a file by 0.2.5-0.2.9)
+    by unlinking that file too, so ``lorewiki install --uninstall``
+    leaves a clean slate.
     """
     actions: list[str] = []
     for tmpl in (tool.primary, *tool.aliases):
         target = tool.resolve(tmpl)
-        if not (target.exists() or target.is_symlink()):
-            actions.append(f"[skip] {target} (not present)")
-            continue
-        try:
-            target.unlink()
-        except OSError as exc:
-            actions.append(f"[skip] {target} (unlink failed: {exc})")
-        else:
+        if target.exists() or target.is_symlink():
+            try:
+                target.unlink()
+            except OSError as exc:
+                actions.append(f"[skip] {target} (unlink failed: {exc})")
+                continue
             actions.append(f"[rm]   {target}")
+            # Clean up the now-empty parent dir if we can.
+            with contextlib.suppress(OSError):
+                target.parent.rmdir()
+        else:
+            actions.append(f"[skip] {target} (not present)")
     return actions
 
 

{lorewiki-0.3.0 → lorewiki-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lorewiki"
-version = "0.3.0"
+version = "0.3.2"
 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"