diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 0cfe183..a06cbd5 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -7,8 +7,8 @@
{
"name": "bugkit",
"source": "./",
- "version": "1.0.0",
- "description": "AI-friendly bug reports for any project."
+ "version": "1.1.0",
+ "description": "Bug report forms and tested integration recipes."
}
]
}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 816db9e..0e822be 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "bugkit",
- "description": "AI-friendly bug reports for any project. Users click, AI fixes, done.",
- "version": "1.0.0",
+ "description": "Bug report forms, context export and integration acceptance checks.",
+ "version": "1.1.0",
"author": {
"name": "bugkit"
},
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..a0354c4
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.zip binary
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..d54990d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,31 @@
+name: Bug report
+description: Report a reproducible extension or integration-example defect.
+body:
+ - type: markdown
+ attributes:
+ value: Remove private text, URLs, credentials and screenshot data before posting. Use SECURITY.md for vulnerabilities.
+ - type: dropdown
+ id: area
+ attributes:
+ label: Area
+ options: [Chrome extension, Application installer, Recipe or specification, Documentation]
+ validations:
+ required: true
+ - type: input
+ id: version
+ attributes:
+ label: BugKit version and browser/runtime
+ placeholder: "1.1.0; Chrome version; Windows/macOS/Linux"
+ validations:
+ required: true
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Steps, expected result and actual result
+ description: Include a small synthetic example when possible.
+ validations:
+ required: true
+ - type: textarea
+ id: context
+ attributes:
+ label: Sanitized context or error
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..872ca12
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,3 @@
+Describe the concrete problem and resulting behavior.
+
+Validation: list relevant executed checks and any untested platform/provider path. Use synthetic data and retain BugKit v1 compatibility, licenses and attribution.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..b712cdb
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,12 @@
+version: 2
+updates:
+ - package-ecosystem: npm
+ directory: /
+ schedule:
+ interval: monthly
+ open-pull-requests-limit: 3
+ - package-ecosystem: github-actions
+ directory: /
+ schedule:
+ interval: monthly
+ open-pull-requests-limit: 3
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
index 44a90ab..8612a93 100644
--- a/.github/workflows/checks.yml
+++ b/.github/workflows/checks.yml
@@ -1,4 +1,4 @@
-name: Recipe checks
+name: BugKit checks
on:
push:
branches: [main]
@@ -19,7 +19,25 @@ jobs:
- 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: Check source and manifest
+ run: npm run check
+ - name: Execute extension and recipe contracts without external delivery
+ run: npm test
- name: Verify patch whitespace
run: git diff --check
+ browser:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+ with:
+ node-version: 24
+ cache: npm
+ - run: npm ci
+ - run: npx playwright install --with-deps chromium
+ - name: Exercise the real extension
+ run: npm run test:browser
+ - name: Verify documentation and page controls
+ run: npm run test:docs
+ - name: Build source-bound Chrome ZIP
+ run: python scripts/package.py
diff --git a/.gitignore b/.gitignore
index 2aff0ac..53c1450 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,10 @@ node_modules/
.env.local
.bugreports.jsonl
.playwright-mcp/
+
+dist/
+artifacts/
+playwright-report/
+test-results/
+__pycache__/
+AGENTS.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 278f40d..d74d54d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
# Changelog
+## 1.1.0 — 2026-11-13
+
+- Added the standalone BugKit MARK Chrome extension, local demo, session drafts and Markdown/JSON/PNG export.
+- Added a ready-to-load ZIP, source-bound build manifest and automated real-Chromium acceptance checks.
+- Replaced the project logo with an ImageGen asset and updated README, Pages, English/Russian setup and troubleshooting.
+- Unified plugin and universal installer requirements: upgrades preserve reports and verify recovery, authorization and closure.
+- Framed the shared recipe context as untrusted data, added baseline/application masking and text-only export, and tolerated malformed optional blocks.
+- Retained the existing MIT license, recipe adapters and BugKit v1 field/status compatibility.
+
## Unreleased
- Match install commands to the registered marketplace and provide the advertised
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ed1546c..1efd990 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,7 +7,8 @@ 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
+npm run check
+npm test
```
Use synthetic reports, temporary files and loopback services. Never run a test
@@ -18,3 +19,9 @@ 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.
+
+For extension behavior, also run `npm ci`, `npx playwright install chromium`
+and `npm run test:browser`. The browser harness uses only an isolated profile
+and synthetic loopback data. Change both package/manifest versions together.
+Build release ZIPs from a clean commit with `python scripts/package.py`, then
+exercise the extracted package and verify its digest before publishing.
diff --git a/HARDENING.md b/HARDENING.md
new file mode 100644
index 0000000..d2aed3f
--- /dev/null
+++ b/HARDENING.md
@@ -0,0 +1,56 @@
+# Application integration acceptance
+
+These requirements apply when adapting BugKit to an application. Recipe snippets do not implement a host's authorization, transactions or notification system. Implement and verify applicable requirements before calling an integration complete. The Chrome extension has its own [scope](docs/EXTENSION.md).
+
+## Data and authorization
+
+- Derive author, roles, tenant and release from authenticated server state, never submitted fields. Verify every referenced entity against the actor's scope.
+- Reuse a scoped query and authorized-target operation for lists, details, counters, exports, edits, attachments and batches. Missing and inaccessible records have the same response.
+- Allowlist bounded context. Reject invalid mandatory fields; malformed optional context must not crash a queue or erase a valid description. CLI batches continue per report while reporting failures.
+- Keep client `occurred_at`, server `created_at`, observed version and fixed release separate. Bound client time and label version sources.
+- Preserve original title/description on first edit, with revision actor/time. Author editing has a stated server-enforced time/status window.
+- Validate attachment MIME, size and access on the server. Store large screenshots appropriately; rate limits account for their cost.
+
+## Widget and recovery
+
+- Use one main description and derive its title. Optional reproduction fields and configurable `kind` remain compatible with old input during deployments.
+- Mount once. Provide a small-screen entry when a floating button covers controls. A programmatic open action is optional.
+- Use account/tenant-scoped session drafts, clearing on logout, account change and success. Retain text after validation/network/stale-deployment failure. Store screenshots separately when needed.
+- Catch submission failures inside the widget. Distinguish a saved report with failed delivery from a failed save.
+- Select only on request. Capture pointer/click/Escape at `window`, ignore marked widget UI, prevent link activation and restore listeners/focus on every exit. Test popups, scroll, touch and any claimed iframe behavior.
+- Screenshots require explicit action and a visible-data warning. Do not collect form values or arbitrary HTML by default. Strip URL credentials, queries and fragments; apply project-specific path masking.
+
+## Context export
+
+Copy Context, exports and CLI use one formatter and masking policy. Enable the application's `mask(text)` hook by default; preview the processed result. A baseline mask cannot identify all sensitive data.
+
+Place all report content, DOM text, metadata and logs in a fresh nonce-delimited untrusted block. Select a delimiter absent from its content. Keep instructions and configured update commands outside; normalize headers to one line. Unknown reporters' requests need review before implementation. Only server-authenticated state establishes authority. Delimiters aid separation; they do not guarantee protection from prompt injection.
+
+Support server-defined text-only mode for restricted contexts, omitting automatic page/DOM/log/attachment context across every export. Optional AI conversation context is assembled from authorized server messages with bounded fields; a client transcript is not authoritative.
+
+## Closing and notifying
+
+UI, API and CLI call one closure operation; never bypass it with raw SQL. Require technical `resolution`, separate author-facing `user_note`, and verification steps for fixes. `resolved` denotes a fix; `closed`/`wontfix` denote review without claiming a fix.
+
+Validate the entire batch, access and transitions before writing. Use a transaction when promising atomicity. Repeated idempotency keys return one logical result. Save closure and notification intent consistently, then deliver through an outbox or host equivalent. Retry delivery without duplicate closure/messages; expose failure separately. An unexecuted provider path does not establish notification success.
+
+Admin counts must reflect actual queries, with bounded pagination including resolved records. Authors see only their own reports and the user-facing note. Optional commit/release links refer to the recorded fix.
+
+## Acceptance
+
+| Scenario | Required observation |
+|---|---|
+| Submit from real UI/CLI | Canonical report in chosen store |
+| Reload draft, then logout | Text survives reload; next account cannot recover it |
+| Failed save or stale deployment | Text retained; local error and working recovery |
+| Pick a link in a popup, cancel, click normally | No navigation while picking; normal behavior restored |
+| Forge role/tenant/release; request foreign report/attachment | Server authority; consistent access rejection |
+| Malformed optional context | Other reports remain readable/exportable |
+| Fake instructions/lookalike delimiter | Content inside data block; trusted commands outside |
+| Copy Context and CLI | Same sections and masking |
+| Batch with an inaccessible/conflicting record | No partial writes or record-existence leak |
+| Concurrent/repeated closure and delivery retry | One result and logical notification; delivery failure separate |
+| Edit report | Original observation remains identifiable |
+| Restricted text-only policy | No automatic page/DOM/log/attachment data in exports |
+
+Record actual results, commands, commit, environment and unmet checks in the host's integration note. Repository snippet tests do not establish acceptance of an untested host integration.
diff --git a/INSTALL.md b/INSTALL.md
index 047e94a..f8632c2 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,107 +1,37 @@
-# bugkit — universal install prompt
+# Install BugKit
-> **How to use this file (not Claude Code):**
->
-> - **Cursor / Copilot Chat / ChatGPT / Codex / Gemini CLI / Aider / Cline:** paste this into your AI chat:
->
-> ```
-> Install bugkit in this project from https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
-> ```
->
-> The agent fetches this file and follows it.
->
-> - **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@bugkit`, then `/bugkit:install` instead.
+## Use the Chrome extension
----
-
-You are installing **bugkit** — a portable, AI-friendly bug report system — into the current project. The value: reports carry enough context (URL, element selector, stack trace, viewport, etc.) that an AI assistant can fix the bug from one paste. The data contract is standardized in **bugkit Spec v1** so the "Copy Context → Paste → Fix → Close" ritual is identical across any project that installs it.
-
-## Step 1 — Understand the project
-
-1. **Stack** — read `package.json` / `go.mod` / `Cargo.toml` / `pyproject.toml` / `requirements.txt` / `composer.json` / `Gemfile` / etc.
-2. **Shape** — full-stack web app, API-only backend, CLI tool, static site, mobile app, bot, other.
-3. **Existing infra** — database, auth, notifications layer, CI/CD. Reuse what exists.
-4. **Conventions** — skim `CLAUDE.md`, `AGENTS.md`, a source file or two. Match the project's style.
-
-Report back three bullets on what you found, then continue.
-
-## Step 2 — Ask ONE question
-
-Ask the user:
-
-> **Where should bug reports be stored or delivered?** Pick one:
-> 1. **Local DB** (recommended if the project has one) — full admin UI with status tracking
-> 2. **GitHub Issues** — no DB needed; bugs open as issues with a `bugkit` label
-> 3. **Telegram** — bugs get DM'd to a chat via bot token
-> 4. **JSONL file** — simplest; append to `./.bugreports.jsonl`. Local-only.
-> 5. **Email** — send via SMTP / SendGrid / Resend
-> 6. **Slack** / **Discord** — webhook to a channel
-> 7. **Multiple** — e.g. "DB + mirror to Telegram for notifications"
-
-Recommend based on stack if unsure:
-- Full-stack web app with a DB → option 1
-- Open-source CLI / static site → option 2
-- Personal / MVP → option 4, upgrade later
-- Solo dev in Telegram → option 3
+Download **BugKit-MARK-1.1.0.zip** from [GitHub Releases](https://github.com/bglglzd/bugkit/releases/latest), extract it, then load its **extension** folder at `chrome://extensions` with Developer mode enabled. Click the toolbar icon or press Ctrl+Shift+Y (⌘+Shift+Y on macOS). No development tools or application changes are required.
-## Step 3 — Fetch the matching recipe and implement
+See the [Russian walkthrough](docs/INSTALL.ru.md) and [extension reference](docs/EXTENSION.md) for updates, permissions and recovery.
-| Sink | Recipe URL |
-|---|---|
-| Local DB | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/web-app-full.md` |
-| GitHub Issues | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/github-issues.md` |
-| Telegram | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/telegram-bot.md` |
-| JSONL | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/jsonl-file.md` |
-| Email | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/email.md` |
-| Slack / Discord | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/slack-discord.md` |
-| CLI | `https://raw.githubusercontent.com/bglglzd/bugkit/main/recipes/cli-tool.md` |
+## Integrate reporting into a project
-Fetch the chosen recipe and follow it. Non-negotiables from the spec (`https://raw.githubusercontent.com/bglglzd/bugkit/main/SPEC.md`):
+Claude Code:
-1. **Field names** — use exactly: `id, type, title, description, status, created_at, reporter, environment, page, client, element, error, logs, attachments, resolution, resolved_at, resolved_by, commit_sha, how_to_verify`. Do not rename.
-2. **Status lifecycle** — `open → in_progress → resolved → closed`, plus terminal `wontfix`. Resolution required when moving to a terminal state.
-3. **AI context format** — admins MUST be able to produce the exact text block from SPEC.md §3. Do not reorder sections, do not invent new labels.
-4. **`bugkit_spec: "1"`** — include in stored reports.
+```text
+/plugin marketplace add bglglzd/bugkit
+/plugin install bugkit@bugkit
+/bugkit:install
+```
-## Step 4 — Offer voice transcription (web recipes only)
+Other coding agents can read the task below. These are installer instructions for a project that has explicitly requested BugKit integration.
-If the chosen recipe produces a browser-facing form (Local DB, GitHub Issues, or similar), after the main install succeeds, ask:
-
-> **Voice transcription lets reporters speak their bug description instead of typing. Uses the browser's Web Speech API by default — free, no keys, works in Chrome/Edge/Safari. Want to enable it? (Y/n)**
-
-If yes, add a 🎤 mic button next to the description textarea. Wire up the Web Speech API per `recipes/web-app-full.md §Voice (optional)`. Optional upgrade: local Whisper (whisper.cpp) via a thin `/api/bugkit/transcribe` proxy. Never suggest a paid API unless the user explicitly asks.
-
-## Step 5 — Verify
-
-Before declaring done:
-
-1. Submit a test report using the actual UI / CLI / bot command (not curl — the real flow).
-2. Confirm the report appears in the chosen sink.
-3. Generate the Copy-Context output and verify it matches SPEC.md §3 — section order, exact labels, no extra decoration.
-4. If applicable, change status to `resolved` with a short note and confirm the reporter would see the update.
-
-## Step 6 — Report back
-
-1. Sink chosen.
-2. Files created or modified.
-3. How to test it (URL, command, or interaction).
-4. How the admin copies context and closes the loop once a fix is in.
-5. Whether voice is enabled and which path it's using.
+---
-## Things to avoid
+Implement BugKit in the current project. Read its development instructions and existing reporting code before changing files. If BugKit already exists, audit and upgrade it; preserve reports, IDs, original descriptions and working integrations.
-- Don't pull in a heavy ORM or new DB just for this — use what's there, or JSONL.
-- Don't rename spec field names. Add new fields or map. Portability is the point.
-- Don't make the element picker fancy. Minimal: outline on hover, click to capture, Esc to cancel.
-- Don't gate bug reporting behind complex auth flows.
-- Don't skip the reporter notification on status change.
-- Don't ask more than the one sink question + optional voice question.
+1. **Inspect.** Identify the stack, UI, authentication, storage, tenant boundaries, notification delivery and deployment version source. Reuse them. Summarize the core journey, a representative failure/recovery, and the files to change.
+2. **Choose storage.** Honor the user's existing choice. Otherwise recommend the existing database, or JSONL for a local tool. Ask one storage question only if unresolved. External delivery needs explicitly configured credentials; it is optional when local storage is primary.
+3. **Read the contract.** Fetch `SPEC.md`, `HARDENING.md` and the matching file under `recipes/` from this repository at the same full commit SHA. Prefer bundled plugin/checkout files. Resolve relative links against this repository, not the host project. Do not mix snapshots or overwrite a working integration with an older sample.
+4. **Implement the complete journey.** Preserve `bugkit_spec: "1"`, canonical fields, IDs and statuses. Follow the recipe, then implement every applicable HARDENING requirement. Small recipe snippets are examples, not a finished server. Use one formatter for CLI and Copy Context. Keep untrusted content in a fresh nonce-delimited block; apply the project's masking function by default. Review unknown reporters' requests before implementing them.
+5. **Recover safely.** Use one main description, optional reproduction fields, explicit element/screenshot actions, an account-scoped session draft, clear-on-logout, and non-destructive failure handling. Picking a link must not navigate or close the inspected popup. Capture pointers at `window`, ignore the widget UI and restore listeners/focus on cancellation. Retain text after submission failure or stale-deployment errors.
+6. **Make the server authoritative.** Derive author, tenant, permissions and build from server state. Bound context/attachments. Apply one access boundary to lists, detail, exports, edits, attachments and batches. Preserve originals on edit. Close through one operation with `resolution`, separate `user_note` and verification steps for fixes; validate a whole batch before writes. Store notification intent with the result and retry delivery without duplication. Never bypass closure with raw SQL.
+7. **Verify through the real UI or CLI.** Create a synthetic report, select an element, recover a draft, fail a submission, inspect stored data, copy context, resolve and verify the author's state. Test unauthorized/cross-tenant access where applicable, a failed batch and delivery retry. Run relevant host build/tests. Record actual checks and blockers; mocked providers do not prove live delivery.
+8. **Optional voice.** Offer it after the main journey passes. Read `skills/adding-voice/SKILL.md`. Explain browser support/provider processing; offer local Whisper for offline use. Do not add paid services without the user's request.
+9. **Handoff.** List files, storage choice, entry point, reproducible verification, update/rollback instructions and limits. Save an integration note in the host's existing docs so future upgrades do not need rediscovery.
-## If you get stuck
+Recipes: [database/web app](recipes/web-app-full.md), [GitHub Issues](recipes/github-issues.md), [Telegram](recipes/telegram-bot.md), [JSONL](recipes/jsonl-file.md), [email](recipes/email.md), [Slack/Discord](recipes/slack-discord.md), [CLI](recipes/cli-tool.md).
-- Read SPEC.md in full.
-- Read the chosen recipe in full.
-- Compose from multiple recipes if needed — but keep the Copy-Context format unchanged.
-- Ask the user for one missing piece at a time.
+Source: [bglglzd/bugkit](https://github.com/bglglzd/bugkit). These instructions do not authorize contacting users, publishing code or modifying production data.
diff --git a/README.md b/README.md
index 7d54746..5e25557 100644
--- a/README.md
+++ b/README.md
@@ -1,112 +1,75 @@
-
+
-
+# BugKit
-# bugkit
+Capture bug reports in Chrome, or add reporting to your application. Reports include a description, page context and selected elements, with Markdown for a developer or coding agent.
-**Bug reports with context your coding agent can use.**
+[Download Chrome extension](https://github.com/bglglzd/bugkit/releases/latest) · [Installation](INSTALL.md) · [Русская инструкция](docs/INSTALL.ru.md) · [Demo and documentation](https://bglglzd.github.io/bugkit/)
-*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.*
+
-
+## Chrome extension: BugKit MARK
-*Workflow illustration; integration and validation happen in your project.*
+1. Download **BugKit-MARK-1.1.0.zip** from [Releases](https://github.com/bglglzd/bugkit/releases/latest) and extract it to a permanent folder.
+2. Open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked** and select the extracted **extension** folder containing `manifest.json`.
+3. Open a website. Click the BugKit MARK toolbar icon, or press **Ctrl+Shift+Y** (**⌘+Shift+Y** on macOS).
+4. Select an element, describe the problem and review the report. Copy Markdown or save `.md`, `.json` and an optional screenshot.
-
+No Git, Node.js, account, API key or build is needed. The interface is currently in Russian. Change the shortcut at `chrome://extensions/shortcuts`. Keep the extracted folder: Chrome loads the extension from there. To update, replace its contents, click **Reload** on the extension card and reload the website tab. GitHub ZIP installations do not update automatically. There is no Chrome Web Store listing.
-[](https://github.com/bglglzd/bugkit)
-[](./SPEC.md)
-[](./LICENSE)
+The panel is injected only when invoked. Reports stay local until copied or exported. Session drafts retain text and selected elements across page reloads; screenshots must be added again after a reload. Drafts disappear when the tab or browser session closes. The extension cannot detect logout on arbitrary websites: clear its draft before sharing a browser session or changing accounts.
-
+URL credentials, query parameters and fragments are removed from report context. Form values, full HTML, console history and network traffic are not collected. Selected visible text, URL paths and screenshots can still contain private information; review them before sharing. Screenshots require a separate action, cover the visible viewport and exclude the MARK panel.
----
+Chrome blocks injection on internal pages, its extension store and some viewers. Closed Shadow DOM and iframe contents are not inspected. File URLs require **Allow access to file URLs**. MARK does not send issues to a server or change their status. See [permissions and limitations](docs/EXTENSION.md).
-## Who this is for
+## Add BugKit to an application
-**🛠 Building for a client, boss, or team lead**
-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.
+This path adds a form, storage, status management and notifications to an existing project. It uses a specification and agent instructions; it is not a prebuilt backend. [INSTALL.md](INSTALL.md) covers both paths.
-**🚀 Running a product with real users**
-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.
+For Claude Code, run each command separately:
----
-
-## Install
-
-### Claude Code
-
-Three commands. Paste each one separately and wait for it to finish before the next.
-
-**1.** Add the bugkit marketplace:
-
-```
+```text
/plugin marketplace add bglglzd/bugkit
-```
-
-**2.** Install the plugin:
-
-```
/plugin install bugkit@bugkit
-```
-
-**3.** Start the installer in your project:
-
-```
/bugkit:install
```
-### Any other AI agent
-
-Cursor, GitHub Copilot, ChatGPT, Gemini, Aider, Cline — paste this one line into the chat:
+For other agents, pass this instruction:
+```text
+Install BugKit in this project using https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
```
-Install bugkit in this project from https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
-```
-
----
-
-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.
-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.
+The installer reuses existing UI, authentication and storage, then implements the selected [recipe](recipes/). Both installer paths require [integration acceptance checks](HARDENING.md), including draft recovery, access checks, safe context export and separate technical/user resolution notes. Optional voice input belongs to application integrations; MARK has no microphone feature. Browser speech recognition may use the browser provider's service.
----
+## Develop and verify
-## Why this beats a feedback form
+Node.js **24 LTS or newer** is needed for development. The regular checks have no dependencies:
-| Traditional feedback form | bugkit |
-|---|---|
-| "Something is broken" | Selector, XPath, HTML, viewport, stack trace, voice transcript |
-| Rebuild context in every conversation | Copy one predictable context block |
-| Format differs per project | Standardized spec — same ritual across every project |
-| No defined status flow | Status lifecycle and notification recipes |
-| Typing long descriptions is a chore | 🎤 press-to-speak, auto-transcribed |
-
----
-
-## Docs
+```sh
+npm run check
+npm test
+npm run demo
+```
-- **[SPEC.md](./SPEC.md)** — the portable data contract
-- **[recipes/](./recipes/)** — 7 sink adapters (DB, GitHub Issues, Telegram, JSONL, email, Slack, Discord, CLI)
-- **[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
+The synthetic demo listens on `http://127.0.0.1:4173`. Stop it with Ctrl+C. Browser acceptance uses a pinned development dependency and Chromium:
-## Verify the recipes
+```sh
+npm ci
+npx playwright install chromium
+npm run test:browser
+```
-With Node.js 24 LTS, no package installation is required:
+Browser checks use a disposable profile and real extension APIs. They do not operate an existing browser. [Validation boundaries](VALIDATION.md) distinguish automated checks from manual Windows/macOS verification and provider fixtures.
-```bash
-node --test tests/*.test.mjs
-```
+To build the release ZIP, install Python **3.11+** and run `python scripts/package.py` from a clean committed checkout. Its manifest binds the source commit and SHA256 of packaged files; local data, dependencies and private evidence are excluded.
-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).
+## Reference
----
+- [SPEC.md](SPEC.md): portable v1 report fields and context format, with additive reliability fields.
+- [HARDENING.md](HARDENING.md): required behavior for application integrations.
+- [recipes/](recipes/): database, GitHub Issues, Telegram, JSONL, email, Slack/Discord and CLI examples.
+- [Contributing](CONTRIBUTING.md), [changelog](CHANGELOG.md), [security](SECURITY.md) and [MIT license](LICENSE).
-MIT — use it anywhere. ⭐ Star or watch this repo for new releases.
+BugKit MARK was contributed as a standalone local extension and integrated here with its name retained. Application-specific code and internal deployment instructions are not part of this repository.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..8b7437c
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,5 @@
+# Security reports
+
+Do not post credentials, private reports or screenshots containing personal data in public issues. Use GitHub's **Report a vulnerability** option when available. If unavailable, ask for a private reporting route without disclosing the vulnerability or affected data.
+
+The extension is local and requires deliberate export. Application recipes must follow the host's privacy and access rules; see [HARDENING.md](HARDENING.md). Fixes target the latest release.
diff --git a/SPEC.md b/SPEC.md
index 6a8f360..814b0c7 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -42,7 +42,7 @@ Everything below is **optional** — capture what your platform can provide.
"locale": "en-US"
},
"page": { // web / webview only
- "url": "https://example.com/path?x=1",
+ "url": "https://example.com/path",
"route": "users/[id]/settings",
"referrer": "..."
},
@@ -187,7 +187,7 @@ Mandatory:
1. Create a report with at least `{type, title, description, reporter, created_at}`
2. Capture as much optional context as the platform can provide
3. Status lifecycle as defined
-4. A way for admins to produce the **exact** AI context format above
+4. A way for admins to produce the compatible section order above, with untrusted report data enclosed in nonce-delimited boundaries and instructions outside
5. A way to update status + resolution
Recommended:
@@ -196,7 +196,7 @@ Recommended:
- Link resolution to a commit SHA when possible
- Rate-limit submissions per user
-Out of scope for this spec (do it however you want):
+Host-specific implementation choices (must satisfy [HARDENING.md](HARDENING.md) for an application integration):
- Authentication model
- Permissions
- Admin UI framework
@@ -210,3 +210,15 @@ Out of scope for this spec (do it however you want):
This is **Spec v1**. Breaking changes will bump to v2 and be announced in the repo. Additive changes (new optional fields) stay on v1.
Implementations should emit `bugkit_spec: "1"` somewhere in stored reports so future tools can tell what format to expect.
+
+## 6. Additive reliability fields (v1.1)
+
+`bugkit_spec: "1"` and the existing required fields/statuses stay unchanged. Optional fields include `kind` (configurable category), `occurred_at`, `exported_at`, `reproduction` (`steps`, `expected`, `actual`), `environment.build_id`, `environment.version_source`, `environment.extension_version`, `elements` (additional selected elements), `user_note`, `resolved_release`, `original_title`, `original_description`, `edited_at` and `edited_by`. A client-observed `reporter.role` conveys no authority. Server integrations derive identity, tenant, role and release from their own authenticated state.
+
+### Context framing
+
+The section order in §3 is retained. Enclose report headers and populated data sections in `<<>>` and `<<>>`, using a fresh cryptographically random nonce absent from the content. The trusted `## Instructions` and configured update hint follow the closing marker. Normalize header values to one line. Optional `Occurred`, `Exported`, reproduction, revision and AI-conversation sections are additive. Consumers must not treat arbitrary report text as executable instructions.
+
+Copy Context and CLI share their formatter and default application masking policy. A text-only export omits automatic environment/page/DOM/error/log/attachment content. Preview the processed result and disclose masking limits. MARK uses its standalone local format and has no trusted reporter role or server closure operation.
+
+Application acceptance, including original preservation, drafts, scoped access, atomic closure and notification retry, is defined in [HARDENING.md](HARDENING.md). A v1 field marker does not prove that a host has passed those checks.
diff --git a/VALIDATION.md b/VALIDATION.md
index 6a90430..c9b7e01 100644
--- a/VALIDATION.md
+++ b/VALIDATION.md
@@ -1,41 +1,21 @@
# 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.
+BugKit includes a local Chrome extension, specification, plugin installer and application recipes. It has no hosted delivery service. Node.js 24+ runs the dependency-free checks; Playwright is a pinned development-only dependency for real Chromium acceptance. Python 3.11+ packages committed files.
-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.
+```sh
+npm run check
+npm test
+npm ci
+npx playwright install chromium
+npm run test:browser
+```
-The suite exercises:
+CI runs syntax and contract checks on Linux and Windows, plus real extension acceptance in Chromium. Browser tests use a disposable profile, loopback synthetic demo and DevTools' extension action. They exercise actual injection, element selection, clipboard, downloads, captureVisibleTab, draft reload, SPA route isolation, narrow layout and restricted-page help. Pixel comparison checks that the capture excludes the panel. The clipboard-read permission granted by the harness is for checking exported text; MARK itself requests only clipboardWrite.
-- 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.
+Results and screenshots are written to ignored `artifacts/browser/`. There is no connection to an existing browser or personal profile. The DevTools action verifies the toolbar action path, not physical shortcut key dispatch. Native Chrome installation and macOS keyboard/system behavior remain manual checks.
-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.
+Contract tests execute documented recipe snippets with real temporary JSONL files and loopback HTTP. Provider SDKs, browser speech objects and some picker objects are explicitly synthetic. No real Telegram/Slack/Discord/email message or GitHub issue is created. Tests cover delivery rejection, complete IDs, safe argv, large Unicode payloads, required close hints, context masking/framing, malformed optional blocks and text-only export. Whisper proxy tests use a synthetic upstream; no model/server is run.
-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.
+These tests establish supplied code/example behavior. They do not establish a generated application's framework integration, authorization, database transaction behavior, live provider credentials, microphone recognition, email deliverability or AI fix quality. The installer must perform the host-specific [acceptance checklist](HARDENING.md).
+
+To verify an artifact, build with `python scripts/package.py` from a clean committed checkout, extract its ZIP, and rerun browser acceptance with `BUGKIT_EXTENSION_DIR` pointing to the extracted `extension/`. Compare the release download's digest against `SHA256SUMS.txt` and the source-bound `build-manifest.json`. A rebuilt ZIP is a new artifact until its bytes and relevant checks are verified.
diff --git a/assets/GENERATION.md b/assets/GENERATION.md
new file mode 100644
index 0000000..98d4d5b
--- /dev/null
+++ b/assets/GENERATION.md
@@ -0,0 +1,9 @@
+# BugKit logo
+
+Generated with the built-in ImageGen tool on 2026-11-13. `bugkit-logo.png` is the original transparent raster output. Extension toolbar sizes and the Pages favicon are Lanczos-resized PNG derivatives; the mark was not redrawn. The original MIT project license is retained.
+
+Prompt:
+
+> Use case: logo-brand. Create ONE final professional logo symbol for BugKit, a developer tool for capturing precise bug reports and selected UI elements. Output a square transparent PNG with a single centered logo, generous transparent margin, no text, no wordmark, no mockup, no extra variants. Brand continuity: the existing BugKit identity uses coral (#ff4a6e) and warm orange (#ff7b3a); use these restrained accents with a strong dark ink silhouette that remains legible on both light and dark interfaces. Design a distinctive compact geometric beetle integrated with four focus/selection corner brackets: calm symmetry, clear negative space, bold simple shapes, immediately recognizable at 32px. Precise flat vector-like execution, careful optical balance, no thin lines, no tiny details, no eyes or cute mascot expression, no gradients, no shadows, no texture, no 3D, no glow. The icon should feel like a useful developer utility rather than promotional artwork. Transparent background is mandatory.
+
+`extension-preview.png` is an actual Chromium screenshot of the extension on the bundled synthetic demo, produced by `scripts/browser-test.mjs`. The social preview combines the generated logo with factual product labels; its layout source is `social-preview.html`.
diff --git a/assets/bugkit-logo.png b/assets/bugkit-logo.png
new file mode 100644
index 0000000..2870079
Binary files /dev/null and b/assets/bugkit-logo.png differ
diff --git a/assets/extension-preview.png b/assets/extension-preview.png
new file mode 100644
index 0000000..87e599a
Binary files /dev/null and b/assets/extension-preview.png differ
diff --git a/assets/social-preview.html b/assets/social-preview.html
new file mode 100644
index 0000000..0829e3a
--- /dev/null
+++ b/assets/social-preview.html
@@ -0,0 +1 @@
+BugKit social preview
BugKit
Chrome bug reports Application integrations
Local capture · Markdown / JSON · MIT
diff --git a/assets/social-preview.png b/assets/social-preview.png
new file mode 100644
index 0000000..99b630f
Binary files /dev/null and b/assets/social-preview.png differ
diff --git a/commands/install.md b/commands/install.md
index 88aabf7..d55a031 100644
--- a/commands/install.md
+++ b/commands/install.md
@@ -1,11 +1,5 @@
---
-description: Install bugkit — AI-friendly bug reporting — in this project.
+description: Install or upgrade BugKit reporting and verify the complete journey.
---
-The user wants to install bugkit in this project.
-
-Invoke the `installing-bugkit` skill and follow it exactly. It will detect the
-project's stack, ask one question (where reports should be stored), implement
-the matching recipe, offer optional voice transcription, and verify the result.
-
-Do not start writing code before invoking the skill — it handles the full flow.
+Invoke the `installing-bugkit` skill. It reads the shared INSTALL.md, SPEC.md and HARDENING.md contract, adapts the chosen recipe and verifies recovery and authorization. Preserve existing reports and working integration code.
diff --git a/demo/demo.js b/demo/demo.js
new file mode 100644
index 0000000..d6caa8b
--- /dev/null
+++ b/demo/demo.js
@@ -0,0 +1,14 @@
+const result = document.querySelector('#action-result')
+let clicks = 0
+for (const button of document.querySelectorAll('button')) {
+ button.addEventListener('click', () => {
+ clicks += 1
+ result.textContent = `Обычный клик сработал: ${button.textContent.trim()} (${clicks})`
+ result.dataset.clicks = String(clicks)
+ })
+}
+const shadow = document.querySelector('#shadow-example').attachShadow({mode: 'open'})
+shadow.innerHTML = ''
+shadow.querySelector('button').addEventListener('click', () => {
+ result.textContent = 'Обычный клик внутри Shadow DOM сработал'
+})
diff --git a/demo/index.html b/demo/index.html
new file mode 100644
index 0000000..9854de2
--- /dev/null
+++ b/demo/index.html
@@ -0,0 +1,30 @@
+
+
+
+
+
+
+
+ Studio — тестовая страница MARK
+
+
+
+
+ studio / workspaceДемо 2.4.1
+
+
Синтетические данные
Проверка расширения
Откройте MARK через значок расширения или горячую клавишу. Выберите кнопку, ссылку или элемент списка и составьте первый отчёт.
Нажмите кнопку, чтобы проверить обычный клик. При выборе через MARK действие не должно выполняться.
+
+
+
Детали проверки
+
Значения полей не должны автоматически попадать в отчёт.
Разные элементы
Повторяющиеся ID специально добавлены для проверки селекторов.
+
+
Проверка после прокрутки
Прокрутите страницу и выберите нижнюю кнопку. Координаты подсветки должны совпадать с элементом.
+
+
+
+
diff --git a/docs/demo/style.css b/docs/demo/style.css
new file mode 100644
index 0000000..bc38dad
--- /dev/null
+++ b/docs/demo/style.css
@@ -0,0 +1,39 @@
+:root { color-scheme: light; font-family: "Segoe UI", Arial, -apple-system, system-ui, sans-serif; color: #202624; background: #f5f7f6; }
+* { box-sizing: border-box; }
+body { margin: 0; font-size: 15px; line-height: 1.6; }
+header, main, footer { width: min(1040px, calc(100% - 48px)); margin: auto; }
+header { display: flex; align-items: center; justify-content: space-between; min-height: 90px; border-bottom: 1px solid #d7dfda; }
+a { color: #354c40; text-underline-offset: 4px; }
+.wordmark { text-decoration: none; font-weight: 700; letter-spacing: -.025em; font-size: 21px; }
+.wordmark span { color: #7d8d83; font-weight: 400; }
+.version { color: #57665d; font-size: 12px; }
+.intro { max-width: 670px; padding: 60px 0 34px; }
+.eyebrow { color: #4b6154; font-size: 13px; margin: 0 0 12px; font-weight: 600; }
+h1 { font-size: clamp(30px, 5vw, 44px); line-height: 1.18; letter-spacing: -.035em; margin: 0 0 18px; text-wrap: balance; }
+h2 { font-size: 20px; line-height: 1.3; margin: 0 0 18px; }
+h3 { font-size: 15px; margin: 0 0 4px; }
+p { color: #536158; margin: 0 0 18px; max-width: 70ch; }
+section { background: #fff; border: 1px solid #d7dfda; border-radius: 10px; padding: 26px; margin-bottom: 24px; }
+.section-heading { display: flex; align-items: center; justify-content: space-between; gap: 16px; margin-bottom: 20px; }
+.section-heading h2 { margin: 0; }
+button { border: 1px solid #cad3cf; background: #fff; color: #243b2c; border-radius: 6px; padding: 10px 14px; font: 600 13px "Segoe UI", Arial, sans-serif; cursor: pointer; }
+button:hover { background: #edf3ef; }
+button:focus-visible, a:focus-visible, input:focus-visible { outline: 3px solid #38764d; outline-offset: 3px; }
+#create-project { background: #294f36; color: white; border-color: #294f36; }
+.project-row { display: flex; align-items: center; gap: 16px; padding: 18px 0; border-top: 1px solid #e0e6e2; }
+.project-row > div { flex: 1; }
+.project-row p { margin: 0; font-size: 13px; }
+.project-icon { display: grid; place-items: center; background: #ebdef2; color: #633676; width: 40px; height: 40px; border-radius: 8px; font-weight: 700; }
+.project-icon.green { background: #deeee4; color: #2d5f40; }
+.status { font-size: 12px; border-radius: 5px; padding: 3px 8px; background: #f5ebd3; color: #72531b; }
+.status.quiet { background: #e8eeea; color: #4c6253; }
+.text-button { background: none; padding: 0; border: 0; font-size: 15px; font-weight: 400; }
+#action-result { font-size: 12px; margin: 14px 0 0; }
+.two-columns { display: grid; grid-template-columns: 1fr 1fr; gap: 36px; }
+label { display: block; font-size: 13px; margin: 0 0 5px; }
+input { display: block; width: 100%; border: 1px solid #bdc9c0; border-radius: 6px; font: inherit; padding: 9px 11px; margin-bottom: 14px; }
+.hint { font-size: 12px; margin-bottom: 0; }
+.repeat { display: flex; gap: 10px; }
+.long-section { margin-top: 280px; }
+footer { padding: 12px 0 42px; color: #57665d; font-size: 12px; }
+@media (max-width: 640px) { header, main, footer { width: calc(100% - 28px); } .intro { padding-top: 34px; } section { padding: 18px; } .two-columns { grid-template-columns: 1fr; gap: 24px; } .project-row { flex-wrap: wrap; } .project-row > div { min-width: 180px; } .project-row .status { margin-left: 56px; } .section-heading { align-items: flex-start; } }
diff --git a/docs/extension-package.txt b/docs/extension-package.txt
new file mode 100644
index 0000000..4d94fa8
--- /dev/null
+++ b/docs/extension-package.txt
@@ -0,0 +1,28 @@
+BugKit MARK 1.1.0 — Chrome extension
+
+1. Keep this extracted folder in a permanent location.
+2. Open chrome://extensions and enable Developer mode.
+3. Choose Load unpacked and select the extension folder next to this file.
+4. Open a website and click the toolbar icon, or Ctrl+Shift+Y (macOS: Command+Shift+Y).
+5. Select an element, describe the issue, review and copy/save the report.
+
+No Node.js, Git, account or API keys are needed. The interface is Russian.
+Change shortcuts at chrome://extensions/shortcuts.
+To update, close MARK, replace files in the same folder, Reload the extension,
+and reload the website. Unpacked installations do not update automatically.
+
+Русский:
+Распакуйте ZIP в постоянную папку. Откройте chrome://extensions, включите
+«Режим разработчика», нажмите «Загрузить распакованное» и выберите extension.
+На сайте нажмите значок BugKit MARK или Ctrl+Shift+Y (macOS: Command+Shift+Y).
+Отметьте элемент, опишите проблему и проверьте текст перед передачей.
+Для обновления замените файлы, обновите расширение и перезагрузите вкладку.
+
+Reports stay local until you copy/export them. Drafts last for the tab/browser
+session; screenshots are not restored after page reload. Clear drafts before
+switching website accounts. Visible text, URL paths and screenshots may contain
+private information. MARK does not collect form values, full HTML, console or
+network traffic. Internal Chrome pages and the extension store are restricted.
+
+Source, full instructions, limitations and MIT license:
+https://github.com/bglglzd/bugkit
diff --git a/docs/index.html b/docs/index.html
index 76a7196..1545e0a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -1,221 +1,60 @@
-
+
-
-
- bugkit — reports with context for coding agents
-
-
-
-
+
+
+ BugKit — Chrome extension and reporting integrations
+
+
+
+
-
+
+
-
-
-
-
-
bugkit
-
Reports with context for coding agents.
-
- 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.
-
-
-
-
-
-
-
-
-
-
-
-
-
- bugkit workflow illustration
-
-
-
Workflow illustration: report → context → agent → verify. Integration happens in your project.
-
-
-
Who this is for
-
-
-
🛠 Building for a client or boss
-
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?"
-
-
-
🚀 Running a product with users
-
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.
Select an element, describe the problem and export a report. Use the local Chrome extension, or integrate reporting and status tracking into your application's existing stack.
Download BugKit-MARK-1.1.0.zip and keep its extracted folder in a permanent location.
+
Load the extension folder
Open chrome://extensions, enable Developer mode and choose Load unpacked. Select extension, which contains manifest.json.
+
Open a website and invoke MARK
Click its toolbar icon, or press Ctrl+Shift+Y (macOS: ⌘+Shift+Y). Select an element, add a description and review the export.
+
+
No Node.js, Git, account or API key is needed. Change shortcuts at chrome://extensions/shortcuts. To update, replace the files, reload the extension and reload the website tab. ZIP installs have no automatic updates.
The installer adapts reporting to your existing UI, authentication and store. It adds forms, context export and a closure path according to the chosen recipe. This is a code integration, not a hosted backend.
+
+
Claude Code
Run each command separately in the target project.
Pass this task to the agent working in your project.
Install BugKit in this project using https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
+
+
+
Both installers require draft recovery, server-side authorization, masked context export and separate technical and author-facing resolution notes. Verify these paths in the host application. Existing reports and IDs must be preserved during upgrades.
Captures explicitly selected elements and optional visible screenshots. Exports Markdown, JSON and PNG. Draft text survives page reloads within the tab's browser session.
No automatic collection of form values, full HTML, console history or network traffic. It does not send reports to a server or fix bugs.
Review before sharing
URL queries, fragments and credentials are stripped. Paths, visible text, identifiers and screenshots may still disclose private data. Clear drafts when changing website accounts.
Internal Chrome pages and some viewers block extensions. Iframe contents and closed Shadow DOM are not inspected. Physical macOS setup and native keyboard dispatch need manual verification.
+
+
-
-
Install — pick your AI agent
-
-
-
-
-
-
-
-
-
-
-
-
- 1
-
-
Add the marketplace
-
-
/plugin marketplace add bglglzd/bugkit
-
-
-
-
-
- 2
-
-
Install the plugin
-
-
/plugin install bugkit@bugkit
-
-
-
-
-
- 3
-
-
Run the installer
-
-
/bugkit:install
-
-
-
-
-
-
Run each command one at a time — wait for it to finish before pasting the next.
-
-
-
Install bugkit in this project from
-https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
-
-
-
-
Install bugkit in this project from
-https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
-
-
-
-
Install bugkit in this project from
-https://raw.githubusercontent.com/bglglzd/bugkit/main/INSTALL.md
-
-
-
-
Paste the full contents of INSTALL.md into your AI chat. Works with Gemini CLI, Aider, Cline, and anything else that accepts a prompt.
-
-
-
-
How it works
-
User finds bug
- ↓ clicks bug icon, picks the broken element, speaks or types
-Report saved with full context (URL, selector, stack trace, viewport, transcript)
- ↓
-Admin opens report → clicks "Copy Context for AI"
- ↓ standardized prompt with everything the AI needs
-Paste into Claude Code / Cursor / Copilot / ChatGPT
- ↓
-AI fixes the bug, ships a commit
- ↓
-Admin marks report "resolved" with a short note + commit SHA
- ↓
-Application sends its configured status notification
Standardized spec — same ritual across all your projects
-
No defined status flow
Status lifecycle and notification recipes
-
Typing long descriptions is a chore
🎤 press-to-speak, auto-transcribed
-
-
-
-
Voice — free, no keys, works on slow computers
-
- 🎤 Mic button next to the description field. Press, speak, transcript streams into the textarea live. Edit if you want, submit.
-
-
- Default is the browser's Web Speech API — free, no install, no keys. Optional upgrade is local Whisper (whisper.cpp) for offline / Firefox / full privacy — ~150MB one-time model download, CPU-only. Never paid APIs as the default path.
-
-
+# BugKit
-# bugkit
+Capture bug reports in Chrome, or add reporting to your application. Reports include a description, page context and selected elements, with Markdown for a developer or coding agent.
-**Bug reports with context your coding agent can use.**
+[Download Chrome extension](https://github.com/bglglzd/bugkit/releases/latest) · [Installation](INSTALL.md) · [Русская инструкция](docs/INSTALL.ru.md) · [Demo and documentation](https://bglglzd.github.io/bugkit/)
-*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.*
+
-
+## Chrome extension: BugKit MARK
-*Workflow illustration; integration and validation happen in your project.*
+1. Download **BugKit-MARK-1.1.0.zip** from [Releases](https://github.com/bglglzd/bugkit/releases/latest) and extract it to a permanent folder.
+2. Open `chrome://extensions`, enable **Developer mode**, choose **Load unpacked** and select the extracted **extension** folder containing `manifest.json`.
+3. Open a website. Click the BugKit MARK toolbar icon, or press **Ctrl+Shift+Y** (**⌘+Shift+Y** on macOS).
+4. Select an element, describe the problem and review the report. Copy Markdown or save `.md`, `.json` and an optional screenshot.
-
- 
- 
