@@ -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.
diff --git a/VALIDATION.md b/VALIDATION.md
new file mode 100644
index 0000000..6a90430
--- /dev/null
+++ b/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.
diff --git a/assets/og-image.svg b/assets/og-image.svg
index 651b244..38004d9 100644
--- a/assets/og-image.svg
+++ b/assets/og-image.svg
@@ -1,5 +1,5 @@
-