diff --git a/README.md b/README.md
index 9a33c3b6..309f59e3 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,26 @@ git config merge.beads.name "bd JSONL merge driver"
 echo ".beads/beads.jsonl merge=beads" >> .gitattributes
 ```
 
+### Files Created by `bd init`
+
+**`bd init` creates these files in your repository:**
+
+**Should be committed to git:**
+- `.gitattributes` - Configures git merge driver for intelligent JSONL merging (critical for team collaboration)
+- `.beads/beads.jsonl` - Issue data in JSONL format (source of truth, synced via git)
+- `.beads/config.yaml` - Repository configuration template
+- `.beads/README.md` - Documentation about beads for repository visitors
+- `.beads/metadata.json` - Database metadata
+
+**Should be in `.gitignore` (local-only):**
+- `.beads/beads.db` - SQLite cache (auto-synced with JSONL)
+- `.beads/beads.db-*` - SQLite journal files
+- `.beads/bd.sock` / `.beads/bd.pipe` - Daemon communication socket
+- `.beads/.exclusive-lock` - Daemon lock file
+- `.git/beads-worktrees/` - Git worktrees (only created when using protected branch workflows)
+
+The `.gitignore` entries are automatically created inside `.beads/.gitignore` by `bd init`, but your project's root `.gitignore` should also exclude the database and daemon files if you want to keep your git status clean.
+
 **Using devcontainers?** Open the repository in a devcontainer (GitHub Codespaces or VS Code Remote Containers) and bd will be automatically installed with git hooks configured. See [.devcontainer/README.md](.devcontainer/README.md) for details.
 
 Most tasks will be created and managed by agents during conversations. You can check on things with:
diff --git a/docs/GIT_INTEGRATION.md b/docs/GIT_INTEGRATION.md
index 508106b8..3720644a 100644
--- a/docs/GIT_INTEGRATION.md
+++ b/docs/GIT_INTEGRATION.md
@@ -434,6 +434,8 @@ export BEADS_NO_DAEMON=1  # Direct mode
 
 ### Recommended .gitattributes
 
+**IMPORTANT:** The `.gitattributes` file should be **committed to git**, not ignored. It configures merge behavior for the entire team.
+
 ```
 # Intelligent merge driver for JSONL (auto-configured by bd init)
 .beads/beads.jsonl merge=beads
@@ -442,6 +444,11 @@ export BEADS_NO_DAEMON=1  # Direct mode
 .beads/*.jsonl text diff
 ```
 
+This file is automatically created by `bd init` and is essential for:
+- Preventing spurious merge conflicts in `.beads/beads.jsonl`
+- Enabling field-level 3-way merging instead of line-by-line
+- Ensuring all team members get intelligent JSONL merging
+
 ### Git LFS Considerations
 
 **Do NOT use Git LFS for `.beads/beads.jsonl`:**