snapfail 0.0.22 → 0.0.23

package/dist/index.js

@@ -1938,9 +1938,7 @@ ${r2}
 }).prompt();
 
 // src/skill.ts
-function generateSkillMd(config, framework) {
-  return `# snapfail
-
+var SKILL_BODY = `
 snapfail captures browser error context (stack, console, network, replay timeline)
 and stores it so you can diagnose root causes. Evidence is structured for LLM reasoning.
 
@@ -1952,14 +1950,18 @@ When the user reports an error or unexpected behavior in their app, run:
 snapfail incidents --json
 \`\`\`
 
-Then drill into a specific incident:
+Then get full structured context for a specific incident:
 
 \`\`\`
-snapfail incident <id> --json
+snapfail explain <id>
 \`\`\`
 
-**Always use \`--json\` when querying from the LLM** \u2014 it returns structured data
-without ANSI color codes.
+\`snapfail explain\` outputs all captured evidence (stack, console, network, timeline, device,
+multiple samples) formatted as structured text. **Read it and reason about the root cause
+yourself** \u2014 do not delegate this to another model.
+
+**Always use \`--json\` when querying from the LLM** for \`incidents\` and \`incident\` \u2014
+it returns structured data without ANSI color codes.
 
 ## Commands
 
@@ -1968,34 +1970,47 @@ snapfail incidents [--status=unresolved|resolved|ignored] [--json]
   List incident groups. Default status: unresolved.
 
 snapfail incident <id> [--sample <n>] [--json]
-  Show incident detail: group summary + most recent sample (stack, console, network, timeline).
-  Use --sample <n> (0-indexed) to compare different occurrences of the same error.
+  Group summary + one sample (stack, console, network, timeline).
+  Use --sample <n> (0-indexed) to compare different occurrences.
 
 snapfail explain <id>
-  AI diagnosis: root cause, plain summary, fix prompt. (requires @snapfail/ai)
+  Outputs structured evidence for up to 3 samples. Read and diagnose directly.
 \`\`\`
 
+All commands accept \`--pk <project_key>\` to override the project key from \`.env\`.
+
 ## Interpreting an incident
 
-Key fields from \`snapfail incident <id> --json\`:
+Key fields:
 
 - \`group.title\` \u2014 normalized error message (dynamic values replaced with [uuid], [id], etc.)
-- \`group.count\` \u2014 total occurrences
-- \`group.environments\` \u2014 where it happened: "dev" | "prod"
+- \`group.count\` \u2014 total occurrences (\u2260 number of groups)
+- \`group.environments\` \u2014 "dev" | "prod"
 - \`group.severity\` \u2014 "critical" | "error" | "warning"
 - \`sample.stackFrames\` \u2014 call stack at the time of the error
-- \`sample.consoleEntries\` \u2014 last ~15s of console output before the error
-- \`sample.networkEntries\` \u2014 last ~15s of network requests (scrubbed)
-- \`sample.timeline\` \u2014 derived user interaction sequence (clicks, navigation, mutations)
+- \`sample.consoleEntries\` \u2014 console output before the error
+- \`sample.networkEntries\` \u2014 network requests (auth headers scrubbed)
+- \`sample.timeline\` \u2014 user interaction sequence (clicks, navigation, mutations)
+- \`sample.device.userAgent\` \u2014 browser/OS \u2014 critical for mobile/in-app browser bugs
 - \`sample.url\` / \`sample.route\` \u2014 where the error occurred
-
+`;
+function generateSkillMd(config, framework) {
+  return `# snapfail
+${SKILL_BODY}
 ## Config
 
 Project key: \`${config.projectKey}\`
 Endpoint: \`${config.endpoint}\`
-${framework ? `Framework: ${framework}
-` : ""}
-Config file: \`.snapfail.json\` (gitignored)
+${framework ? `Framework: \`${framework}\`
+` : ""}`;
+}
+function generateGlobalSkillMd() {
+  return `# snapfail
+${SKILL_BODY}
+## Project key
+
+The project key is read automatically from \`SNAPFAIL_PROJECT_KEY\` in \`.env\` or the shell.
+Pass \`--pk <key>\` to override when querying a specific project.
 `;
 }
 
@@ -2316,10 +2331,10 @@ async function runInit(cwd = process.cwd()) {
     writeProjectKey(selectedKey, cwd, "NEXT_PUBLIC_SNAPFAIL_PROJECT_KEY");
   addToGitignore(cwd, ".env");
   log.success("SNAPFAIL_PROJECT_KEY written to .env");
-  const skillDir = join2(cwd, ".agents", "skills", "snapfail");
+  const skillDir = join2(cwd, ".claude", "skills", "snapfail");
   mkdirSync2(skillDir, { recursive: true });
   writeFileSync3(join2(skillDir, "SKILL.md"), generateSkillMd({ projectKey: selectedKey, endpoint: DEFAULT_ENDPOINT }, framework), "utf-8");
-  log.success("SKILL.md created at .agents/skills/snapfail/SKILL.md");
+  log.success("SKILL.md created at .claude/skills/snapfail/SKILL.md");
   const pm = detectPackageManager(cwd);
   if (framework === "astro") {
     const cfg = findConfigFile(cwd, ["astro.config.ts", "astro.config.mjs", "astro.config.js"]);
@@ -2392,6 +2407,19 @@ async function runExplain(opts) {
 `);
 }
 
+// src/commands/skill.ts
+import { writeFileSync as writeFileSync4, mkdirSync as mkdirSync3, existsSync as existsSync4 } from "fs";
+import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
+var SKILL_DIR = join3(homedir2(), ".claude", "skills", "snapfail");
+var SKILL_FILE = join3(SKILL_DIR, "SKILL.md");
+async function runSkill() {
+  mkdirSync3(SKILL_DIR, { recursive: true });
+  const existed = existsSync4(SKILL_FILE);
+  writeFileSync4(SKILL_FILE, generateGlobalSkillMd(), "utf-8");
+  console.log(existed ? `Updated ${SKILL_FILE}` : `Created ${SKILL_FILE}`);
+}
+
 // src/index.ts
 function parseArgs(argv) {
   const [, , rawCommand = "incidents", ...rest] = argv;
@@ -2426,6 +2454,10 @@ async function main() {
       await runInit();
       return;
     }
+    if (command === "skill") {
+      await runSkill();
+      return;
+    }
     if (command === "incidents") {
       await runIncidents({
         json,
@@ -2457,7 +2489,7 @@ async function main() {
       return;
     }
     console.error(`Unknown command: ${command}`);
-    console.error(`snapfail v${VERSION} \u2014 Usage: snapfail [incidents|incident|init|explain] [--version]`);
+    console.error(`snapfail v${VERSION} \u2014 Usage: snapfail [incidents|incident|init|explain|skill] [--version]`);
     process.exit(1);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snapfail",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "type": "module",
   "description": "CLI for snapfail — project setup, incident inspection and AI diagnostics",
   "license": "MIT",

package/src/index.ts

@@ -3,6 +3,7 @@ import { runIncidents } from "./commands/incidents.ts";
 import { runIncident } from "./commands/incident.ts";
 import { runInit } from "./commands/init.ts";
 import { runExplain } from "./commands/explain.ts";
+import { runSkill } from "./commands/skill.ts";
 
 function parseArgs(argv: string[]): {
   command: string;
@@ -48,6 +49,11 @@ async function main(): Promise<void> {
       return;
     }
 
+    if (command === "skill") {
+      await runSkill();
+      return;
+    }
+
     if (command === "incidents") {
       await runIncidents({
         json,
@@ -83,7 +89,7 @@ async function main(): Promise<void> {
     }
 
     console.error(`Unknown command: ${command}`);
-    console.error(`snapfail v${VERSION} — Usage: snapfail [incidents|incident|init|explain] [--version]`);
+    console.error(`snapfail v${VERSION} — Usage: snapfail [incidents|incident|init|explain|skill] [--version]`);
     process.exit(1);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);