unbound-cli 0.4.0 → 0.5.1

package/src/commands/policy.js

@@ -3,17 +3,138 @@ const api = require('../api');
 const output = require('../output');
 const { formatDate, confirm, parseCommaSeparated } = require('../utils');
 
+// ============================================================================
+// Constants and docs URLs
+// ============================================================================
+
+const DOCS_POLICIES = 'https://docs.getunbound.ai/policies';
+const DOCS_COST = 'https://docs.getunbound.ai/policies/cost-policies';
+const DOCS_MODEL = 'https://docs.getunbound.ai/policies/model-policies';
+const DOCS_SECURITY = 'https://docs.getunbound.ai/policies/security-policies';
+const DOCS_TOOL = 'https://docs.getunbound.ai/policies/tool-policies';
+
+const POLICY_TYPES = ['SECURITY', 'MODEL', 'COST'];
+const GUARDRAIL_ACTIONS = ['BLOCK', 'REDACT', 'ROUTE', 'AUDIT'];
+const TOOL_ACTIONS = ['AUDIT', 'BLOCK', 'WARN', 'REQUIRE_SLACK_APPROVAL'];
+const SECURITY_SUB_TYPES = ['guardrails', 'default_routing', 'error_code_routing'];
+const MCP_ACTION_TYPES = ['read', 'write', 'destructive'];
+
+// ============================================================================
+// Helpers: auth, resolution, validation, display
+// ============================================================================
+
+function requireLogin() {
+  if (!config.isLoggedIn()) {
+    const err = new Error('Not logged in. Run `unbound login` first.');
+    err.displayed = false;
+    throw err;
+  }
+}
+
+/**
+ * Memoized loader for /api/v1/policies/form_data/. Unwraps the {data: ...}
+ * envelope so callers see a flat object with user_groups, tool_types,
+ * guardrails, ai_models, command_policies.
+ */
+// Module-level cache for /api/v1/policies/form_data/. Each CLI invocation is a
+// fresh Node process, so the cache lifetime is exactly one command and no
+// cross-invocation staleness is possible. Using module-level state (instead of
+// per-call-site factories) guarantees that all call sites inside a single
+// action handler share the same fetched payload — e.g.
+// `policy model create --allowed X --group Y` resolves both flags via one
+// form_data round-trip, not two.
+let _formDataCache = null;
+
+async function loadFormData() {
+  if (_formDataCache) return _formDataCache;
+  const response = await api.get('/api/v1/policies/form_data/');
+  _formDataCache = response.data || response;
+  return _formDataCache;
+}
+
+/**
+ * Resolves a comma-separated list of names or numeric IDs against a list of
+ * {id, name} objects. Returns an array of numeric IDs. Throws a friendly
+ * error if any input cannot be matched, listing the available values.
+ */
+function resolveByName(items, input, { kind, matchKey = 'name' } = {}) {
+  const names = parseCommaSeparated(input);
+  if (!names || names.length === 0) return [];
+
+  const ids = [];
+  for (const raw of names) {
+    if (/^\d+$/.test(raw)) {
+      const id = Number(raw);
+      if (!items.some((item) => item.id === id)) {
+        throw new Error(
+          `No ${kind} with id ${id}. Available: ${items.map((i) => `${i.id}:${i[matchKey]}`).join(', ') || '(none)'}`
+        );
+      }
+      ids.push(id);
+      continue;
+    }
+
+    const lower = raw.toLowerCase();
+    const match = items.find((item) => (item[matchKey] || '').toLowerCase() === lower);
+    if (!match) {
+      throw new Error(
+        `No ${kind} named "${raw}". Available: ${items.map((i) => i[matchKey]).join(', ') || '(none)'}`
+      );
+    }
+    ids.push(match.id);
+  }
+  return ids;
+}
+
+/**
+ * Same as resolveByName but returns the full matched objects (not just IDs).
+ * Useful when the caller needs extra fields like `id` AND `name`.
+ */
+function resolveFull(items, input, { kind, matchKey = 'name' } = {}) {
+  const names = parseCommaSeparated(input);
+  if (!names || names.length === 0) return [];
+
+  const results = [];
+  for (const raw of names) {
+    if (/^\d+$/.test(raw)) {
+      const id = Number(raw);
+      const match = items.find((item) => item.id === id);
+      if (!match) {
+        throw new Error(
+          `No ${kind} with id ${id}. Available: ${items.map((i) => `${i.id}:${i[matchKey]}`).join(', ') || '(none)'}`
+        );
+      }
+      results.push(match);
+      continue;
+    }
+
+    const lower = raw.toLowerCase();
+    const match = items.find((item) => (item[matchKey] || '').toLowerCase() === lower);
+    if (!match) {
+      throw new Error(
+        `No ${kind} named "${raw}". Available: ${items.map((i) => i[matchKey]).join(', ') || '(none)'}`
+      );
+    }
+    results.push(match);
+  }
+  return results;
+}
+
 function formatScope(groups) {
-  if (!groups || groups.length === 0) return '-';
+  if (!groups || groups.length === 0) return 'Everyone';
   return groups.map((g) => g.name).join(', ');
 }
 
 function formatToolTypes(types) {
-  if (!types || types.length === 0) return '-';
+  if (!types || types.length === 0) return 'All';
   return types.join(', ');
 }
 
 function displayPolicy(policy) {
+  if (!policy) {
+    output.warn('No policy data to display.');
+    return;
+  }
   output.keyValue([
     ['ID', String(policy.id)],
     ['Name', policy.name],
@@ -24,39 +145,205 @@ function displayPolicy(policy) {
     ['Scope Groups', formatScope(policy.scope_user_groups)],
     ['Scope Tools', formatToolTypes(policy.scope_tool_types)],
     ['Config Summary', policy.config_summary || '-'],
-    ['Config', policy.config ? JSON.stringify(policy.config) : '-'],
+    ['Config', policy.config ? JSON.stringify(policy.config, null, 2) : '-'],
     ['Created', formatDate(policy.created_at)],
     ['Updated', formatDate(policy.updated_at)],
   ]);
 }
 
-function displayEffectivePolicies(data, opts) {
-  if (opts.json) {
-    output.json(data);
+/**
+ * Unwraps the response from /api/v1/command-policies/ endpoints.
+ *
+ * The command-policies backend returns the serialized policy object
+ * UNWRAPPED — e.g. `{id, name, policy_type, ...}` at the top level.
+ * This is intentionally different from /api/v1/policies/ which wraps in
+ * `{policy: {...}}`. Confirmed in `webapp/api/v1/command_policy_handlers.py`:
+ *   - create (POST): `return JsonResponse(serialize_policy(policy), status=201)`
+ *   - get (GET):     `return JsonResponse(serialize_policy(policy))`
+ *   - update (PUT):  `return JsonResponse(serialize_policy(policy))`
+ *
+ * This helper defensively also handles a future wrapped shape
+ * (`{policy: ...}` or `{command_policy: ...}`) so a backend change that
+ * adds an envelope doesn't silently render every field as undefined.
+ */
+function unwrapToolPolicy(response) {
+  if (!response || typeof response !== 'object') return response;
+  if (response.command_policy) return response.command_policy;
+  // Only unwrap `policy` if it looks like a nested envelope — if the response
+  // itself has an `id` at top level, it's already unwrapped and `policy` would
+  // be a nested field (not the envelope).
+  if (response.policy && typeof response.policy === 'object' && response.id === undefined) {
+    return response.policy;
+  }
+  return response;
+}
+
+function displayToolPolicy(policy) {
+  if (!policy) {
+    output.warn('No policy data to display.');
     return;
   }
+  const rows = [
+    ['ID', String(policy.id)],
+    ['Name', policy.name],
+    ['Description', policy.description || '-'],
+    ['Policy Type', policy.policy_type],
+    ['Action', policy.action],
+    ['Enabled', String(policy.enabled)],
+    ['Status', policy.status || '-'],
+    ['Custom Message', policy.custom_message || '-'],
+    ['Scope Groups', formatScope(policy.scope_user_groups)],
+  ];
+  if (policy.policy_type === 'TERMINAL_COMMAND') {
+    rows.push(['Command Family', policy.command_family || '-']);
+    rows.push(['Config', policy.config ? JSON.stringify(policy.config, null, 2) : '-']);
+  } else if (policy.policy_type === 'MCP_TOOL') {
+    rows.push(['MCP Server', policy.mcp_server || '-']);
+    rows.push(['MCP Tool', policy.mcp_tool || '-']);
+    rows.push(['MCP Action Type', policy.mcp_tool_action_type || '-']);
+  }
+  rows.push(['Target Pattern', policy.target_pattern || '-']);
+  rows.push(['Created', formatDate(policy.created_at)]);
+  rows.push(['Updated', formatDate(policy.updated_at)]);
+  output.keyValue(rows);
+}
 
-  const policies = data.effective_policies || data.policies || [];
-  output.table(policies, [
-    { key: 'id', header: 'ID' },
-    { key: 'name', header: 'Name' },
-    { key: 'type', header: 'Type' },
-    { key: 'enabled', header: 'Enabled' },
-    { key: 'priority', header: 'Priority', format: (v) => (v != null ? String(v) : '-') },
-    { key: 'config_summary', header: 'Config Summary', format: (v) => v || '-' },
-  ]);
+function parseJsonOrThrow(str, flagName = '--config') {
+  try {
+    return JSON.parse(str);
+  } catch {
+    throw new Error(`Invalid JSON for ${flagName} option.`);
+  }
 }
 
-function register(program) {
-  const policy = program
-    .command('policy')
-    .description('Manage policies. Policies control security guardrails, model access, and cost limits applied to user groups and tools.');
+/**
+ * Given a `--guardrail name:action[:threshold]` string, parse into the
+ * {guardrail_id, action, threshold, route_model_id, entities, enabled} shape
+ * the backend expects. Resolves the name and validates the action.
+ */
+function parseGuardrailSpec(spec, allGuardrails, routeModelId) {
+  const parts = spec.split(':');
+  if (parts.length < 2 || parts.length > 3) {
+    throw new Error(`Invalid --guardrail spec "${spec}". Expected format: <name>:<action>[:<threshold>]`);
+  }
+  const [name, actionRaw, thresholdRaw] = parts;
+  const action = actionRaw.toUpperCase();
+  if (!GUARDRAIL_ACTIONS.includes(action)) {
+    throw new Error(
+      `Invalid guardrail action "${actionRaw}". Must be one of: ${GUARDRAIL_ACTIONS.join(', ')}`
+    );
+  }
+
+  const matched = resolveFull(allGuardrails, name, { kind: 'guardrail' });
+  if (matched.length !== 1) {
+    throw new Error(`Invalid --guardrail spec "${spec}": name must resolve to exactly one guardrail`);
+  }
+  const guardrail = matched[0];
+
+  if (guardrail.supported_actions && !guardrail.supported_actions.includes(action)) {
+    throw new Error(
+      `Guardrail "${guardrail.name}" does not support action ${action}. Supported: ${guardrail.supported_actions.join(', ')}`
+    );
+  }
+
+  if (action === 'ROUTE' && !routeModelId) {
+    throw new Error(`Guardrail "${guardrail.name}" uses ROUTE but --route-model was not provided.`);
+  }
+
+  const threshold = thresholdRaw != null ? Number(thresholdRaw) : 1;
+  if (Number.isNaN(threshold) || threshold < 1 || threshold > 100) {
+    throw new Error(`Invalid threshold "${thresholdRaw}" for guardrail "${guardrail.name}". Must be 1-100.`);
+  }
+
+  return {
+    guardrail_id: guardrail.id,
+    enabled: true,
+    action,
+    threshold,
+    route_model_id: action === 'ROUTE' ? routeModelId : null,
+    entities: (guardrail.entities || []).map((e) => ({ entity_id: e.id, enabled: true })),
+  };
+}
+
+/**
+ * Given a `--route source:target` string and the full model list, return a
+ * {source_model_id, destination_model_id} object with resolved numeric IDs.
+ */
+function parseRouteSpec(spec, allModels) {
+  const parts = spec.split(':');
+  if (parts.length !== 2) {
+    throw new Error(`Invalid --route spec "${spec}". Expected format: <source-model>:<target-model>`);
+  }
+  const [srcName, tgtName] = parts;
+  if (!srcName) throw new Error(`Invalid --route spec "${spec}": source model name is empty`);
+  if (!tgtName) throw new Error(`Invalid --route spec "${spec}": target model name is empty`);
+  const src = resolveFull(allModels, srcName, { kind: 'model' })[0];
+  const tgt = resolveFull(allModels, tgtName, { kind: 'model' })[0];
+  return { source_model_id: src.id, destination_model_id: tgt.id };
+}
+
+/**
+ * Given a `--error-route code:source:target` string, return the
+ * {error_code, source_model_id, target_model_id} object the backend expects.
+ */
+function parseErrorRouteSpec(spec, allModels) {
+  const parts = spec.split(':');
+  if (parts.length !== 3) {
+    throw new Error(`Invalid --error-route spec "${spec}". Expected format: <error-code>:<source-model>:<target-model>`);
+  }
+  const [code, srcName, tgtName] = parts;
+  if (!code) throw new Error(`Invalid --error-route spec "${spec}": error code is empty`);
+  if (!srcName) throw new Error(`Invalid --error-route spec "${spec}": source model name is empty`);
+  if (!tgtName) throw new Error(`Invalid --error-route spec "${spec}": target model name is empty`);
+  const src = resolveFull(allModels, srcName, { kind: 'model' })[0];
+  const tgt = resolveFull(allModels, tgtName, { kind: 'model' })[0];
+  return { error_code: code, source_model_id: src.id, target_model_id: tgt.id };
+}
+
+/**
+ * Parse a `--field key=pattern` argument into an [key, pattern] tuple.
+ */
+function parseFieldSpec(spec) {
+  const eq = spec.indexOf('=');
+  if (eq <= 0 || eq === spec.length - 1) {
+    throw new Error(`Invalid --field spec "${spec}". Expected format: <key>=<pattern>`);
+  }
+  return [spec.slice(0, eq), spec.slice(eq + 1)];
+}
+
+/**
+ * Convert a `--sub-type` flag (kebab-case) to the backend's snake_case form.
+ */
+function normalizeSubType(subType) {
+  if (!subType) return null;
+  const normalized = subType.replace(/-/g, '_').toLowerCase();
+  if (!SECURITY_SUB_TYPES.includes(normalized)) {
+    throw new Error(
+      `Invalid --sub-type "${subType}". Must be one of: guardrails, default-routing, error-code-routing`
+    );
+  }
+  return normalized;
+}
+
+function normalizeAction(action, allowed, flagName) {
+  if (!action) return null;
+  const up = action.toUpperCase();
+  if (!allowed.includes(up)) {
+    throw new Error(`Invalid ${flagName} "${action}". Must be one of: ${allowed.join(', ')}`);
+  }
+  return up;
+}
 
-  // policy list
+// ============================================================================
+// Top-level: list, get, delete, form-data, effective
+// ============================================================================
+
+function registerTopLevel(policy) {
+  // ---- list ----
   policy
     .command('list')
-    .description('List all policies. Supports filtering by type, enabled status, and search term.')
-    .option('--type <type>', 'Filter by policy type: SECURITY, MODEL, or COST')
+    .description('List Cost, Model, and Security policies. For Tool policies use `policy tool list`.')
+    .option('--type <type>', 'Filter by type: COST, MODEL, or SECURITY')
     .option('--enabled', 'Show only enabled policies')
     .option('--search <term>', 'Search policies by name')
     .option('--json', 'Output raw JSON instead of a table')
@@ -64,15 +351,21 @@ function register(program) {
 Examples:
   $ unbound policy list
   $ unbound policy list --type SECURITY
-  $ unbound policy list --enabled --json
-  $ unbound policy list --search "default"
+  $ unbound policy list --type COST --enabled
+  $ unbound policy list --search "budget" --json
+
+Learn more: ${DOCS_POLICIES}
 `)
     .action(async (opts) => {
       try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
-          return;
+        requireLogin();
+
+        if (opts.type) {
+          const type = opts.type.toUpperCase();
+          if (!POLICY_TYPES.includes(type)) {
+            throw new Error(`Invalid --type "${opts.type}". Must be one of: ${POLICY_TYPES.join(', ')}. For tool policies, use \`unbound policy tool list\`.`);
+          }
+          opts.type = type;
         }
 
         const query = {};
@@ -87,14 +380,20 @@ Examples:
           return;
         }
 
-        output.table(data.policies, [
+        const policies = data.policies || [];
+        if (policies.length === 0) {
+          output.info('No policies found.');
+          return;
+        }
+
+        output.table(policies, [
           { key: 'id', header: 'ID' },
           { key: 'name', header: 'Name' },
           { key: 'type', header: 'Type' },
           { key: 'enabled', header: 'Enabled' },
           { key: 'priority', header: 'Priority', format: (v) => (v != null ? String(v) : '-') },
           { key: 'scope_user_groups', header: 'Scope', format: (v) => formatScope(v) },
-          { key: 'created_at', header: 'Created', format: (v) => formatDate(v) },
+          { key: 'config_summary', header: 'Summary', format: (v) => v || '-' },
         ]);
       } catch (err) {
         output.error(err.message);
@@ -102,11 +401,11 @@ Examples:
       }
     });
 
-  // policy get
+  // ---- get ----
   policy
     .command('get <id>')
-    .description('Get detailed information about a specific policy by its ID.')
-    .option('--json', 'Output raw JSON instead of formatted key-value pairs')
+    .description('Get details of a single Cost, Model, or Security policy. For Tool policies use `policy tool get`.')
+    .option('--json', 'Output raw JSON')
     .addHelpText('after', `
 Examples:
   $ unbound policy get 1
@@ -114,139 +413,12 @@ Examples:
 `)
     .action(async (id, opts) => {
       try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
-          return;
-        }
-
+        requireLogin();
         const data = await api.get(`/api/v1/policies/${id}/`);
-
         if (opts.json) {
           output.json(data);
           return;
         }
-
-        displayPolicy(data.policy);
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // policy create
-  policy
-    .command('create')
-    .description('Create a new policy. Requires a name and type. Optionally set config, scope, and priority.')
-    .requiredOption('--name <name>', 'Policy name (required)')
-    .requiredOption('--type <type>', 'Policy type: SECURITY, MODEL, or COST (required)')
-    .option('--config <json>', 'Policy configuration as a JSON string')
-    .option('--enabled', 'Enable the policy (default: true)', true)
-    .option('--no-enabled', 'Create the policy in disabled state')
-    .option('--scope-groups <ids>', 'Comma-separated user group IDs to scope this policy to')
-    .option('--scope-tools <types>', 'Comma-separated tool types to scope this policy to (e.g. CLAUDE_CODE,CURSOR)')
-    .option('--priority <n>', 'Policy priority (integer)', parseInt)
-    .addHelpText('after', `
-Examples:
-  $ unbound policy create --name "Security Policy" --type SECURITY
-  $ unbound policy create --name "Model Restrictions" --type MODEL --config '{"allowed_models":["gpt-4"]}'
-  $ unbound policy create --name "Cost Limit" --type COST --scope-groups 1,2 --priority 10
-  $ unbound policy create --name "Disabled Draft" --type SECURITY --no-enabled
-`)
-    .action(async (opts) => {
-      try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
-          return;
-        }
-
-        const body = {
-          name: opts.name,
-          type: opts.type,
-          enabled: opts.enabled,
-        };
-
-        if (opts.config) {
-          try {
-            body.config = JSON.parse(opts.config);
-          } catch {
-            output.error('Invalid JSON for --config option.');
-            process.exitCode = 1;
-            return;
-          }
-        }
-
-        if (opts.scopeGroups) {
-          body.scope_user_groups = parseCommaSeparated(opts.scopeGroups).map(Number);
-        }
-        if (opts.scopeTools) {
-          body.scope_tool_types = parseCommaSeparated(opts.scopeTools);
-        }
-        if (opts.priority != null) {
-          body.priority = opts.priority;
-        }
-
-        const data = await api.post('/api/v1/policies/', { body });
-        output.success('Policy created.');
-        displayPolicy(data.policy);
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // policy update
-  policy
-    .command('update <id>')
-    .description('Update an existing policy. Only provided fields will be changed.')
-    .option('--name <name>', 'Update policy name')
-    .option('--config <json>', 'Update policy configuration (JSON string)')
-    .option('--enabled', 'Enable the policy')
-    .option('--no-enabled', 'Disable the policy')
-    .option('--scope-groups <ids>', 'Comma-separated user group IDs')
-    .option('--scope-tools <types>', 'Comma-separated tool types')
-    .option('--priority <n>', 'Policy priority (integer)', parseInt)
-    .addHelpText('after', `
-Examples:
-  $ unbound policy update 1 --name "Updated Name"
-  $ unbound policy update 1 --enabled
-  $ unbound policy update 1 --no-enabled
-  $ unbound policy update 1 --config '{"max_cost":100}' --priority 5
-  $ unbound policy update 1 --scope-groups 1,3 --scope-tools CURSOR,CLAUDE_CODE
-`)
-    .action(async (id, opts) => {
-      try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
-          return;
-        }
-
-        const body = {};
-        if (opts.name !== undefined) body.name = opts.name;
-        if (opts.enabled !== undefined) body.enabled = opts.enabled;
-        if (opts.priority != null) body.priority = opts.priority;
-
-        if (opts.config) {
-          try {
-            body.config = JSON.parse(opts.config);
-          } catch {
-            output.error('Invalid JSON for --config option.');
-            process.exitCode = 1;
-            return;
-          }
-        }
-
-        if (opts.scopeGroups) {
-          body.scope_user_groups = parseCommaSeparated(opts.scopeGroups).map(Number);
-        }
-        if (opts.scopeTools) {
-          body.scope_tool_types = parseCommaSeparated(opts.scopeTools);
-        }
-
-        const data = await api.put(`/api/v1/policies/${id}/`, { body });
-        output.success('Policy updated.');
         displayPolicy(data.policy);
       } catch (err) {
         output.error(err.message);
@@ -254,10 +426,10 @@ Examples:
       }
     });
 
-  // policy delete
+  // ---- delete ----
   policy
     .command('delete <id>')
-    .description('Delete a policy by its ID. Prompts for confirmation unless --yes is provided.')
+    .description('Delete a Cost, Model, or Security policy. For Tool policies use `policy tool delete`.')
     .option('--yes', 'Skip confirmation prompt')
     .addHelpText('after', `
 Examples:
@@ -266,12 +438,7 @@ Examples:
 `)
     .action(async (id, opts) => {
       try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
-          return;
-        }
-
+        requireLogin();
         if (!opts.yes) {
           const confirmed = await confirm(`Are you sure you want to delete policy ${id}?`);
           if (!confirmed) {
@@ -279,7 +446,6 @@ Examples:
             return;
           }
         }
-
         await api.del(`/api/v1/policies/${id}/`);
         output.success(`Policy ${id} deleted.`);
       } catch (err) {
@@ -288,109 +454,1435 @@ Examples:
       }
     });
 
-  // policy form-data
+  // ---- form-data (the bugfix) ----
   policy
     .command('form-data')
-    .description('Retrieve reference data for creating policies. Includes available user groups, tool types, guardrails, and models.')
-    .option('--json', 'Output raw JSON')
+    .description('Show reference data for building policies: user groups, tool types, guardrails, AI models, and existing command policies.')
+    .option('--json', 'Output raw JSON (flattened — the backend envelope is unwrapped)')
     .addHelpText('after', `
+Use this command before creating a policy to discover what names are
+available for --group, --allowed, --excluded, --guardrail, etc.
+
 Examples:
   $ unbound policy form-data
-  $ unbound policy form-data --json
+  $ unbound policy form-data --json | jq '.user_groups[].name'
+
+Learn more: ${DOCS_POLICIES}
 `)
     .action(async (opts) => {
       try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
-          return;
-        }
+        requireLogin();
 
-        const data = await api.get('/api/v1/policies/form_data/');
+        const response = await api.get('/api/v1/policies/form_data/');
+        const data = response.data || response;
 
         if (opts.json) {
           output.json(data);
           return;
         }
 
-        // Display each section of the form data
-        if (data.user_groups) {
-          console.log('');
-          output.info('User Groups');
+        // User groups
+        console.log('');
+        output.info('User Groups');
+        if (data.user_groups && data.user_groups.length > 0) {
           output.table(data.user_groups, [
             { key: 'id', header: 'ID' },
             { key: 'name', header: 'Name' },
+            { key: 'all_org_users', header: 'All Org', format: (v) => (v ? 'yes' : 'no') },
+            { key: 'member_count', header: 'Members', format: (v) => (v != null ? String(v) : '-') },
           ]);
+        } else {
+          console.log('  (none)');
         }
 
+        // Tool types
+        console.log('');
+        output.info('Tool Types');
         if (data.tool_types && data.tool_types.length > 0) {
-          console.log('');
-          output.info('Tool Types');
-          for (const type of data.tool_types) {
-            console.log(`  ${type}`);
+          for (const t of data.tool_types) {
+            const value = typeof t === 'string' ? t : t.value;
+            const label = typeof t === 'string' ? '' : ` (${t.label})`;
+            console.log(`  ${value}${label}`);
           }
+        } else {
+          console.log('  (none)');
         }
 
-        if (data.guardrails) {
-          console.log('');
-          output.info('Guardrails');
+        // Guardrails (include supported_actions and entity count)
+        console.log('');
+        output.info('Guardrails');
+        if (data.guardrails && data.guardrails.length > 0) {
           output.table(data.guardrails, [
             { key: 'id', header: 'ID' },
             { key: 'name', header: 'Name' },
-            { key: 'type', header: 'Type' },
+            { key: 'supported_actions', header: 'Actions', format: (v) => (Array.isArray(v) ? v.join('|') : '-') },
+            { key: 'entities', header: 'Entities', format: (v) => (Array.isArray(v) ? String(v.length) : '0') },
+            { key: 'description', header: 'Description', format: (v) => v || '-' },
           ]);
+        } else {
+          console.log('  (none)');
         }
 
-        if (data.models) {
-          console.log('');
-          output.info('Models');
-          output.table(data.models, [
+        // AI models grouped by provider
+        console.log('');
+        output.info('AI Models');
+        if (data.ai_models && data.ai_models.length > 0) {
+          const byProvider = {};
+          for (const m of data.ai_models) {
+            const p = m.provider_name || 'Unknown';
+            if (!byProvider[p]) byProvider[p] = [];
+            byProvider[p].push(m);
+          }
+          for (const provider of Object.keys(byProvider).sort()) {
+            console.log(`  ${provider}`);
+            for (const m of byProvider[provider]) {
+              console.log(`    ${m.id}: ${m.name}`);
+            }
+          }
+        } else {
+          console.log('  (none)');
+        }
+
+        // Command policies (was missing entirely before)
+        console.log('');
+        output.info('Command Policies (used by Security policies for command_policy/mcp_policy sub-types)');
+        if (data.command_policies && data.command_policies.length > 0) {
+          output.table(data.command_policies, [
             { key: 'id', header: 'ID' },
             { key: 'name', header: 'Name' },
-            { key: 'provider', header: 'Provider' },
+            { key: 'policy_type', header: 'Policy Type' },
+            { key: 'command_family', header: 'Family', format: (v) => v || '-' },
+            { key: 'mcp_server', header: 'MCP Server', format: (v) => v || '-' },
+            { key: 'action', header: 'Action' },
+            { key: 'enabled', header: 'Enabled', format: (v) => (v ? 'yes' : 'no') },
           ]);
+        } else {
+          console.log('  (none)');
         }
+
+        console.log('');
+        console.log(`Learn more: ${DOCS_POLICIES}`);
       } catch (err) {
         output.error(err.message);
         process.exitCode = 1;
       }
     });
 
-  // policy effective
+  // ---- effective ----
   policy
     .command('effective <id>')
-    .description('View effective policies for a user or group. Effective policies are the resolved set after inheritance and priority.')
-    .option('--user', 'Resolve effective policies for a user ID (default)')
-    .option('--group', 'Resolve effective policies for a group ID')
+    .description('View effective policies for a user or group. Shows the resolved set after inheritance, priority, and merge.')
+    .option('--user', 'Resolve for a user ID (default)')
+    .option('--group', 'Resolve for a user-group ID')
     .option('--json', 'Output raw JSON')
     .addHelpText('after', `
 Examples:
-  $ unbound policy effective 42              # Effective policies for user 42
-  $ unbound policy effective 42 --user       # Same as above (--user is default)
-  $ unbound policy effective 5 --group       # Effective policies for group 5
+  $ unbound policy effective 42              # user 42 (default)
+  $ unbound policy effective 42 --user
+  $ unbound policy effective 5 --group       # group 5
   $ unbound policy effective 42 --json
+
+Learn more: ${DOCS_POLICIES}
 `)
     .action(async (id, opts) => {
       try {
-        if (!config.isLoggedIn()) {
-          output.error('Not logged in. Run `unbound login` first.');
-          process.exitCode = 1;
+        requireLogin();
+        const path = opts.group
+          ? `/api/v1/user_groups/${id}/effective_policies/`
+          : `/api/v1/users/${id}/effective_policies/`;
+        const data = await api.get(path);
+
+        if (opts.json) {
+          output.json(data);
           return;
         }
 
-        let data;
-        if (opts.group) {
-          data = await api.get(`/api/v1/user_groups/${id}/effective_policies/`);
+        const eff = data.effective_policies || {};
+
+        if (eff.model) {
+          console.log('');
+          output.info('Model Policy');
+          output.keyValue([
+            ['ID', String(eff.model.id)],
+            ['Name', eff.model.name],
+            ['Priority', eff.model.priority != null ? String(eff.model.priority) : '-'],
+            ['Config', JSON.stringify(eff.model.config || {}, null, 2)],
+          ]);
+        } else {
+          console.log('');
+          output.info('Model Policy: (none)');
+        }
+
+        if (eff.cost) {
+          console.log('');
+          output.info('Cost Policy');
+          output.keyValue([
+            ['ID', String(eff.cost.id)],
+            ['Name', eff.cost.name],
+            ['Monthly Budget', String((eff.cost.config || {}).monthly_budget ?? '-')],
+          ]);
         } else {
-          data = await api.get(`/api/v1/users/${id}/effective_policies/`);
+          console.log('');
+          output.info('Cost Policy: (none)');
+        }
+
+        if (eff.security) {
+          console.log('');
+          output.info('Security Policy (merged)');
+          output.keyValue([
+            ['Guardrails', String((eff.security.guardrails || []).length)],
+            ['Default Routing Rules', String((eff.security.default_routing_rules || []).length)],
+            ['Error Routing Rules', String((eff.security.error_routing_rules || []).length)],
+            ['Command Policies', String((eff.security.command_policy_ids || []).length)],
+          ]);
+        } else {
+          console.log('');
+          output.info('Security Policy: (none)');
+        }
+
+        if (eff.tool && eff.tool.length > 0) {
+          console.log('');
+          output.info('Tool Policies');
+          output.table(eff.tool, [
+            { key: 'id', header: 'ID' },
+            { key: 'name', header: 'Name' },
+            { key: 'policy_type', header: 'Type' },
+            { key: 'action', header: 'Action' },
+            { key: 'command_family', header: 'Family', format: (v) => v || '-' },
+            { key: 'mcp_server', header: 'MCP Server', format: (v) => v || '-' },
+          ]);
+        } else {
+          console.log('');
+          output.info('Tool Policies: (none)');
         }
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+// ============================================================================
+// Cost policies
+// ============================================================================
+
+function registerCost(policy) {
+  const cost = policy
+    .command('cost')
+    .description('Manage Cost policies. Set monthly budget limits per user group.')
+    .addHelpText('after', `
+Cost policies cap AI spending per user group on a monthly basis.
+Learn more: ${DOCS_COST}
 
-        displayEffectivePolicies(data, opts);
+Subcommands:
+  list                    List all cost policies
+  create [options]        Create a new cost policy
+  update <id> [options]   Update an existing cost policy
+`);
+
+  cost
+    .command('list')
+    .description('List all Cost policies.')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const data = await api.get('/api/v1/policies/', { query: { type: 'COST' } });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        const policies = data.policies || [];
+        if (policies.length === 0) {
+          output.info('No cost policies found.');
+          return;
+        }
+        output.table(policies, [
+          { key: 'id', header: 'ID' },
+          { key: 'name', header: 'Name' },
+          { key: 'priority', header: 'Priority', format: (v) => (v != null ? String(v) : '-') },
+          { key: 'scope_user_groups', header: 'Scope', format: (v) => formatScope(v) },
+          { key: 'config', header: 'Monthly Budget', format: (v) => (v && v.monthly_budget != null ? String(v.monthly_budget) : '-') },
+          { key: 'enabled', header: 'Enabled' },
+        ]);
       } catch (err) {
         output.error(err.message);
         process.exitCode = 1;
       }
     });
+
+  cost
+    .command('create')
+    .description('Create a new Cost policy with a monthly budget.')
+    .requiredOption('--name <name>', 'Policy name (required)')
+    .option('--monthly-budget <amount>', 'Monthly budget in USD (number). Required unless --config is used.', parseFloat)
+    .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to (default: all users)')
+    .option('--priority <n>', 'Priority (lower = higher precedence). Auto-assigned if omitted.', parseInt)
+    .option('--disabled', 'Create the policy in disabled state')
+    .option('--config <json>', 'Advanced: raw config JSON. Mutually exclusive with --monthly-budget.')
+    .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('after', `
+Examples:
+  $ unbound policy cost create --name "Eng Budget" --monthly-budget 1000 --group engg
+  $ unbound policy cost create --name "Everyone $500" --monthly-budget 500
+  $ unbound policy cost create --name "Top Priority" --monthly-budget 2000 --priority 1
+  $ unbound policy cost create --name "Draft" --monthly-budget 100 --disabled
+
+To see available user group names, run: unbound policy form-data
+Learn more: ${DOCS_COST}
+`)
+    .action(async (opts) => {
+      try {
+        requireLogin();
+
+        if (opts.config && opts.monthlyBudget != null) {
+          throw new Error('Cannot combine --config with type-specific flags (--monthly-budget).');
+        }
+
+        let configObj;
+        if (opts.config) {
+          configObj = parseJsonOrThrow(opts.config);
+        } else {
+          if (opts.monthlyBudget == null || Number.isNaN(opts.monthlyBudget)) {
+            throw new Error('--monthly-budget <amount> is required (or use --config to supply a raw config).');
+          }
+          configObj = { monthly_budget: opts.monthlyBudget };
+        }
+
+        const body = {
+          name: opts.name,
+          type: 'COST',
+          config: configObj,
+          enabled: !opts.disabled,
+        };
+
+        if (opts.group) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+        if (opts.priority != null) body.priority = opts.priority;
+
+        const data = await api.post('/api/v1/policies/', { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Cost policy "${opts.name}" created.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  cost
+    .command('update <id>')
+    .description('Update an existing Cost policy. Only provided fields are changed.')
+    .option('--name <name>', 'New name')
+    .option('--monthly-budget <amount>', 'New monthly budget in USD', parseFloat)
+    .option('--group <names|ids>', 'Replace scope: comma-separated user group names or IDs')
+    .option('--priority <n>', 'New priority', parseInt)
+    .option('--enabled', 'Enable the policy')
+    .option('--disabled', 'Disable the policy')
+    .option('--config <json>', 'Advanced: replace config with raw JSON')
+    .option('--json', 'Output raw JSON')
+    .addHelpText('after', `
+Examples:
+  $ unbound policy cost update 5 --monthly-budget 1500
+  $ unbound policy cost update 5 --disabled
+  $ unbound policy cost update 5 --group engg,everyone --priority 2
+
+Learn more: ${DOCS_COST}
+`)
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+
+        if (opts.enabled && opts.disabled) {
+          throw new Error('Cannot combine --enabled and --disabled.');
+        }
+        if (opts.config && opts.monthlyBudget != null) {
+          throw new Error('Cannot combine --config with --monthly-budget.');
+        }
+
+        const body = {};
+        if (opts.name !== undefined) body.name = opts.name;
+        if (opts.priority != null) body.priority = opts.priority;
+        if (opts.enabled) body.enabled = true;
+        if (opts.disabled) body.enabled = false;
+
+        if (opts.config) {
+          body.config = parseJsonOrThrow(opts.config);
+        } else if (opts.monthlyBudget != null) {
+          if (Number.isNaN(opts.monthlyBudget)) throw new Error('Invalid --monthly-budget value.');
+          body.config = { monthly_budget: opts.monthlyBudget };
+        }
+
+        if (opts.group !== undefined) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+
+        const data = await api.put(`/api/v1/policies/${id}/`, { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Cost policy ${id} updated.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+// ============================================================================
+// Model policies
+// ============================================================================
+
+function registerModel(policy) {
+  const model = policy
+    .command('model')
+    .description('Manage Model policies. Control which AI models are available to a user group.')
+    .addHelpText('after', `
+Model policies restrict which AI models users can invoke. Choose one of:
+  --all-models                Allow everything (with --excluded as optional exceptions)
+  --allowed <names>           Allow only the listed models
+  --excluded <names>          Allow everything except the listed models (implies --all-models)
+
+Learn more: ${DOCS_MODEL}
+
+Subcommands:
+  list                    List all model policies
+  create [options]        Create a new model policy
+  update <id> [options]   Update an existing model policy
+`);
+
+  model
+    .command('list')
+    .description('List all Model policies.')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const data = await api.get('/api/v1/policies/', { query: { type: 'MODEL' } });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        const policies = data.policies || [];
+        if (policies.length === 0) {
+          output.info('No model policies found.');
+          return;
+        }
+        output.table(policies, [
+          { key: 'id', header: 'ID' },
+          { key: 'name', header: 'Name' },
+          { key: 'priority', header: 'Priority', format: (v) => (v != null ? String(v) : '-') },
+          { key: 'scope_user_groups', header: 'Scope', format: (v) => formatScope(v) },
+          { key: 'config_summary', header: 'Summary', format: (v) => v || '-' },
+          { key: 'enabled', header: 'Enabled' },
+        ]);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  model
+    .command('create')
+    .description('Create a new Model policy.')
+    .requiredOption('--name <name>', 'Policy name (required)')
+    .option('--all-models', 'Allow all models (use with --excluded for exceptions)')
+    .option('--allowed <names>', 'Allow only the listed models (comma-separated names or IDs)')
+    .option('--excluded <names>', 'When used with --all-models: exclude the listed models')
+    .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to')
+    .option('--priority <n>', 'Priority (lower = higher precedence). Auto-assigned if omitted.', parseInt)
+    .option('--disabled', 'Create the policy in disabled state')
+    .option('--config <json>', 'Advanced: raw config JSON')
+    .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('after', `
+Examples:
+  $ unbound policy model create --name "Anthropic Only" --allowed claude-3-5-sonnet,claude-3-opus
+  $ unbound policy model create --name "No Opus" --all-models --excluded claude-3-opus
+  $ unbound policy model create --name "Everything" --all-models --group engg
+  $ unbound policy model create --name "Sonnet For Everyone" --allowed claude-3-5-sonnet
+
+To see available model names, run: unbound policy form-data
+Learn more: ${DOCS_MODEL}
+`)
+    .action(async (opts) => {
+      try {
+        requireLogin();
+
+        const usingConfig = !!opts.config;
+        const usingFlags = opts.allModels || opts.allowed || opts.excluded;
+        if (usingConfig && usingFlags) {
+          throw new Error('Cannot combine --config with type-specific flags (--all-models, --allowed, --excluded).');
+        }
+
+        let configObj;
+        if (usingConfig) {
+          configObj = parseJsonOrThrow(opts.config);
+        } else {
+          if (!usingFlags) {
+            throw new Error('Must provide one of --all-models, --allowed, or --excluded.');
+          }
+          if (opts.allowed && (opts.allModels || opts.excluded)) {
+            throw new Error('--allowed is mutually exclusive with --all-models and --excluded.');
+          }
+
+          const formData = await loadFormData();
+          const models = formData.ai_models || [];
+
+          configObj = { support_all_models: false, allowed_model_ids: [], excluded_model_ids: [] };
+
+          if (opts.allowed) {
+            configObj.allowed_model_ids = resolveByName(models, opts.allowed, { kind: 'model' });
+          } else if (opts.allModels) {
+            configObj.support_all_models = true;
+            if (opts.excluded) {
+              configObj.excluded_model_ids = resolveByName(models, opts.excluded, { kind: 'model' });
+            }
+          } else if (opts.excluded) {
+            // --excluded alone implies --all-models
+            configObj.support_all_models = true;
+            configObj.excluded_model_ids = resolveByName(models, opts.excluded, { kind: 'model' });
+          }
+        }
+
+        const body = {
+          name: opts.name,
+          type: 'MODEL',
+          config: configObj,
+          enabled: !opts.disabled,
+        };
+
+        if (opts.group) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+        if (opts.priority != null) body.priority = opts.priority;
+
+        const data = await api.post('/api/v1/policies/', { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Model policy "${opts.name}" created.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  model
+    .command('update <id>')
+    .description('Update an existing Model policy. Only provided fields are changed.')
+    .option('--name <name>', 'New name')
+    .option('--all-models', 'Replace config with "allow all"')
+    .option('--allowed <names>', 'Replace allowed-model list')
+    .option('--excluded <names>', 'Replace excluded-model list (implies all-models)')
+    .option('--group <names|ids>', 'Replace scope')
+    .option('--priority <n>', 'New priority', parseInt)
+    .option('--enabled', 'Enable the policy')
+    .option('--disabled', 'Disable the policy')
+    .option('--config <json>', 'Advanced: replace config with raw JSON')
+    .option('--json', 'Output raw JSON')
+    .addHelpText('after', `
+Examples:
+  $ unbound policy model update 3 --allowed claude-3-5-sonnet
+  $ unbound policy model update 3 --all-models --excluded claude-3-opus
+  $ unbound policy model update 3 --disabled
+
+Learn more: ${DOCS_MODEL}
+`)
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+
+        if (opts.enabled && opts.disabled) throw new Error('Cannot combine --enabled and --disabled.');
+        const flagConfig = opts.allModels || opts.allowed || opts.excluded;
+        if (opts.config && flagConfig) {
+          throw new Error('Cannot combine --config with type-specific flags.');
+        }
+        if (opts.allowed && (opts.allModels || opts.excluded)) {
+          throw new Error('--allowed is mutually exclusive with --all-models and --excluded.');
+        }
+
+        const body = {};
+        if (opts.name !== undefined) body.name = opts.name;
+        if (opts.priority != null) body.priority = opts.priority;
+        if (opts.enabled) body.enabled = true;
+        if (opts.disabled) body.enabled = false;
+
+        if (opts.config) {
+          body.config = parseJsonOrThrow(opts.config);
+        } else if (flagConfig) {
+          const formData = await loadFormData();
+          const models = formData.ai_models || [];
+          body.config = { support_all_models: false, allowed_model_ids: [], excluded_model_ids: [] };
+          if (opts.allowed) {
+            body.config.allowed_model_ids = resolveByName(models, opts.allowed, { kind: 'model' });
+          } else if (opts.allModels) {
+            body.config.support_all_models = true;
+            if (opts.excluded) body.config.excluded_model_ids = resolveByName(models, opts.excluded, { kind: 'model' });
+          } else if (opts.excluded) {
+            body.config.support_all_models = true;
+            body.config.excluded_model_ids = resolveByName(models, opts.excluded, { kind: 'model' });
+          }
+        }
+
+        if (opts.group !== undefined) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+
+        const data = await api.put(`/api/v1/policies/${id}/`, { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Model policy ${id} updated.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+// ============================================================================
+// Security policies
+// ============================================================================
+
+function registerSecurity(policy) {
+  const security = policy
+    .command('security')
+    .description('Manage Security policies. Guardrails for PII/secrets and model routing rules.')
+    .addHelpText('after', `
+Security policies come in three sub-types:
+  guardrails            Detect/block/redact sensitive content (PII, secrets, etc.)
+  default-routing       Route one model's traffic to another
+  error-code-routing    Re-route on specific HTTP error codes (e.g. 429 → fallback model)
+
+Learn more: ${DOCS_SECURITY}
+
+Subcommands:
+  list                    List all security policies
+  create [options]        Create a new security policy
+  update <id> [options]   Update an existing security policy
+`);
+
+  security
+    .command('list')
+    .description('List all Security policies.')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const data = await api.get('/api/v1/policies/', { query: { type: 'SECURITY' } });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        const policies = data.policies || [];
+        if (policies.length === 0) {
+          output.info('No security policies found.');
+          return;
+        }
+        output.table(policies, [
+          { key: 'id', header: 'ID' },
+          { key: 'name', header: 'Name' },
+          { key: 'config', header: 'Sub-type', format: (v) => (v && v.sub_type) || '-' },
+          { key: 'scope_user_groups', header: 'Scope', format: (v) => formatScope(v) },
+          { key: 'config_summary', header: 'Summary', format: (v) => v || '-' },
+          { key: 'enabled', header: 'Enabled' },
+        ]);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  security
+    .command('create')
+    .description('Create a new Security policy.')
+    .requiredOption('--name <name>', 'Policy name (required)')
+    .option('--sub-type <type>', 'Sub-type: guardrails | default-routing | error-code-routing')
+    .option('--guardrail <spec>', 'Guardrail spec: <name>:<action>[:<threshold>]. Repeatable. For guardrails sub-type.', (val, prev = []) => [...prev, val])
+    .option('--route-model <name>', 'Target model name for guardrail ROUTE actions')
+    .option('--route <spec>', 'Default routing rule: <source-model>:<target-model>. Repeatable. For default-routing sub-type.', (val, prev = []) => [...prev, val])
+    .option('--error-route <spec>', 'Error routing rule: <error-code>:<source-model>:<target-model>. Repeatable. For error-code-routing sub-type.', (val, prev = []) => [...prev, val])
+    .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to')
+    .option('--priority <n>', 'Priority (lower = higher precedence)', parseInt)
+    .option('--disabled', 'Create the policy in disabled state')
+    .option('--config <json>', 'Advanced: raw config JSON (skips flag-based builder)')
+    .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('after', `
+Examples:
+  Guardrails sub-type:
+  $ unbound policy security create --name "Block PII" --sub-type guardrails \\
+      --guardrail PII:BLOCK --guardrail Secrets:REDACT --group engg
+
+  $ unbound policy security create --name "Route PII To Safe Model" --sub-type guardrails \\
+      --guardrail PII:ROUTE --route-model claude-3-5-sonnet
+
+  Default routing sub-type:
+  $ unbound policy security create --name "Prefer Sonnet" --sub-type default-routing \\
+      --route gpt-4:claude-3-5-sonnet
+
+  Error code routing sub-type:
+  $ unbound policy security create --name "429 Fallback" --sub-type error-code-routing \\
+      --error-route 429:gpt-4:claude-3-5-sonnet
+
+To see available guardrail and model names: unbound policy form-data
+Learn more: ${DOCS_SECURITY}
+`)
+    .action(async (opts) => {
+      try {
+        requireLogin();
+
+        const flagMode = opts.subType || (opts.guardrail && opts.guardrail.length) || (opts.route && opts.route.length) || (opts.errorRoute && opts.errorRoute.length);
+        if (opts.config && flagMode) {
+          throw new Error('Cannot combine --config with type-specific flags (--sub-type, --guardrail, --route, --error-route).');
+        }
+
+        let configObj;
+        if (opts.config) {
+          configObj = parseJsonOrThrow(opts.config);
+        } else {
+          if (!opts.subType) {
+            throw new Error('--sub-type is required (one of: guardrails, default-routing, error-code-routing).');
+          }
+          const subType = normalizeSubType(opts.subType);
+          configObj = { sub_type: subType };
+
+          if (subType === 'guardrails') {
+            if (!opts.guardrail || opts.guardrail.length === 0) {
+              throw new Error('At least one --guardrail is required for sub-type guardrails.');
+            }
+            const formData = await loadFormData();
+            const guardrails = formData.guardrails || [];
+            const models = formData.ai_models || [];
+
+            let routeModelId = null;
+            if (opts.routeModel) {
+              const m = resolveFull(models, opts.routeModel, { kind: 'model' })[0];
+              routeModelId = m.id;
+            }
+
+            configObj.guardrails = opts.guardrail.map((spec) => parseGuardrailSpec(spec, guardrails, routeModelId));
+          } else if (subType === 'default_routing') {
+            if (!opts.route || opts.route.length === 0) {
+              throw new Error('At least one --route is required for sub-type default-routing.');
+            }
+            const formData = await loadFormData();
+            const models = formData.ai_models || [];
+            configObj.default_routing_rules = opts.route.map((spec) => parseRouteSpec(spec, models));
+          } else if (subType === 'error_code_routing') {
+            if (!opts.errorRoute || opts.errorRoute.length === 0) {
+              throw new Error('At least one --error-route is required for sub-type error-code-routing.');
+            }
+            const formData = await loadFormData();
+            const models = formData.ai_models || [];
+            configObj.error_routing_rules = opts.errorRoute.map((spec) => parseErrorRouteSpec(spec, models));
+          }
+        }
+
+        const body = {
+          name: opts.name,
+          type: 'SECURITY',
+          config: configObj,
+          enabled: !opts.disabled,
+        };
+
+        if (opts.group) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+        if (opts.priority != null) body.priority = opts.priority;
+
+        const data = await api.post('/api/v1/policies/', { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Security policy "${opts.name}" created.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  security
+    .command('update <id>')
+    .description('Update an existing Security policy. Only provided fields are changed.')
+    .option('--name <name>', 'New name')
+    .option('--group <names|ids>', 'Replace scope')
+    .option('--priority <n>', 'New priority', parseInt)
+    .option('--enabled', 'Enable the policy')
+    .option('--disabled', 'Disable the policy')
+    .option('--config <json>', 'Replace config with raw JSON (required for config changes on security policies)')
+    .option('--json', 'Output raw JSON')
+    .addHelpText('after', `
+Security policy config updates require --config <json> because the shape
+is sub-type specific. Fetch the current config with:
+  $ unbound policy get <id> --json | jq '.policy.config'
+
+Then pass the updated config back:
+  $ unbound policy security update <id> --config '{"sub_type":"guardrails","guardrails":[...]}'
+
+For simple metadata changes, use the other flags.
+
+Learn more: ${DOCS_SECURITY}
+`)
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+        if (opts.enabled && opts.disabled) throw new Error('Cannot combine --enabled and --disabled.');
+
+        const body = {};
+        if (opts.name !== undefined) body.name = opts.name;
+        if (opts.priority != null) body.priority = opts.priority;
+        if (opts.enabled) body.enabled = true;
+        if (opts.disabled) body.enabled = false;
+        if (opts.config) body.config = parseJsonOrThrow(opts.config);
+
+        if (opts.group !== undefined) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+
+        const data = await api.put(`/api/v1/policies/${id}/`, { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Security policy ${id} updated.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+// ============================================================================
+// Tool policies (routes to /api/v1/command-policies/)
+// ============================================================================
+
+function registerTool(policy) {
+  const tool = policy
+    .command('tool')
+    .description('Manage Tool policies: controls for shell commands (TERMINAL_COMMAND) and MCP tool calls (MCP_TOOL).')
+    .addHelpText('after', `
+Tool policies live in a separate backend table from Cost/Model/Security
+policies and are reached via /api/v1/command-policies/.
+
+Learn more: ${DOCS_TOOL}
+
+Subcommands:
+  list                      List all tool policies
+  get <id>                  Get a single tool policy
+  delete <id>               Delete a tool policy
+  create-terminal [options] Create a terminal command policy
+  create-mcp [options]      Create an MCP tool policy
+  update <id> [options]     Update an existing tool policy
+  families                  List terminal command families and their fields
+  mcp-servers               List known MCP servers and their tools
+`);
+
+  tool
+    .command('list')
+    .description('List tool (command) policies, paginated.')
+    .option('--type <type>', 'Filter by policy type: TERMINAL or MCP')
+    .option('--search <term>', 'Search by name, description, or command family')
+    .option('--page <n>', 'Page number (default 1)', parseInt)
+    .option('--page-size <n>', 'Page size (default 50)', parseInt)
+    .option('--all', 'Fetch all pages (may be slow for large orgs)')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        requireLogin();
+
+        let policyType;
+        if (opts.type) {
+          const up = opts.type.toUpperCase();
+          if (up === 'TERMINAL' || up === 'TERMINAL_COMMAND') policyType = 'TERMINAL_COMMAND';
+          else if (up === 'MCP' || up === 'MCP_TOOL') policyType = 'MCP_TOOL';
+          else throw new Error(`Invalid --type "${opts.type}". Must be TERMINAL or MCP.`);
+        }
+
+        const fetchPage = async (page, pageSize) => {
+          const query = { page, page_size: pageSize };
+          if (policyType) query.policy_type = policyType;
+          if (opts.search) query.search = opts.search;
+          return api.get('/api/v1/command-policies/', { query });
+        };
+
+        const pageSize = opts.pageSize || 50;
+        let policies = [];
+        let meta;
+
+        if (opts.all) {
+          let page = 1;
+          while (true) {
+            const data = await fetchPage(page, pageSize);
+            policies = policies.concat(data.policies || []);
+            meta = data;
+            if (!data.total_pages || page >= data.total_pages) break;
+            page += 1;
+          }
+        } else {
+          const page = opts.page || 1;
+          const data = await fetchPage(page, pageSize);
+          policies = data.policies || [];
+          meta = data;
+        }
+
+        if (opts.json) {
+          output.json({ policies, total: meta.total, page: meta.page, page_size: meta.page_size, total_pages: meta.total_pages });
+          return;
+        }
+
+        if (policies.length === 0) {
+          output.info('No tool policies found.');
+          return;
+        }
+
+        output.table(policies, [
+          { key: 'id', header: 'ID' },
+          { key: 'name', header: 'Name' },
+          { key: 'policy_type', header: 'Type' },
+          { key: 'type_display', header: 'Family/Server', format: (v) => v || '-' },
+          { key: 'target_pattern', header: 'Target', format: (v) => v || '-' },
+          { key: 'action', header: 'Action' },
+          { key: 'enabled', header: 'Enabled', format: (v) => (v ? 'yes' : 'no') },
+          { key: 'scope_user_groups', header: 'Scope', format: (v) => formatScope(v) },
+        ]);
+
+        if (!opts.all && meta.total_pages && meta.total_pages > 1) {
+          console.log('');
+          output.info(`Page ${meta.page} of ${meta.total_pages} (total: ${meta.total}). Use --all to fetch every page.`);
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('get <id>')
+    .description('Get a single tool (command) policy by ID.')
+    .option('--json', 'Output raw JSON')
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+        const data = await api.get(`/api/v1/command-policies/${id}/`);
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        displayToolPolicy(unwrapToolPolicy(data));
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('delete <id>')
+    .description('Delete a tool (command) policy by ID.')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+        if (!opts.yes) {
+          const confirmed = await confirm(`Are you sure you want to delete tool policy ${id}?`);
+          if (!confirmed) {
+            output.warn('Aborted.');
+            return;
+          }
+        }
+        await api.del(`/api/v1/command-policies/${id}/`);
+        output.success(`Tool policy ${id} deleted.`);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('create-terminal')
+    .description('Create a TERMINAL_COMMAND policy: monitor or block shell commands run by AI coding tools.')
+    .requiredOption('--name <name>', 'Policy name (required)')
+    .requiredOption('--command-family <family>', 'Command family (e.g. git, filesystem, network). See `policy tool families`.')
+    .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable. At least one required unless --config is used.', (val, prev = []) => [...prev, val])
+    .requiredOption('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
+    .option('--description <text>', 'Human-readable description')
+    .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN.')
+    .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to')
+    .option('--disabled', 'Create the policy in disabled state')
+    .option('--config <json>', 'Advanced: raw config JSON (skips --field builder)')
+    .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('after', `
+Examples:
+  $ unbound policy tool create-terminal --name "Block rm -rf" \\
+      --command-family filesystem --field command='rm -rf*' --action BLOCK \\
+      --custom-message "Destructive commands are blocked."
+
+  $ unbound policy tool create-terminal --name "Audit git push" \\
+      --command-family git --field command='git push*' --action AUDIT
+
+  $ unbound policy tool create-terminal --name "Warn curl" \\
+      --command-family network --field command='curl*' --action WARN \\
+      --custom-message "Outbound HTTP calls are being audited."
+
+Discover valid command families and their fields: unbound policy tool families
+Learn more: ${DOCS_TOOL}
+`)
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const action = normalizeAction(opts.action, TOOL_ACTIONS, '--action');
+        if ((action === 'BLOCK' || action === 'WARN') && !opts.customMessage) {
+          throw new Error('--custom-message is required when --action is BLOCK or WARN.');
+        }
+        if (opts.config && opts.field) {
+          throw new Error('Cannot combine --config with --field.');
+        }
+
+        let configObj;
+        if (opts.config) {
+          configObj = parseJsonOrThrow(opts.config);
+        } else {
+          if (!opts.field || opts.field.length === 0) {
+            throw new Error('At least one --field <key>=<pattern> is required (or use --config).');
+          }
+          configObj = {};
+          for (const spec of opts.field) {
+            const [k, v] = parseFieldSpec(spec);
+            configObj[k] = v;
+          }
+        }
+
+        const body = {
+          name: opts.name,
+          description: opts.description || '',
+          policy_type: 'TERMINAL_COMMAND',
+          command_family: opts.commandFamily,
+          config: configObj,
+          action,
+          enabled: !opts.disabled,
+        };
+        if (opts.customMessage) body.custom_message = opts.customMessage;
+
+        if (opts.group) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+
+        const data = await api.post('/api/v1/command-policies/', { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Terminal policy "${opts.name}" created.`);
+        displayToolPolicy(unwrapToolPolicy(data));
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('create-mcp')
+    .description('Create an MCP_TOOL policy: monitor or block MCP server tool calls.')
+    .requiredOption('--name <name>', 'Policy name (required)')
+    .requiredOption('--mcp-server <server>', 'MCP server name (e.g. Linear, Slack). See `policy tool mcp-servers`.')
+    .option('--mcp-tool <tool>', 'Specific tool name on the MCP server (e.g. create_issue). Mutually exclusive with --mcp-action-type.')
+    .option('--mcp-action-type <type>', `Match by tool action type: ${MCP_ACTION_TYPES.join(' | ')}. Mutually exclusive with --mcp-tool.`)
+    .requiredOption('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
+    .option('--description <text>', 'Human-readable description')
+    .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN.')
+    .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to')
+    .option('--disabled', 'Create the policy in disabled state')
+    .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('after', `
+Examples:
+  Match a specific tool on a server:
+  $ unbound policy tool create-mcp --name "Block Linear writes" \\
+      --mcp-server Linear --mcp-tool create_issue --action BLOCK \\
+      --custom-message "Issue creation is blocked. Contact admin."
+
+  Match all destructive tools on a server:
+  $ unbound policy tool create-mcp --name "Audit all destructive Slack" \\
+      --mcp-server Slack --mcp-action-type destructive --action AUDIT
+
+Discover valid MCP servers and their tools: unbound policy tool mcp-servers
+Learn more: ${DOCS_TOOL}
+`)
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const action = normalizeAction(opts.action, TOOL_ACTIONS, '--action');
+        if ((action === 'BLOCK' || action === 'WARN') && !opts.customMessage) {
+          throw new Error('--custom-message is required when --action is BLOCK or WARN.');
+        }
+
+        const hasTool = !!opts.mcpTool;
+        const hasActionType = !!opts.mcpActionType;
+        if (hasTool && hasActionType) {
+          throw new Error('--mcp-tool and --mcp-action-type are mutually exclusive.');
+        }
+        if (!hasTool && !hasActionType) {
+          throw new Error('Either --mcp-tool or --mcp-action-type is required.');
+        }
+        if (hasActionType) {
+          const at = opts.mcpActionType.toLowerCase();
+          if (!MCP_ACTION_TYPES.includes(at)) {
+            throw new Error(`Invalid --mcp-action-type "${opts.mcpActionType}". Must be one of: ${MCP_ACTION_TYPES.join(', ')}`);
+          }
+          opts.mcpActionType = at;
+        }
+
+        const body = {
+          name: opts.name,
+          description: opts.description || '',
+          policy_type: 'MCP_TOOL',
+          mcp_server: opts.mcpServer,
+          action,
+          enabled: !opts.disabled,
+          config: {},
+        };
+        if (hasTool) body.mcp_tool = opts.mcpTool;
+        if (hasActionType) body.mcp_tool_action_type = opts.mcpActionType;
+        if (opts.customMessage) body.custom_message = opts.customMessage;
+
+        if (opts.group) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+
+        const data = await api.post('/api/v1/command-policies/', { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`MCP policy "${opts.name}" created.`);
+        displayToolPolicy(unwrapToolPolicy(data));
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('update <id>')
+    .description('Update an existing tool (command) policy. Only provided fields are changed.')
+    .option('--name <name>', 'New name')
+    .option('--description <text>', 'New description')
+    .option('--action <action>', `New action: ${TOOL_ACTIONS.join(' | ')}`)
+    .option('--custom-message <text>', 'New custom message')
+    .option('--group <names|ids>', 'Replace scope')
+    .option('--enabled', 'Enable the policy')
+    .option('--disabled', 'Disable the policy')
+    .option('--command-family <family>', '(TERMINAL only) new command family')
+    .option('--field <key=pattern>', '(TERMINAL only) replace config field. Repeatable.', (val, prev = []) => [...prev, val])
+    .option('--mcp-server <server>', '(MCP only) new MCP server')
+    .option('--mcp-tool <tool>', '(MCP only) new MCP tool')
+    .option('--mcp-action-type <type>', '(MCP only) new MCP action type')
+    .option('--config <json>', 'Advanced: replace config with raw JSON')
+    .option('--json', 'Output raw JSON')
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+        if (opts.enabled && opts.disabled) throw new Error('Cannot combine --enabled and --disabled.');
+        if (opts.config && opts.field) throw new Error('Cannot combine --config with --field.');
+        if (opts.mcpTool && opts.mcpActionType) throw new Error('--mcp-tool and --mcp-action-type are mutually exclusive.');
+
+        const body = {};
+        if (opts.name !== undefined) body.name = opts.name;
+        if (opts.description !== undefined) body.description = opts.description;
+        if (opts.action) body.action = normalizeAction(opts.action, TOOL_ACTIONS, '--action');
+        if (opts.customMessage !== undefined) body.custom_message = opts.customMessage;
+        if (opts.enabled) body.enabled = true;
+        if (opts.disabled) body.enabled = false;
+
+        if (opts.commandFamily) body.command_family = opts.commandFamily;
+        if (opts.field) {
+          const cfg = {};
+          for (const spec of opts.field) {
+            const [k, v] = parseFieldSpec(spec);
+            cfg[k] = v;
+          }
+          body.config = cfg;
+        } else if (opts.config) {
+          body.config = parseJsonOrThrow(opts.config);
+        }
+
+        if (opts.mcpServer) body.mcp_server = opts.mcpServer;
+        if (opts.mcpTool) body.mcp_tool = opts.mcpTool;
+        if (opts.mcpActionType) {
+          const at = opts.mcpActionType.toLowerCase();
+          if (!MCP_ACTION_TYPES.includes(at)) {
+            throw new Error(`Invalid --mcp-action-type "${opts.mcpActionType}". Must be one of: ${MCP_ACTION_TYPES.join(', ')}`);
+          }
+          body.mcp_tool_action_type = at;
+        }
+
+        if (opts.group !== undefined) {
+          const formData = await loadFormData();
+          body.scope_user_group_ids = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+        }
+
+        if ((body.action === 'BLOCK' || body.action === 'WARN') && !body.custom_message && opts.customMessage === undefined) {
+          output.warn('Action changed to BLOCK/WARN without --custom-message. The existing custom_message will remain; pass --custom-message to replace it.');
+        }
+
+        const data = await api.put(`/api/v1/command-policies/${id}/`, { body });
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        output.success(`Tool policy ${id} updated.`);
+        displayToolPolicy(unwrapToolPolicy(data));
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('families')
+    .description('List terminal command families and the fields they accept.')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const data = await api.get('/api/v1/command-policies/metadata/families/');
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        const families = data.families || [];
+        if (families.length === 0) {
+          output.info('No command families available.');
+          return;
+        }
+        for (const f of families) {
+          console.log('');
+          output.info(f.name);
+          const fields = Array.isArray(f.fields) ? f.fields : Object.keys(f.fields || {});
+          if (fields.length === 0) {
+            console.log('  (no fields)');
+          } else {
+            for (const field of fields) {
+              const desc = (f.field_descriptions && f.field_descriptions[field]) || '';
+              console.log(`  ${field}${desc ? ` — ${desc}` : ''}`);
+            }
+          }
+          if (f.risk_level) console.log(`  risk: ${f.risk_level}`);
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  tool
+    .command('mcp-servers')
+    .description('List known MCP servers and their available tools.')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        requireLogin();
+        const data = await api.get('/api/v1/command-policies/metadata/mcp-servers/');
+        if (opts.json) {
+          output.json(data);
+          return;
+        }
+        const servers = data.mcp_servers || [];
+        if (servers.length === 0) {
+          output.info('No MCP servers known.');
+          return;
+        }
+        for (const s of servers) {
+          console.log('');
+          output.info(s.mcp_server);
+          const tools = s.tool_calls || [];
+          if (tools.length === 0) {
+            console.log('  (no tools)');
+          } else {
+            for (const t of tools) console.log(`  ${t}`);
+          }
+          if (s.tool_action_types && typeof s.tool_action_types === 'object' && Object.keys(s.tool_action_types).length > 0) {
+            console.log(`  action types: ${Object.keys(s.tool_action_types).join(', ')}`);
+          }
+        }
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+// ============================================================================
+// Backward-compatible generic create/update
+// ============================================================================
+
+function registerLegacy(policy) {
+  // Keep the old `policy create --type X --config JSON` and `policy update <id> --config JSON`
+  // working as an escape hatch for scripts and power users who already know the backend shape.
+
+  policy
+    .command('create')
+    .description('Create a Cost/Model/Security policy. Prefer `policy cost|model|security create` for type-specific flags.')
+    .requiredOption('--name <name>', 'Policy name (required)')
+    .requiredOption('--type <type>', 'Policy type: COST, MODEL, or SECURITY (required)')
+    .requiredOption('--config <json>', 'Policy configuration as a JSON string')
+    .option('--enabled', 'Enable the policy (default: true)', true)
+    .option('--no-enabled', 'Create the policy in disabled state')
+    .option('--scope-groups <ids>', 'Comma-separated user group IDs')
+    .option('--scope-tools <types>', 'Comma-separated tool types')
+    .option('--priority <n>', 'Priority (integer)', parseInt)
+    .addHelpText('after', `
+Advanced / power-user escape hatch. For guided flag-based creation prefer:
+  $ unbound policy cost create --help
+  $ unbound policy model create --help
+  $ unbound policy security create --help
+  $ unbound policy tool create-terminal --help    (TOOL policies go through this path)
+  $ unbound policy tool create-mcp --help
+
+Examples:
+  $ unbound policy create --name "Cost Limit" --type COST \\
+      --config '{"monthly_budget":1000}' --scope-groups 1,2
+
+Learn more: ${DOCS_POLICIES}
+`)
+    .action(async (opts) => {
+      try {
+        requireLogin();
+
+        const type = opts.type.toUpperCase();
+        if (!POLICY_TYPES.includes(type)) {
+          throw new Error(`Invalid --type "${opts.type}". Must be one of: ${POLICY_TYPES.join(', ')}. For tool policies, use \`unbound policy tool create-terminal\` or \`create-mcp\`.`);
+        }
+
+        const body = {
+          name: opts.name,
+          type,
+          config: parseJsonOrThrow(opts.config),
+          enabled: opts.enabled,
+        };
+
+        if (opts.scopeGroups) {
+          body.scope_user_group_ids = parseCommaSeparated(opts.scopeGroups).map(Number);
+        }
+        if (opts.scopeTools) {
+          body.scope_tool_types = parseCommaSeparated(opts.scopeTools);
+        }
+        if (opts.priority != null) body.priority = opts.priority;
+
+        const data = await api.post('/api/v1/policies/', { body });
+        output.success(`Policy "${opts.name}" created.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+
+  policy
+    .command('update <id>')
+    .description('Update a Cost/Model/Security policy via raw config. Prefer `policy cost|model|security update`.')
+    .option('--name <name>', 'New name')
+    .option('--config <json>', 'Replace config with raw JSON')
+    .option('--enabled', 'Enable')
+    .option('--no-enabled', 'Disable')
+    .option('--scope-groups <ids>', 'Comma-separated user group IDs')
+    .option('--scope-tools <types>', 'Comma-separated tool types')
+    .option('--priority <n>', 'Priority (integer)', parseInt)
+    .addHelpText('after', `
+Advanced escape hatch. Prefer the type-specific update subcommands.
+
+Examples:
+  $ unbound policy update 5 --name "New Name"
+  $ unbound policy update 5 --config '{"monthly_budget":2000}'
+  $ unbound policy update 5 --no-enabled
+
+Learn more: ${DOCS_POLICIES}
+`)
+    .action(async (id, opts) => {
+      try {
+        requireLogin();
+
+        const body = {};
+        if (opts.name !== undefined) body.name = opts.name;
+        if (opts.enabled !== undefined) body.enabled = opts.enabled;
+        if (opts.priority != null) body.priority = opts.priority;
+        if (opts.config) body.config = parseJsonOrThrow(opts.config);
+        if (opts.scopeGroups) body.scope_user_group_ids = parseCommaSeparated(opts.scopeGroups).map(Number);
+        if (opts.scopeTools) body.scope_tool_types = parseCommaSeparated(opts.scopeTools);
+
+        const data = await api.put(`/api/v1/policies/${id}/`, { body });
+        output.success(`Policy ${id} updated.`);
+        displayPolicy(data.policy);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+// ============================================================================
+// register(program)
+// ============================================================================
+
+function register(program) {
+  const policy = program
+    .command('policy')
+    .description('Manage policies. Four types: cost, model, security, tool.')
+    .addHelpText('after', `
+Unbound has four policy types. Each has its own subcommand for guided
+flag-based create/update. Tool policies live in a separate backend table
+and are reached via \`unbound policy tool\`.
+
+  cost      Monthly budget limits per user group.      ${DOCS_COST}
+  model     Control which AI models are available.     ${DOCS_MODEL}
+  security  Guardrails (PII, secrets), routing rules.  ${DOCS_SECURITY}
+  tool      Shell command and MCP tool controls.       ${DOCS_TOOL}
+
+Generic commands (Cost/Model/Security only):
+  list        List policies, optionally filtered by type
+  get <id>    Get policy details
+  delete <id> Delete a policy
+  form-data   Show reference data (user groups, models, guardrails, etc.)
+  effective   View effective policies for a user or group
+
+Examples:
+  $ unbound policy form-data                                      # see available names
+  $ unbound policy cost create --name "Eng Budget" --monthly-budget 1000 --group engg
+  $ unbound policy model create --name "No Opus" --all-models --excluded claude-3-opus
+  $ unbound policy security create --name "Block PII" --sub-type guardrails --guardrail PII:BLOCK
+  $ unbound policy tool create-terminal --name "Block rm -rf" --command-family filesystem \\
+      --field command='rm -rf*' --action BLOCK --custom-message "Blocked by policy"
+  $ unbound policy tool create-mcp --name "Audit Linear writes" \\
+      --mcp-server Linear --mcp-action-type write --action AUDIT
+
+Learn more: ${DOCS_POLICIES}
+`);
+
+  registerTopLevel(policy);
+  registerCost(policy);
+  registerModel(policy);
+  registerSecurity(policy);
+  registerTool(policy);
+  registerLegacy(policy);
 }
 
 module.exports = { register };