scribeclock 0.1.4 → 0.1.6

package/README.md

@@ -71,6 +71,7 @@ the app become tasks on the project; docs: https://scribeclock.com/help/bug-repo
 
 ```bash
 scribeclock connect --env          # links this repo to its project, writes .scribeclock.json + SCRIBECLOCK_INGEST_KEY to .env
+scribeclock ingest prompt --platform ios | pbcopy   # the prompt to paste into your AI agent: key, event shape, stack-specific steps
 scribeclock ingest test            # sends a test error straight to https://scribeclock.com/ingest → issue + task
 scribeclock issues                 # what users hit: level, title, where, count, users, last seen, task
 scribeclock issues show 3f2a9c1b   # stack trace, breadcrumbs, trace logs, context

package/dist/commands/ingest.js

@@ -6,6 +6,7 @@ import { EXIT } from "../types.js";
 import { fmtDate, relTime } from "../util/format.js";
 import { PROJECT_FLAG, cmd, emit, guardedEmit, list, num, personName, projectArg, requirePositional, str, taskKey } from "./_shared.js";
 import { parseDotenv } from "./ops.js";
+import { AGENT_PROMPT_PLATFORMS, buildAgentPrompt } from "./ingestAgentPrompt.js";
 export const INGEST_URL = "https://scribeclock.com/ingest";
 export const INGEST_DOCS_URL = "https://scribeclock.com/help/bug-reports";
 const KEY_ENV = "SCRIBECLOCK_INGEST_KEY";
@@ -757,6 +758,35 @@ export const ingestSnippetsCommand = cmd({
         return EXIT.OK;
     },
 });
+export const ingestPromptCommand = cmd({
+    path: "ingest prompt",
+    group: "Bug reports",
+    summary: "Print the prompt to paste into an AI agent so it connects this repository: key, event shape and the exact steps for the stack.",
+    description: "The same prompt the project's Bug reports page offers. It embeds the ingest key (from --key, SCRIBECLOCK_INGEST_KEY or .env), the project and repository from .scribeclock.json, and stack-specific steps: the reporter file to write, crash hooks, bug reports, breadcrumbs, trace logs, sessions, screens, clicks, custom events, then a verified test event. Pipe it to the clipboard (pbcopy / xclip) or straight into the agent.",
+    tool: ["list_ingest_keys"],
+    flags: [
+        { name: "platform", alias: "p", type: "string", choices: AGENT_PROMPT_PLATFORMS.map((o) => o.id), description: "Stack to write the steps for (default: auto — the agent detects it)." },
+        { name: "key", alias: "k", type: "string", description: "Ingest key to embed (default: from the environment / .env; omitted → the agent fetches one itself)." },
+        { name: "no-key", type: "boolean", description: "Never embed a key (the agent runs connect_repo / scribeclock connect)." },
+    ],
+    examples: ["scribeclock ingest prompt --platform ios | pbcopy", "scribeclock ingest prompt --no-key", "scribeclock connect --env && scribeclock ingest prompt"],
+    async run(ctx, inv) {
+        const key = inv.flags["no-key"] ? null : ingestKeyFor(ctx, str(inv.flags.key));
+        const text = buildAgentPrompt({
+            key,
+            repo: ctx.repo.config.repo ?? remoteUrl(ctx.cwd) ?? null,
+            platform: (str(inv.flags.platform) ?? "auto"),
+            endpoint: INGEST_URL,
+            docsUrl: INGEST_DOCS_URL,
+        });
+        if (ctx.flags.json) {
+            ctx.out.jsonOut({ ok: true, platform: str(inv.flags.platform) ?? "auto", has_key: Boolean(key), prompt: text });
+            return EXIT.OK;
+        }
+        ctx.out.log(text);
+        return EXIT.OK;
+    },
+});
 // ───────────────────────────── health ─────────────────────────────
 export const healthCommand = cmd({
     path: "health",
@@ -919,7 +949,7 @@ export const analyticsCommand = cmd({
         REPO_FLAG,
         { name: "days", alias: "d", type: "number", description: "Window in days (default 30, max 180)." },
         { name: "environment", alias: "e", type: "string", description: "Only this environment." },
-        { name: "report", type: "string", choices: ["overview", "daily", "retention", "screens", "clicks", "events", "breakdowns", "releases", "issues", "hourly"], description: "One section only." },
+        { name: "report", type: "string", choices: ["overview", "daily", "retention", "screens", "clicks", "events", "breakdowns", "releases", "issues", "hourly", "weekday"], description: "One section only." },
         { name: "csv", type: "boolean", description: "Print the daily series as CSV." },
     ],
     examples: ["scribeclock analytics", "scribeclock analytics --days 7 --report releases", "scribeclock analytics --days 90 --csv > usage.csv", "scribeclock analytics --json | jq .totals"],
@@ -945,11 +975,11 @@ export const analyticsCommand = cmd({
                 out.log("");
                 out.log(out.bold("Overview") + out.dim("  (vs previous window)"));
                 out.kv([
-                    ["active users", `${String(t.users ?? 0)} (${delta(t.users, prev.users)}) · ${String(t.new_users ?? 0)} new · stickiness ${pct(t.stickiness_pct)} · MAU ${String(t.mau ?? 0)}`],
+                    ["active users", `${String(t.users ?? 0)} (${delta(t.users, prev.users)}) · ${String(t.new_users ?? 0)} new · ${String(t.returning_users ?? 0)} returning · stickiness ${pct(t.stickiness_pct)} · MAU ${String(t.mau ?? 0)}`],
                     ["sessions", `${String(t.sessions ?? 0)} (${delta(t.sessions, prev.sessions)}) · ${String(t.avg_session_minutes ?? 0)} min avg · ${String(t.avg_screens_per_session ?? 0)} screens/session`],
                     ["crash-free", `${pct(t.crash_free_sessions_pct)} sessions · ${pct(t.crash_free_users_pct)} users`],
                     ["page views / clicks", `${String(t.pageviews ?? 0)} / ${String(t.clicks ?? 0)} · ${String(t.events ?? 0)} events (${delta(t.events, prev.events)})`],
-                    ["errors / crashes", `${String(t.errors ?? 0)} (${delta(t.errors, prev.errors)}) / ${String(t.crashes ?? 0)} (${delta(t.crashes, prev.crashes)}) · ${String(t.users_affected ?? 0)} users affected`],
+                    ["errors / crashes", `${String(t.errors ?? 0)} (${delta(t.errors, prev.errors)}) / ${String(t.crashes ?? 0)} (${delta(t.crashes, prev.crashes)}) · ${String(t.users_affected ?? 0)} users affected · ${String(t.errors_per_1k_sessions ?? "–")} per 1K sessions`],
                     ["bug reports", `${String(t.bug_reports ?? 0)} (${delta(t.bug_reports, prev.bug_reports)})`],
                     ["issues", `${String(t.issues_opened ?? 0)} opened · ${String(t.issues_resolved ?? 0)} resolved · ${String(t.issues_regressed ?? 0)} regressed · ${String(t.open_issues ?? 0)} open · MTTR ${String(t.mttr_hours ?? 0)} h`],
                     ["emails", `${String(t.emails_immediate ?? 0)} immediate · ${String(t.emails_digest ?? 0)} digests`],
@@ -1022,9 +1052,16 @@ export const analyticsCommand = cmd({
                 out.log(`  ${hourly.map((h) => String(h.hour).padStart(2, "0")).join(" ")}`);
                 out.log(`  ${hourly.map((h) => { const n = Number(h.events); const lvl = n === 0 ? " " : n < max / 4 ? "▁" : n < max / 2 ? "▃" : n < (3 * max) / 4 ? "▅" : "█"; return ` ${lvl}`; }).join(" ")}`);
             }
+            const weekday = (data.weekday ?? []);
+            if (show("weekday") && weekday.some((w) => Number(w.sessions) || Number(w.events) || Number(w.errors))) {
+                out.log("");
+                out.log(out.bold("Day of week (UTC)"));
+                const names = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+                out.table(["day", "sessions", "events", "errors"], weekday.map((w) => [names[Number(w.weekday)] ?? String(w.weekday), w.sessions, w.events, w.errors]), { indent: 2 });
+            }
             if (data.hint && !Number(t.events) && !Number(t.sessions))
                 out.info(out.dim(String(data.hint)));
         });
     },
 });
-export const INGEST_COMMANDS = [connectCommand, issuesList, issuesShow, issuesResolve, issuesIgnore, issuesReopen, issuesTask, bugCommand, ingestKeys, ingestRevoke, ingestTest, ingestSnippetsCommand, ingestForward, ingestSettings, issuesUrgency, analyticsCommand, healthCommand];
+export const INGEST_COMMANDS = [connectCommand, issuesList, issuesShow, issuesResolve, issuesIgnore, issuesReopen, issuesTask, bugCommand, ingestKeys, ingestRevoke, ingestTest, ingestSnippetsCommand, ingestPromptCommand, ingestForward, ingestSettings, issuesUrgency, analyticsCommand, healthCommand];

package/dist/commands/ingestAgentPrompt.js

@@ -0,0 +1,155 @@
+/**
+ * The prompt a developer hands to an AI agent (Claude Code, Cursor, Codex, …) to connect a repository to
+ * Scribe Clock: get an ingest key, store it, add a reporter for the app's stack, verify, commit.
+ *
+ * One source of truth, copied verbatim to apps/web/src/lib/ingestAgentPrompt.ts and
+ * scribeclock-cli/src/commands/ingestAgentPrompt.ts (no imports, so the same file runs in Deno, Vite and
+ * Node). It is shown on the Bug reports page (with the project's key), in the help guide (without a key),
+ * printed by `scribeclock ingest prompt`, and returned by the connect_repo MCP tool as `agent_prompt`.
+ */
+export const AGENT_PROMPT_PLATFORMS = [
+    { id: "auto", label: "Detect from the code" },
+    { id: "web", label: "Web (browser)" },
+    { id: "ios", label: "iOS / macOS (Swift)" },
+    { id: "android", label: "Android (Kotlin / Java)" },
+    { id: "react-native", label: "React Native / Expo" },
+    { id: "flutter", label: "Flutter" },
+    { id: "node", label: "Node / backend (JS, TS)" },
+    { id: "python", label: "Python" },
+    { id: "other", label: "Other (any language)" },
+];
+const EVENT_SHAPE = `{
+  "type": "error | crash | bug_report | message | event",
+  "level": "fatal | error | warning | info",
+  "message": "Error message, bug report title, or analytics event name (for type event: $pageview, $click, or your own like checkout_started)",
+  "exception": { "type": "TypeError", "value": "x is undefined", "stacktrace": "text stack trace", "frames": [{ "file": "", "function": "", "line": 0, "col": 0, "in_app": true }] },
+  "description": "Bug report body (Markdown)",
+  "environment": "production | staging | development",
+  "release": "1.4.2 (app version + build)",
+  "platform": "web | ios | android | react-native | flutter | node | python | …",
+  "url": "https://…", "route": "/screen/or/route", "screen": "ScreenName", "element": "button:Save",
+  "session_id": "uuid per app session (new after 30 min idle)",
+  "user": { "id": "…", "email": "…", "name": "…" },
+  "tags": { "feature": "checkout" },
+  "context": { "device": { "model": "" }, "os": { "name": "", "version": "" }, "app": { "version": "", "build": "" }, "locale": "" },
+  "breadcrumbs": [{ "timestamp": "ISO-8601", "category": "ui.click | navigation | http | log", "message": "", "data": {} }],
+  "logs": [{ "timestamp": "ISO-8601", "level": "info", "message": "trace log line" }],
+  "attachments": [{ "url": "https://…/screenshot.png", "name": "screenshot.png", "type": "image/png" }],
+  "reporter": { "name": "", "email": "" },
+  "properties": { "any": "analytics event properties" },
+  "fingerprint": "optional grouping key", "event_id": "optional idempotency id", "timestamp": "ISO-8601"
+}`;
+function platformBlock(p, key, environment) {
+    switch (p) {
+        case "web":
+            return `WEB (browser): use the hosted SDK, it already does errors, sessions, page views and click autocapture.
+   - In the HTML document, before the app bundle:
+     <script src="https://scribeclock.com/sdk/scribeclock.js" data-key="${key}" data-environment="${environment ?? "production"}" data-release="<app version>" async></script>
+     (or import it and call ScribeClock.init({ key, environment, release }) in the app entry point; the key may be inlined — it is publishable and write-only).
+   - After sign-in: ScribeClock.setUser({ id, email, name }). On sign-out: ScribeClock.setUser(null).
+   - Call ScribeClock.track("event_name", { ...properties }) for the actions that matter (signup, checkout_started, export, …).
+   - Wire the app's feedback form to ScribeClock.reportBug({ title, description, email, screenshotUrl }).
+   - Mark private form areas with data-sc-private so autocapture never records them.
+   - SPA: the SDK sends $pageview on history changes; for a custom router call ScribeClock.pageview(screenName).`;
+        case "ios":
+            return `iOS / macOS (Swift): write ONE dependency-free file, Sources/ScribeClock/ScribeClock.swift (or in the app target), using URLSession:
+   - ScribeClock.configure(key:environment:release:) — read the key from Info.plist (SCRIBECLOCK_INGEST_KEY filled from an .xcconfig / CI secret) or from the environment in Debug. release = CFBundleShortVersionString + " (" + CFBundleVersion + ")".
+   - Crashes: install NSSetUncaughtExceptionHandler and signal handlers (SIGABRT, SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP) that write a small JSON crash file (type "crash", exception type/value, Thread.callStackSymbols, breadcrumbs, last logs, context) to Application Support using only async-signal-safe work where possible; on the next launch read it, POST it, delete it.
+   - Errors: capture(_ error: Error, level:), captureMessage(_:level:). Never throw from the reporter.
+   - Breadcrumbs (ring buffer of 100): screen changes, taps, HTTP requests (method, path, status), app lifecycle. Logs (ring buffer of 300 lines) via log(_:level:).
+   - Analytics: a session id (UUID) created at launch and renewed after 30 minutes in the background; screen(_ name: String) sends {"type":"event","name":"$pageview","screen":name}; tap(_ element: String, screen:) sends {"name":"$click","element":element}; track(_ name:, properties:) for custom events; setUser(id:email:name:). Provide a SwiftUI View modifier .scribeClockScreen("Name") (onAppear) and, for UIKit, an optional viewDidAppear swizzle.
+   - Bug reports: reportBug(title:description:email:screenshot:) — upload the screenshot wherever the app already stores files and pass its URL in attachments, or omit it.
+   - Transport: queue events in memory and on disk, batch up to 50, flush every 10 s and when the app enters the background (use a background URLSession configuration so the request completes), retry with exponential backoff, drop after 3 attempts. Headers: Authorization: Bearer <key>, Content-Type: application/json. Every event carries environment, release, platform "ios" (or "macos"), context { device.model, os.name/version, app.version/build, locale }, session_id and user.
+   - Add XCTest coverage for batching, the 30-minute session rule, and the crash file round trip.`;
+        case "android":
+            return `ANDROID (Kotlin): write a small ScribeClock object (OkHttp or HttpURLConnection, no other dependencies):
+   - configure(context, key, environment, release = BuildConfig.VERSION_NAME + " (" + VERSION_CODE + ")"); the key comes from BuildConfig / local.properties / CI secret, never from source control.
+   - Crashes: Thread.setDefaultUncaughtExceptionHandler → write a crash JSON file (type "crash", exception class, message, stack trace, breadcrumbs, logs, context) then chain to the previous handler; on next start POST and delete it.
+   - captureException(Throwable, level), captureMessage, breadcrumb(category, message, data) ring buffer of 100, log(level, message) ring buffer of 300.
+   - Analytics: session id renewed after 30 min in background (ProcessLifecycleOwner), screen(name) → $pageview (hook Activity/Fragment lifecycle or Navigation's addOnDestinationChangedListener), click(element, screen) → $click, track(name, properties), setUser(id, email, name).
+   - reportBug(title, description, email, screenshotUrl) for the in-app feedback screen.
+   - Transport: in-memory + file queue, batches of 50, flush every 10 s and onStop/WorkManager for background delivery, exponential backoff, drop after 3 attempts. Headers: Authorization: Bearer <key>. Every event carries environment, release, platform "android", context { device.model, os.version, app.version/build, locale }, session_id, user.`;
+        case "react-native":
+            return `REACT NATIVE / EXPO (TypeScript): write src/scribeclock.ts (fetch only):
+   - init({ key, environment, release: Application.nativeApplicationVersion + build }); key from app config / EAS secret (EXPO_PUBLIC_SCRIBECLOCK_INGEST_KEY) — publishable, write-only.
+   - Crashes/errors: ErrorUtils.setGlobalHandler((error, isFatal) => send({ type: isFatal ? "crash" : "error", exception: { type: error.name, value: error.message, stacktrace: error.stack } })) and chain the previous handler; also hook unhandled promise rejections.
+   - Breadcrumbs (100) from navigation state changes, presses and fetch; logs (300) from console.* in development builds only.
+   - Analytics: session id renewed after 30 min via AppState; screen(name) → $pageview on React Navigation's onStateChange; press(element, screen) → $click; track(name, props); setUser(user).
+   - reportBug({ title, description, email, screenshotUrl }).
+   - Transport: queue, batches of 50, flush every 10 s and on AppState "background", retry with backoff, drop after 3 attempts. platform = Platform.OS; context from expo-device / react-native-device-info if present.`;
+        case "flutter":
+            return `FLUTTER (Dart): write lib/scribeclock.dart (package:http only):
+   - ScribeClock.configure(key:, environment:, release:) from --dart-define=SCRIBECLOCK_INGEST_KEY=…; release from package_info_plus.
+   - Crashes: FlutterError.onError and PlatformDispatcher.instance.onError → type "crash"/"error" with exception type, toString(), stack trace; chain the previous handlers.
+   - captureException, captureMessage, breadcrumb (100), log (300), screen(name) via a NavigatorObserver → $pageview, tap(element, screen) → $click, track(name, properties), setUser, reportBug(title, description, email, screenshotUrl).
+   - Session id renewed after 30 min in background (WidgetsBindingObserver lifecycle); batches of 50, flush every 10 s and on paused, backoff, drop after 3 attempts; context from device_info_plus.`;
+        case "node":
+            return `NODE / BACKEND (JavaScript or TypeScript): write src/scribeclock.ts (global fetch only):
+   - init({ key: process.env.SCRIBECLOCK_INGEST_KEY, environment: process.env.NODE_ENV, release: package.json version or the git SHA, platform: "node" }).
+   - process.on("uncaughtException") and process.on("unhandledRejection") → send type "crash" (then exit as before); an Express/Fastify/Koa error middleware → type "error" with { url, route, user, request id }; a logger transport (pino/winston) that keeps the last 300 lines as logs and attaches them to the next error.
+   - captureException(err, { route, user, tags }), captureMessage, track(name, properties, { user }) for product analytics from the backend (signup_completed, order_paid …).
+   - Transport: batch up to 50, flush every 5 s and on SIGTERM/beforeExit (await the last flush), retry with backoff, drop after 3 attempts, never throw.`;
+        case "python":
+            return `PYTHON: write scribeclock.py (requests or urllib only):
+   - init(key=os.environ["SCRIBECLOCK_INGEST_KEY"], environment=os.environ.get("APP_ENV"), release=<version or git SHA>, platform="python").
+   - sys.excepthook (and threading.excepthook) → type "crash" with exception type, str(exc), traceback.format_exc(); a logging.Handler that keeps the last 300 records and attaches them; framework hooks: Django middleware / Flask errorhandler / FastAPI exception handler → type "error" with url, route, user.
+   - capture_exception(exc, route=None, user=None, tags=None), capture_message, track(name, properties, user=None).
+   - Transport: a background thread with a queue, batches of 50, flush every 5 s and at exit (atexit), retry with backoff, drop after 3 attempts, never raise into the app.`;
+        default:
+            return `ANY LANGUAGE: write a small reporter module (HTTP client only) with: configure(key, environment, release); capture_exception / capture_message; a global unhandled-exception / crash hook that sends type "crash"; breadcrumbs (last 100) and logs (last 300) attached to each report; analytics: session id (new after 30 min idle), screen → {"type":"event","name":"$pageview","screen":…}, click → {"name":"$click","element":…}, track(name, properties), set_user; report_bug(title, description, email, screenshot_url); batched transport (≤ 50 events, flush every 10 s and on exit / background, backoff, drop after 3 attempts, never throw into the app).`;
+    }
+}
+/** Markdown prompt for an agent; `key` present → it is embedded (the key is publishable and write-only). */
+export function buildAgentPrompt(input = {}) {
+    const endpoint = input.endpoint ?? "https://scribeclock.com/ingest";
+    const docs = input.docsUrl ?? "https://scribeclock.com/help/bug-reports";
+    const platform = (AGENT_PROMPT_PLATFORMS.some((p) => p.id === input.platform) ? input.platform : "auto");
+    const key = input.key?.trim() || "";
+    const keyRef = key || "$SCRIBECLOCK_INGEST_KEY";
+    const env = input.environment?.trim() || null;
+    const project = input.projectName?.trim() ? `Project: ${input.projectName.trim()}${input.repo ? ` (${input.repo})` : ""}` : input.repo ? `Repository: ${input.repo}` : null;
+    const getKey = key
+        ? `1. The ingest key is above. Store it as SCRIBECLOCK_INGEST_KEY in the app's configuration (environment variable, secrets manager, .xcconfig / BuildConfig / --dart-define / app config). It is publishable and write-only, but keep it out of git anyway (add any file that holds it to .gitignore).`
+        : `1. Get the project's ingest key (sc_ing_…), in this order:
+   a. If you have the Scribe Clock MCP server: call connect_repo with repo = "owner/name" from \`git remote get-url origin\` (add create_project=true if no project lists this repository). The reply contains SCRIBECLOCK_INGEST_KEY and an agent_prompt with stack-specific steps.
+   b. Else if Node is available: run \`npx scribeclock connect --env\` inside the repository (sign in when it asks); it writes .scribeclock.json and puts SCRIBECLOCK_INGEST_KEY into .env.
+   c. Else ask the developer to copy the key from the project's Bug reports page in Scribe Clock (sidebar → App analytics → Bug reports).
+   Store it as SCRIBECLOCK_INGEST_KEY in the app's configuration (environment variable, secrets manager, .xcconfig / BuildConfig / --dart-define / app config). It is publishable and write-only, but keep it out of git anyway.`;
+    const stack = platform === "auto"
+        ? `3. Detect the stack from the repository (package.json, Package.swift / *.xcodeproj, build.gradle, pubspec.yaml, pyproject / requirements) and follow the matching block below. A monorepo gets one reporter per app, all with the same key.
+
+${["web", "ios", "android", "react-native", "flutter", "node", "python"].map((p) => `   ${platformBlock(p, keyRef, env).replace(/\n/g, "\n   ")}`).join("\n\n")}`
+        : `3. ${platformBlock(platform, keyRef, env)}`;
+    return [
+        `Connect this repository to Scribe Clock (${docs.replace(/\/help.*$/, "")}) so that errors, crashes, user bug reports, trace logs and product analytics from the app flow into Scribe Clock. There, every new problem becomes a task for the team (bundled with its duplicates, carrying an urgency), and the project's Analytics page shows active users, sessions, retention, screens, clicks, releases and crash-free rates.`,
+        ``,
+        ...(project ? [project] : []),
+        `Ingest endpoint: ${endpoint} (POST JSON, header \`Authorization: Bearer <key>\`; one event, or {"events":[…]} with up to 50)`,
+        ...(key ? [`Ingest key: ${key}`] : []),
+        `Docs (read first): ${docs}`,
+        ...(env ? [`Default environment: ${env}`] : []),
+        ``,
+        `Do this, in order, and do not stop until step 5 passes:`,
+        ``,
+        getKey,
+        ``,
+        `2. Install nothing heavy: the reporter is one small file using the platform's own HTTP client. Do not add Sentry, Firebase or other SDKs for this.`,
+        ``,
+        stack,
+        ``,
+        `4. Whatever the stack, the reporter must:
+   - send uncaught exceptions / crashes (type "crash" when the app dies, "error" otherwise) with exception type, message and stack trace;
+   - offer captureException / captureMessage / reportBug(title, description, email, screenshot) for the app to call;
+   - attach the last 100 breadcrumbs (navigation, taps/clicks, HTTP calls, lifecycle) and the last 300 log lines to every report;
+   - send analytics: a session_id that renews after 30 minutes idle, setUser({ id, email, name }), a $pageview event with "screen" on every screen change, a $click event with "element" on taps of buttons/links, and track(name, properties) for the actions that matter;
+   - put environment, release (version + build), platform and context { device, os, app, locale } on every event;
+   - batch (≤ 50), flush periodically and on background/exit, retry with backoff, drop after 3 attempts, never block or crash the app, and strip passwords, tokens and card numbers from anything it sends.`,
+        ``,
+        `5. Verify end to end: send one event {"type":"message","level":"info","message":"scribeclock connect test"} with the key and confirm the response is HTTP 200 with "ok": true; then send one type "error" with a fake stack trace and confirm it shows up — with the MCP server call project_health (or list_issues), with the CLI run \`scribeclock health\`, otherwise ask the developer to check the project's Bug reports page. Resolve that test issue afterwards (update_issue status=resolved / \`scribeclock issues resolve <id>\`).`,
+        ``,
+        `6. Commit the reporter and a short README section ("Crash reports and analytics go to Scribe Clock; set SCRIBECLOCK_INGEST_KEY"), without the key. Report back with: where the key is read from, what is captured automatically, and the helpers the app can call.`,
+        ``,
+        `Event shape (every field optional except type and message / exception):`,
+        EVENT_SHAPE,
+    ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribeclock",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "ScribeClock from the terminal: tasks, time clock, projects, PRDs, meetings, files, vault and Cloudflare — a thin client over the ScribeClock MCP server.",
   "license": "UNLICENSED",
   "author": "Haydar Al-Karar LLC, dba Karar Tech",