@gzl10/nexus-backend 0.20.0 → 1.0.0-alpha.0

package/claude-commands/nexus-catalog.md

@@ -0,0 +1,69 @@
+# Catalogar cambios en tabla supletoria `nexus` de Neural
+
+Detecta cambios recientes en SDK, backend modules, y UI composables que deban reflejarse en la tabla supletoria `nexus` de Neural (`nexus_upsert`). Actualiza registros existentes o crea nuevos.
+
+## Argumentos
+
+$ARGUMENTS — Opcional. Scope específico: `sdk`, `backend`, `ui`, `all`. Default: `all`.
+
+## Paso 1: Detectar cambios
+
+Comparar estado actual vs último commit/tag para identificar qué cambió:
+
+```bash
+# Si hay argumento de scope, filtrar por paquete
+# all → revisar los 3 paquetes
+git diff HEAD~5 --name-only -- packages/sdk/src/ packages/backend/src/modules/ packages/ui/src/composables/
+```
+
+Clasificar cada cambio detectado:
+
+| Cambio en... | Categoría nexus | Acción |
+|---|---|---|
+| `sdk/src/types/entity.ts` (entity types) | `entity_type` | Upsert definición |
+| `sdk/src/types/fields.ts` (field types) | `db_type` o `input_type` | Upsert tipo |
+| `sdk/src/fields/*.ts` (factories) | `field_factory` | Upsert factory |
+| `backend/src/modules/*/` (patterns) | `pattern` | Upsert pattern si es reutilizable |
+| `ui/src/composables/*.ts` | `pattern` | Upsert si es API pública para devs externos |
+
+## Paso 2: Consultar estado actual en Neural
+
+Para cada cambio detectado, buscar si ya existe en la tabla:
+
+```
+nexus_search(category: "...", query: "nombre")
+```
+
+Comparar el `summary` existente con el código actual. Si no hay cambios sustanciales, saltar.
+
+## Paso 3: Upsert en Neural
+
+Para cada registro nuevo o modificado, usar `nexus_upsert`.
+
+**Reglas de redacción del `summary`:**
+
+- Pensando en dos audiencias simultáneas:
+  1. **Dev de app** (usa nexus-backend + nexus-ui): qué es, cuándo usarlo, config mínima
+  2. **Dev de plugin** (crea nexus-plugin-*): cómo usarlo desde ctx, integración con engine, gotchas
+- Incluir: propósito, cuándo usar, config/parámetros principales, y advertencias
+- NO incluir código extenso — solo snippets mínimos si clarifican uso
+- Tags descriptivos para filtrado (ej: `crud`, `factory`, `hooks`, `auth`, `sdk`, `how-to`)
+
+## Paso 4: Reportar
+
+Mostrar resumen de cambios:
+
+| Acción | Categoría | Nombre | Motivo |
+|---|---|---|---|
+| created | field_factory | useMarkdownField | Nuevo factory añadido |
+| updated | pattern | EntityServiceHooks | Añadido hook beforeValidate |
+| skipped | entity_type | collection | Sin cambios |
+
+## Destinos de documentación (referencia)
+
+La tabla `nexus` alimenta estos tutoriales en Notion KB:
+
+- [Tutorial: App basada en Nexus](https://www.notion.so/3234fc3785408042be6bf648a2876c54)
+- [Tutorial: Plugin para Nexus](https://www.notion.so/3234fc37854080d9a5dece31975385d2)
+
+La sincronización Neural → Notion se hace con `/neural-sync-notion`, NO desde este command.

package/claude-commands/nexus-new-action.md

@@ -32,13 +32,13 @@ Find which module to add the action to:
 Create `src/modules/{module}/actions/{name}.action.ts`:
 
 ```typescript
-import type { ActionDefinition, ModuleContext, Request, Response } from '@gzl10/nexus-sdk'
-import { useTextField, useSelectField } from '@gzl10/nexus-sdk/fields'
+import type { ActionDefinition } from '@gzl10/nexus-sdk'
+import { useSelectField } from '@gzl10/nexus-sdk/fields'
 
 export const {camelName}Action: ActionDefinition = {
-  name: '{kebab-name}',
+  key: '{kebab-name}',
   label: { en: '{Label}', es: '{Etiqueta}' },
-  icon: '{icon}',
+  icon: 'mdi:{icon}',
   scope: '{scope}',       // 'module' | 'entity' | 'row'
   variant: 'primary',
 
@@ -53,14 +53,14 @@ export const {camelName}Action: ActionDefinition = {
     })
   },
 
-  // Handler
-  handler: (ctx: ModuleContext) => async (req: Request, res: Response) => {
-    const { format } = req.body
+  // 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
 
-    res.json({ success: true, message: 'Action completed' })
+    return { success: true, message: 'Action completed' }
   },
 
   casl: {
@@ -91,9 +91,14 @@ npx tsc --noEmit
 
 ## Gotchas
 
-- Actions use `handler: (ctx) => async (req, res) => {}` — factory pattern like hooks
-- `scope: 'row'` actions receive `req.params.id`
+- 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.

package/claude-commands/nexus-new-entity.md

@@ -129,7 +129,7 @@ definitions: [...existing, {name}Entity]
 ## Step 5: Run migration
 
 ```bash
-npx nexus migrate dev
+pnpm nexus migrate dev
 ```
 
 ## Gotchas

package/claude-commands/nexus-new-module.md

@@ -27,7 +27,7 @@ ls src/modules/
 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** — Ionicons 5 icon name (suggest based on category)
+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
@@ -41,7 +41,7 @@ import type { ModuleManifest } from '@gzl10/nexus-sdk'
 export const {name}Module: ModuleManifest = {
   name: '{name}',
   label: { en: '{Name}', es: '{Nombre}' },
-  icon: '{icon}',
+  icon: 'mdi:{icon}',
   category: '{category}',
   definitions: []
 }
@@ -65,7 +65,7 @@ Add the entity import and include it in `definitions[]`.
 ## Step 5: Verify
 
 ```bash
-npx tsc --noEmit
+pnpm typecheck
 ```
 
 ## Gotchas

package/claude-commands/nexus-new-plugin.md

@@ -100,13 +100,17 @@ export default defineConfig({
 ### src/index.ts
 
 ```typescript
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 import type { PluginManifest, ModuleManifest } from '@gzl10/nexus-sdk'
 import { {name}Entity } from './entities/{name}.js'
 
+const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf-8')) as { name: string; version: string }
+
 const {name}Module: ModuleManifest = {
   name: '{name}',
   label: { en: '{Name}', es: '{Nombre}' },
-  icon: '{icon}',
+  icon: 'mdi:{icon}',
   category: '{category}',
   definitions: [{name}Entity]
 }
@@ -114,11 +118,11 @@ const {name}Module: ModuleManifest = {
 export { {name}Module, {name}Entity }
 
 export const {name}Plugin: PluginManifest = {
-  name: '@{scope}/nexus-plugin-{name}',
+  name: pkg.name,
   code: '{code}',
   label: { en: '{Name}', es: '{Nombre}' },
-  icon: '{icon}',
-  version: '1.0.0',
+  icon: 'mdi:{icon}',
+  version: pkg.version,
   description: { en: '{description_en}', es: '{description_es}' },
   category: '{category}',
   modules: [{name}Module]
@@ -147,7 +151,8 @@ pnpm typecheck
 
 - `code` must be exactly 3 lowercase chars — validated by `registerPlugin()`
 - `export default` the PluginManifest (plugins use default export, modules use named)
+- **NEVER hardcode `name` or `version`** — read from `package.json` with `readFileSync`
 - `peerDependencies` on `@gzl10/nexus-sdk` — not direct dependency
 - `files: ["dist", "migrations"]` — include migrations dir even if empty initially
-- Plugin name in PluginManifest.name must match package.json name exactly
+- Icons use Iconify format: `mdi:bookmark`, `mdi:chart-bar`, etc.
 - Users install with `nexus plugin add`, not `pnpm add`

package/claude-commands/nexus-review-module.md

@@ -0,0 +1,220 @@
+# Nexus Module Review
+
+Analyzes a nexus-ui module page (screenshot or module name) and suggests improvements to EntityDefinition, fields, actions, and display modes based on backend metadata.
+
+## Arguments
+
+$ARGUMENTS — Module to review. Accepts:
+- A **screenshot** (user pastes image or provides path) — vision identifies the module
+- A **module name** (e.g. "contacts", "inventory") — skips screenshot analysis
+- Empty — ask the user for a screenshot or module name
+
+## Context detection
+
+Detect execution context by inspecting the working directory:
+
+| Check | Context | Metadata source |
+|-------|---------|-----------------|
+| `packages/backend/package.json` with `@gzl10/nexus-backend` | **Monorepo** | Read EntityDefinition from source files |
+| `package.json` has `@gzl10/nexus-backend` dep | **Project** | Read EntityDefinition from source files |
+| Neither | **Remote** | Fetch manifest from API (`GET /api/v1/system/manifest`) |
+
+For **Remote** mode, ask the user for the backend URL if not provided.
+
+## Step 1: Identify module
+
+### From screenshot
+
+Read the image with the Read tool. Extract:
+- **Module name**: from header, sidebar highlight, or breadcrumb
+- **Active entity tab**: which entity is currently displayed
+- **Display mode**: table, board, list, masonry, tree, calendar, timeline
+- **Visible columns/fields**: field names from table headers or card content
+- **Visible actions**: buttons in toolbar, row dropdown items
+- **Data state**: how many rows visible, empty columns, patterns in data
+- **UI issues**: anything visually off (truncation, overflow, empty space, alignment)
+
+### From module name
+
+If the user provides a name directly, skip vision and go to Step 2.
+
+## Step 2: Load entity metadata
+
+### Monorepo / Project mode (preferred)
+
+1. Find the module definition:
+   ```
+   Grep for: export const {moduleName}Module | name: '{moduleName}'
+   In: packages/backend/src/modules/ OR src/modules/ OR demos/*/src/modules/
+   Also check: plugins/*/src/index.ts (for plugin entities)
+   ```
+
+2. Read the module's `index.ts` — extract:
+   - All `EntityDefinition` objects (definitions array)
+   - All `ActionDefinition` objects (actions array + entity.actions)
+   - Module manifest metadata (label, icon, category)
+
+3. For each entity, catalog:
+   - **Fields**: name, input type, `db.type`, `meta.showInDisplay`, `meta.showInForm`, `meta.searchable`, `meta.sortable`
+   - **Display config**: `displayMode`, `availableDisplayModes`, `groupBy`, `groupableFields`, `calendarFrom/To`, `defaultSort`
+   - **CRUD flags**: `allowCreate`, `allowEdit`, `allowDelete`, `hidden`
+   - **Features**: `taggeable`, `attachable`, `realtime`, `refreshInterval`
+   - **Actions**: scope (module/entity/row), label, variant, disabled condition, batch
+   - **CASL**: subject, sensitiveFields, permissions wildcards
+
+### Remote mode (fallback)
+
+Fetch `GET {baseUrl}/api/v1/system/manifest` (no auth needed for public capabilities, but manifest needs auth).
+
+If auth needed:
+```bash
+nexus client login --url {baseUrl}
+nexus client fetch GET /api/v1/system/manifest
+```
+
+Parse the ManifestDTO — it contains the same metadata serialized via `toEntityDefinitionDTO`.
+
+## Step 3: Analyze and generate findings
+
+Cross-reference the visible UI (from screenshot) with entity metadata. If no screenshot, analyze metadata standalone for common issues.
+
+### Analysis categories
+
+Run through each category. Only report genuine findings, not noise.
+
+#### 3.1 Display mode fitness
+
+| Check | Finding |
+|-------|---------|
+| Entity has select/enum fields but no BoardDisplay available | Suggest adding to `availableDisplayModes` + `groupableFields` |
+| Entity has date/datetime fields but no CalendarDisplay | Suggest `calendarFrom`/`calendarTo` config |
+| Entity has `created_at` + temporal data but no TimelineDisplay | Suggest as available mode |
+| Entity type is tree/dag but default display is table | Suggest tree as default |
+| `availableDisplayModes` is restricted but useful modes are excluded | Suggest expanding |
+
+#### 3.2 Field visibility
+
+| Check | Finding |
+|-------|---------|
+| Field with `showInDisplay: true` (or default) but provides little value in tables (e.g., long text, JSON, description) | Suggest `showInDisplay: false` |
+| Field important for identification not shown in display (e.g., email, status, type) | Suggest `showInDisplay: true` |
+| Too many columns visible (>8 in table) — information overload | Suggest hiding less important ones |
+| Too few columns visible (<3) — table feels empty | Suggest showing more relevant fields |
+| `labelField` not set or points to a non-descriptive field | Suggest better `labelField` |
+| Password/secret field without `sensitiveFields` in CASL | Flag security issue |
+
+#### 3.3 Search and sort
+
+| Check | Finding |
+|-------|---------|
+| No `defaultSort` configured | Suggest by most recent (if timestamps) or alphabetical (if labelField) |
+| Fields that should be searchable but `searchable: false` | Suggest enabling |
+| Fields that should be sortable but `sortable: false` | Suggest enabling |
+| No fields marked as `searchable` | Suggest at least labelField + key identifier fields |
+
+#### 3.4 Actions review
+
+| Check | Finding |
+|-------|---------|
+| Row action that doesn't need the row ID (e.g., "Export all") | Suggest entity or module scope instead |
+| Entity/module action that logically operates on a single record | Suggest row scope |
+| Action without clear label or with generic label ("Execute", "Run") | Suggest descriptive label |
+| Batch-capable action not marked `batch: true` | Suggest enabling batch |
+| Destructive action without `variant: 'danger'` | Suggest adding danger variant |
+| Action with `ConfirmConfig` but confirm message is generic | Suggest specific message |
+| Many row actions (>4) — dropdown gets long | Suggest grouping or hiding less-used ones |
+
+#### 3.5 Entity configuration
+
+| Check | Finding |
+|-------|---------|
+| Collection without `timestamps: true` | Suggest adding (audit trail) |
+| Entity with delete but no `softDelete` for important data | Suggest soft delete |
+| Entity with `realtime: false` that would benefit from live updates | Suggest `'sync'` or `'live'` |
+| Entity suitable for tags but `taggeable` not set | Suggest enabling |
+| Entity with file references but `attachable` not set | Suggest enabling |
+| `expose: true` (default) for internal/auxiliary entities | Suggest `expose: false` or `hidden: true` |
+| Entity with only 1-2 records that should be `single` type | Suggest type change |
+
+#### 3.6 Screenshot-specific (only when screenshot provided)
+
+| Check | Finding |
+|-------|---------|
+| Empty columns visible in >70% of rows | Suggest `showInDisplay: false` or rethink field |
+| Data truncated in columns (ellipsis visible) | Suggest wider column or `showInDisplay: false` |
+| Actions visible that don't make sense in current context | Investigate scope mismatch |
+| Missing pagination or infinite scroll with many rows | Check pagination config |
+| No search bar visible for a collection with many records | Check toolbar rendering |
+| Inconsistent date formats | Check field input type |
+
+## Step 4: Present findings
+
+Group findings by priority and category:
+
+```markdown
+## Module Review: {moduleName}
+
+### Entity: {entityName} ({type})
+
+#### High impact
+- [display] {finding with specific suggestion and code change}
+- [fields] {finding}
+
+#### Medium impact
+- [actions] {finding}
+- [search] {finding}
+
+#### Low impact / Nice-to-have
+- [config] {finding}
+
+### Suggested changes
+
+For each high/medium finding, show the specific code change:
+
+**{entity}.fields.{field}:**
+```typescript
+// Current (inferred)
+meta: { showInDisplay: true }
+// Suggested
+meta: { showInDisplay: false }  // Long text, rarely useful in table view
+```
+```
+
+## Step 5: Apply changes (optional)
+
+After presenting findings, ask:
+
+```
+{N} findings found. Options:
+  [1] Apply high-impact changes (I'll edit the EntityDefinition files)
+  [2] Create work items in Plane for manual review
+  [3] Just the report, thanks
+```
+
+- **Option 1**: Edit the source files directly. Only for monorepo/project mode.
+- **Option 2**: Create work items using Plane tools (like neural-review).
+- **Option 3**: Done.
+
+For option 2, create a single work item with all findings:
+
+```
+mcp__neural__plane_work_item_create(
+  workspace_slug, project_id,
+  name: "review: {moduleName} module UI/DX improvements",
+  description_html: "{findings as HTML list}",
+  priority: "medium"
+)
+```
+
+Assign to the relevant module in Plane (`plane_module_add_work_items`).
+
+## Rules
+
+- **Do NOT change entity types** (collection to single, etc.) without explicit user approval
+- **Do NOT remove fields** — only suggest visibility changes
+- **Do NOT modify CASL permissions** — only flag security issues
+- **Do NOT touch migrations** — only EntityDefinition metadata
+- **Be specific**: every finding must include the exact field/action/config and the suggested change
+- **No false positives**: if unsure, skip. Quality over quantity
+- **Context matters**: a CRM module has different needs than an audit log. Adapt heuristics
+- **Multiple screenshots**: if the user provides more screenshots of the same module (different tabs, scroll positions), accumulate findings across all of them

package/claude-commands/nexus-test.md

@@ -0,0 +1,207 @@
+# Nexus Manual Tester
+
+Interactive testing via nexus-client against a running (or auto-started) backend.
+
+## Arguments
+
+$ARGUMENTS — What to test (e.g. "create a contact, verify it exists, delete it"). If empty, ask the user. If the user says "en la demo" or similar, use demo mode (see below).
+
+## Context detection
+
+Detect the execution context by inspecting the working directory:
+
+| Check | Context | CLI prefix | Notes |
+|-------|---------|-----------|-------|
+| `packages/backend/package.json` exists with `@gzl10/nexus-backend` | **Monorepo** | see below | Nexus monorepo development |
+| Otherwise | **Project** | `pnpm nexus` or `npx nexus` | External project using Nexus |
+
+**Monorepo sub-modes** (detected from $ARGUMENTS):
+
+| Mode | Trigger | CLI prefix | Target |
+|------|---------|-----------|--------|
+| **Core** (default) | No demo/plugin mention | `pnpm nexus` | `packages/backend` |
+| **Demo** | "en la demo", "demo", "demo-backend", or when testing plugins | `pnpm nexus:demo` | `demos/demo-backend` |
+
+**Project context:** Use `pnpm nexus` if `nexus` is in local devDependencies, otherwise `npx nexus`. Backend start command: whatever `scripts.dev` is in `package.json`.
+
+Throughout the steps below, `$CLI` refers to the resolved CLI prefix.
+
+## Plugin testing rule
+
+**In monorepo context:** Plugins MUST be tested in demo mode only (`pnpm nexus:demo` / `demos/demo-backend`). NEVER install or activate plugins in the core backend (`packages/backend`). If the user asks to test a plugin without mentioning "demo", auto-select demo mode and inform them.
+
+**In project context:** Plugins are tested directly (the project IS the app).
+
+Before testing a plugin:
+
+1. **Verify the plugin is installed and enabled:**
+   ```bash
+   $CLI plugin list
+   ```
+   If the plugin is not listed or not enabled, install/enable it first:
+   ```bash
+   $CLI plugin add <plugin-name>
+   $CLI plugin enable <plugin-name>
+   ```
+
+2. **Run pending migrations:**
+   ```bash
+   $CLI migrate deploy
+   ```
+
+3. Only then proceed with testing.
+
+## Step 0: Discover available endpoints
+
+Read the REST Client files to understand what endpoints and payloads are available:
+
+- **Monorepo core:** `packages/backend/requests/*.http`
+- **Monorepo demo:** `demos/demo-backend/requests/*.http` (if exists), plus core requests
+- **Monorepo plugins:** `plugins/*/requests/*.http`
+- **Project:** `requests/*.http` (if exists)
+
+Use these as reference for endpoint paths, expected payloads, and authentication patterns.
+
+## Step 1: Build (if needed) and ensure backend is running
+
+**Monorepo demo mode only:** Build core packages if dist directories are missing:
+
+```bash
+pnpm build --filter @gzl10/nexus-sdk --filter @gzl10/nexus-backend --filter @gzl10/nexus-client --filter @gzl10/nexus-ui
+```
+
+Check if the backend is reachable:
+
+```bash
+$CLI client health
+```
+
+If it fails (connection refused), start the backend in background **forcing JSON logs** so you can parse them reliably (sin códigos ANSI ni multilínea de pino-pretty):
+
+- **Monorepo core:** `cd packages/backend && LOG_FORMAT=json pnpm dev &`
+- **Monorepo demo:** `cd demos/demo-backend && LOG_FORMAT=json pnpm dev &`
+- **Project:** `LOG_FORMAT=json pnpm dev &` (from project root)
+
+`LOG_FORMAT=json` produce una línea JSON por evento — útil para grep/jq y para que la IA filtre logs sin parsear ANSI. Si el `.env` ya define `LOG_FORMAT`, el override del entorno tiene prioridad solo si no se exporta antes.
+
+Wait until `$CLI client health` succeeds (poll every 2s, max 30s).
+
+Record whether we started the backend (to shut it down at the end).
+
+## Step 2: Login
+
+```bash
+$CLI client login [email] [password]
+```
+
+- If credentials provided in $ARGUMENTS, use those
+- If not, defaults from .env (ADMIN_EMAIL / ADMIN_PASSWORD) are used automatically
+- If no defaults, ask the user
+
+Session is persisted via PAT in `~/.nexus/session.json` indexed by project path — no expiration, survives across commands, supports multiple projects.
+
+Confirm login succeeded (check output for user JSON).
+
+## Step 3: Execute operations
+
+Translate the user's instructions into nexus CLI calls:
+
+```bash
+$CLI client entity <module/entity> <action> [args]
+```
+
+Available commands:
+
+**Entity CRUD:**
+
+- `$CLI client entity <path> list` — list entities
+- `$CLI client entity <path> get <id>` — get by ID
+- `$CLI client entity <path> create '<json>'` — create
+- `$CLI client entity <path> update <id> '<json>'` — update
+- `$CLI client entity <path> delete <id>` — delete
+
+**Actions (module/entity/row):**
+
+- `$CLI client action <module> <key> ['<json>']` — module action (POST by default)
+- `$CLI client action <module> <key> <id> ['<json>']` — row action
+- `$CLI client action <module> <key> -m GET` — read action (e.g. sessions, list-tokens)
+
+**Generic HTTP (any endpoint):**
+
+- `$CLI client fetch <METHOD> <url> ['<json>']` — hit any endpoint
+- `$CLI client fetch GET /auth/me` — example read
+- `$CLI client fetch POST /mail/send '{"to":"x"}'` — example write
+- `$CLI client fetch GET /some/endpoint --pat <token>` — bypass session, use PAT directly
+
+**Storage:**
+
+- `$CLI client storage upload <file...> [--folder X] [--scope X] [--visibility public|internal|private]` — upload one or more files
+- `$CLI client storage download <id> [--output path]` — download file to disk (default: original filename in CWD)
+- `$CLI client storage list [--mimetype X] [--folder X] [--scope X] [--limit N]` — list storage files
+- `$CLI client storage delete <id>` — delete file by ID
+- `$CLI client storage stats` — storage statistics (total files, size, by type)
+
+**Other:**
+
+- `$CLI client health` — health check
+- `$CLI client login [email] [password]` — authenticate (creates PAT)
+- `$CLI client me` — current user info
+- `$CLI logs [--lines N] [--file path]` — tail backend log file in real time (requires LOG_FILE in .env)
+- `$CLI migrate list` — show migration status (alias for `migrate status`)
+
+**Command selection guide:**
+- **entity** — CRUD on entities (list, get, create, update, delete)
+- **action** — declared actions in modules/plugins (have a key, may need body or row id)
+- **storage** — file upload/download/list/delete/stats
+- **fetch** — anything else (custom routes, plugin endpoints, non-standard paths)
+
+Use `--debug` flag on any command for verbose HTTP logging.
+
+For each operation:
+1. Execute via `$CLI client`
+2. Capture and display the response
+3. Interpret whether it succeeded or failed
+
+## Step 4: Verify coherence with database
+
+After each write operation (create, update, delete), verify via db shell:
+
+```bash
+$CLI db shell <<< "SELECT * FROM <table> WHERE id = '<id>';"
+```
+
+Compare the API response with the raw database state:
+- **Create:** record exists in DB with correct values
+- **Update:** record reflects new values, updated_at changed
+- **Delete:** record no longer exists (or soft-deleted if applicable)
+
+Report discrepancies clearly.
+
+## Step 5: Logout and cleanup
+
+```bash
+$CLI client logout
+```
+
+This revokes the PAT server-side and removes the entry from `~/.nexus/session.json`.
+
+If we started the backend in Step 1, stop it:
+
+```bash
+kill %1  # or the recorded PID
+```
+
+## Step 6: Report
+
+Summarize:
+- Operations executed and their results
+- Database coherence: PASS / FAIL per operation
+- Any errors or unexpected behavior
+
+Format as a table:
+
+| # | Operation | API Result | DB Check | Status |
+|---|-----------|------------|----------|--------|
+| 1 | POST /contacts | 201 Created | Row exists | PASS |
+| 2 | PATCH /contacts/:id | 200 Updated | Values match | PASS |
+| 3 | DELETE /contacts/:id | 204 | Row gone | PASS |

package/claude-commands/nexus-update-tutorial-plugin.md

@@ -13,7 +13,7 @@ Read these files to understand the current state of the plugin API:
 1. `packages/sdk/AGENTS.md` — SDK reference and gotchas
 2. `packages/backend/AGENTS.md` — Backend reference, CLI, gotchas
 3. `demos/demo-plugin/` — plugin developer reference (all files)
-4. `plugins/tags/src/index.ts` — simplest real plugin
+4. `plugins/secrets/src/index.ts` — simplest real plugin
 5. `packages/sdk/src/types/manifest.ts` — PluginManifest interface (verify)
 6. `packages/sdk/src/types/entity.ts` — entity types (verify)
 7. `packages/backend/src/cli.ts` — CLI commands (verify plugin commands)

package/dist/{app-error-CKbYJQ9V.d.ts → app-error-DMO71vXw.d.ts}

@@ -38,6 +38,7 @@ declare const ErrorCodes: {
     readonly STORAGE_FILE_TOO_LARGE: "STORAGE_FILE_TOO_LARGE";
     readonly STORAGE_FILE_TYPE_NOT_ALLOWED: "STORAGE_FILE_TYPE_NOT_ALLOWED";
     readonly STORAGE_PAYLOAD_TOO_LARGE: "STORAGE_PAYLOAD_TOO_LARGE";
+    readonly STORAGE_ERROR: "STORAGE_ERROR";
     readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
     readonly RESOURCE_CONFLICT: "RESOURCE_CONFLICT";
     readonly RESOURCE_CREATE_NOT_SUPPORTED: "RESOURCE_CREATE_NOT_SUPPORTED";