beads/docs/reference
Bùi Phan Viết Cường aa8cc065f4
docs(troubleshooting): document the two native-Windows integration traps (#5838)
* docs(troubleshooting): document the two native-Windows integration traps

bd.exe is a native Windows binary, and two consequences of that are
undocumented. Both cost real debugging time because neither fails loudly.

- npm installs bd as a generated bd.cmd shim, so Node's execFile/spawn --
  which run their target directly, without a shell -- never resolve it and
  die with "spawn bd ENOENT" while bd works in the same terminal.
- Git Bash resolves /tmp to its own temp directory; bd, being native,
  resolves it against the current drive root. `bd export -o /tmp/x.jsonl`
  reports success and writes C:\tmp\x.jsonl.

Adds a subsection for each under Platform-Specific Issues, following the
symptom/solution shape already used there, plus cross-links from the FAQ
Windows entry and the installation Windows notes.

Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of CuongBPV

* Update troubleshooting for Windows `/tmp` path issues

Clarify behavior of `/tmp` paths in Git Bash and provide solutions for Windows path handling.

* Update FAQ for Windows integration details

Clarify integration details regarding `bd.exe` and `/tmp` paths in Windows.

---------

Co-authored-by: CuongBPV <cuongbpv@fpt.com>
2026-08-20 05:41:39 -07:00
..
advanced.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
antivirus.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
configuration.md feat(lint): configurable per-type lint sections via lint.sections.<type> (#5855) 2026-08-19 11:23:33 -07:00
events-journal.md docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00
faq.md docs(troubleshooting): document the two native-Windows integration traps (#5838) 2026-08-20 05:41:39 -07:00
git-integration.md fix: reject incompatible timeout in generated hooks (#5522) 2026-08-10 20:47:53 -07:00
index.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
json-schema.md docs: re-review and bump the three 90-day-stale freshness markers (#5394) 2026-08-07 02:35:11 -07:00
observability.md refactor(telemetry): adopt standard OTel SDK env vars with BD_OTEL_* back-compat (#3859) 2026-08-03 00:05:06 -07:00
protected-branches.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
troubleshooting.md docs(troubleshooting): document the two native-Windows integration traps (#5838) 2026-08-20 05:41:39 -07:00
worktrees.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00