fix: make installation and report recipes follow their contracts

.github/workflows/checks.yml

@@ -0,0 +1,25 @@
+name: Recipe checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+concurrency:
+  group: recipes-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  recipes:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+      - name: Execute recipe contracts without external delivery
+        run: node --test tests/*.test.mjs
+      - name: Verify patch whitespace
+        run: git diff --check

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+- Match install commands to the registered marketplace and provide the advertised
+  optional voice command.
+- Preserve canonical report context, full IDs and storage-specific close hints.
+- Validate Telegram callback authorization and delivery outcomes; send long
+  context as a file and retain real reasons for Won't Fix.
+- Surface chat/email delivery rejection, split Slack text within its limit and
+  attach full Discord context with mentions disabled.
+- Pass complete GitHub CLI bodies through stdin without a shell, preserve
+  finalized voice segments and fix picker coordinates after scrolling.
+- Reject invalid terminal resolutions and propagate actual JSONL storage errors.
+- Add executable recipe contracts and Linux/Windows CI with synthetic boundaries.
+- Reuse the canonical CLI context, surface reporter-notification failures, handle
+  SVG picker classes and feature labels, and correct local Whisper setup/format
+  conversion instructions. Replace unsupported fix-time promises on the landing
+  page and share images with factual copy.

CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Contributing
+
+Keep the portable contract in `SPEC.md` compatible. Prefer the canonical context
+formatter to a second, shorter copy. Describe which installing-project helpers
+an example expects and which environment values stay on its server.
+
+For a behavioral recipe change, reproduce the problem and run:
+
+```bash
+node --test tests/*.test.mjs
+```
+
+Use synthetic reports, temporary files and loopback services. Never run a test
+against real recipients, provider credentials or a user's report store. Clearly
+label mocked SDK/browser boundaries and document what still needs verification
+in the installing project. Keep optional voice input optional; browser speech
+may use a browser-provider service, while local Whisper is a separate setup.
+
+Keep PRs focused, retain licenses/attribution, and list the relevant checks and
+limits. Do not commit local agent instructions, private reports or credentials.

INSTALL.md

@@ -12,7 +12,7 @@
 >
 > - **Any AI agent that doesn't auto-fetch URLs:** copy the content below the `---` line into the chat directly.
 >
-> **Claude Code users should NOT use this file.** Run `/plugin marketplace add bglglzd/bugkit`, `/plugin install bugkit@bglglzd-bugkit`, then `/bugkit:install` instead.
+> **Claude Code users should NOT use this file.** Run `/plugin marketplace add bglglzd/bugkit`, `/plugin install bugkit@bugkit`, then `/bugkit:install` instead.
 
 ---
 

README.md

@@ -4,9 +4,9 @@
 
 # bugkit
 
-**Users click. AI fixes. Done.**
+**Bug reports with context your coding agent can use.**
 
-*AI-friendly bug reports for any project. Paste the report into Claude Code, Cursor, or any AI agent — and the fix ships in minutes.*
+*Capture the page, selected element and errors with a report. Give the structured context to your coding agent, verify its patch, and record the resolution.*
 
 <img src="./assets/workflow.svg" alt="Illustrated workflow: report a problem, collect context, hand it to an agent, verify the fix" width="900" />
 
@@ -25,10 +25,10 @@
 ## Who this is for
 
 **🛠  Building for a client, boss, or team lead**
-Send them the staging link. They click the bug icon, pick what's broken, speak or type what they want. You paste into your AI agent. Fix ships the same day.
+Send them the staging link. They select the affected element and type or speak a description. Copy the structured report to your agent, then verify and record the fix.
 
 **🚀  Running a product with real users**
-Users click the bug icon from inside your app. Reports arrive with full context (URL, selector, stack trace, voice transcript). Paste → AI fixes → user gets notified. No more "can you repro?" back-and-forth.
+Reports can include the URL, selector, stack trace and voice transcript. Choose a recipe for storage/delivery and connect its status and notification flow to your application.
 
 ---
 
@@ -47,7 +47,7 @@ Three commands. Paste each one separately and wait for it to finish before the n
 **2.** Install the plugin:
 
 ```
-/plugin install bugkit@bglglzd-bugkit
+/plugin install bugkit@bugkit
 ```
 
 **3.** Start the installer in your project:
@@ -68,7 +68,9 @@ Install bugkit in this project from https://raw.githubusercontent.com/bglglzd/bu
 
 Either path detects your stack, asks **one** question (where should bug reports go — DB, GitHub Issues, Telegram, JSONL, email, Slack, Discord), and implements the matching [recipe](./recipes/). Voice transcription is offered too — 🎤 mic button next to the description field, Web Speech API by default, local Whisper as an offline upgrade, never paid APIs.
 
-Full install takes about 5–10 minutes for a web app.
+This repository ships a specification, plugin prompts and integration recipes.
+The installer adapts them to your project; it is not a hosted reporting service.
+Verify the generated integration using that project's actual UI or CLI.
 
 ---
 
@@ -77,9 +79,9 @@ Full install takes about 5–10 minutes for a web app.
 | Traditional feedback form | bugkit |
 |---|---|
 | "Something is broken" | Selector, XPath, HTML, viewport, stack trace, voice transcript |
-| Fix takes days | Fix ships in minutes |
+| Rebuild context in every conversation | Copy one predictable context block |
 | Format differs per project | Standardized spec — same ritual across every project |
-| No closed-loop status | Reporter notified at each state change |
+| No defined status flow | Status lifecycle and notification recipes |
 | Typing long descriptions is a chore | 🎤 press-to-speak, auto-transcribed |
 
 ---
@@ -91,6 +93,20 @@ Full install takes about 5–10 minutes for a web app.
 - **[INSTALL.md](./INSTALL.md)** — the universal paste-in prompt for non-Claude-Code agents
 - **[Landing page](https://bglglzd.github.io/bugkit)** — one-page tour with copy-ready install commands
 
+## Verify the recipes
+
+With Node.js 24 LTS, no package installation is required:
+
+```bash
+node --test tests/*.test.mjs
+```
+
+The checks execute documented snippets with real temporary JSONL files and
+loopback HTTP services. Browser speech, provider SDKs and report stores used by
+adapter tests are explicit synthetic fixtures. Tests do not contact Telegram,
+Slack, Discord, email, GitHub Issues or a paid AI service. See
+[validation boundaries](./VALIDATION.md) and [contributing](./CONTRIBUTING.md).
+
 ---
 
 MIT — use it anywhere. ⭐ Star or watch this repo for new releases.

VALIDATION.md

@@ -0,0 +1,41 @@
+# Validation boundaries
+
+bugkit contains a portable report specification, plugin commands/skills and
+recipes that an installing agent adapts to a project. It has no runtime package
+manifest or hosted delivery service. Recipe-specific SDKs belong to the target
+project; keep them on supported versions there.
+
+Run `node --test tests/*.test.mjs` with Node 24 LTS. CI runs the same checks on
+Linux and Windows. Tests extract the actual documented code blocks, rather than
+keeping a separate implementation of each adapter.
+
+The suite exercises:
+
+- Registered marketplace/install-command consistency and the advertised voice
+  command asset.
+- Canonical SPEC context fields, section order and storage-specific close hints.
+- Actual temporary JSONL create/list/show/copy/close, full UUID/numeric selection,
+  failure visibility and terminal resolution validation.
+- Telegram complete IDs, webhook secret and chat/user authorization, reason
+  replies, large context files and delivery failures using loopback HTTP.
+- Slack chunk reconstruction and Discord file delivery with long Unicode text,
+  controlled mentions, acknowledgement requests and rejected deliveries.
+- Resend's resolved-promise error contract and GitHub issue-body reconstruction
+  with explicit fake SDKs. No actual email or issue is created.
+- Literal CLI argv/stdin, synthetic speech-result sequences/restarts, and picker
+  coordinates with synthetic scrolled HTML/SVG browser objects.
+- Both Whisper proxy snippets' input validation, multipart byte forwarding and
+  upstream HTTP rejection using a synthetic loopback endpoint. Setup commands
+  are checked against the linked upstream source; no actual Whisper server or
+  model is executed by this suite.
+
+These checks establish the supplied examples' contracts. They do not establish
+live provider credentials, a generated project's framework integration, real
+microphone recognition, email deliverability, rate-limit behavior or AI fix
+quality. Plugin validation/clean local installation can be performed without an
+inference request using an isolated Claude Code configuration directory.
+
+Store a report before mirroring it. Delivery errors must remain distinguishable
+from a saved report; retrying a partially accepted multi-message operation may
+duplicate a notification. Telegram pending-reason storage in the example is for
+a single process; use durable storage for multiple workers/serverless handlers.

commands/voice.md

@@ -0,0 +1,9 @@
+---
+description: Add optional voice transcription to an existing bugkit web form.
+---
+
+The user wants optional voice input for their existing bugkit installation.
+Invoke the `adding-voice` skill. Preserve typed input, explain the browser/local
+transcription choice, and verify the supported path without paid API fallback.
+If the project has no browser-facing form, explain that this command does not
+apply to its sink; do not add a microphone flow to a CLI or bot.

docs/index.html

@@ -3,10 +3,10 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>bugkit — Users click. AI fixes. Done.</title>
-  <meta name="description" content="AI-friendly bug reports for any project. Users report bugs with full context. Paste into Claude Code / Cursor / Copilot. Fix ships in minutes.">
-  <meta property="og:title" content="bugkit — Users click. AI fixes. Done.">
-  <meta property="og:description" content="AI-friendly bug reports for any project. Paste into any AI coding agent. Fix ships in minutes.">
+  <title>bugkit — reports with context for coding agents</title>
+  <meta name="description" content="AI-friendly bug reports for any project. Users report bugs with full context. Paste into Claude Code / Cursor / Copilot. Verify the generated patch and record its resolution.">
+  <meta property="og:title" content="bugkit — reports with context for coding agents">
+  <meta property="og:description" content="AI-friendly bug reports for any project. Paste into any AI coding agent. Verify the generated patch and record its resolution.">
   <meta property="og:image" content="https://bglglzd.github.io/bugkit/assets/og-image.svg">
   <meta property="og:url" content="https://bglglzd.github.io/bugkit/">
   <meta name="twitter:card" content="summary_large_image">
@@ -19,9 +19,9 @@
   <section class="hero">
     <img src="assets/logo.svg" alt="bugkit logo" class="logo">
     <h1>bugkit</h1>
-    <div class="tagline">Users click. AI fixes. Done.</div>
+    <div class="tagline">Reports with context for coding agents.</div>
     <p class="subtitle">
-      AI-friendly bug reports for any project. Users report bugs with full context — URL, element selector, stack trace, viewport, voice transcript. Admins hit one button. Paste into Claude Code or any AI coding agent. Fix ships in minutes.
+      AI-friendly bug reports for any project. Users report bugs with full context — URL, element selector, stack trace, viewport, voice transcript. Admins hit one button. Paste into Claude Code or any AI coding agent. Verify the generated patch and record its resolution.
     </p>
     <div class="badges">
       <a href="https://github.com/bglglzd/bugkit"><img alt="stars" src="https://img.shields.io/github/stars/bglglzd/bugkit?style=social"></a>
@@ -45,11 +45,11 @@ <h2>Who this is for</h2>
   <div class="personas">
     <div class="persona">
       <h3>🛠  Building for a client or boss</h3>
-      <p>Send them the staging link. They click the bug icon, pick the broken element, speak or type what they want. You paste the output into your AI coding agent. Fix ships the same day — exactly how they described it. No more "did they mean the header or the hero?"</p>
+      <p>Send them the staging link. They click the bug icon, pick the broken element, speak or type what they want. You paste the output into your AI coding agent. Verify the generated patch against their report. No more "did they mean the header or the hero?"</p>
     </div>
     <div class="persona">
       <h3>🚀  Running a product with users</h3>
-      <p>Users click the bug icon from inside your app. Reports arrive with full context — selector, stack trace, viewport, voice transcript. Paste → AI fixes → user gets notified. Your product improves as fast as you can read reports.</p>
+      <p>Users click the bug icon from inside your app. Reports arrive with full context — selector, stack trace, viewport, voice transcript. Copy context to your agent, verify its patch, and connect status notifications to your application.</p>
     </div>
   </div>
 
@@ -80,8 +80,8 @@ <h2>Install — pick your AI agent</h2>
           <div class="step-content">
             <div class="step-label">Install the plugin</div>
             <div class="step-row">
-              <pre class="step-cmd">/plugin install bugkit@bglglzd-bugkit</pre>
-              <button class="step-copy-btn" data-copy-text="/plugin install bugkit@bglglzd-bugkit">Copy</button>
+              <pre class="step-cmd">/plugin install bugkit@bugkit</pre>
+              <button class="step-copy-btn" data-copy-text="/plugin install bugkit@bugkit">Copy</button>
             </div>
           </div>
         </li>
@@ -131,7 +131,7 @@ <h2>How it works</h2>
   ↓
 Admin marks report "resolved" with a short note + commit SHA
   ↓
-Reporter gets notified</div>
+Application sends its configured status notification</div>
 
   <h2>Why this beats a feedback form</h2>
   <table>
@@ -141,9 +141,9 @@ <h2>Why this beats a feedback form</h2>
     <tbody>
       <tr><td>"Something is broken"</td><td>Selector, XPath, HTML, viewport, URL, stack trace, voice transcript</td></tr>
       <tr><td>Admin reads, asks clarifying questions</td><td>Admin pastes to AI, AI already has everything</td></tr>
-      <tr><td>Fix takes days</td><td>Fix ships in minutes</td></tr>
+      <tr><td>Rebuild context in each conversation</td><td>Copy one predictable context block</td></tr>
       <tr><td>Format differs per project</td><td>Standardized spec — same ritual across all your projects</td></tr>
-      <tr><td>No closed-loop status</td><td>Reporter notified at each state change</td></tr>
+      <tr><td>No defined status flow</td><td>Status lifecycle and notification recipes</td></tr>
       <tr><td>Typing long descriptions is a chore</td><td>🎤 press-to-speak, auto-transcribed</td></tr>
     </tbody>
   </table>