skillwiki 0.4.2 → 0.4.4-beta.1

package/skills/wiki-query/SKILL.md

@@ -1,41 +1,36 @@
 ---
-version: 0.2.1
+version: 0.2.2
 name: wiki-query
 description: Search the vault and synthesize an answer with E2 4-signal ranking. Optional file to queries/ or comparisons/.
 ---
-
 # wiki-query
-
 ## When This Skill Activates
-
 - User asks a question that should be answered from vault contents.
 - A vault is resolvable (see step 0).
-
 ## Output language
-
 Run `skillwiki lang` at the start. Generate query-result prose and `--human` summaries in the resolved language. Frontmatter keys, file names, schema headers, index/log structural lines, citation markers, and wikilink slugs MUST stay English.
-
 ## Pre-orientation reads
 Standard four reads (SCHEMA, index, log, project context if applicable).
-
 ## Steps
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
 1. **Determine scope.** Ask the user once if ambiguous: vault | current project | project+concepts.
 2. **Refresh graph.** If `.skillwiki/graph.json` is missing or older than 24h: `skillwiki graph build <vault>`.
 3. **Compute overlap.** `skillwiki overlap <vault>`.
 4. **Score candidates** in prompt using the 4 signals:
-   - Direct wikilink: 3.0×
-   - Source overlap: 4.0× (read from overlap output)
-   - Adamic-Adar: 1.5× (read from graph output)
-   - Type affinity: 1.0×
+- Direct wikilink: 3.0×
+- Source overlap: 4.0× (read from overlap output)
+- Adamic-Adar: 1.5× (read from graph output)
+- Type affinity: 1.0×
 5. **Read top candidates** in full (frontmatter + body).
 6. **Synthesize answer** with explicit citations to the candidate pages.
 7. **Optional file.** If user accepts: write to `queries/<slug>.md` or `comparisons/<slug>.md` with full frontmatter, validate, then update `index.md` then `log.md`.
-
 ## Stop conditions
 - Zero matching pages.
 - User declines to file.
-
+## Pitfalls
+### Claimed-status vs actual-state gap
+When a wiki page (especially a work item `tasks.md`) claims that fixes were applied, features were completed, or files were removed — **verify on disk before accepting the claim**. In one incident, a `tasks.md` marked 6 items DONE but 5 were not actually applied: a script claimed "removed" was still 2020 bytes on disk, a crontab claimed "updated to 30min" was still `*/10`, and a build target claimed "verified has consumers" had no web server serving it. 
+**Rule**: After reading a work item that declares completion, run at least one verification command per critical claim (check file existence, grep a config, inspect a crontab). Documents can drift from reality — the filesystem is the source of truth.
 ## Forbidden
 - Filing without `validate` passing.
 - Skipping the orientation reads even for "quick" queries.

package/skills/wiki-sync/SKILL.md

@@ -3,88 +3,113 @@ version: 0.2.1
 name: wiki-sync
 description: Safely sync the vault git repository. Runs skillwiki sync status, then guides push or pull with lint guards and conflict resolution.
 ---
-
 # wiki-sync
-
 ## When This Skill Activates
-
 - User wants to push local vault changes to the remote.
 - User wants to pull remote changes into their local vault.
 - User asks about vault sync status, git state, or multi-device coordination.
 - Periodic maintenance before or after editing sessions.
-
 ## Pre-orientation reads
-
 Standard four reads.
-
 ## Steps
-
 0. Resolve vault: `skillwiki path` (record source for context).
 1. Run `skillwiki sync status <vault>`. Read the JSON output.
-   - Exit code 0: vault is clean (nothing to sync).
-   - Exit code 22: warnings — dirty/ahead/behind (needs action).
+- Exit code 0: vault is clean (nothing to sync).
+- Exit code 22: warnings — dirty/ahead/behind (needs action).
 2. Present the current state: `status`, `dirty`, `ahead`, `behind`, `last_commit`.
 3. Ask the user which operation they want: **push**, **pull**, or **both** (pull then push).
-
 ### Push workflow
-
 4. If vault is dirty, ask the user to review uncommitted changes before proceeding.
 5. Run `skillwiki lint <vault>`. If errors exist, stop and report — do not push lint errors to remote.
 6. If lint passes (errors = 0), stage and commit:
-   - `git -C <vault> add -A`
-   - `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
+- `git -C <vault> add -A`
+- `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
 7. Run `git -C <vault> push origin HEAD`. Report result.
 8. Append one `log.md` entry summarizing: files pushed, lint result, commit hash.
-
 ### Pull workflow
-
 9. If vault is dirty, stash first: `git -C <vault> stash push -m "auto-stash before pull $(date -u +%Y-%m-%dT%H:%MZ)"`.
 10. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
 11. If a stash was created, pop it: `git -C <vault> stash pop`.
 12. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
 13. Run `skillwiki lint <vault>` after pull to verify vault integrity.
 14. Append one `log.md` entry summarizing: commits pulled, lint result, any conflicts.
-
 ### Pull-then-push workflow
-
 15. Execute the pull workflow (steps 9-13) first.
 16. Then execute the push workflow (steps 4-8).
-
 ## Conflict Resolution
-
 When merge conflicts are detected:
-
 - **Frontmatter conflicts:**
-  - For `updated:` fields: always take the newer timestamp (compare both sides, keep the later one).
-  - For all other frontmatter fields: present both versions to the user and ask which to keep.
+- For `updated:` fields: always take the newer timestamp (compare both sides, keep the later one).
+- For all other frontmatter fields: present both versions to the user and ask which to keep.
 - **Body conflicts:**
-  - Do not auto-resolve body conflicts.
-  - Mark unresolved regions with `???` on a line by itself between the conflicting versions, so the user can see both sides and decide.
-  - Example:
-    ```
-    Content from local version
-    ???
-    Content from remote version
-    ```
+- Do not auto-resolve body conflicts.
+- Mark unresolved regions with `???` on a line by itself between the conflicting versions, so the user can see both sides and decide.
+- Example:
+```
+Content from local version
+???
+Content from remote version
+```
 - After resolving conflicts, run `skillwiki lint <vault>` to verify before committing.
-
 ## Multi-device coordination
-
 When the user mentions editing from Obsidian desktop and Claude Code on a server (or any two-device setup):
-
 - Recommend pulling before every editing session on each device.
 - Recommend pushing after every editing session on each device.
 - If both devices edit the same page between syncs, conflicts are inevitable — the Conflict Resolution section handles this.
 - Suggest enabling auto-commit in Obsidian (Community Plugins: `obsidian-git`) to reduce dirty-state drift.
-
+## Rclone-backed vault with git snapshotting (cron pattern)
+Some deployments use a cloud-backed vault (`rclone mount`) with a separate git repository for versioned snapshots. This pattern separates "live working vault" from "versioned backup".
+### Architecture
+```
+~/wiki           → rclone mount to cloud storage (S3/IDrive/etc) — live vault
+~/wiki-git       → git repository cloned from GitHub — snapshot target
+cron hourly      → rsync ~/wiki/ → ~/wiki-git/ → git commit → git push
+```
+### Implementation (wiki-snapshot.sh)
+```bash
+#!/bin/bash
+WIKI_DIR="/root/wiki"
+GIT_DIR="/root/wiki-git"
+DATE=$(date +%Y%m%d_%H%M%S)
+# Sync from rclone mount to git repo (quiet mode for slow mounts)
+rsync -a --delete -q \
+--exclude='.snapshots' --exclude='.git' --exclude='.obsidian' --exclude='.skillwiki' \
+"$WIKI_DIR/" "$GIT_DIR/"
+cd "$GIT_DIR" || exit 1
+git config user.email "cron@hermes.local"
+git config user.name "Hermes Snapshot"
+# Check for changes
+if [ -z "$(git status --porcelain)" ]; then
+exit 0  # Nothing to commit
+fi
+git add -A
+git commit -m "Snapshot $DATE"
+# Pull with rebase to handle remote changes (e.g., README edits on GitHub)
+if ! git pull --rebase origin main 2>/dev/null; then
+git pull origin main 2>/dev/null || true
+fi
+git push origin main || echo "Push failed"
+```
+### Pitfalls specific to this pattern
+1. **Divergent branches from external pushes**: If something else pushes to the same GitHub repo (manual edits from macOS desktop, GitHub web UI edits, another server), the local `~/wiki-git` will diverge. The `--rebase` flag handles most cases, but if commits conflict:
+```bash
+cd ~/wiki-git
+git rebase --abort 2>/dev/null || true
+git fetch origin main
+git reset --hard origin/main
+bash ~/.hermes/scripts/wiki-snapshot.sh  # Re-sync fresh
+```
+**Prevention**: Avoid editing the GitHub repo directly via web interface or uncoordinated clones. The canonical flow is:
+- Server: rclone mount → rsync → git commit → git push
+- macOS/desktop: git pull → edit → git commit → git push → server pulls on next cron
+2. **Slow rsync on rclone mounts**: The rclone FUSE mount can be slow for large directory listings. Use `rsync -q` (quiet) to reduce output overhead, and consider `--delete-delay` instead of `--delete` if file churn is high. The rclone mount latency can cause `du` and `find` operations to timeout — this is normal, not an error.
+3. **Golden Rule violation**: Never mix sync methods on the same vault. If using rclone mount + git snapshotting, do NOT also enable Obsidian Sync, Syncthing, or iCloud on `~/wiki`. The rclone mount IS the sync mechanism.
+4. **Credential exposure**: The rclone mount and git remote use different credentials. Ensure git credentials are cached or use HTTPS with token, but never commit rclone config to git.
 ## Stop conditions
-
 - `skillwiki sync status` reports `not_a_repo` — the vault is not a git repository. Advise the user to initialize one.
 - Lint errors are found before a push — do not push until resolved.
 - `git push` or `git pull` fails with a network error — report and stop.
-
 ## Forbidden
-
 - Pushing when lint errors exist.
 - Auto-resolving body conflicts without user review.
 - Force-pushing (`git push --force`).