Add documentation for smart-threading configuration option

- README.md: Document smart-threading in Behavior Settings table
- README.md: Add Smart Threading subsection with explanation
- CLAUDE.md: Add mandatory documentation check to Pre-Push Checklist

Author: jensens

CLAUDE.md

@@ -599,13 +599,22 @@ Quick summary:
    - Create unreleased section if it doesn't exist
    - Include issue number when applicable
 
-3. **Run relevant tests locally**
+3. **Always check and update documentation**
+   - **README.md**: Update configuration tables, usage examples, or feature descriptions
+   - **EXTENDING.md**: Update if hooks API changed
+   - **RELEASE.md**: Update if release process changed
+   - Check if new configuration options need documentation
+   - Check if new features need usage examples
+   - Update any affected sections (don't just append)
+   - **MANDATORY**: After any code change that adds/modifies features or configuration, verify documentation is updated
+
+4. **Run relevant tests locally**
    ```bash
    source .venv/bin/activate
    pytest tests/test_*.py -v
    ```
 
-4. **Check CI status before marking PR ready**
+5. **Check CI status before marking PR ready**
    ```bash
    gh pr checks <PR_NUMBER>
    ```

README.md

@@ -84,11 +84,23 @@ The **main section** must be called `[settings]`, even if kept empty.
 |--------|-------------|---------|
 | `default-target` | Target directory for VCS checkouts | `./sources` |
 | `threads` | Number of parallel threads for fetching sources | `4` |
+| `smart-threading` | Process HTTPS packages serially to avoid overlapping credential prompts (see below) | `True` |
 | `offline` | Skip all VCS fetch operations (handy for offline work) | `False` |
 | `default-install-mode` | Default `install-mode` for packages: `direct` or `skip` | `direct` |
 | `default-update` | Default update behavior: `yes` or `no` | `yes` |
 | `default-use` | Default use behavior (when false, sources not checked out) | `True` |
 
+##### Smart Threading
+
+When `smart-threading` is enabled (default), mxdev uses a two-phase approach to prevent credential prompts from overlapping:
+
+1. **Phase 1**: HTTPS packages are processed serially (one at a time) to ensure clean, visible credential prompts
+2. **Phase 2**: Remaining packages (SSH, local) are processed in parallel for speed
+
+This solves the problem where parallel git operations would cause multiple credential prompts to overlap, making it confusing which package needs credentials.
+
+**When to disable**: Set `smart-threading = false` if you have git credential helpers configured (e.g., credential cache, credential store) and never see prompts.
+
 #### Package Overrides
 
 ##### `version-overrides`