skillwiki 0.2.0-beta.2 → 0.2.0-beta.21

package/skills/wiki-ingest/SKILL.md

@@ -0,0 +1,58 @@
+---
+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 `npx 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 `npx 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).
+5. **Validate.** For each generated page: run `npx 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]]"]`.
+
+## 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/`.
+
+## 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/wiki-init/SKILL.md

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

@@ -0,0 +1,33 @@
+---
+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).
+1. Run `skillwiki lint <vault>`. Read the JSON.
+2. Reason over findings; present grouped by severity with concrete suggested actions per kind.
+3. If `log_rotate_needed` is present and the user consents, run `skillwiki log-rotate <vault> --apply`. Otherwise leave alone.
+4. 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/wiki-query/SKILL.md

@@ -0,0 +1,40 @@
+---
+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: `npx skillwiki graph build <vault>`.
+3. **Compute overlap.** `npx 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.
+
+## Forbidden
+- Filing without `validate` passing.
+- Skipping the orientation reads even for "quick" queries.

package/skills/wiki-reingest/SKILL.md

@@ -0,0 +1,54 @@
+---
+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/templates/SCHEMA.md

@@ -49,5 +49,22 @@ Rule: every tag on every page MUST appear in this taxonomy. Add new tags here fi
 
 - File names: lowercase-hyphenated, no spaces.
 - Wikilinks in YAML: quoted, `"[[name]]"`. Body wikilinks: unquoted `[[name]]`.
-- Citations in body: `^[raw/...]` markers; every entry in `sources:` MUST appear in body.
+- Citations in body: `^[raw/...]` markers at paragraph-end; every entry in `sources:` MUST appear in body and in `## Sources` footer.
+- Legacy inline `^[raw/...]` markers remain valid; `migrate-citations` converts them.
 - sha256 in `raw/` frontmatter is computed by `skillwiki hash` over body bytes after closing `---`.
+
+## Obsidian Integration
+
+- **Attachment folder:** `raw/assets/` — binary assets (images, diagrams) live here.
+  Set Obsidian's "Attachment folder path" to `raw/assets` for automatic filing.
+- **Dataview queries** (read-only; do not replace index.md):
+
+```dataview
+LIST WHERE type = "concept" AND contains(tags, "architecture")
+```
+
+```dataview
+TABLE updated, length(sources) AS sources
+WHERE file.folder = "concepts"
+SORT updated DESC
+```