bug-report

Name: bug-report
Author: inkeep

3.1kstars191forks

How to install bug-report?

inkeep/open-knowledge/bug-report

$npx -y skills add inkeep/open-knowledge --skill bug-report

Installs into the current project.

Summary

Use when the user reports a problem with OpenKnowledge, asks for help debugging OK, or wants to file a bug report. This skill guides the agent to capture diagnostic information via the ok bug-report CLI command.

Files · 1

View on GitHub

SKILL.md

1	# Bug Report — agent guidance
2
3	When a user reports a problem with OpenKnowledge or asks for debugging help, use the `ok bug-report` command to capture a structured diagnostic bundle.
4
5	## Quick path
6
7	```bash
8	ok bug-report --no-reveal
9	```
10
11	The `--no-reveal` flag suppresses the Finder reveal (use it when running as an agent — you want the file path, not a Finder window).
12
13	## What the command does
14
15	1. Gathers all structured log files from `~/.ok/logs/` (NDJSON format, pino)
16	2. When invoked inside an OK project directory, filters logs to that project's records
17	3. Collects system info: OK version, Node/Bun versions, macOS version, locale, timezone, free disk space
18	4. Collects lock directory contents (server.lock, spawn-error-log) when a project context exists
19	5. Extracts recent IPC error records from desktop logs
20	6. Runs an auto-redaction pass over all content (home paths, API tokens, credentials are scrubbed)
21	7. Writes `~/.ok/bug-reports/<timestamp>-bugreport.zip`
22	8. Prints the bundle path to stdout
23
24	## What's in the bundle
25
26	```
27	<timestamp>-bugreport.zip
28	├── MANIFEST.json — what's inside, redaction audit report
29	├── sysinfo.json — versions, locale, disk, build channel
30	├── README.md — what's safe to share, discipline version
31	├── logs/ — NDJSON log files (auto-redacted)
32	├── lockdir/ — server.lock, spawn-error-log (if project)
33	└── recent-ipc-errors.json — last 50 structured IPC errors
34	```
35
36	## Agent workflow
37
38	1. Run `ok bug-report --no-reveal` in the user's project directory (or home if no project)
39	2. Read the path from stdout
40	3. Unzip to a temp directory: `unzip -o <path> -d /tmp/ok-diag-<timestamp>/`
41	4. Read `MANIFEST.json` — check the `redactions` array (if non-empty, some content was scrubbed)
42	5. Read `sysinfo.json` — check versions, disk space, build channel
43	6. Grep the log files for errors: `grep '"level":50' logs/*.log \| head -20` (level 50 = error in pino)
44	7. Read `recent-ipc-errors.json` for IPC-layer failures
45	8. Report findings to the user with actionable next steps
46
47	## If the command is not available
48
49	The `ok bug-report` command ships with `@inkeep/open-knowledge` >= 0.7.0. If the user's version is older:
50
51	1. Check version: `ok --version`
52	2. If < 0.7.0: suggest `npm install -g @inkeep/open-knowledge@latest` to update
53	3. Fallback: manually inspect `~/.ok/logs/` for recent `.log` files (NDJSON format, greppable)
54
55	## Privacy
56
57	The bundle auto-redacts:
58	- macOS home paths (`/Users/<name>/` → `~/`)
59	- GitHub PAT prefixes (`ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`)
60	- AWS access keys, Anthropic tokens, OpenAI tokens
61	- Bearer authorization headers
62
63	The `MANIFEST.json` `redactions` array lists every file and pattern that was scrubbed. The bundle is safe for the user to attach to a GitHub issue.

People who liked this also viewed

6 picks

Type

bug-report

3.1kstars191forks

View on GitHub

How to install bug-report?

inkeep/open-knowledge/bug-report

$npx -y skills add inkeep/open-knowledge --skill bug-report

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Bug Report — agent guidance
2
3	When a user reports a problem with OpenKnowledge or asks for debugging help, use the `ok bug-report` command to capture a structured diagnostic bundle.
4
5	## Quick path
6
7	```bash
8	ok bug-report --no-reveal
9	```
10
11	The `--no-reveal` flag suppresses the Finder reveal (use it when running as an agent — you want the file path, not a Finder window).
12
13	## What the command does
14
15	1. Gathers all structured log files from `~/.ok/logs/` (NDJSON format, pino)
16	2. When invoked inside an OK project directory, filters logs to that project's records
17	3. Collects system info: OK version, Node/Bun versions, macOS version, locale, timezone, free disk space
18	4. Collects lock directory contents (server.lock, spawn-error-log) when a project context exists
19	5. Extracts recent IPC error records from desktop logs
20	6. Runs an auto-redaction pass over all content (home paths, API tokens, credentials are scrubbed)
21	7. Writes `~/.ok/bug-reports/<timestamp>-bugreport.zip`
22	8. Prints the bundle path to stdout
23
24	## What's in the bundle
25
26	```
27	<timestamp>-bugreport.zip
28	├── MANIFEST.json — what's inside, redaction audit report
29	├── sysinfo.json — versions, locale, disk, build channel
30	├── README.md — what's safe to share, discipline version
31	├── logs/ — NDJSON log files (auto-redacted)
32	├── lockdir/ — server.lock, spawn-error-log (if project)
33	└── recent-ipc-errors.json — last 50 structured IPC errors
34	```
35
36	## Agent workflow
37
38	1. Run `ok bug-report --no-reveal` in the user's project directory (or home if no project)
39	2. Read the path from stdout
40	3. Unzip to a temp directory: `unzip -o <path> -d /tmp/ok-diag-<timestamp>/`
41	4. Read `MANIFEST.json` — check the `redactions` array (if non-empty, some content was scrubbed)
42	5. Read `sysinfo.json` — check versions, disk space, build channel
43	6. Grep the log files for errors: `grep '"level":50' logs/*.log \| head -20` (level 50 = error in pino)
44	7. Read `recent-ipc-errors.json` for IPC-layer failures
45	8. Report findings to the user with actionable next steps
46
47	## If the command is not available
48
49	The `ok bug-report` command ships with `@inkeep/open-knowledge` >= 0.7.0. If the user's version is older:
50
51	1. Check version: `ok --version`
52	2. If < 0.7.0: suggest `npm install -g @inkeep/open-knowledge@latest` to update
53	3. Fallback: manually inspect `~/.ok/logs/` for recent `.log` files (NDJSON format, greppable)
54
55	## Privacy
56
57	The bundle auto-redacts:
58	- macOS home paths (`/Users/<name>/` → `~/`)
59	- GitHub PAT prefixes (`ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`)
60	- AWS access keys, Anthropic tokens, OpenAI tokens
61	- Bearer authorization headers
62
63	The `MANIFEST.json` `redactions` array lists every file and pattern that was scrubbed. The bundle is safe for the user to attach to a GitHub issue.

People who liked this also viewed

6 picks

Type