# Create a new Nexus standalone action

Add a standalone action to a module. Actions are operations without dedicated persistence (send email, export, batch process).

## Arguments

$ARGUMENTS — Action name (e.g. "export-csv", "send-report", "sync-data"). Kebab-case.

## Step 1: Detect context

Find which module to add the action to:

1. Check current directory — if inside `src/modules/{name}/`, use that module
2. Otherwise, list available modules and ask

## Step 2: Ask for details

1. **Scope** — where does the action button appear?
   - `module` — button in the module toolbar (no entity context)
   - `entity` — button in entity list toolbar (entity context, no specific row)
   - `row` — dropdown per row (receives `:id` param)

2. **Input fields** — does the action need a form before executing? (optional)
3. **Output** — what to show after execution?
   - No output (just success notification)
   - Structured output (modal with fields)
   - Page redirect
4. **Variant** — button style: `default`, `primary`, `danger`

## Step 3: Generate action file

Create `src/modules/{module}/actions/{name}.action.ts`:

```typescript
import type { ActionDefinition } from '@gzl10/nexus-sdk'
import { useSelectField } from '@gzl10/nexus-sdk/fields'

export const {camelName}Action: ActionDefinition = {
  key: '{kebab-name}',
  label: { en: '{Label}', es: '{Etiqueta}' },
  icon: 'mdi:{icon}',
  scope: '{scope}',       // 'module' | 'entity' | 'row'
  variant: 'primary',

  // Input form (optional — omit if no form needed)
  input: {
    format: useSelectField({
      label: { en: 'Format', es: 'Formato' },
      options: [
        { value: 'csv', label: 'CSV' },
        { value: 'json', label: 'JSON' }
      ]
    })
  },

  // Handler — signature: (ctx, input, req?, res?) => Promise<unknown>
  handler: async (ctx, input) => {
    const { format } = input as { format: string }

    // Action logic here
    // Use ctx.db, ctx.services, ctx.logger, ctx.errors

    return { success: true, message: 'Action completed' }
  },

  casl: {
    subject: '{Subject}',
    permissions: {
      ADMIN: { actions: ['execute'] }
    }
  }
}
```

## Step 4: Update module manifest

Read the module's `index.ts`, add the import, and include in `actions[]`:

```typescript
import { {camelName}Action } from './actions/{name}.action.js'

// Add to manifest
actions: [...existing, {camelName}Action]
```

## Step 5: Verify

```bash
npx tsc --noEmit
```

## Gotchas

- Handler signature: `handler: async (ctx, input, c?) => {}` — direct function, NOT factory pattern. `c` is the Hono `Context`.
- Hooks use factory pattern `(ctx) => ({...})`, but action handlers do NOT
- `key` is the route identifier (NOT `name`)
- `scope: 'row'` actions receive the entity id via `c.req.param('id')` if `c` is needed
- `input` defines the form shown before execution (Record<string, FieldDefinition>)
- `output: {}` shows raw JSON result, `output` with fields shows structured modal
- `batch: true` + `timeout: number` for batch processing with SSE progress
- `disabled` accepts `FieldCondition` for per-row client-side evaluation
- `hidden: true` makes the action API-only (not shown in UI)
- `inputSchema` accepts a Zod schema for server-side validation
- Icons use Iconify format: `mdi:play`, `mdi:export`, etc.
