skillwiki 0.2.3 → 0.2.5

package/dist/auto-update-bg.js

@@ -14,7 +14,7 @@ if (!home || !currentVersion) process.exit(0);
 var cacheFile = join(home, ".skillwiki", ".update-cache.json");
 setTimeout(() => process.exit(0), 3e4);
 try {
-  const latest = execSync("npm view skillwiki@beta version", {
+  const latest = execSync("npm view skillwiki@latest version", {
     encoding: "utf8",
     timeout: 15e3
   }).trim();
@@ -25,7 +25,7 @@ try {
     currentVersion
   };
   if (semverGt(latest, currentVersion)) {
-    execSync("npm install -g skillwiki@beta", {
+    execSync("npm install -g skillwiki@latest", {
       stdio: "ignore",
       timeout: 6e4
     });

package/dist/cli.js

@@ -2239,7 +2239,7 @@ function extractSourceEntries(rawFm) {
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
 var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation"];
+var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "missing_diagram"];
 async function runLint(input) {
   const buckets = {};
   const fixed = [];
@@ -2302,6 +2302,8 @@ async function runLint(input) {
     const fmWikilinkFlags = [];
     const wikilinkCitationFlags = [];
     const brokenSourceFlags = [];
+    const missingTldrFlags = [];
+    const missingDiagramFlags = [];
     for (const page of scan.data.typedKnowledge) {
       const text = await readPage(page);
       const split = splitFrontmatter(text);
@@ -2332,6 +2334,13 @@ async function runLint(input) {
       const bodyLines = body.split("\n").filter((l) => l.trim().length > 0).length;
       const hasOverview = /^## Overview/m.test(body);
       if (!hasOverview) noOverview.push(page.relPath);
+      const bodyFirst15 = body.split("\n").slice(0, 15).join("\n");
+      if (!/^##\s+TL;\s*DR/m.test(bodyFirst15)) missingTldrFlags.push(page.relPath);
+      const fmData = extractFrontmatter(text);
+      const pageTags = fmData.ok && Array.isArray(fmData.data.tags) ? fmData.data.tags : [];
+      if (pageTags.includes("architecture") && !body.includes("```mermaid")) {
+        missingDiagramFlags.push(page.relPath);
+      }
       if (bodyLines < STRUCT_MIN_BODY_LINES) {
         const hasRelated = /^## (Related|Relationships)/m.test(body);
         const sectionCount = (body.match(/^## /gm) ?? []).length;
@@ -2351,6 +2360,8 @@ async function runLint(input) {
     if (fmWikilinkFlags.length > 0) buckets.frontmatter_wikilink = fmWikilinkFlags;
     if (wikilinkCitationFlags.length > 0) buckets.wikilink_citation = wikilinkCitationFlags;
     if (brokenSourceFlags.length > 0) buckets.broken_sources = brokenSourceFlags;
+    if (missingTldrFlags.length > 0) buckets.missing_tldr = missingTldrFlags;
+    if (missingDiagramFlags.length > 0) buckets.missing_diagram = missingDiagramFlags;
     const workItemHealth = [];
     const workItemDirs = /* @__PURE__ */ new Map();
     for (const page of scan.data.workItems) {
@@ -2540,6 +2551,39 @@ ${trimmedBody}`;
       if (remaining.length > 0) buckets.missing_overview = remaining;
       else delete buckets.missing_overview;
     }
+    if (input.fix && missingTldrFlags.length > 0) {
+      for (const relPath of missingTldrFlags) {
+        try {
+          const absPath = `${input.vault}/${relPath}`;
+          const raw = await readFile13(absPath, "utf8");
+          const split = splitFrontmatter(raw);
+          if (!split.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const body = split.data.body;
+          const rawFm = split.data.rawFrontmatter;
+          const trimmedBody = body.replace(/^\n+/, "");
+          const newContent = `---
+${rawFm}
+---
+
+## TL;DR
+
+- Pending summary.
+
+${trimmedBody}`;
+          await writeFile7(absPath, newContent, "utf8");
+          fixed.push(relPath);
+        } catch {
+          unresolved.push(relPath);
+        }
+      }
+      const fixedSet = new Set(fixed);
+      const remaining = missingTldrFlags.filter((p) => !fixedSet.has(p));
+      if (remaining.length > 0) buckets.missing_tldr = remaining;
+      else delete buckets.missing_tldr;
+    }
     if (input.fix && wikilinkCitationFlags.length > 0) {
       const WIKILINK_RE = /\[\[raw\/([^\]|]+)(?:\|[^\]]*)?\]\]/g;
       const FENCE_RE2 = /```[\s\S]*?```/g;
@@ -3015,7 +3059,7 @@ function checkPluginVersionDrift(home, currentVersion) {
   if (pluginVersion === currentVersion) {
     return check("pass", "plugin_version_drift", "Plugin/CLI version", `Both at v${currentVersion}`);
   }
-  const updateCmd = semverGt(pluginVersion, currentVersion) ? "npm install -g skillwiki@beta" : "claude plugin update skillwiki@llm-wiki";
+  const updateCmd = semverGt(pluginVersion, currentVersion) ? "npm install -g skillwiki@latest" : "claude plugin update skillwiki@llm-wiki";
   return check(
     "warn",
     "plugin_version_drift",
@@ -3667,7 +3711,7 @@ async function runUpdate(input) {
     readFileSync6(new URL("../../package.json", import.meta.url), "utf8")
   );
   const currentVersion = pkg2.version;
-  const tag = input.distTag ?? "beta";
+  const tag = input.distTag ?? "latest";
   const target = join23(input.home, ".claude", "skills");
   let latest;
   try {
@@ -3761,7 +3805,7 @@ async function runSelfUpdate(input) {
     } else {
       source = "npm";
       try {
-        availableVersion = execSync3("npm view skillwiki@beta version", {
+        availableVersion = execSync3("npm view skillwiki@latest version", {
           encoding: "utf8",
           timeout: 15e3
         }).trim();
@@ -3831,7 +3875,7 @@ async function runSelfUpdate(input) {
   }
   let latestVersion;
   try {
-    latestVersion = execSync3("npm view skillwiki@beta version", {
+    latestVersion = execSync3("npm view skillwiki@latest version", {
       encoding: "utf8",
       timeout: 15e3
     }).trim();
@@ -3849,12 +3893,12 @@ async function runSelfUpdate(input) {
         currentVersion,
         availableVersion: latestVersion,
         updateAvailable: false,
-        humanHint: `Already on latest beta: v${currentVersion}`
+        humanHint: `Already on latest: v${currentVersion}`
       })
     };
   }
   try {
-    execSync3("npm install -g skillwiki@beta", {
+    execSync3("npm install -g skillwiki@latest", {
       stdio: "pipe",
       timeout: 6e4
     });
@@ -3872,7 +3916,7 @@ async function runSelfUpdate(input) {
       availableVersion: latestVersion,
       updateAvailable: true,
       newVersion: latestVersion,
-      humanHint: `Updated skillwiki ${currentVersion} \u2192 ${latestVersion} via npm@beta`
+      humanHint: `Updated skillwiki ${currentVersion} \u2192 ${latestVersion} via npm@latest`
     })
   };
 }
@@ -5973,11 +6017,11 @@ program.command("frontmatter-fix [vault]").description("fix common frontmatter i
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runFrontmatterFix({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
 });
-program.command("update").description("update skillwiki CLI to the latest version").option("--tag <tag>", "npm dist-tag", "beta").action(async (opts) => emit(await runUpdate({
+program.command("update").description("update skillwiki CLI to the latest version").option("--tag <tag>", "npm dist-tag", "latest").action(async (opts) => emit(await runUpdate({
   home: process.env.HOME ?? "",
   distTag: opts.tag
 })));
-program.command("self-update").description("update skillwiki CLI from local source or npm@beta").option("--check", "check for updates without installing", false).action(async (opts) => emit(await runSelfUpdate({
+program.command("self-update").description("update skillwiki CLI from local source or npm@latest").option("--check", "check for updates without installing", false).action(async (opts) => emit(await runSelfUpdate({
   home: process.env.HOME ?? "",
   check: !!opts.check
 })));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/bin/skillwiki

@@ -2,4 +2,4 @@
 # skillwiki CLI wrapper — delegates to npx so the CLI is available
 # automatically when this plugin is enabled (Claude Code adds bin/ to PATH).
 set -euo pipefail
-exec npx -y skillwiki@beta "$@"
+exec npx -y skillwiki@latest "$@"

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "private": true,
   "files": [
     "wiki-*",

package/skills/wiki-crystallize/SKILL.md

@@ -22,7 +22,9 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 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.
+3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
+   - `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+   - 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`.
 

package/skills/wiki-ingest/SKILL.md

@@ -27,7 +27,9 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 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).
+4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers). Every page MUST include:
+   - `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+   - 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`.

package/templates/SCHEMA.md

@@ -52,6 +52,17 @@ Rule: every tag on every page MUST appear in this taxonomy. Add new tags here fi
 - 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 `---`.
+- Every typed-knowledge page SHOULD include a `## TL;DR` section near the top (after frontmatter, before `## Overview`). Lint flags pages missing it as `missing_tldr` (info).
+
+## Mermaid Diagrams
+
+Pages explaining architectures, workflows, or complex concepts SHOULD include inline Mermaid diagrams. Lint flags architecture-tagged pages without a ` ```mermaid ` block as `missing_diagram` (info).
+
+Obsidian-compatible Mermaid rules:
+- Prefer `graph TB` / `sequenceDiagram`.
+- Use `subgraph "Title"` (avoid `subgraph ID[Label]`).
+- Avoid `\n` in labels; use `<br/>` or single-line labels.
+- Keep node IDs ASCII and simple (`CMUX_DB`, `OC_GW`).
 
 ## Obsidian Integration