update docs for clarity

Author: groksrc

src/pages/getting-started.mdx

@@ -151,9 +151,9 @@ basic-memory project add "work-notes" ~/Documents/work
 You: "Create a new project called 'work-notes' in ~/Documents/work"
 ```
 
-**Single project users:**
+**For users who primarily work in one project:**
 
-If you only use one project, you can skip the project selection prompt. Add this to `~/.basic-memory/config.json`:
+Enable Default Project Mode to automatically use your main project. Add this to `~/.basic-memory/config.json`:
 
 ```json
 {
@@ -162,7 +162,7 @@ If you only use one project, you can skip the project selection prompt. Add this
 }
 ```
 
-With this enabled, the AI uses your default project automatically without asking.
+With this enabled, the AI uses your default project automatically when no project is specified. You can still override this by explicitly specifying a different project when needed.
 
 ## Creating Your First Knowledge Note
 

src/pages/guides/mcp-tools-reference.mdx

@@ -117,19 +117,69 @@ Assistant: Perfect! I'll use the 'research' project for our work.
 [Uses project="research" in all subsequent tool calls]
 ```
 
-### Project Modes
+### Default Project Mode
 
-For detailed information about project modes (default project mode, constrained mode, etc.), see the [User Guide - Multi-Project Features](/user-guide#multi-project-features).
+**For single-project users who want automatic project selection:**
+
+Enable in `~/.basic-memory/config.json`:
+```json
+{
+  "default_project_mode": true,
+  "default_project": "main"
+}
+```
+
+**Behavior:**
+- Tools automatically use your default project when no `project` parameter is specified
+- You **can still override** by explicitly passing a different project to tools
+- Best for users who primarily work in one project but occasionally need others
+
+**Example:**
+```
+# With default_project_mode enabled and default_project="main"
+write_note("My Note", "Content", "folder")  # Uses "main" project
+write_note("Work Note", "Content", "folder", project="work")  # Uses "work" project
+```
+
+### Single Project Mode
+
+**For locked, single-project sessions:**
+
+Start MCP server with `--project` flag:
+```bash
+basic-memory mcp --project work
+```
+
+**Behavior:**
+- **Locks** the entire MCP session to one project
+- The `project` parameter in tool calls is **ignored** - cannot switch projects
+- Best for automation, focused sessions, or restricted access scenarios
+
+**Example:**
+```bash
+# Start locked to "work" project
+basic-memory mcp --project work
+
+# All operations use "work" regardless of parameters
+write_note("My Note", "Content", "folder")  # Uses "work"
+write_note("Note", "Content", "folder", project="personal")  # Still uses "work"!
+```
 
 ### Project Resolution Hierarchy
 
 When multiple project specifications exist, Basic Memory uses this priority order:
 
-1. **CLI Constraint** (highest priority) - `--project` parameter
+1. **Single Project Mode** (highest priority) - `--project` CLI parameter or `BASIC_MEMORY_MCP_PROJECT` env var
 2. **Explicit Parameter** (medium priority) - `project` parameter in tool call
-3. **Default Project Mode** (lowest priority) - Automatic default when enabled
+3. **Default Project Mode** (lowest priority) - Automatic default when `default_project_mode=true`
+
+**Quick Comparison:**
 
-This ensures predictable behavior and allows explicit override when needed.
+| Mode | Can Switch Projects? | Use Case |
+|------|---------------------|----------|
+| Multi-Project (default) | Yes, via explicit parameters | Managing multiple knowledge bases |
+| Default Project Mode | Yes, can override default | Single project with occasional multi-project |
+| Single Project Mode | No, locked to one | Automation, security, focused sessions |
 
 <CardGroup cols={2}>
   <Card title="list_memory_projects" icon="layers">

src/pages/user-guide.mdx

@@ -245,9 +245,9 @@ If you only use one project, you can skip the selection prompt. Add this to `~/.
 }
 ```
 
-With this enabled, the AI uses your default project automatically without asking.
+With this enabled, the AI uses your default project automatically without asking. You can still override this by explicitly specifying a different project in tool calls.
 
-### Constrained Project Mode
+### Single Project Mode
 
 For focused work sessions or automation, you can lock the MCP server to a specific project:
 
@@ -256,15 +256,16 @@ For focused work sessions or automation, you can lock the MCP server to a specif
 basic-memory mcp --project work-notes
 ```
 
+This **locks** the entire MCP session to one project - the `project` parameter in tool calls will be ignored.
+
 **When to use:**
 - Automation workflows that should only access one project
 - Focused work sessions where you want to prevent accidental cross-project operations
 - Team environments with project-specific access
 
-**Benefits:**
-- All tools automatically operate within the specified project
-- No risk of accidentally modifying the wrong project
-- Simplified workflow for single-project tasks
+**Key difference from Default Project Mode:**
+- **Single Project Mode**: Locks session to one project, cannot switch
+- **Default Project Mode**: Uses default automatically, but can still switch projects
 
 <Warning>
 Moving notes from one project to another is not currently supported. The easiest

src/pages/whats-new.mdx

@@ -67,9 +67,9 @@ If you only use one project, enable automatic project selection:
 ```
 
 With this enabled:
-- AI uses your default project automatically
-- No project selection prompt
-- Suitable for single knowledge base workflows
+- AI uses your default project automatically when no project is specified
+- You can still override by explicitly passing a different project to tools
+- Suitable for users who primarily work in one project
 
 #### Single Project Mode
 
@@ -79,7 +79,7 @@ Lock an MCP session to a specific project using the `--project` flag:
 basic-memory mcp --project work-notes
 ```
 
-All operations in this session use the specified project. Useful for automation and focused work sessions.
+**Key behavior:** All operations in this session use the specified project - the `project` parameter in tool calls is ignored. Useful for automation, security, and focused work sessions where you want to prevent accidental cross-project operations.
 
 #### What Changed from v0.14.x