skillwiki 0.8.0 → 0.8.1-beta.10

package/skills/skills/wiki-audit/SKILL.md

@@ -0,0 +1,34 @@
+---
+version: 0.2.1
+name: wiki-audit
+description: Verify per-page that every ^[raw/...] resolves and sources frontmatter matches the body.
+---
+
+# wiki-audit
+
+## When This Skill Activates
+
+- User asks for a per-page audit or invokes a pre-merge gate.
+- A vault is resolvable (see step 0).
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate audit narrative 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.
+
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. `skillwiki audit <page>`. Read the JSON report.
+2. Reason over the report:
+   - For each unresolved marker: suggest ingesting the missing source or correcting the path.
+   - For each `unused_sources` entry: suggest adding a body marker or removing from `sources:`.
+   - For each `missing_from_sources` entry: suggest adding to `sources:`.
+3. Append one `log.md` entry summarizing the audit and any suggested follow-ups.
+
+## Stop conditions
+None — audit always completes.
+
+## Forbidden
+- Auto-applying suggested fixes (audit is observation-only).

package/skills/skills/wiki-canvas/SKILL.md

@@ -0,0 +1,57 @@
+---
+version: 0.2.1
+name: wiki-canvas
+description: Generate an Obsidian Canvas visualization of the vault graph. Runs skillwiki graph build then skillwiki canvas generate.
+---
+
+# wiki-canvas
+
+## When This Skill Activates
+
+- User wants a visual map of their vault structure.
+- User asks to see how pages are connected.
+- After significant ingestion or restructuring, user wants an updated overview.
+- User mentions Obsidian Canvas or visual vault exploration.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path`.
+1. Run `skillwiki graph build <vault>` to produce the adjacency graph at `<vault>/.skillwiki/graph.json`. If graph.json already exists and the vault has not changed, this step can be skipped — but regenerate after any ingestion, reingest, archive, or restructuring to keep the canvas current.
+2. Run `skillwiki canvas generate <vault>`. This reads graph.json and writes `<vault>/vault-graph.canvas`.
+3. Present the result to the user: node count, edge count, and the output path.
+4. Advise the user on opening the canvas:
+   - In Obsidian, open the vault folder and click `vault-graph.canvas` in the file explorer, or use the Quick Switcher (`Cmd/Ctrl+O`) and search for "vault-graph".
+   - Nodes are arranged in columns by type: **entities** (red), **concepts** (green), **comparisons** (orange), **queries** (cyan), **meta** (purple). Unclassified pages appear in yellow in the comparisons column.
+   - Edges represent wikilink connections. Click any node to jump to the source page; drag to rearrange.
+   - Zoom and pan with mouse/trackpad to explore large vaults.
+5. Append one `log.md` entry noting the canvas generation (node/edge counts).
+
+## When to regenerate
+
+Regenerate the canvas after any of these events:
+- One or more `wiki-ingest` runs that added new pages.
+- `wiki-reingest` or `wiki-archive` that changed or removed pages.
+- Manual restructuring of the vault directories.
+- After running `wiki-lint` and fixing structural issues.
+
+Stale canvases are not harmful, but they will not reflect new or removed pages until regenerated.
+
+## Future: Bases view
+
+Obsidian Bases (`.base` files) offer tabular data views of vault content. A Bases generation capability may be added in a future version to complement the graph canvas with filterable, sortable table layouts. For now, the canvas is the primary visualization.
+
+## Stop conditions
+
+- `skillwiki graph build` returns a non-zero exit code — investigate before continuing.
+- `graph.json` is missing or invalid — the canvas command will surface the error; direct the user to run `skillwiki graph build` first.
+- User cancels before generation.
+
+## Forbidden
+
+- Modifying `vault-graph.canvas` by hand after generation — regenerate it instead.
+- Regenating the canvas without first regenerating graph.json when the vault has changed.
+- Deleting the previous canvas without generating a replacement.

package/skills/skills/wiki-crystallize/SKILL.md

@@ -0,0 +1,29 @@
+---
+version: 0.2.1
+name: wiki-crystallize
+description: Distill the current working session into a typed-knowledge page with provenance.
+---
+# wiki-crystallize
+## When This Skill Activates
+- User asks to crystallize, consolidate, or promote draft material into typed-knowledge pages.
+- A vault is resolvable (see step 0).
+## Output language
+Run `skillwiki lang` at the start. Generate consolidated page 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. If cwd is inside `projects/{slug}/`, also read project README and recent work logs.
+## Steps
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. Identify type: entity / concept / comparison / query / summary.
+2. Set `provenance:`. Default `research`. If in project context: `project` with `provenance_projects: ["[[slug]]"]`.
+3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
+- `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
+- For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
+4. `skillwiki validate <page>`. If non-zero, STOP.
+5. Apply writes: page → `index.md` → `log.md`.
+## Stop conditions
+- `validate` non-zero.
+- Missing `provenance:` for project-context runs.
+## Forbidden
+- Filing without explicit `provenance:`.
+- Updating `index.md` before `validate` passes.
+- Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.

package/skills/skills/wiki-gate-plan-mode/SKILL.md

@@ -0,0 +1,80 @@
+---
+version: 0.2.1
+name: wiki-gate-plan-mode
+description: Toggle EnterPlanMode gating — force superpowers planning skills instead of built-in plan mode
+---
+
+# wiki-gate-plan-mode
+
+Gate the agent away from Claude Code's built-in `EnterPlanMode` tool, forcing
+all planning through `superpowers:brainstorming` → `superpowers:writing-plans`
+(or a configurable pipeline). Uses `permissions.deny` for two-layer enforcement:
+the tool is removed from the model's context before it ever sees it.
+
+## When This Skill Activates
+
+- User says "gate plan mode", "disable EnterPlanMode", "force superpowers planning"
+- User asks to toggle, check, or configure plan-mode gating
+- User wants to enforce structured planning workflows in a project
+
+## Pre-orientation reads
+
+None for the first run.
+
+## Steps
+
+0. **Parse arguments.** Accept one of:
+   - `on` — enable gating (add EnterPlanMode to deny)
+   - `off` — disable gating (remove EnterPlanMode from deny)
+   - `status` (default if no argument) — report current state
+
+1. **Locate settings file.** Check in this order:
+   - `~/.claude/settings.json` (user-level, global — primary target for plan-mode gating)
+   - `.claude/settings.json` (project-level, checked into repo — use if user specifies project scope)
+   If the target file does not exist, create it with `{ "permissions": { "deny": [] } }`.
+
+2. **Read current state.** Parse the settings JSON. Check whether `"EnterPlanMode"` is present in `permissions.deny[]`.
+
+3. **Apply the requested action:**
+
+   **`on`:**
+   - If `"EnterPlanMode"` is already in `permissions.deny`, report "already gated" and stop.
+   - Otherwise, add `"EnterPlanMode"` to `permissions.deny[]`. Create the array if absent.
+   - Write the updated JSON back, preserving formatting.
+   - Report: "EnterPlanMode gated — agent will use superpowers planning skills."
+
+   **`off`:**
+   - If `"EnterPlanMode"` is not in `permissions.deny`, report "already ungated" and stop.
+   - Otherwise, remove `"EnterPlanMode"` from `permissions.deny[]`. If the array is now empty, remove the `deny` key.
+   - Write the updated JSON back.
+   - Report: "EnterPlanMode ungated — built-in plan mode is available."
+
+   **`status`:**
+   - Check both `~/.claude/settings.json` and `.claude/settings.json`.
+   - Report whether EnterPlanMode is currently gated or ungated.
+   - If gated, list which settings file contains the deny entry.
+
+4. **Suggest CLAUDE.md directive (on action only).** After enabling gating, check whether the project's `CLAUDE.md` contains a planning directive (search for "EnterPlanMode" or "superpowers:brainstorming"). If not found, suggest adding:
+
+   ```
+   ## Planning
+
+   Use superpowers:brainstorming → superpowers:writing-plans for all planning. EnterPlanMode is disabled.
+   ```
+
+   Do NOT edit CLAUDE.md automatically — only suggest.
+
+## Schema Warning
+
+The JSON Schema Store's `claude-code-settings.json` schema has a closed regex for `permissions.deny` that includes `ExitPlanMode` but **omits `EnterPlanMode`**. IDEs (VS Code, JetBrains) will show a validation warning. This is a schema staleness issue, not a runtime issue — Claude Code's runtime accepts `EnterPlanMode` in `permissions.deny` and enforces it correctly. See `[[queries/claude-code-plan-mode-schema-validation]]` for full analysis.
+
+## Stop conditions
+
+- No project directory found (not inside a git repo or project).
+- Settings file exists but is not valid JSON and cannot be parsed.
+
+## Forbidden
+
+- Do not add any tool other than `EnterPlanMode` to the deny list.
+- Do not modify CLAUDE.md automatically — only suggest changes.
+- Do not remove other entries from `permissions.deny` when toggling off — only remove `EnterPlanMode`.

package/skills/skills/wiki-ingest/SKILL.md

@@ -0,0 +1,55 @@
+---
+version: 0.2.1
+name: wiki-ingest
+description: Convert URLs, files, or pasted text into typed-knowledge pages with raw provenance. Supports single and batch mode.
+---
+# wiki-ingest
+## When This Skill Activates
+- User shares a URL, paste, or local file to capture in the vault.
+- The output target is `entities/`, `concepts/`, `comparisons/`, or `queries/`.
+- A vault is resolvable (see step 0).
+## Output language
+Run `skillwiki lang` at the start. Generate page-body prose, narrative sections, 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 (mandatory before any write)
+1. `SCHEMA.md`
+2. `index.md`
+3. Last 20–30 entries of `log.md`
+4. (Project context only) `projects/{slug}/README.md` and last ~5 work-item logs.
+## Steps (in order — N6, N7, N8)
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
+1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
+2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
+3. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
+4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers). Every page MUST include:
+- `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
+- For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
+5. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
+6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.
+7. **Confidence flag.** If only one source is cited, set `confidence: low`.
+## Provenance defaults
+- Default `provenance: research`.
+- If cwd is inside `projects/{slug}/`, set `provenance: project` and add `provenance_projects: ["[[slug]]"]`.
+## Raw Data Locality
+Raw ephemeral data (market feeds, logs, transient JSON) must be written to the **project local** `raw/` directory, NOT the cloud-mounted wiki path. See `references/raw-data-locality.md` for the full pattern.
+**Quick rule:**
+- Transient data → `~/projects/{slug}/raw/` (local, git-tracked)
+- Compound pages → `~/wiki/projects/{slug}/compound/` (cloud, durable)
+## Stop conditions
+- `fetch-guard` non-zero.
+- Fetch timeout / size limit exceeded.
+- `validate` non-zero on any page.
+- sha256 already exists in vault for the same source.
+## Forbidden
+- Skipping `fetch-guard`.
+- Updating `index.md` or `log.md` before all pages validate.
+- Modifying any existing file in `raw/`.
+- Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
+- Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
+## Batch Mode
+When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):
+1. **Loop per source.** Execute steps 1–5 for each source individually (guard → fetch → hash → generate → validate).
+2. **Accumulate, don't write yet.** Collect all raw files and pages in memory. Do not write `index.md` or `log.md` until every source has validated.
+3. **Fail fast.** If any page fails validation, STOP. Report all failures. Do not write index/log for any source.
+4. **Deduplication.** Before writing each raw file, check `sha256` against existing vault raw sources. Skip sources whose content is already present.
+5. **Single index/log update.** After all sources validate, write all raw files and pages, then update `index.md` and `log.md` once.
+6. **Progress.** After each source completes validation, report progress (e.g., "Validated 3/10 sources").

package/skills/skills/wiki-init/SKILL.md

@@ -0,0 +1,37 @@
+---
+version: 0.2.1
+name: wiki-init
+description: Bootstrap a CodeWiki vault — domain-aware SCHEMA.md, index.md, log.md, and ~/.skillwiki/.env binding. Use when starting a fresh vault.
+---
+
+# wiki-init
+
+## When This Skill Activates
+
+- User asks to create, build, or start a vault, wiki, or knowledge base.
+- The resolved vault path (see step 0) does not yet contain SCHEMA.md.
+
+## Pre-orientation reads
+
+None for the first run.
+
+## Steps
+
+0. **Resolve target.** Run `skillwiki path --init-time` to see what target the CLI will pick. Confirm with the user, or override with `--target <dir>`.
+1. Verify target is empty or has no SCHEMA.md.
+2. Ask the domain question: "What knowledge domain will this vault cover? Be specific."
+3. Propose a 10–15 tag taxonomy tailored to the domain. Confirm or accept the user's revision.
+4. Ask the language question: "What language should generated page prose use? Default is `en`. Aliases like `chinese-traditional` or `zh-Hant` are accepted."
+5. Run `skillwiki init --target <dir> --domain "<answer>" --taxonomy "<comma list>" --lang "<lang>"`.
+6. **Suggest first sources.** Propose 3–5 initial sources (URLs, papers, articles) appropriate to the domain. Prompt the user to provide the first one to ingest, then hand off to wiki-ingest.
+
+## Stop conditions
+
+- Target non-empty and `--force` not consented.
+- `~/.skillwiki/.env` already binds a different vault or language and `--force` not consented.
+
+## Forbidden
+
+- Modifying anything outside the target directory or `~/.skillwiki/.env`.
+- Writing to `~/.hermes/.env` (read-only fallback).
+- Running any LLM-driven content generation in this skill.

package/skills/skills/wiki-lint/SKILL.md

@@ -0,0 +1,25 @@
+---
+version: 0.2.2
+name: wiki-lint
+description: Vault health check via the umbrella `skillwiki lint` subcommand. Read-only by default; rotation requires explicit user consent.
+---
+# wiki-lint
+## When This Skill Activates
+- User asks for a vault health report, lint, or audit.
+- Periodic maintenance.
+## Pre-orientation reads
+Standard four reads.
+## Steps
+0. Resolve vault: `skillwiki path` (record source for context).
+- **CRITICAL**: Verify the correct vault when the user has multiple wiki instances (e.g., ~/wiki vs ~/wiki-fin). User may explicitly specify which vault to target — confirm before destructive operations.
+1. Run `skillwiki lint <vault>`. Read the JSON.
+2. Reason over findings; present grouped by severity with concrete suggested actions per kind. If the CLI was recently updated with new lint checks, re-running lint on the full vault may flag pre-existing pages that predate the new rule — treat these as legitimate findings, not false positives.
+3. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
+4. **Post-migration verification**: If the user recently migrated content (e.g., moved entity/concept pages to another vault), re-run lint and verify that broken_wikilinks count decreased. Remaining broken links for migrated content indicate pages still referencing the moved files — these should be cleaned up (remove citations or migrate the referencing pages too).
+5. Append one `log.md` entry summarizing the lint counts (errors/warnings/info).
+## Stop conditions
+None — lint reports all findings even on per-page errors.
+## Forbidden
+- Auto-rotating logs.
+- Auto-updating sha256 fields.
+- Modifying any page beyond the lint summary entry in `log.md`.

package/skills/skills/wiki-query/SKILL.md

@@ -0,0 +1,36 @@
+---
+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×
+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/skills/wiki-reingest/SKILL.md

@@ -0,0 +1,55 @@
+---
+version: 0.2.1
+name: wiki-reingest
+description: Detect and act on source drift. Runs skillwiki drift, reviews changes, archives old raw + ingests new content.
+---
+
+# wiki-reingest
+
+## When This Skill Activates
+
+- User wants to check if any vault sources have changed since ingestion.
+- Periodic drift check during lint or maintenance cycles.
+- User explicitly asks to re-ingest a specific source.
+
+## Output language
+
+Run `skillwiki lang` at the start. Generate log entries in the resolved language.
+
+## Pre-orientation reads
+
+Standard four reads (SCHEMA, index, log, project context if applicable).
+
+## Steps
+
+0. Resolve vault: `skillwiki path` and `skillwiki lang`.
+1. Run `skillwiki drift [vault]`. Read the JSON output.
+2. Present findings grouped by status:
+   - **drifted:** Source content has changed. Show stored vs current sha256.
+   - **fetch_failed:** Could not re-fetch. Show error details.
+   - **unchanged:** No action needed.
+3. For each drifted source, ask the user: archive old + ingest new, or skip?
+4. If the user approves re-ingest for a source:
+   a. Run `skillwiki archive <raw-path>` to archive the old raw file.
+   b. Follow the `wiki-ingest` skill to ingest the updated content as a new raw file.
+   c. Update any concept/entity pages that cite the old source to reference the new one.
+5. Append a `log.md` entry summarizing: scanned, drifted, re-ingested, skipped.
+
+## N9 Compliance
+
+Raw files are immutable (N9). Re-ingest never modifies an existing raw file. Instead:
+- Archive the old raw file (moves to `_archive/raw/`).
+- Create a new raw file with updated content and new sha256.
+- This preserves full provenance history.
+
+## Stop conditions
+
+- `skillwiki drift` returns non-zero exit code other than DRIFT_DETECTED.
+- User declines all re-ingest actions.
+- No raw sources have `source_url` (nothing to check).
+
+## Forbidden
+
+- Modifying files in `raw/` directly (N9).
+- Re-ingesting without user approval for each drifted source.
+- Skipping the drift check and assuming sources have changed.

package/skills/skills/wiki-sync/SKILL.md

@@ -0,0 +1,240 @@
+---
+version: 0.6.1
+name: wiki-sync
+description: Safely sync the vault git repository — multi-session safe via advisory lockfile. Handles rebase conflict storms from archive-commit × snapshot-stream patterns. 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.
+- Multiple Claude Code sessions targeting the same vault.
+- Periodic maintenance before or after editing sessions.
+## Pre-orientation reads
+Standard four reads.
+## Steps
+0. Resolve vault: `skillwiki path` (record source for context).
+
+## Pre-flight peer check (multi-session safe)
+
+**Before any git stash or pull/push operation**, check for peer sessions:
+
+1. Run `skillwiki sync peers <vault>` to detect other sessions with active locks or recent `wiki-sync:*` stashes.
+2. If any non-self peer is present (locked or has stashes newer than 5 minutes):
+   - Surface the peer's session_id, PID, and summary to the user
+   - Ask the user to wait for the peer to finish, or pass `--force` to proceed anyway
+   - If `--force` is not given and peer is detected, **abort and exit**
+3. Acquire an advisory lock: `skillwiki sync lock <vault> --summary "wiki-sync <op>"` (where `<op>` is "pull" or "push")
+   - If lock is held (exit code 48), surface the holder (session_id, PID, summary) and abort
+4. **Always pair with unlock on exit** (success or error):
+   - `skillwiki sync unlock <vault>` in a finally block or error handler
+
+### Stash backlog warning
+
+On every invocation, count `wiki-sync:*` stashes older than 24 hours via `skillwiki sync peers`:
+- If any old stashes exist, warn the user: "Found N wiki-sync stash(es) older than 24h — audit and clean before proceeding"
+- **Do not auto-drop old stashes** — the user audits each one
+
+## Sync workflow
+
+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).
+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)"`
+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. Run `skillwiki sync status <vault> --include-stashes` to check for untracked file collisions (see Untracked file fingerprint below).
+10. If vault is dirty, stash first with the identifiable name format:
+    ```bash
+    VAULT="<vault>"
+    SESSION_ID="$(echo $CLAUDE_SESSION_ID)" # or fallback to PID/hostname
+    CWD_HASH="$(echo -n "$VAULT" | sha256sum | cut -c1-8)"
+    ISO_TS="$(date -u +%Y-%m-%dT%H:%MZ)"
+    MSG="wiki-sync:${SESSION_ID}:${CWD_HASH}:${ISO_TS}:pre-pull"
+    git -C "$VAULT" stash push -m "$MSG"
+    ```
+11. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
+12. If a stash was created, pop it: `git -C <vault> stash pop`.
+13. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
+14. Run `skillwiki lint <vault>` after pull to verify vault integrity.
+15. Append one `log.md` entry summarizing: commits pulled, lint result, any conflicts.
+
+### Pull-then-push workflow
+16. Execute the pull workflow (steps 9-14) first.
+17. Then execute the push workflow (steps 4-8).
+
+## Stash naming convention
+
+When `wiki-sync` creates a stash, use the identifiable message format:
+
+```
+wiki-sync:{session_id}:{cwd_hash}:{iso8601_timestamp}:{summary}
+```
+
+- **session_id**: prefer `$CLAUDE_SESSION_ID` env var if set, else `$$` (shell PID), else `unknown`
+- **cwd_hash**: first 8 chars of sha256(`$VAULT` path)
+- **iso8601_timestamp**: e.g., `2026-05-23T03:25:00Z` (UTC)
+- **summary**: short label like `pre-pull`, `pre-push`, or custom reason
+
+This allows any session to list `git stash list` and identify which stash came from which session/working directory.
+
+## Untracked file fingerprint (pre-pull)
+
+Before `git pull --rebase`, check for untracked files that exist on the remote and may collide:
+
+```bash
+for f in $(git -C "$VAULT" ls-files --others --exclude-standard); do
+  if git -C "$VAULT" cat-file -e "origin/main:$f" 2>/dev/null; then
+    # File exists on remote; check if identical
+    if diff -q <(git -C "$VAULT" show "origin/main:$f") "$VAULT/$f" >/dev/null 2>&1; then
+      # Byte-identical — safe to remove (presync artifact)
+      rm "$VAULT/$f"
+    else
+      # DIFFERENT — surface to user, DO NOT silently --include-untracked
+      echo "UNTRACKED COLLISION: $f differs from origin/main — surface to user for resolution"
+    fi
+  fi
+  # If file does not exist on remote, leave it alone (pull won't touch it)
+done
+```
+
+If collisions are found (different content), ask the user to resolve manually before pulling.
+
+## 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.
+
+### 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
+```
+- After resolving conflicts, run `skillwiki lint <vault>` to verify before committing.
+
+### Modify/delete conflicts
+
+When `git pull --rebase` reports `CONFLICT (modify/delete)`:
+
+1. Identify the commit that deleted the file:
+   ```bash
+   git -C "$VAULT" log --diff-filter=D --pretty=oneline -- <path>
+   ```
+2. Read the commit message and any retro / log entry referencing it to determine if the deletion was intentional or accidental.
+3. Decide:
+   - `git -C "$VAULT" rm <path>` — accept the deletion (rebase continues)
+   - `git -C "$VAULT" add <path>` — keep the local restoration (rebase continues)
+4. `git -C "$VAULT" rebase --continue`.
+
+### Rebase conflict storm (archive commits × snapshot stream)
+
+When many local archive-only commits (e.g., `archive: moved X to _archive/`) are rebased over an origin/main that receives frequent snapshot commits (e.g., sg01 `Snapshot YYYYMMDD_HHMMSS`), every archive commit re-triggers the same content conflicts on shared files (`log.md`, `knowledge.md`, `spec.md`). This is predictable and can be resolved systematically.
+
+**Detection**: 3+ consecutive rebase stops on commits whose message matches `^archive: moved`.
+
+**Resolution**: For each archive commit during the storm:
+
+```bash
+# Apply --ours to all conflicting files (keep HEAD = origin/main + snapshots)
+for f in $(git -C "$VAULT" diff --name-only --diff-filter=U); do
+  git -C "$VAULT" checkout --ours "$f" && git -C "$VAULT" add "$f"
+done
+git -C "$VAULT" rebase --continue
+```
+
+**After the storm passes** (non-archive commits or clean rebase), pop the stash and handle any remaining conflicts per the normal Conflict Resolution sections above.
+
+**Prevention**:
+- Sync more frequently — don't let local fall >5 commits behind origin/main
+- Bundle archive commits — `skillwiki archive --batch` groups 5-10 transcript archives into one commit, reducing rebase surface
+- For vaults with snapshot cron, prefer smaller, more frequent syncs over large batch rebases
+
+See `concepts/wiki-sync-rebase-conflict-storm-pattern.md` for detailed analysis.
+
+## 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.
+- Peer lock is held or peer stashes exist — abort and ask the user to wait or pass `--force`.
+- Untracked file collision detected on pull — surface to user for manual resolution.
+
+## Forbidden
+- Pushing when lint errors exist.
+- Auto-resolving body conflicts without user review.
+- Force-pushing (`git push --force`).
+- Modifying files in `raw/` to resolve conflicts (N9 — archive and re-ingest instead).
+- Stashing without the `wiki-sync:...` name format (breaks peer detection).
+- Force-deleting a peer's lockfile (use `--force` only if peer is confirmed dead).