skillwiki 0.2.1-beta.1 → 0.2.1-beta.10

package/dist/cli.js

@@ -878,6 +878,10 @@ function hasOrphanedCitations(body) {
   }
   return false;
 }
+function hasWikilinkCitations(body) {
+  const stripped = stripFences(body);
+  return /\[\[raw\/[^\]]+\]\]/.test(stripped);
+}
 
 // src/commands/audit.ts
 async function runAudit(input) {
@@ -1172,9 +1176,12 @@ var VAULT_DIRS = [
   "queries",
   "meta",
   "projects",
-  ".obsidian"
+  ".obsidian",
+  "_Templates"
 ];
 var ATTACHMENT_FOLDER = "raw/assets";
+var NEW_FILE_FOLDER = "raw/transcripts";
+var TEMPLATE_FOLDER = "_Templates";
 function extractDomainFromSchema(text) {
   const m = text.match(/^##\s+Domain\s*\n([\s\S]*?)(?=\n\n|\n##|\s*$)/m);
   if (!m) return "";
@@ -1305,9 +1312,26 @@ async function runInit(input) {
   });
   if (err1) return err1;
   const errObsidian = await writeOrPreserve(".obsidian/app.json", async () => {
-    return JSON.stringify({ attachmentFolderPath: ATTACHMENT_FOLDER }, null, 2) + "\n";
+    return JSON.stringify({ attachmentFolderPath: ATTACHMENT_FOLDER, newFileLocation: "folder", newFileFolderPath: NEW_FILE_FOLDER }, null, 2) + "\n";
   });
   if (errObsidian) return errObsidian;
+  const errTemplatesJson = await writeOrPreserve(".obsidian/templates.json", async () => {
+    return JSON.stringify({ folder: TEMPLATE_FOLDER }, null, 2) + "\n";
+  });
+  if (errTemplatesJson) return errTemplatesJson;
+  const errTemplate = await writeOrPreserve(`${TEMPLATE_FOLDER}/tpl-ad-hoc-capture.md`, async () => {
+    return [
+      "---",
+      "project: ",
+      "tags: []",
+      "priority: ",
+      "ingested: {{date:YYYY-MM-DD}}",
+      "---",
+      "",
+      ""
+    ].join("\n");
+  });
+  if (errTemplate) return errTemplate;
   const err22 = await writeOrPreserve("log.md", async () => {
     const tpl = await readFile6(join7(input.templates, "log.md"), "utf8");
     return tpl.replace(/\{\{INIT_DATE\}\}/g, today).replace("{{DOMAIN}}", domain).replace("{{WIKI_LANG}}", canonicalLang);
@@ -1354,7 +1378,8 @@ async function runInit(input) {
       env_skipped: skipEnv,
       imported_from_hermes: importedFromHermes,
       discovered_tags,
-      humanHint
+      humanHint,
+      templates_created: created.includes(`${TEMPLATE_FOLDER}/tpl-ad-hoc-capture.md`)
     })
   };
 }
@@ -1704,7 +1729,7 @@ function hasDuplicateFrontmatter(body) {
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "tag_not_in_taxonomy"];
 var WARNING_ORDER = ["index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "missing_overview"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink"];
+var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation"];
 async function runLint(input) {
   const buckets = {};
   const links = await runLinks({ vault: input.vault });
@@ -1757,6 +1782,7 @@ async function runLint(input) {
     const dupFrontmatter = [];
     const noOverview = [];
     const fmWikilinkFlags = [];
+    const wikilinkCitationFlags = [];
     for (const page of scan.data.typedKnowledge) {
       const text = await readPage(page);
       const split = splitFrontmatter(text);
@@ -1766,6 +1792,7 @@ async function runLint(input) {
       if (hasDuplicateFrontmatter(body)) dupFrontmatter.push(page.relPath);
       if (isLegacyCitationStyle(body)) legacyPages.push(page.relPath);
       if (hasOrphanedCitations(body)) orphanedPages.push(page.relPath);
+      if (hasWikilinkCitations(body)) wikilinkCitationFlags.push(page.relPath);
       const fmLinks = rawFm.match(/\[\[([^\[\]|]+)(?:\|[^\[\]]*)?\]\]/g) ?? [];
       for (const link of fmLinks) {
         const target = link.replace(/^\[\[/, "").replace(/(?:\|[^\[\]]*)?\]\]$/, "").trim();
@@ -1794,6 +1821,7 @@ async function runLint(input) {
     if (dupFrontmatter.length > 0) buckets.duplicate_frontmatter = dupFrontmatter;
     if (noOverview.length > 0) buckets.missing_overview = noOverview;
     if (fmWikilinkFlags.length > 0) buckets.frontmatter_wikilink = fmWikilinkFlags;
+    if (wikilinkCitationFlags.length > 0) buckets.wikilink_citation = wikilinkCitationFlags;
   }
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
@@ -2170,29 +2198,35 @@ import { join as join18, dirname as dirname7 } from "path";
 async function runArchive(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  let relPath;
-  if (input.page.includes("/")) {
-    relPath = scan.data.typedKnowledge.find((p) => p.relPath === input.page)?.relPath;
-  } else {
-    relPath = scan.data.typedKnowledge.find((p) => p.relPath.replace(/\.md$/, "").split("/").pop() === input.page)?.relPath;
+  const lookup = (pages) => {
+    if (input.page.includes("/")) return pages.find((p) => p.relPath === input.page)?.relPath;
+    return pages.find((p) => p.relPath.replace(/\.md$/, "").split("/").pop() === input.page)?.relPath;
+  };
+  let relPath = lookup(scan.data.typedKnowledge);
+  let isRaw = false;
+  if (!relPath) {
+    relPath = lookup(scan.data.raw);
+    isRaw = relPath != null;
   }
   if (!relPath) return { exitCode: ExitCode.ARCHIVE_TARGET_NOT_FOUND, result: err("ARCHIVE_TARGET_NOT_FOUND", { page: input.page }) };
   if (relPath.startsWith("_archive/")) return { exitCode: ExitCode.ARCHIVE_ALREADY_ARCHIVED, result: err("ARCHIVE_ALREADY_ARCHIVED", { page: relPath }) };
   const archivePath = join18("_archive", relPath);
   await mkdir5(dirname7(join18(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
-  const indexPath = join18(input.vault, "index.md");
-  try {
-    const idx = await readFile13(indexPath, "utf8");
-    const slug = relPath.replace(/\.md$/, "").split("/").pop();
-    const originalLines = idx.split("\n");
-    const filtered = originalLines.filter((l) => !l.includes(`[[${slug}]]`));
-    if (filtered.length !== originalLines.length) {
-      await writeFile6(indexPath, filtered.join("\n"), "utf8");
-      indexUpdated = true;
+  if (!isRaw) {
+    const indexPath = join18(input.vault, "index.md");
+    try {
+      const idx = await readFile13(indexPath, "utf8");
+      const slug = relPath.replace(/\.md$/, "").split("/").pop();
+      const originalLines = idx.split("\n");
+      const filtered = originalLines.filter((l) => !l.includes(`[[${slug}]]`));
+      if (filtered.length !== originalLines.length) {
+        await writeFile6(indexPath, filtered.join("\n"), "utf8");
+        indexUpdated = true;
+      }
+    } catch (e) {
+      if (e?.code !== "ENOENT") throw e;
     }
-  } catch (e) {
-    if (e?.code !== "ENOENT") throw e;
   }
   await rename3(join18(input.vault, relPath), join18(input.vault, archivePath));
   return { exitCode: ExitCode.OK, result: ok({ archived_from: relPath, archived_to: archivePath, index_updated: indexUpdated, humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}` }) };
@@ -2241,16 +2275,31 @@ async function runDrift(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   const results = [];
+  const newResults = [];
   for (const raw of scan.data.raw) {
     const text = await readPage(raw);
     const split = splitFrontmatter(text);
     if (!split.ok) continue;
     const { rawFrontmatter, body } = split.data;
+    const ingestedMatch = rawFrontmatter.match(/^ingested:\s*(.+)$/m);
+    const ingestedRaw = ingestedMatch?.[1]?.trim() ?? "";
+    const ingested = ingestedRaw.replace(/^["']|["']$/g, "");
+    if (input.newSince && ingested && ingested >= input.newSince) {
+      newResults.push({
+        raw_path: raw.relPath,
+        source_url: "",
+        stored_sha256: "",
+        current_sha256: null,
+        status: "new",
+        ingested
+      });
+    }
     const sourceUrlMatch = rawFrontmatter.match(/^source_url:\s*(.+)$/m);
     const storedHashMatch = rawFrontmatter.match(/^sha256:\s*([a-f0-9]+)$/m);
     if (!sourceUrlMatch || !storedHashMatch) continue;
     const sourceUrl = sourceUrlMatch[1].trim();
     const storedHash = storedHashMatch[1];
+    if (!sourceUrl.startsWith("http://") && !sourceUrl.startsWith("https://")) continue;
     const resp = await doFetch(sourceUrl, FETCH_OPTS);
     if (!resp.ok) {
       results.push({
@@ -2295,12 +2344,13 @@ ${body}`;
   const unchanged = results.filter((r) => r.status === "unchanged").length;
   const exitCode = drifted.length > 0 ? ExitCode.DRIFT_DETECTED : ExitCode.OK;
   const hintLines = [`scanned: ${results.length}, unchanged: ${unchanged}`];
+  if (newResults.length > 0) hintLines.push(`new: ${newResults.length}`, ...newResults.map((n) => `  ${n.raw_path} (ingested: ${n.ingested})`));
   if (drifted.length > 0) hintLines.push(`drifted: ${drifted.length}`, ...drifted.map((d) => `  ${d.raw_path}`));
   if (fetchFailed.length > 0) hintLines.push(`fetch_failed: ${fetchFailed.length}`, ...fetchFailed.map((f) => `  ${f.raw_path}: ${f.fetch_error}`));
   if (updated.length > 0) hintLines.push(`updated: ${updated.length}`, ...updated.map((u) => `  ${u.raw_path}`));
   return {
     exitCode,
-    result: ok({ scanned: results.length, drifted, fetch_failed: fetchFailed, updated, unchanged, humanHint: hintLines.join("\n") })
+    result: ok({ scanned: results.length, drifted, fetch_failed: fetchFailed, updated, newFiles: newResults, unchanged, humanHint: hintLines.join("\n") })
   };
 }
 
@@ -2575,6 +2625,37 @@ async function runUpdate(input) {
   };
 }
 
+// src/commands/transcripts.ts
+import { readdir as readdir4, stat as stat6, readFile as readFile14 } from "fs/promises";
+import { join as join19 } from "path";
+async function runTranscripts(input) {
+  const dir = join19(input.vault, "raw", "transcripts");
+  let entries;
+  try {
+    entries = await readdir4(dir, { withFileTypes: true });
+  } catch {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: { ok: false, error: "VAULT_PATH_INVALID", detail: `raw/transcripts/ not found: ${dir}` } };
+  }
+  const transcripts = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const filePath = join19(dir, entry.name);
+    const content = await readFile14(filePath, "utf8");
+    const fm = extractFrontmatter(content);
+    if (!fm.ok) continue;
+    const ingested = typeof fm.data.ingested === "string" ? fm.data.ingested : "";
+    if (input.since && ingested && ingested < input.since) continue;
+    const s = await stat6(filePath);
+    transcripts.push({
+      file: `raw/transcripts/${entry.name}`,
+      ingested,
+      size: s.size
+    });
+  }
+  const hint = transcripts.length > 0 ? transcripts.map((t) => `${t.file} (ingested: ${t.ingested || "unknown"}, ${t.size}B)`).join("\n") : "no transcript files found";
+  return { exitCode: ExitCode.OK, result: ok({ transcripts, humanHint: hint }) };
+}
+
 // src/cli.ts
 var pkg = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command();
@@ -2710,10 +2791,10 @@ program.command("archive <page> [vault]").description("archive a typed-knowledge
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runArchive({ vault: v.vault, page }));
 });
-program.command("drift [vault]").description("detect content drift in raw sources").option("--apply", "update sha256 in drifted sources").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+program.command("drift [vault]").description("detect content drift in raw sources").option("--apply", "update sha256 in drifted sources").option("--new <date>", "list raw files ingested on/after this date (YYYY-MM-DD)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runDrift({ vault: v.vault, apply: opts.apply }));
+  else emit(await runDrift({ vault: v.vault, apply: opts.apply, newSince: opts.new }));
 });
 program.command("dedup [vault]").description("detect duplicate raw sources by sha256").option("--apply", "rewire citations and remove duplicate raw files", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -2734,6 +2815,11 @@ program.command("update").description("update skillwiki CLI to the latest versio
   home: process.env.HOME ?? "",
   distTag: opts.tag
 })));
+program.command("transcripts [vault]").description("list transcript files in raw/transcripts/").option("--since <date>", "only files ingested on or after this date (YYYY-MM-DD)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runTranscripts({ vault: v.vault, since: opts.since }));
+});
 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,7 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.1",
-  "version": "0.2.1-beta.1",
+  "version": "0.2.1-beta.10",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

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

@@ -1,9 +1,8 @@
 {
   "name": "skillwiki",
-  "version": "0.2.1-beta.1",
-  "version": "0.2.1-beta.1",
+  "version": "0.2.1-beta.10",
   "skills": "./",
-  "description": "Project-aware Karpathy-style knowledge base for Claude Code: 11 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI (8 subcommands, JSON-by-default).",
+  "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": {
     "name": "karlorz",
     "url": "https://github.com/karlorz"

package/skills/package.json

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

package/skills/using-skillwiki/SKILL.md

@@ -20,6 +20,7 @@ Invoke a skillwiki skill when the user:
 - Wants a health check or lint on their vault
 - Mentions crystallizing a session into a note
 - Talks about project workspaces, ADRs, or distillation
+- Wants to quickly capture an idea, bug, task, or note without interrupting their workflow
 - Wants to archive or clean up old vault pages
 - Needs to detect source drift or re-ingest updated content
 - Has a spec/plan in a non-skillwiki format (CodeStable, RFC, AIDE)
@@ -27,15 +28,15 @@ Invoke a skillwiki skill when the user:
 
 ## Vault Structure
 
-A skillwiki vault has two layers:
+A skillwiki vault has three layers. The canonical architecture lives in `SCHEMA.md` at the vault root — read it before creating any new directories.
 
-**Layer 1 — Raw (`raw/`):** Immutable source material. Never modify after ingest.
+**Layer 1 — Raw (`raw/`):** Immutable source material. Never modify after ingest. `raw/transcripts/` doubles as the ad-hoc capture point for meeting notes and unprocessed ideas.
 
 ```
 raw/
 ├── articles/    # Web articles, clippings
 ├── papers/      # PDFs, arxiv papers
-├── transcripts/ # Meeting notes, interviews
+├── transcripts/ # Meeting notes, interviews, ad-hoc captures
 └── assets/      # Images, diagrams referenced by sources
 ```
 
@@ -48,7 +49,19 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 ---
 ```
 
-**Layer 2 — Agent-owned pages:** `entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`, `projects/`. Citations use `^[raw/articles/source-file.md]` markers at paragraph-end.
+**Layer 2 — Typed Knowledge:** `entities/`, `concepts/`, `comparisons/`, `queries/`, `meta/`. Agent-owned pages with `^[raw/...]` citation markers at paragraph-end. Global scope — project association via `provenance_projects:` frontmatter, not directory nesting.
+
+**Layer 3 — Project Workspaces (`projects/{slug}/`):** Per-project lifecycle directories with `work/` (spec + plan + retro), `compound/` (distilled lessons/patterns), `architecture/` (ADRs), and `history/` (archived specs/plans).
+
+**No `inbox/` directory.** Ad-hoc captures go to `raw/transcripts/` or directly into a project work item via `proj-work`. Do not invent new top-level directories — extend Layer 2 via SCHEMA.md tag taxonomy if needed.
+
+### Ad-hoc capture: 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 `.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 |
 
 ## Skill Map
 
@@ -62,6 +75,7 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 | `wiki-audit` | Verify raw provenance references and source frontmatter integrity |
 | `wiki-archive` | Archive a typed-knowledge page — move to `_archive/`, remove from index |
 | `wiki-reingest` | Detect drift in raw sources (sha256 comparison) and re-ingest updated content |
+| `wiki-add-task` | Quick-capture ideas, bugs, tasks, notes into `raw/transcripts/` without leaving the current workflow |
 | `wiki-adapter-prd` | Map foreign PRD formats (CodeStable, RFC, AIDE, Hermes) into vault pages |
 | `proj-init` | Bootstrap a project workspace (README, requirements, architecture) |
 | `proj-work` | Open or run a work item under a project's work/ directory |

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

@@ -0,0 +1,104 @@
+---
+name: wiki-add-task
+description: Capture ad-hoc ideas, bugs, tasks, or notes into the vault via /wiki-add-task or filesystem drop.
+---
+
+# wiki-add-task
+
+Capture ad-hoc ideas, bugs, tasks, and notes into the vault. Three entry points depending on where you are:
+
+| 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 |
+| Dev-loop discovery | Automatic, next cycle | Scans `raw/transcripts/` for new files since last cycle, surfaces as claimable work |
+
+## When This Skill Activates
+
+- User invokes `/wiki-add-task` with a description.
+- User says "add task", "capture this", "note this", "remember this", "log this idea", or similar.
+- User provides a short text description and optionally a type tag.
+
+## Output language
+
+Run `skillwiki lang` at the start. Entry prose and `--human` summaries use the resolved language. Frontmatter keys, file names, and structural markers stay English.
+
+## Steps
+
+0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`.
+1. **Parse arguments.** Extract from the user's message:
+   - `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:
+   ```markdown
+   ### HH:MM — [type]
+
+   [text]
+
+   <!---meta: {"captured_at": "YYYY-MM-DDTHH:MM:SS", "type": "[type]"}--->
+   ```
+   - Use 24-hour time for HH:MM.
+   - Do not overwrite or modify existing entries.
+4. **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`
+   - 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:
+   - 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
+
+The file `raw/transcripts/YYYY-MM-DD-ad-hoc-captures.md` is a standard raw source with frontmatter:
+
+```yaml
+---
+source_url:
+ingested: YYYY-MM-DD
+sha256:
+---
+```
+
+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.
+
+## Stop conditions
+
+- `skillwiki path` returns NO_VAULT_CONFIGURED.
+- No `text` provided (prompt user once, then stop).
+
+## Forbidden
+
+- Creating an `inbox/` directory. All captures go to `raw/transcripts/`.
+- Modifying existing entries in the captures file — only append.
+- 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).
+
+## Filesystem drop (offline capture)
+
+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:
+   ---
+   ```
+3. Write your idea/bug/task/note below the frontmatter
+
+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.
+
+## Dev-loop discovery
+
+When the dev-loop QUERY step runs, it should scan `raw/transcripts/` for files with `ingested:` date newer than the last cycle. New files are surfaced as claimable work items. The agent then decides whether to:
+- Create a work item via `proj-work` (for tasks and bugs)
+- Ingest as a knowledge page via `wiki-ingest` (for ideas with sources)
+- Leave in place (for notes that don't need action yet)