# Create a new Nexus module

Scaffold a new module in the current project. Modules are auto-discovered from `src/modules/`.

## Arguments

$ARGUMENTS — Module name (e.g. "inventory", "crm", "blog"). Lowercase, no spaces.

## Step 1: Detect project structure

Find the modules directory:

```
src/modules/          # standard location
```

If not found, ask the user where modules live.

Check existing modules to avoid name collisions:

```bash
ls src/modules/
```

## Step 2: Ask for details

Ask the user (if not provided in arguments):

1. **Category** — one of: content, data, assets, messaging, jobs, ai, analytics, integrations, commerce, security, legal, settings
2. **Icon** — Iconify icon name with `mdi:` prefix (e.g. `mdi:cart`, `mdi:chart-bar`). Suggest based on category
3. **Initial entity?** — yes/no. If yes, ask type: collection, single, or tree

## Step 3: Generate module

Create `src/modules/{name}/index.ts`:

```typescript
import type { ModuleManifest } from '@gzl10/nexus-sdk'
// import entities here

export const {name}Module: ModuleManifest = {
  name: '{name}',
  label: { en: '{Name}', es: '{Nombre}' },
  icon: 'mdi:{icon}',
  category: '{category}',
  definitions: []
}
```

**Conventions (CRITICAL):**
- Named export: `export const {name}Module` — NOT `export default`
- Category must be one of the 12 valid values — NO 'custom'
- definitions[] array for entities — they auto-mount, no manual routes

## Step 4: Generate initial entity (if requested)

Use the same patterns as `/nexus-new-entity` but inline here:

- **collection**: `table`, `labelField`, field factories from `@gzl10/nexus-sdk/fields`, `casl`
- **single**: `key` (not table), `defaults`
- **tree**: `table`, `seed: []`, parent_id auto-injected

Add the entity import and include it in `definitions[]`.

## Step 5: Verify

```bash
pnpm typecheck
```

## Gotchas

- Entities use `table` (collection/tree) or `key` (single), NOT `name`
- Field `required` is top-level in factory config, NOT inside `validation`
- `useSelectField` options is a direct array `[{value, label}]`, NOT `{static: [...]}`
- Tree entities require `seed` (can be empty `[]`)
- Hooks pattern: `hooks: (ctx) => ({ beforeCreate: async (data) => { return data } })`
- Individual hooks do NOT receive ctx — only the wrapper function does