Bug Report — agent guidance

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.

Quick path

ok bug-report --no-reveal

The --no-reveal flag suppresses the Finder reveal (use it when running as an agent — you want the file path, not a Finder window).

What the command does

1. Gathers all structured log files from ~/.ok/logs/ (NDJSON format, pino)
2. When invoked inside an OK project directory, filters logs to that project's records
3. Collects system info: OK version, Node/Bun versions, macOS version, locale, timezone, free disk space
4. Collects lock directory contents (server.lock, spawn-error-log) when a project context exists
5. Extracts recent IPC error records from desktop logs
6. Runs an auto-redaction pass over all content (home paths, API tokens, credentials are scrubbed)
7. Writes ~/.ok/bug-reports/<timestamp>-bugreport.zip
8. Prints the bundle path to stdout

What's in the bundle

<timestamp>-bugreport.zip
├── MANIFEST.json       — what's inside, redaction audit report
├── sysinfo.json        — versions, locale, disk, build channel
├── README.md           — what's safe to share, discipline version
├── logs/               — NDJSON log files (auto-redacted)
├── lockdir/            — server.lock, spawn-error-log (if project)
└── recent-ipc-errors.json — last 50 structured IPC errors

Agent workflow

1. Run ok bug-report --no-reveal in the user's project directory (or home if no project)
2. Read the path from stdout
3. Unzip to a temp directory: unzip -o <path> -d /tmp/ok-diag-<timestamp>/
4. Read MANIFEST.json — check the redactions array (if non-empty, some content was scrubbed)
5. Read sysinfo.json — check versions, disk space, build channel
6. Grep the log files for errors: grep '"level":50' logs/*.log | head -20 (level 50 = error in pino)
7. Read recent-ipc-errors.json for IPC-layer failures
8. Report findings to the user with actionable next steps

If the command is not available

The ok bug-report command ships with @inkeep/open-knowledge >= 0.7.0. If the user's version is older:

1. Check version: ok --version
2. If < 0.7.0: suggest npm install -g @inkeep/open-knowledge@latest to update
3. Fallback: manually inspect ~/.ok/logs/ for recent .log files (NDJSON format, greppable)

Privacy

The bundle auto-redacts:

• macOS home paths (/Users/<name>/ → ~/)
• GitHub PAT prefixes (ghp_, gho_, ghu_, ghs_, ghr_)
• AWS access keys, Anthropic tokens, OpenAI tokens
• Bearer authorization headers

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.