TT-4413: add agent account, policy, and rule management

docs/COMMANDS.md

@@ -452,15 +452,32 @@ nylas webhook server --port 8080 --tunnel cloudflared # With public tunnel
 Create and manage Nylas-managed agent accounts backed by provider `nylas`.
 
 ```bash
-nylas agent list                               # List agent accounts
-nylas agent create <email>                     # Create agent account
-nylas agent create <email> --app-password PW   # Create account with IMAP/SMTP app password
-nylas agent delete <agent-id|email>            # Delete/revoke agent account
-nylas agent delete <agent-id|email> --yes      # Skip confirmation
+nylas agent account list                       # List agent accounts
+nylas agent account create <email>             # Create agent account
+nylas agent account create <email> --app-password PW  # Create account with IMAP/SMTP app password
+nylas agent account create <email> --policy-id <policy-id>  # Create account attached to a policy
+nylas agent account get <agent-id|email>       # Show one agent account
+nylas agent account delete <agent-id|email>    # Delete/revoke agent account
+nylas agent account delete <agent-id|email> --yes  # Skip confirmation
+nylas agent policy list                        # List policy for default agent account
+nylas agent policy list --all                  # List all policies attached to agent accounts
+nylas agent policy create --name NAME          # Create a policy
+nylas agent policy get <policy-id>             # Show one policy
+nylas agent policy read <policy-id>            # Read one policy
+nylas agent policy update <policy-id> --name NAME  # Update a policy
+nylas agent policy delete <policy-id> --yes    # Delete an unattached policy
+nylas agent rule list                          # List rules for default agent policy
+nylas agent rule list --all                    # List all rules attached to agent policies
+nylas agent rule read <rule-id>                # Read one rule
+nylas agent rule get <rule-id>                 # Show one rule
+nylas agent rule create --name NAME --condition from.domain,is,example.com --action mark_as_spam  # Create a rule from common flags
+nylas agent rule create --data-file rule.json  # Create a rule from full JSON
+nylas agent rule update <rule-id> --name NAME --description TEXT  # Update a rule
+nylas agent rule delete <rule-id> --yes        # Delete a rule
 nylas agent status                             # Check connector + account status
 ```
 
-**Details:** `docs/commands/agent.md`
+**Details:** `docs/commands/agent.md`, `docs/commands/agent-policy.md`, `docs/commands/agent-rule.md`
 
 ---
 

docs/commands/agent-policy.md

@@ -0,0 +1,194 @@
+# Agent Policies
+
+Detailed reference for `nylas agent policy`.
+
+Agent policies are filtered through `provider=nylas` agent accounts in the CLI, even though the underlying policy objects are application-level resources.
+
+## Commands
+
+```bash
+nylas agent policy list
+nylas agent policy list --all
+nylas agent policy create --name "Strict Policy"
+nylas agent policy create --data-file policy.json
+nylas agent policy get <policy-id>
+nylas agent policy read <policy-id>
+nylas agent policy update <policy-id> --name "Updated Policy"
+nylas agent policy update <policy-id> --data-file update.json
+nylas agent policy delete <policy-id> --yes
+```
+
+## Scope Model
+
+The CLI intentionally treats policies as an agent-scoped surface:
+
+- `nylas agent policy list` shows only the policy attached to the current default `provider=nylas` grant
+- `nylas agent policy list --all` shows only policies referenced by at least one `provider=nylas` agent account
+- text output includes the attached agent email and grant ID so you can see which agent account uses which policy
+
+This means:
+
+- a policy can exist in the application but still not appear under `nylas agent policy`
+- a policy with no attached `provider=nylas` account is hidden from the agent policy list
+
+## Listing Policies
+
+### Default Agent Policy
+
+```bash
+nylas agent policy list
+nylas agent policy list --json
+```
+
+Behavior:
+
+- resolves the current default local grant
+- requires that default grant to be `provider=nylas`
+- returns the single attached policy for that grant
+
+### All Agent Policies
+
+```bash
+nylas agent policy list --all
+nylas agent policy list --all --json
+```
+
+Behavior:
+
+- lists all policies referenced by at least one `provider=nylas` agent account
+- text output includes one `Agent:` line per attached agent account
+
+## Reading Policies
+
+```bash
+nylas agent policy get <policy-id>
+nylas agent policy read <policy-id>
+nylas agent policy read <policy-id> --json
+```
+
+Notes:
+
+- `get` and `read` are aliases
+- text output expands the policy into readable sections for:
+  - rules
+  - limits
+  - options
+  - spam detection
+- `--json` returns the raw API payload
+
+Use `--json` when you need the exact field names for automation or a follow-up update.
+
+## Creating Policies
+
+### Simple Create
+
+```bash
+nylas agent policy create --name "Strict Policy"
+nylas agent policy create --name "Strict Policy" --json
+```
+
+This is the fastest path when you only need a named policy object and will add rules or settings later.
+
+### Full JSON Create
+
+```bash
+nylas agent policy create --data-file policy.json
+nylas agent policy create --data '{"name":"Strict Policy","rules":["rule-123"]}'
+```
+
+Example payload:
+
+```json
+{
+  "name": "Strict Policy",
+  "rules": ["rule-123"],
+  "limits": {
+    "limit_attachment_size_limit": 50480000,
+    "limit_attachment_count_limit": 10,
+    "limit_count_daily_message_per_grant": 500,
+    "limit_inbox_retention_period": 30,
+    "limit_spam_retention_period": 7
+  },
+  "options": {
+    "additional_folders": [],
+    "use_cidr_aliasing": false
+  },
+  "spam_detection": {
+    "use_list_dnsbl": false,
+    "use_header_anomaly_detection": false,
+    "spam_sensitivity": 1
+  }
+}
+```
+
+## Updating Policies
+
+### Simple Update
+
+```bash
+nylas agent policy update <policy-id> --name "Updated Policy"
+```
+
+### Partial JSON Update
+
+```bash
+nylas agent policy update <policy-id> --data-file update.json
+nylas agent policy update <policy-id> --data '{"spam_detection":{"spam_sensitivity":0.8}}'
+```
+
+Behavior:
+
+- `--name` updates the policy name directly
+- `--data` and `--data-file` send a partial JSON body
+- if both are provided, the explicit flags win for overlapping top-level fields
+
+Recommended workflow:
+
+1. `nylas agent policy read <policy-id> --json`
+2. edit the payload you need
+3. `nylas agent policy update <policy-id> --data-file update.json`
+
+## Deleting Policies
+
+```bash
+nylas agent policy delete <policy-id> --yes
+```
+
+Safety rule:
+
+- delete is rejected if any `provider=nylas` agent account still references the policy
+
+To remove a policy from active use:
+
+1. create or choose another policy
+2. create future agent accounts with `--policy-id <new-policy-id>`
+3. remove or rotate away the attached agent accounts that still reference the old policy
+4. delete the now-unattached policy
+
+## Relationship to Agent Accounts
+
+Policies are attached at agent account creation time:
+
+```bash
+nylas agent account create me@yourapp.nylas.email --policy-id <policy-id>
+```
+
+There is currently no separate `agent account update` command, so the main CLI-managed attachment point is account creation.
+
+## Troubleshooting
+
+If `nylas agent policy list` returns nothing:
+
+- make sure your default local grant is a `provider=nylas` account
+- verify the agent account actually has a `settings.policy_id`
+- try `nylas auth list` to confirm which grant is marked default
+
+If `nylas agent policy delete` fails:
+
+- the policy is still attached to one or more `provider=nylas` agent accounts
+- run `nylas agent policy list --all` to see the attached agent mappings
+
+## See Also
+
+- [Agent overview](agent.md)
+- [Agent rules](agent-rule.md)