Implement BEADS_DIR environment variable (bd-e16b)

Add BEADS_DIR as a replacement for BEADS_DB to point to the .beads
directory instead of the database file directly.

Rationale:
- With --no-db mode, there's no .db file to point to
- The .beads directory is the logical unit (contains config.yaml, db
  files, jsonl files)
- More intuitive: point to the beads directory not the database file

Implementation:
- Add BEADS_DIR environment variable support to FindDatabasePath()
- Priority order: BEADS_DIR > BEADS_DB > auto-discovery
- Maintain backward compatibility with BEADS_DB (now deprecated)
- Update --no-db mode to respect BEADS_DIR
- Update MCP integration (config.py, bd_client.py)
- Update documentation to show BEADS_DIR as preferred method

Testing:
- Backward compatibility: BEADS_DB still works
- BEADS_DIR works with regular database mode
- BEADS_DIR works with --no-db mode
- Priority: BEADS_DIR takes precedence over BEADS_DB

Follow-up issues for refactoring:
- bd-efe8: Refactor path canonicalization into helper function
- bd-c362: Extract database search logic into helper function

Closes bd-e16b

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

integrations/beads-mcp/src/beads_mcp/config.py

@@ -32,6 +32,7 @@ class Config(BaseSettings):
     model_config = SettingsConfigDict(env_prefix="")
 
     beads_path: str = Field(default_factory=_default_beads_path)
+    beads_dir: str | None = None
     beads_db: str | None = None
     beads_actor: str | None = None
     beads_no_auto_flush: bool = False
@@ -75,6 +76,35 @@ class Config(BaseSettings):
 
         return v
 
+    @field_validator("beads_dir")
+    @classmethod
+    def validate_beads_dir(cls, v: str | None) -> str | None:
+        """Validate BEADS_DIR points to an existing .beads directory.
+
+        Args:
+            v: Path to .beads directory or None
+
+        Returns:
+            Validated path or None
+
+        Raises:
+            ValueError: If path is set but directory doesn't exist
+        """
+        if v is None:
+            return v
+
+        path = Path(v)
+        if not path.exists():
+            raise ValueError(
+                f"BEADS_DIR points to non-existent directory: {v}\n"
+                + "Please verify the .beads directory path is correct."
+            )
+
+        if not path.is_dir():
+            raise ValueError(f"BEADS_DIR must point to a directory, not a file: {v}")
+
+        return v
+
     @field_validator("beads_db")
     @classmethod
     def validate_beads_db(cls, v: str | None) -> str | None:
@@ -129,7 +159,8 @@ def load_config() -> Config:
             + "After installation, restart Claude Code.\n\n"
             + "Advanced configuration (optional):\n"
             + f"  BEADS_PATH            - Path to bd executable (default: {default_path})\n"
-            + "  BEADS_DB              - Path to beads database file (default: auto-discover)\n"
+            + "  BEADS_DIR             - Path to .beads directory (default: auto-discover)\n"
+            + "  BEADS_DB              - Path to database file (deprecated, use BEADS_DIR)\n"
             + "  BEADS_WORKING_DIR     - Working directory for bd commands (default: $PWD or cwd)\n"
             + "  BEADS_ACTOR           - Actor name for audit trail (default: $USER)\n"
             + "  BEADS_NO_AUTO_FLUSH   - Disable automatic JSONL sync (default: false)\n"