skillwiki 0.2.1-beta.15 → 0.2.1-beta.16

package/dist/cli.js

@@ -73,7 +73,8 @@ var ExitCode = {
   RAW_DEDUP_DETECTED: 33,
   MIGRATION_APPLIED: 34,
   UNKNOWN_WIKI_PROFILE: 35,
-  DEDUP_APPLIED: 36
+  DEDUP_APPLIED: 36,
+  PROJECT_NOT_FOUND: 37
 };
 
 // ../shared/src/json-output.ts
@@ -120,12 +121,10 @@ var RawSourceSchema = z.object({
   sha256: sha256Hex,
   project: wikilink.optional(),
   work_item: wikilink.optional(),
-  kind: z.enum(["postmortem", "session-log", "meeting-notes", "other"]).optional()
+  kind: z.enum(["postmortem", "session-log", "meeting-notes", "other", "idea", "bug", "task", "note"]).optional()
 }).superRefine((v, ctx) => {
-  const projectFields = [v.project, v.work_item, v.kind];
-  const present = projectFields.filter((x) => x !== void 0).length;
-  if (present !== 0 && present !== 3) {
-    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "project, work_item, kind must all be set together" });
+  if (v.work_item !== void 0 && (v.project === void 0 || v.kind === void 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "project and kind are required when work_item is set" });
   }
 });
 var WorkItemSchema = z.object({
@@ -1341,11 +1340,11 @@ async function runInit(input) {
   const errTemplate = await writeOrPreserve(`${TEMPLATE_FOLDER}/tpl-ad-hoc-capture.md`, async () => {
     return [
       "---",
-      "project: ",
-      "tags: []",
-      "priority: ",
-      "created: {{date:YYYY-MM-DD}}T{{time:HH:mm}}",
-      "ingested: ",
+      "source_url:",
+      "ingested: {{date:YYYY-MM-DD}}",
+      "sha256:          # run: skillwiki hash <this-file>",
+      "kind:             # idea | bug | task | note | other",
+      'project:          # optional: "[[slug]]"',
       "---",
       "",
       ""
@@ -2782,6 +2781,129 @@ async function runTranscripts(input) {
   return { exitCode: ExitCode.OK, result: ok({ transcripts, humanHint: hint }) };
 }
 
+// src/commands/project-index.ts
+import { readdir as readdir5, readFile as readFile16, writeFile as writeFile11, mkdir as mkdir6 } from "fs/promises";
+import { join as join20, dirname as dirname8 } from "path";
+var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
+async function runProjectIndex(input) {
+  const slug = input.slug;
+  const projectDir = join20(input.vault, "projects", slug);
+  try {
+    await readdir5(projectDir);
+  } catch {
+    return {
+      exitCode: ExitCode.PROJECT_NOT_FOUND,
+      result: err("PROJECT_NOT_FOUND", { slug, path: projectDir })
+    };
+  }
+  const wikilinkPattern = `[[${slug}]]`;
+  const entries = [];
+  for (const dir of LAYER2_DIRS) {
+    let files;
+    try {
+      files = await readdir5(join20(input.vault, dir), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of files) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+      const filePath = join20(input.vault, dir, entry.name);
+      let text;
+      try {
+        text = await readFile16(filePath, "utf8");
+      } catch {
+        continue;
+      }
+      const fm = extractFrontmatter(text);
+      if (!fm.ok) continue;
+      const pp = fm.data.provenance_projects;
+      if (!Array.isArray(pp) || !pp.some((p) => String(p) === wikilinkPattern)) continue;
+      entries.push({
+        page: `${dir}/${entry.name}`,
+        type: fm.data.type ?? dir.slice(0, -1),
+        // singularize dir name
+        title: fm.data.title ?? entry.name.replace(/\.md$/, "")
+      });
+    }
+  }
+  const typeOrder = { entity: 0, concept: 1, comparison: 2, query: 3, summary: 4, meta: 5 };
+  entries.sort((a, b) => {
+    const ta = typeOrder[a.type] ?? 99;
+    const tb = typeOrder[b.type] ?? 99;
+    return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
+  });
+  const indexPath = join20(projectDir, "knowledge.md");
+  let existing = false;
+  let stale = false;
+  try {
+    const existingText = await readFile16(indexPath, "utf8");
+    existing = true;
+    const existingEntries = existingText.split("\n").filter((l) => l.startsWith("- [["));
+    const existingPages = new Set(existingEntries.map((l) => {
+      const m = l.match(/\[\[([^\]]+)\]\]/);
+      return m ? m[1] : "";
+    }));
+    const currentPages = new Set(entries.map((e) => e.page.replace(/\.md$/, "")));
+    stale = existingPages.size !== currentPages.size || [...currentPages].some((p) => !existingPages.has(p));
+  } catch {
+  }
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const grouped = /* @__PURE__ */ new Map();
+  for (const e of entries) {
+    const group = e.type;
+    if (!grouped.has(group)) grouped.set(group, []);
+    grouped.get(group).push(e);
+  }
+  let body = `# Knowledge Index: ${slug}
+
+Autogenerated by \`skillwiki project-index\` on ${today}.
+
+`;
+  for (const [type, items] of grouped) {
+    body += `## ${type}
+
+`;
+    for (const item of items) {
+      const pageRef = item.page.replace(/\.md$/, "");
+      body += `- [[${pageRef}]] \u2014 ${item.title}
+`;
+    }
+    body += "\n";
+  }
+  if (entries.length === 0) {
+    body += `No Layer 2 pages reference \`[[${slug}]]\` in provenance_projects.
+`;
+  }
+  if (input.apply) {
+    try {
+      await mkdir6(dirname8(indexPath), { recursive: true });
+      await writeFile11(indexPath, body, "utf8");
+    } catch (e) {
+      return {
+        exitCode: ExitCode.WRITE_FAILED,
+        result: err("WRITE_FAILED", { file: indexPath, message: String(e) })
+      };
+    }
+  }
+  const action = input.apply ? `written ${entries.length} entries to ${indexPath}` : `${entries.length} entries found (use --apply to write)`;
+  const staleHint = stale ? " (STALE \u2014 existing index outdated)" : existing ? " (up to date)" : "";
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      slug,
+      entries,
+      existing,
+      stale,
+      index_path: `projects/${slug}/knowledge.md`,
+      humanHint: `project: ${slug}
+entries: ${entries.length}${staleHint}
+${action}
+
+${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e.title}`).join("\n")}`
+    })
+  };
+}
+
 // src/cli.ts
 var pkg = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
@@ -2947,6 +3069,11 @@ program.command("transcripts [vault]").description("list transcript files in raw
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runTranscripts({ vault: v.vault, since: opts.since }));
 });
+program.command("project-index <slug> [vault]").description("generate a knowledge index for a project workspace").option("--apply", "write knowledge.md to the project directory", false).option("--wiki <name>", "wiki profile name").action(async (slug, vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runProjectIndex({ vault: v.vault, slug, apply: !!opts.apply }));
+});
 triggerAutoUpdate(process.env.HOME ?? "", pkg.version);
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.15",
+  "version": "0.2.1-beta.16",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.15",
+  "version": "0.2.1-beta.16",
   "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.",
   "author": {

package/skills/package.json

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

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

@@ -9,8 +9,8 @@ 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 | Appends entry to `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` |
-| Filesystem drop | You're NOT in a Claude session (Obsidian, editor, sync) | Create/edit any file in `raw/transcripts/` — dev-loop discovers it on next cycle |
+| `/wiki-add-task <text>` | You're in a Claude session | Creates `raw/transcripts/YYYY-MM-DD-{type}-{slug}.md` with raw-valid 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 |
 
 ## When This Skill Activates
@@ -30,52 +30,76 @@ 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. **Determine target file.** The capture file is `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` where YYYY-MM-DD is today's date. If the file exists, append; otherwise create it with standard raw frontmatter.
-3. **Write the entry.** Append to the capture file:
+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:
+   ```yaml
+   ---
+   source_url:
+   ingested: YYYY-MM-DD
+   ingested_by: manual
+   sha256:
+   kind: {type}
+   project: "[[{slug}]]"
+   ---
+   ```
+   - 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).
+4. **Write body.** Below the frontmatter, write:
    ```markdown
-   ### HH:MM — [type]
+   # {type}: {text}
 
-   [text]
-
-   <!---meta: {"captured_at": "YYYY-MM-DDTHH:MM:SS", "type": "[type]"}--->
+   {text}
    ```
-   - Use 24-hour time for HH:MM.
-   - Do not overwrite or modify existing entries.
-4. **Cross-reference (optional).** If a `project` slug was provided:
+   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:
    - Check that `projects/{slug}/` exists in the vault.
-   - Append a one-line reference to the project's work log or compound notes:
-     `- [YYYY-MM-DD] capture: [text] → raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md`
+   - 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).
-5. **Update log.md.** Append: `## [YYYY-MM-DD] capture | [type]: [text (first 60 chars)]`
-6. **Confirm to user.** Report what was captured and where. Suggest next steps:
+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:
    - 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."
    - If `type: note` → "Will be available for future wiki-query searches."
 
-## Ad-hoc captures file format
+## Capture file format
 
-The file `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` is a standard raw source with frontmatter:
+Each capture is a standalone raw source file with valid frontmatter:
 
 ```yaml
 ---
 source_url:
-ingested: YYYY-MM-DD
-sha256:
+ingested: 2026-05-08
+ingested_by: manual
+sha256: <64-char hex computed over body>
+kind: idea
+project: "[[llm-wiki]]"
 ---
+
+# idea: Fix the template mismatch
+
+Fix the template mismatch between wiki-add-task and the vault template.
 ```
 
-The `sha256` is computed over the body after the closing `---`. On each append, recompute and update `sha256`. This keeps source-drift detection functional even though the file grows throughout the day.
+The `kind` field uses the capture type and must be one of: `idea`, `bug`, `task`, `note` (plus the existing `postmortem`, `session-log`, `meeting-notes`, `other` for non-capture raw sources).
+
+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`).
 
 ## Stop conditions
 
 - `skillwiki path` returns NO_VAULT_CONFIGURED.
 - No `text` provided (prompt user once, then stop).
+- Target file already exists (use a different slug or add a suffix).
 
 ## Forbidden
 
 - Creating an `inbox/` directory. All captures go to `raw/transcripts/`.
-- Modifying existing entries in the captures file — only append.
+- Appending to existing capture files — each capture gets its own file.
 - Creating a work item — this is capture-only. Use `proj-work` for full work items.
 - Writing to any Layer 2 or Layer 3 location. Captures are Layer 1 (raw).
 
@@ -83,16 +107,10 @@ The `sha256` is computed over the body after the closing `---`. On each append,
 
 When you're not in a Claude session, drop files directly into `raw/transcripts/`:
 
-1. Create any `.md` file in `raw/transcripts/` — name it descriptively (e.g., `2026-05-07-idea-xyz.md`)
-2. Add raw frontmatter at the top:
-   ```yaml
-   ---
-   source_url:
-   ingested: YYYY-MM-DD
-   sha256:
-   ---
-   ```
+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
 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/templates/project-README.md

@@ -12,3 +12,7 @@
 - `architecture/` — how it's designed (incl. ADRs).
 - `work/YYYY-MM-DD-{slug}/` — per-work-item folders containing `spec.md`, `plan.md`, `log.md`.
 - `compound/` — project-local concrete learnings.
+
+## Knowledge
+
+Run `skillwiki project-index {{slug}} --apply` to generate `knowledge.md` listing all Layer 2 pages that reference `[[{{slug}}]]` in their provenance_projects.