docs: Fix incorrect paths, obsolete flags, and missing BIP39 recovery info

README.md

@@ -171,7 +171,7 @@ For complete command reference, flags, and examples, see [docs/03-reference/comm
 - Optional passphrase protection (25th word)
 - Recover: `pass-cli change-password --recover`
 - Skip during init: `pass-cli init --no-recovery`
-- See [Recovery Guide](specs/003-bip39-mnemonic-based/quickstart.md) for details
+- See [Recovery Guide](specs/archive/003-bip39-mnemonic-based/quickstart.md) for details
 
 **Audit Logging** (Optional):
 - Tamper-evident HMAC-SHA256 signed audit trail
@@ -190,12 +190,12 @@ For complete security details, best practices, and migration guides, see [docs/0
 - [Usage Guide](docs/03-reference/command-reference.md) - Complete command reference, TUI shortcuts, configuration
 - [Installation](docs/01-getting-started/quick-install.md) - All installation methods and package managers
 - [Security](docs/03-reference/security-architecture.md) - Encryption details, best practices, migration guides
-- [Troubleshooting](docs/04-reference/troubleshooting.md) - Common issues and solutions
+- [Troubleshooting](docs/04-troubleshooting/faq.md) - Common issues and solutions
 
 **Additional Resources**:
-- [Doctor Command](docs/05-development/doctor-command.md) - Health check diagnostics
-- [CI/CD Integration](docs/05-development/ci-cd.md) - GitHub Actions and pipeline examples
-- [Branch Workflow](docs/05-development/branch-workflow.md) - Git workflow for contributors
+- [Health Checks](docs/05-operations/health-checks.md) - Vault health check diagnostics
+- [CI/CD Integration](docs/06-development/ci-cd.md) - GitHub Actions and pipeline examples
+- [Branch Workflow](docs/06-development/branch-workflow.md) - Git workflow for contributors
 
 ## Building from Source
 
@@ -211,7 +211,7 @@ go build -o pass-cli .
 go test ./...
 ```
 
-For testing guidelines, see [test/README.md](test/README.md). For Git workflow, see [docs/05-development/branch-workflow.md](docs/05-development/branch-workflow.md).
+For testing guidelines, see [test/README.md](test/README.md). For Git workflow, see [docs/06-development/branch-workflow.md](docs/06-development/branch-workflow.md).
 
 ## FAQ
 
@@ -232,13 +232,26 @@ cp ~/.pass-cli/vault.enc ~/backup/vault-$(date +%Y%m%d).enc
 
 ### What happens if I forget my master password?
 
-Unfortunately, there's no way to recover your vault without the master password. The encryption is designed to be unbreakable. Keep your master password safe.
+If you have a 24-word BIP39 recovery phrase (generated during vault initialization), you can recover access:
 
-For more questions and troubleshooting, see [docs/04-reference/troubleshooting.md](docs/04-reference/troubleshooting.md).
+```bash
+pass-cli change-password --recover
+```
+
+You'll be challenged to enter 6 random words from your recovery phrase, then you can set a new master password.
+
+**Important**:
+- Recovery phrases were introduced in recent versions. Older vaults don't have them.
+- If you don't have a recovery phrase and forgot your password, the vault is unrecoverable.
+- You can skip recovery phrase generation during init with `pass-cli init --no-recovery` (not recommended).
+
+See [Recovery Guide](specs/archive/003-bip39-mnemonic-based/quickstart.md) for details.
+
+For more questions and troubleshooting, see [docs/04-troubleshooting/faq.md](docs/04-troubleshooting/faq.md).
 
 ## Contributing
 
-Contributions are welcome! See [docs/05-development/branch-workflow.md](docs/05-development/branch-workflow.md) for Git workflow and contribution guidelines.
+Contributions are welcome! See [docs/06-development/branch-workflow.md](docs/06-development/branch-workflow.md) for Git workflow and contribution guidelines.
 
 ## License
 

docs/01-getting-started/quick-start.md

@@ -68,7 +68,7 @@ Store your master password in OS keychain for convenience?
 Benefits:
   ✓ No need to type password for every operation
   ✓ Secure OS-level storage
-  ✓ Can be disabled later with --no-keychain
+  ✓ Can be disabled later (see Keychain Setup guide)
 
 Enable keychain storage? (y/n): y
 
@@ -159,19 +159,23 @@ pass-cli get github
 
 #### Skip Keychain Integration
 
+To initialize a vault without storing the master password in the OS keychain, simply don't use the `--use-keychain` flag:
+
 ```bash
-pass-cli init --no-keychain
+pass-cli init
 ```
 
-Creates a vault without storing the master password in OS keychain. You'll need to enter your password for each operation.
+During the interactive setup, answer "n" when asked about keychain storage. You'll need to enter your password for each operation.
+
+#### Skip Audit Logging
 
-#### Disable Audit Logging
+Audit logging is disabled by default. To enable it during initialization, use:
 
 ```bash
-pass-cli init --no-audit
+pass-cli init --enable-audit
 ```
 
-Creates a vault without audit logging enabled (not recommended for production use).
+If you omit this flag, your vault will be created without audit logging.
 
 ## Your First Credential
 

docs/03-reference/command-reference.md

@@ -1465,11 +1465,17 @@ secret-tool search service pass-cli
 secret-tool clear service pass-cli vault /old/path/vault.enc
 ```
 
-**Prevention**: When deleting or moving vaults, remove the keychain entry first:
+**Prevention**: When deleting or moving vaults, remove the keychain entry first using your OS credential manager:
+
 ```bash
-# Before deleting vault
-pass-cli change-password --no-keychain  # Disables keychain
-# OR manually remove from OS keychain
+# Windows
+cmdkey /delete:pass-cli
+
+# macOS
+security delete-generic-password -s "pass-cli" -a "$USER"
+
+# Linux
+secret-tool clear service pass-cli vault /old/path/vault.enc
 ```
 
 #### What if first-run detection doesn't trigger?

docs/04-troubleshooting/faq.md

@@ -65,6 +65,29 @@ The vault will be automatically re-encrypted with the new password.
 
 ---
 
+**Q: What happens if I forget my master password?**
+
+A: If your vault was initialized with BIP39 recovery (default since recent versions), you can recover:
+
+```bash
+pass-cli change-password --recover
+```
+
+You'll need to:
+1. Enter 6 random words from your 24-word recovery phrase (challenge-response)
+2. Set a new master password
+3. Vault will be re-encrypted with the new password
+
+**Important Notes**:
+- Save your 24-word recovery phrase during initialization (write it down physically)
+- Recovery phrases were introduced in recent versions. Older vaults don't have them.
+- If you don't have a recovery phrase, the vault is unrecoverable without the password
+- You can skip recovery generation with `pass-cli init --no-recovery` (not recommended)
+
+See [BIP39 Recovery Guide](../../specs/archive/003-bip39-mnemonic-based/quickstart.md) for detailed recovery instructions.
+
+---
+
 **Q: Is my data sent to the cloud?**
 
 A: No. Pass-CLI:

docs/05-operations/health-checks.md

@@ -208,7 +208,7 @@ On Windows, ensure only your user account has read/write access.
   Recommendation: Fix configuration syntax or delete to use defaults
 ```
 
-**Solution**: Edit `~/.pass-cli/config.yaml` to fix syntax errors, or delete the file to regenerate defaults.
+**Solution**: Edit `~/.pass-cli/config.yml` to fix syntax errors, or delete the file to regenerate defaults.
 
 #### Missing Configuration (Pass)