From d3bd3b9e0a6e3724a41d361debd369e06483a43d Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Wed, 30 Jul 2025 22:08:04 -0400
Subject: [PATCH] docs: document new password policy flags

---
 README.md                                     |  2 ++
 .../01-getting-started/01-advanced_cli.md     | 10 ++++-----
 .../01-getting-started/03-json_entries.md     | 22 +++++++++++++++++++
 src/tests/test_cli_doc_examples.py            |  2 +-
 4 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 7ce92b9..79c07b5 100644
--- a/README.md
+++ b/README.md
@@ -239,6 +239,8 @@ seedpass entry get "email"
 # Sort or filter the list view
 seedpass list --sort label
 seedpass list --filter totp
+# Generate a password with the safe character set
+seedpass util generate-password --length 20 --special-mode safe --exclude-ambiguous
 
 # Use the **Settings** menu to configure an extra backup directory
 # on an external drive.
diff --git a/docs/docs/content/01-getting-started/01-advanced_cli.md b/docs/docs/content/01-getting-started/01-advanced_cli.md
index ce3fb7a..c9686e9 100644
--- a/docs/docs/content/01-getting-started/01-advanced_cli.md
+++ b/docs/docs/content/01-getting-started/01-advanced_cli.md
@@ -49,7 +49,7 @@ Manage individual entries within a vault.
 | List entries | `entry list` | `seedpass entry list --sort label` |
 | Search for entries | `entry search` | `seedpass entry search "GitHub"` |
 | Retrieve an entry's secret (password or TOTP code) | `entry get` | `seedpass entry get "GitHub"` |
-| Add a password entry | `entry add` | `seedpass entry add Example --length 16` |
+| Add a password entry | `entry add` | `seedpass entry add Example --length 16 --no-special --exclude-ambiguous` |
 | Add a TOTP entry | `entry add-totp` | `seedpass entry add-totp Email --secret JBSW...` |
 | Add an SSH key entry | `entry add-ssh` | `seedpass entry add-ssh Server --index 0` |
 | Add a PGP key entry | `entry add-pgp` | `seedpass entry add-pgp Personal --user-id me@example.com` |
@@ -112,7 +112,7 @@ Miscellaneous helper commands.
 
 | Action | Command | Examples |
 | :--- | :--- | :--- |
-| Generate a password | `util generate-password` | `seedpass util generate-password --length 24` |
+| Generate a password | `util generate-password` | `seedpass util generate-password --length 24 --special-mode safe --exclude-ambiguous` |
 | Verify script checksum | `util verify-checksum` | `seedpass util verify-checksum` |
 | Update script checksum | `util update-checksum` | `seedpass util update-checksum` |
 
@@ -138,7 +138,7 @@ Run or stop the local HTTP API.
 - **`seedpass entry list`** – List entries in the vault, optionally sorted or filtered.
 - **`seedpass entry search <query>`** – Search across labels, usernames, URLs and notes.
 - **`seedpass entry get <query>`** – Retrieve the password or TOTP code for one matching entry, depending on the entry's type.
-- **`seedpass entry add <label>`** – Create a new password entry. Use `--length` to set the password length and optional `--username`/`--url` values.
+- **`seedpass entry add <label>`** – Create a new password entry. Use `--length` and flags like `--no-special`, `--special-mode safe`, or `--exclude-ambiguous` to override the global policy.
 - **`seedpass entry add-totp <label>`** – Create a TOTP entry. Use `--secret` to import an existing secret or `--index` to derive from the seed.
 - **`seedpass entry add-ssh <label>`** – Create an SSH key entry derived from the seed.
 - **`seedpass entry add-pgp <label>`** – Create a PGP key entry. Provide `--user-id` and `--key-type` as needed.
@@ -185,7 +185,7 @@ QR codes for supported types.
 ### `config` Commands
 
 - **`seedpass config get <key>`** – Retrieve a configuration value such as `kdf_iterations`, `backup_interval`, `inactivity_timeout`, `secret_mode_enabled`, `clipboard_clear_delay`, `additional_backup_path`, `relays`, `quick_unlock`, `nostr_max_retries`, `nostr_retry_delay`, or password policy fields like `min_uppercase`.
-- **`seedpass config set <key> <value>`** – Update a configuration option. Example: `seedpass config set kdf_iterations 200000`. Use keys like `min_uppercase`, `min_lowercase`, `min_digits`, `min_special`, `nostr_max_retries`, `nostr_retry_delay`, or `quick_unlock` to adjust settings.
+- **`seedpass config set <key> <value>`** – Update a configuration option. Example: `seedpass config set kdf_iterations 200000`. Use keys like `min_uppercase`, `min_lowercase`, `min_digits`, `min_special`, `include_special_chars`, `allowed_special_chars`, `special_mode`, `exclude_ambiguous`, `nostr_max_retries`, `nostr_retry_delay`, or `quick_unlock` to adjust settings.
 - **`seedpass config toggle-secret-mode`** – Interactively enable or disable Secret Mode and set the clipboard delay.
 - **`seedpass config toggle-offline`** – Enable or disable offline mode to skip Nostr operations.
 
@@ -223,5 +223,5 @@ Shut down the server with `seedpass api stop`.
 - Use the `--help` flag for details on any command.
 - Set a strong master password and regularly export encrypted backups.
 - Adjust configuration values like `kdf_iterations`, `backup_interval`, `inactivity_timeout`, `secret_mode_enabled`, `nostr_max_retries`, `nostr_retry_delay`, or `quick_unlock` through the `config` commands.
-- Customize the global password policy with commands like `config set min_uppercase 3`. When adding a password interactively you can override these values, choose a safe special-character set, and exclude ambiguous characters.
+- Customize the global password policy with commands like `config set min_uppercase 3` or `config set special_mode safe`. When adding a password interactively you can override these values, choose a safe special-character set, and exclude ambiguous characters.
 - `entry get` is script‑friendly and can be piped into other commands.
diff --git a/docs/docs/content/01-getting-started/03-json_entries.md b/docs/docs/content/01-getting-started/03-json_entries.md
index 3551932..720505b 100644
--- a/docs/docs/content/01-getting-started/03-json_entries.md
+++ b/docs/docs/content/01-getting-started/03-json_entries.md
@@ -100,6 +100,17 @@ Each entry is stored within `seedpass_entries_db.json.enc` under the `entries` d
 - **word_count** (`integer`, managed_account only): Number of words in the child seed. Managed accounts always use `12`.
 - **fingerprint** (`string`, managed_account only): Identifier of the child profile, used for its directory name.
 - **tags** (`array`, optional): Category labels to aid in organization and search.
+
+#### Password Policy Fields
+
+- **min_uppercase** (`integer`, default `2`): Minimum required uppercase letters.
+- **min_lowercase** (`integer`, default `2`): Minimum required lowercase letters.
+- **min_digits** (`integer`, default `2`): Minimum required digits.
+- **min_special** (`integer`, default `2`): Minimum required special characters.
+- **include_special_chars** (`boolean`, default `true`): Enable or disable any punctuation in generated passwords.
+- **allowed_special_chars** (`string`, optional): Restrict punctuation to this exact set.
+- **special_mode** (`string`, default `"standard"`): Choose `"safe"` for the `!@#$%^*-_+=?` set, otherwise the full `string.punctuation` is used.
+- **exclude_ambiguous** (`boolean`, default `false`): Omit confusing characters like `O0Il1`.
   Example:
 
   ```json
@@ -161,6 +172,17 @@ Each entry is stored within `seedpass_entries_db.json.enc` under the `entries` d
 }
 ```
 
+#### Password Entry with Policy Overrides
+
+```json
+{
+  "label": "Custom Policy",
+  "length": 16,
+  "include_special_chars": false,
+  "exclude_ambiguous": true
+}
+```
+
 #### 3. Managed User
 
 ```json
diff --git a/src/tests/test_cli_doc_examples.py b/src/tests/test_cli_doc_examples.py
index 63b6794..ee553a6 100644
--- a/src/tests/test_cli_doc_examples.py
+++ b/src/tests/test_cli_doc_examples.py
@@ -20,7 +20,7 @@ class DummyPM:
             search_entries=lambda q, kinds=None: [(1, "GitHub", "user", "", False)],
             retrieve_entry=lambda idx: {"type": EntryType.PASSWORD.value, "length": 8},
             get_totp_code=lambda idx, seed: "123456",
-            add_entry=lambda label, length, username, url: 1,
+            add_entry=lambda label, length, username, url, **kwargs: 1,
             add_totp=lambda label, seed, index=None, secret=None, period=30, digits=6: "totp://",
             add_ssh_key=lambda label, seed, index=None, notes="": 2,
             add_pgp_key=lambda label, seed, index=None, key_type="ed25519", user_id="", notes="": 3,