skillwiki 0.2.4 → 0.2.5

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.4",
+  "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.4",
+  "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.2.4",
+  "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