skillwiki 0.2.1-beta.16 → 0.2.1-beta.21

package/dist/git-M4WGJ5G3.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  git,
+  gitStrict
+} from "./chunk-TPS5XD2J.js";
+export {
+  git,
+  gitStrict
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.16",
+  "version": "0.2.1-beta.21",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"
@@ -19,6 +19,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1045.0",
+    "@aws-sdk/credential-provider-env": "^3.972.34",
     "commander": "^12.1.0",
     "js-yaml": "^4.1.0",
     "zod": "^3.23.0"

package/skills/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.16",
+  "version": "0.2.1-beta.21",
   "skills": "./",
-  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 15 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
+  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 17 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.1-beta.16",
+  "version": "0.2.1-beta.21",
   "private": true,
   "files": [
     "wiki-*",

package/skills/proj-decide/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-decide
 description: Write an Architectural Decision Record (ADR). If the decision generalizes, also create a concepts/ page.
 ---

package/skills/proj-distill/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-distill
 description: 2-step distillation (E4) — analyze project compound entry, then generate a vault concept page with provenance.
 ---

package/skills/proj-init/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-init
 description: Bootstrap a project workspace at projects/{slug}/ with README, requirements/, architecture/, work/, compound/.
 ---
@@ -18,7 +19,7 @@ Standard four reads (vault SCHEMA, index, log) — no project context yet.
 ## Steps
 1. Verify `projects/{slug}/` does not exist.
 2. Create folders: `projects/{slug}/{requirements,architecture,work,compound}/`.
-3. Render `projects/{slug}/README.md` from `project-README.md` template, filling `{{slug}}` and `{{date}}`.
+3. Render `projects/{slug}/README.md` from `project-README.md` template, filling `{{slug}}` and `{{date}}`. The template includes a `## Knowledge Pages` section with a placeholder; agents populate it on first ingest via `skillwiki project-index`.
 4. Update vault `index.md` "Projects" section: add `- [[projects/{slug}]]`.
 5. Append vault `log.md` entry: "Project {slug} initialized."
 

package/skills/proj-work/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: proj-work
 description: Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming/writing-plans output paths.
 ---

package/skills/using-skillwiki/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: using-skillwiki
 description: Invoke at session start or when knowledge-base tasks arise — maps all wiki-*/proj-* skills and teaches the skillwiki CLI workflow
 ---
@@ -25,6 +26,8 @@ Invoke a skillwiki skill when the user:
 - Needs to detect source drift or re-ingest updated content
 - Has a spec/plan in a non-skillwiki format (CodeStable, RFC, AIDE)
 - Asks about their skillwiki configuration or setup health
+- Wants to sync vault changes to/from a git remote
+- Wants to visualize the vault graph as an Obsidian Canvas
 
 ## Vault Structure
 
@@ -59,7 +62,7 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 
 | Entry | When | What happens |
 |-------|------|-------------|
-| `/wiki-add-task <text>` | You're in a Claude session | Appends entry to `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` |
+| `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
 | Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create/edit any `.md` file in `raw/transcripts/` — dev-loop discovers it on next cycle |
 | Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
 
@@ -80,13 +83,15 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
 | `proj-work` | Open or run a work item under a project's work/ directory |
 | `proj-distill` | Distill project compound entries into vault concept pages |
+| `wiki-sync` | Safely sync vault git repository — push/pull with lint guards and conflict resolution |
+| `wiki-canvas` | Generate Obsidian Canvas visualization from vault graph data |
 | `proj-decide` | Write an Architectural Decision Record (ADR) |
 
 ## CLI Backbone
 
 All skills are backed by the `skillwiki` CLI — a deterministic tool with no LLM calls. It handles path resolution, config management, validation, and linting. Skills invoke it via Bash for the mechanical parts and use Claude for the creative parts.
 
-Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`.
+Key CLI subcommands: `init`, `lint`, `config`, `doctor`, `path`, `lang`, `install`, `graph build`, `archive`, `drift`, `compound`, `tag-sync`, `sync status`, `seed`, `stale`, `observe`, `canvas generate`.
 
 Run `skillwiki doctor` to diagnose setup issues. Run `skillwiki config list` to see current configuration.
 

package/skills/wiki-adapter-prd/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-adapter-prd
 description: Map foreign PRD formats (CodeStable, RFCs, structured markdown) into skillwiki raw + typed-knowledge pages.
 ---

package/skills/wiki-add-task/SKILL.md

@@ -1,6 +1,7 @@
 ---
+version: 0.2.1
 name: wiki-add-task
-description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault via /wiki-add-task or filesystem drop.
+description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault with ad-hoc capture frontmatter and descriptive filenames.
 ---
 
 # wiki-add-task
@@ -9,7 +10,7 @@ Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points
 
 | Entry | When | What happens |
 |-------|------|-------------|
-| `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with raw-valid frontmatter |
+| `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with ad-hoc capture frontmatter |
 | Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create any `.md` file in `raw/transcripts/` using the vault template — dev-loop discovers it on next cycle |
 | Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
 
@@ -30,14 +31,12 @@ Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the r
    - `text` — the idea/bug/task/note content (required)
    - `type` — one of: `idea`, `bug`, `task`, `note` (default: `idea`)
    - `project` — optional project slug to cross-reference (e.g., `llm-wiki`)
-2. **Build filename.** Derive a short slug from the text (lowercase, hyphenated, max 8 words). The capture file is `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`. Each capture gets its own file — never append to an existing file.
-3. **Write frontmatter.** Create the file with raw-source frontmatter:
+2. **Build filename.** Derive a slug from the first ~6 words of the text (lowercased, hyphens for spaces, non-alphanumeric stripped). The capture file is `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`. Each capture gets its own file — never append to an existing file.
+3. **Write frontmatter.** Create the file with ad-hoc capture frontmatter:
    ```yaml
    ---
    source_url:
    ingested: YYYY-MM-DD
-   ingested_by: manual
-   sha256:
    kind: {type}
    project: "[[{slug}]]"
    ---
@@ -45,8 +44,8 @@ Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the r
    - Set `kind` to the parsed type (`idea`, `bug`, `task`, `note`).
    - If a `project` slug was provided, set `project: "[[slug]]"`.
    - If no project, omit the `project` field entirely.
-   - Leave `sha256` empty for now — step 5 fills it in.
    - `source_url` is null (these are locally originated captures).
+   - No `sha256` — ad-hoc captures are mutable working notes, not immutable sources.
 4. **Write body.** Below the frontmatter, write:
    ```markdown
    # {type}: {text}
@@ -54,14 +53,13 @@ Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the r
    {text}
    ```
    Use the resolved output language for any prose. The type label and frontmatter stay English.
-5. **Compute and write sha256.** Run `skillwiki hash <file>` to get the SHA-256 of the body. Update the `sha256:` field in the frontmatter with the computed value. This makes the file validate as a raw source.
-6. **Cross-reference (optional).** If a `project` slug was provided:
+5. **Cross-reference (optional).** If a `project` slug was provided:
    - Check that `projects/{slug}/` exists in the vault.
    - Append a one-line reference to the project's compound notes:
      `- [YYYY-MM-DD] capture: [text (first 60 chars)] → raw/transcripts/YYYY-MM-DD-{type}-{slug}.md`
    - Do NOT create a full work item (that's `proj-work`'s job).
-7. **Update log.md.** Append: `## [YYYY-MM-DD] capture | [type]: [text (first 60 chars)]`
-8. **Confirm to user.** Report what was captured and where. Suggest next steps:
+6. **Update log.md.** Append: `## [YYYY-MM-DD] capture | [type]: [text (first 60 chars)]`
+7. **Confirm to user.** Report what was captured and where. Suggest next steps:
    - If `type: idea` → "Consider ingesting related sources to develop this idea."
    - If `type: bug` → "Use proj-work to create a bug-fix work item."
    - If `type: task` → "Use proj-work to track this task through the dev loop."
@@ -69,14 +67,12 @@ Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the r
 
 ## Capture file format
 
-Each capture is a standalone raw source file with valid frontmatter:
+Each capture is a standalone file with ad-hoc capture frontmatter:
 
 ```yaml
 ---
 source_url:
 ingested: 2026-05-08
-ingested_by: manual
-sha256: <64-char hex computed over body>
 kind: idea
 project: "[[llm-wiki]]"
 ---
@@ -90,6 +86,8 @@ The `kind` field uses the capture type and must be one of: `idea`, `bug`, `task`
 
 The `project` and `kind` fields can be set independently — they do not require `work_item`. The `work_item` field is only used when the raw source is directly tied to a project work item (set by `proj-work`).
 
+Ad-hoc captures omit `sha256` — they are mutable working notes, not immutable sources. The `sha256` field is reserved for ingested raw sources that require integrity verification.
+
 ## Stop conditions
 
 - `skillwiki path` returns NO_VAULT_CONFIGURED.
@@ -108,9 +106,8 @@ The `project` and `kind` fields can be set independently — they do not require
 When you're not in a Claude session, drop files directly into `raw/transcripts/`:
 
 1. Create a `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-08-idea-fix-template.md`)
-2. Use the vault template at `_Templates/tpl-ad-hoc-capture.md` for frontmatter scaffolding
+2. Use ad-hoc capture frontmatter: `source_url:`, `ingested:`, `kind:`, and optionally `project:`
 3. Write your idea/bug/task/note below the frontmatter
-4. Run `skillwiki hash <file>` when you're back in a session to fill in sha256
 
 No special format required — the dev-loop QUERY step will discover new files on the next cycle and surface them as claimable work. Mark the type with a heading like `## idea`, `## bug`, `## task`, or just write freeform.
 

package/skills/wiki-archive/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-archive
 description: Archive a superseded typed-knowledge page. Moves page to _archive/, removes from index.md, logs the action.
 ---

package/skills/wiki-audit/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-audit
 description: Verify per-page that every ^[raw/...] resolves and sources frontmatter matches the body.
 ---

package/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/wiki-crystallize/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-crystallize
 description: Distill the current working session into a typed-knowledge page with provenance.
 ---

package/skills/wiki-ingest/SKILL.md

@@ -1,4 +1,5 @@
 ---
+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.
 ---

package/skills/wiki-init/SKILL.md

@@ -1,4 +1,5 @@
 ---
+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.
 ---

package/skills/wiki-lint/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-lint
 description: Vault health check via the umbrella `skillwiki lint` subcommand. Read-only by default; rotation requires explicit user consent.
 ---

package/skills/wiki-query/SKILL.md

@@ -1,4 +1,5 @@
 ---
+version: 0.2.1
 name: wiki-query
 description: Search the vault and synthesize an answer with E2 4-signal ranking. Optional file to queries/ or comparisons/.
 ---

package/skills/wiki-reingest/SKILL.md

@@ -1,4 +1,5 @@
 ---
+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.
 ---

package/skills/wiki-sync/SKILL.md

@@ -0,0 +1,91 @@
+---
+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).
+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. 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.
+- **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.
+
+## 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.
+
+## 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`).
+- Modifying files in `raw/` to resolve conflicts (N9 — archive and re-ingest instead).

package/templates/index.md

@@ -14,6 +14,9 @@
 ## Queries
 <!-- queries listed here -->
 
+## Summaries
+<!-- summaries listed here -->
+
 ## Projects
 <!-- registered projects listed here -->
 

package/templates/project-README.md

@@ -13,6 +13,8 @@
 - `work/YYYY-MM-DD-{slug}/` — per-work-item folders containing `spec.md`, `plan.md`, `log.md`.
 - `compound/` — project-local concrete learnings.
 
-## Knowledge
+## Knowledge Pages
+
+> Auto-populated: concept and entity pages with `provenance_projects: [[{{slug}}]]` are listed here.
 
 Run `skillwiki project-index {{slug}} --apply` to generate `knowledge.md` listing all Layer 2 pages that reference `[[{{slug}}]]` in their provenance_projects.