@@ -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..d0878ba
--- /dev/null
+++ b/VALIDATION.md
@@ -0,0 +1,37 @@
+# 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 a synthetic scrolled browser object.
+
+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/commands/voice.md b/commands/voice.md
new file mode 100644
index 0000000..7081bf2
--- /dev/null
+++ b/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.
diff --git a/docs/index.html b/docs/index.html
index 31ae076..e32fefe 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -80,8 +80,8 @@ /plugin install bugkit@bglglzd-bugkit- +
/plugin install bugkit@bugkit+
Synthetic
', renderPlainText: () => 'Synthetic', + }) + await assert.rejects(sendBugByEmail(report), /Email provider rejected/) + rejected = false; assert.equal((await sendBugByEmail(report)).id, 'synthetic-mail') +}) + +test('GitHub issue rendering retains canonical context and assigns server IDs without rewriting user text', async () => { + const requests = [] + let rejectUpdate = false + class Octokit { constructor() { this.issues = { + create: async input => { requests.push(input); return {data: {number: 42, html_url: 'https://example.invalid/issues/42', body: input.body}} }, + update: async input => { if (rejectUpdate) throw Error('synthetic update rejection'); requests.push(input) }, + } } } + const {createBugReport} = load(await snippet('recipes/github-issues.md', '## Implementation sketch (Node)'), ['createBugReport'], { + Octokit, buildAIContext: await contextBuilder(), extractTitle: text => text.split('\n')[0].slice(0, 200), + }) + const input = {...report, description: 'Synthetic literal #PENDING ```\n