@fleox-agent-crm/agentcrm 0.0.0-stage → 0.3.1

package/plugin/skills/agentcrm-admin/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: agentcrm-admin
+description: Run an AgentCRM like its admin does - find, list, create, update, delete, restore and merge records (companies, people, deals, custom objects), log notes, calls, emails and meetings, manage tasks, set contact photos / company logos and attach files (images, PDFs, documents) to records, notes and tasks, move deals through pipeline stages, edit the data model (custom objects and fields), saved views, users and roles, settings, turn modules on and off, change the appearance (brand color, logo, favicon, presets, themes, custom CSS), enable / disable installed extensions, import and export CSV / JSON, reports, automations and lead forms, and call the AI tool catalog. Use when the user wants to read or change data, features or the look of one of their AgentCRM CRMs.
+license: PolyForm-Noncommercial-1.0.0
+compatibility: Requires Node.js 20+.
+metadata:
+  version: "0.3.1"
+  repository: "https://github.com/fleox/agentcrm"
+allowed-tools: Bash Read Write
+---
+
+# Run an AgentCRM
+
+The CLI runs the admin's own engine headless: the same validation, roles and automations apply. It acts as the site's CLI user (an admin by default; `--as <email>` acts as another user).
+
+**Language:** talk to the user in their language; keep commands and files in English.
+
+Every command is `npx -y @fleox-agent-crm/agentcrm@0.3.1 <command> --json`; always pass `--site <alias>` (see `agentcrm-manage` to pick one). Read `error.hint` when `ok` is false. `npx -y @fleox-agent-crm/agentcrm@0.3.1 help records --json` lists any command's actions and options.
+
+## Rules
+
+- **Learn the model first:** `objects list`, then `objects get <object>` for field ids, types, select options and relations. Never guess field ids.
+- **Search before creating** (`records search`) to avoid duplicates.
+- **Destructive commands print a plan** (`needsConfirmation: true`) unless `--yes`: show the plan, ask, then re-run with `--yes`. This covers `records delete`, `records merge`, `files delete`, `objects delete`, `fields delete`, `views delete`, `import csv` (dry run by default), `compact`, `automations run`, `forms publish`, `forms ingest`, and every workspace-wide change: `modules enable|disable|config set`, `appearance set|preset|logo|favicon|css|reset`, `ext install|enable|disable|uninstall`.
+- Personal data: don't paste whole exports into the chat; summarise.
+
+## Records
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records list --site acme --object deals --filter stage:in:proposal,negotiation --filter amount:gte:10000 --sort amount:desc --limit 20 --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records get <id> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records search "globex" --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records create --site acme --object people --set firstName=Grace --set lastName=Hopper --set email=grace@globex.com --set company=<companyId> --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records update <id> --site acme --set jobTitle=CTO --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records delete <id> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records restore <id> --site acme --json
+```
+
+- Filters: `--filter field:op:value`, repeatable. Ops: eq, neq, contains, notContains, empty, notEmpty, gt, gte, lt, lte, in, notIn, before, after, withinDays. Dates: `YYYY-MM-DD`, `today`, `+30d`. Also `id`, `ownerId`, `createdAt`, `updatedAt`.
+- Values: `--set key=value` (numbers, true / false, null and JSON arrays are parsed; phone numbers and zip codes stay text) or `--fields '{"...": ...}'` / `--fields @file.json`. Select fields take the option id or label; relations take record ids (arrays for "many"); `null` clears.
+- `--columns name,email` trims the output; `--view <id>` applies a saved view; `--deleted` lists the trash.
+- Duplicates: `records duplicates --object people --by email,name`, then `records merge <primaryId> <dupId>...` (plan, then `--yes`). Merging fills empty fields and moves relations and activities.
+
+More examples per object: references/records.md.
+
+## Timeline and tasks
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 notes add <recordId> --site acme --body "Met at the expo; wants a demo in June." --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 activities add --site acme --type call --title "Discovery call" --record <personId> --record <dealId> --meta '{"durationMin":25}' --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 activities list --site acme --record <companyId> --related --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tasks add --site acme --title "Send the proposal" --due 2026-11-10 --assignee me --record <dealId> --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tasks list --site acme --assignee me --overdue --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tasks done <taskId> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tasks reassign <taskId> --site acme --assignee sam@acme.com --json
+```
+
+Activity types: note, task, call, email, meeting. `--body @notes.md` reads a file.
+
+## Images and attachments
+
+People have a **photo** (`avatar` field) and companies a **logo** (`logo`), shown next to the name everywhere; custom objects get one by adding an `image` field (the first becomes the object's image). Files (any type: images, PDFs, Office documents…) attach to a record or to an activity (note, task, call, email, meeting).
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records image <personId> ./ada.jpg --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records image <companyId> ./logo.svg --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records image <personId> --remove --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 notes add <recordId> --body "Signed contract attached." --attach ./contract.pdf --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tasks add --title "Review the quote" --record <dealId> --attach ./quote.xlsx --attach ./scope.pdf --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 activities add --type meeting --title "Workshop" --record <companyId> --attach ./whiteboard.png --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 files upload ./brochure.pdf ./photo.png --record <companyId> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 files upload ./minutes.docx --activity <noteId> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 files list --record <companyId> --related --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 files get <fileId> --out ./contract.pdf --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 files delete <fileId> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 files usage --site acme --json
+```
+
+- Files live next to the data and are **encrypted with the same passphrase** on the journal backend; IndexedDB in local mode; the data repo (`files/`) for git-json (warn: history keeps them); Firebase Storage for Firebase (Storage must be enabled, see docs/files.md).
+- Limit: 25 MB per file by default (`settings set --set maxUploadMb=50`). The admin resizes photos (2560 px) and makes thumbnails; the CLI uploads files as they are — resize big photos before uploading when you can.
+- `files list` returns metadata only (name, type, size, what it is attached to); `files get` writes the decrypted bytes to a local file — never paste file contents into the chat.
+- `files delete` is a soft delete (plan, then `--yes`): the file disappears from records and activities; `compact --yes` physically erases the bytes (also of files whose record / activity was purged) — GDPR erasure.
+- In Markdown bodies an image can be shown inline with `![name](file:<fileId>)` (upload it with `files upload --activity <id>` or `--attach` first).
+- AI tools: `list_files`, `describe_attachments` (metadata only; nothing fetches a URL into the CRM). Backups with files: `export zip --out backup.zip` / `import zip backup.zip` (plan, then `--yes`).
+
+## Pipelines
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 pipelines list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 pipelines move <dealId> Negotiation --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 pipelines move <dealId> Lost --lost-reason "Budget" --site acme --json
+```
+
+Moving sets the deal's probability to the stage's. Adding / renaming stages is done in the admin (Settings → Data model).
+
+## Data model, views, users, settings (admin role)
+
+See references/schema.md for objects, fields (types, options, relations), views, users and roles, and settings.
+
+## Modules: disable what you don't need
+
+Built-in modules: dashboard, deals (deals object + pipelines), reports, forms, tasks, automations, integrations (email and calendar), assistant (in-admin AI); records, search, settings, setup and customize are required. Installed extension modules are listed with `source: "extension"`. Disabling hides pages, navigation, widgets and owned objects for every user; it never deletes data, and enabling again brings everything back.
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 modules list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 modules disable forms --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 modules disable forms --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 modules enable deals --site acme --cascade --yes --json
+```
+
+- When the user says "we only manage contacts" or "hide what we don't use": list the modules, propose which to turn off (with what each hides), and apply only after they agree.
+- A `conflict` error lists the modules that depend on it (`error.message`); `--cascade` also disables them (enable: also enables the dependencies). Show the plan's `changed` list first.
+- Module configuration (JSON, used by extensions such as sales goals): `modules config get <id>` / `modules config set <id> --value '<json>'` (plan, then `--yes`). Never store secrets there.
+
+## Appearance: make it look like our brand
+
+One accent color drives the whole palette (a 50 to 950 scale is generated). Applies live to every user.
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance get --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance presets --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance set --site acme --accent "#0f766e" --neutral stone --radius lg --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance preset ocean --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance logo ./logo.svg --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance favicon ./favicon.png --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance css ./brand.css --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 appearance reset --site acme --json
+```
+
+- **Brand from a hex:** `appearance set --accent <hex>`, then pick `--neutral` by temperature (blue / teal brands: slate; warm brands: stone; otherwise zinc), `--buttons accent` for a colorful brand. **From a logo:** read the dominant non-gray color of the SVG (its `fill`) or the image, propose it as the accent, and upload the logo itself with `appearance logo`.
+- Options and values: references/appearance.md. Each change prints the before / after plan; apply with `--yes`.
+- Presets: default, ocean, forest, sunset, graphite, rose, high-contrast, plus installed theme extensions. A preset keeps the logo, favicon and custom CSS.
+
+## Extensions (installed modules and themes)
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 ext list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 ext disable sales-goals --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 ext enable sales-goals --site acme --yes --json
+```
+
+Installing, building or debugging extensions: the `agentcrm-extensions` skill. Installing runs third-party code with admin rights: always show the plan and ask. If the admin misbehaves after an extension change, `ext disable <id> --yes`, or open the admin with `?safe=1`; CLI commands accept `--safe` to skip extensions.
+
+## Import and export
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 import csv contacts.csv --site acme --object people --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 import csv contacts.csv --site acme --object people --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 export csv --site acme --object companies --out companies.csv --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 export json --site acme --out backup.json --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 export zip --site acme --out backup.zip --json
+```
+
+The import is a DRY RUN until `--yes`: read the report (mapping, per-row action, errors, new select options, companies to create) with the user before applying. Mapping, dedupe and coercion rules: references/import.md.
+
+## Reports and stats
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report pipeline --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report forecast --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report won-lost --site acme --months 6 --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report activity --site acme --days 30 --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report lead-sources --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report stale --site acme --days 21 --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 report conversion --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 stats --site acme --json
+```
+
+## Automations and lead forms
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 automations list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 automations disable <id> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 automations run --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 forms list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 forms publish <formId> --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 forms ingest --site acme --json
+```
+
+Event automations (record created, field changed, stage changed) fire on every write, from the CLI too. Building automations and forms is done in the admin; the CLI enables / disables, runs the scheduled ones and ingests form submissions. For a cron, see the `agentcrm-manage` skill.
+
+## AI tool catalog
+
+The same tools the MCP server and the in-admin assistant expose, including the tools of enabled extension modules (`source: "extension"`) the customisation tools (`list_modules`, `set_module_enabled`, `get_appearance`, `set_appearance`, `apply_appearance_preset`, `list_extensions`, `set_extension_enabled`) and the file tools (`list_files`, `describe_attachments`):
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tools list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 tools call pipeline_summary --site acme --input '{}' --json
+```
+
+Useful when a tool returns exactly what you need in one call (`get_record` with relations and latest activities, `pipeline_summary`).

package/plugin/skills/agentcrm-admin/references/appearance.md

@@ -0,0 +1,26 @@
+# Appearance options
+
+`appearance set` takes any subset; `"null"` resets one value to its default. Every change is workspace-wide (all users, applied live in open admins) and prints a plan (`data.plan.changes`: key → from / to) until `--yes`.
+
+| Option | Key | Values | Default |
+|---|---|---|---|
+| `--accent` | accent | any `#rrggbb` (a 50 to 950 scale is generated, 500 = this color) | `#3366ff` |
+| `--neutral` | neutral | zinc, slate, stone, gray, neutral | zinc |
+| `--radius` | radius | none, sm, md, lg, xl | md |
+| `--density` | density | compact (shorter rows and paddings), comfortable | comfortable |
+| `--font` | font | system (no network) or a Google font: inter, geist, roboto, open-sans, lato, source-sans-3, ibm-plex-sans, dm-sans, manrope, work-sans, plus-jakarta-sans, figtree, outfit, nunito-sans, poppins, space-grotesk | system |
+| `--sidebar` | sidebar | default, dark, accent | default |
+| `--mode` | defaultMode | system, light, dark (only for users who never toggled the mode themselves) | system |
+| `--buttons` | buttons | neutral (near-black), accent | neutral |
+| `--contrast` | contrast | normal, high | normal |
+| `--theme` | themeId | an installed, enabled theme extension id | none |
+
+Changing a visual value marks the preset `custom`. Other actions:
+
+- `appearance preset <id>`: default, ocean, forest, sunset, graphite, rose, high-contrast, or a theme extension id. Keeps logo, favicon, custom CSS and the default mode.
+- `appearance logo <file>` / `appearance favicon <file>`: PNG, JPEG, GIF, WebP, SVG or ICO, at most 200 KB (SVGs with scripts or event handlers are refused); `--remove` deletes it.
+- `appearance css <file|->`: plain CSS (no `<style>` / `<script>`), at most 50 KB, loaded last; `--remove` deletes it. Style through the CSS variables (`--acc-50` to `--acc-950`, `--srf-50` to `--srf-950`, `--primary`, `--radius-scale`, `--font-sans`, `--row-h`…) as `rgb(var(--acc-600))`.
+- `appearance reset`: back to defaults, keeping logo and favicon (`--branding` removes them too).
+- `appearance get --full` includes the logo / favicon data URLs and the custom CSS.
+
+Choosing a palette for a brand: keep the accent a mid-tone (very light accents make buttons hard to read); slate for cool brands, stone for warm ones; `--sidebar accent` only for strong brands; offer `--contrast high` when the user mentions accessibility.

package/plugin/skills/agentcrm-admin/references/import.md

@@ -0,0 +1,16 @@
+# CSV import
+
+1. Dry run (default): `import csv <file> --object <id> --site <alias> --json`.
+2. Read `data.mapping` (header to field id; `""` = skipped), `unmappedColumns`, `created` / `updated` / `skipped` / `failed`, `rows[]` (per row: action, id, messages), `newOptions` (select values that will be added), `createdRelated` (companies created from a company column).
+3. Fix the mapping if needed: `--map '{"E-mail":"email","Societe":"company","Source":"leadSource"}'` or `--map "E-mail=email,Societe=company"`. Special targets: `$id` (update by record id), `$owner` (owner by email or name), `""` (skip).
+4. Apply with `--yes`.
+
+## Rules
+
+- **Dedupe**: people by email, companies by domain, other objects by their label field. `--dedupe update` (default) fills the existing record, `skip` leaves it, `create` makes a new one anyway.
+- **Coercion**: numbers accept `1 200,50` and `$1,200.50`; dates accept ISO, `DD/MM/YYYY` with `--day-first`; booleans yes / no / true / false / 1 / 0; multi values split on `,` `;` `|`.
+- **Relations**: a `company` column with a name or domain links the person to that company, creating it when missing (`createdRelated`).
+- **Delimiter** is detected (`,` `;` tab); force it with `--delimiter ";"`.
+- Re-importing an `export csv` file updates the same records (its first column is the id).
+
+Show the user the counts and the errors before applying; never apply an import with unexplained errors.

package/plugin/skills/agentcrm-admin/references/records.md

@@ -0,0 +1,30 @@
+# Records by object
+
+Standard objects (always present; custom objects come on top):
+
+- `companies`: name, domain, industry (select), employees, annualRevenue (currency), address, linkedin, phone, tags.
+- `people`: firstName, lastName, name (computed), email (unique), phone, jobTitle, company (relation to companies), city, linkedin, lifecycleStage (subscriber, lead, mql, sql, opportunity, customer, evangelist), leadSource, tags.
+- `deals`: name, amount (currency), pipeline, stage, closeDate, probability, company (relation), contacts (relation to people, many), lostReason.
+
+Always confirm with `objects get <object>`: admins add fields and options.
+
+## Examples
+
+```bash
+# A company and its contact
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records create --site acme --object companies --set name="Globex" --set domain=globex.com --set industry=software --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records create --site acme --object people --fields @grace.json --json
+
+# A deal linked to both
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records create --site acme --object deals --fields '{"name":"Globex pilot","amount":12000,"closeDate":"2026-12-15","company":"<companyId>","contacts":["<personId>"]}' --json
+
+# Leads created this week, without an owner
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records list --site acme --object people --filter lifecycleStage:eq:lead --filter createdAt:withinDays:-7 --filter ownerId:empty --json
+
+# Assign an owner
+npx -y @fleox-agent-crm/agentcrm@0.3.1 records update <id> --site acme --owner <userId> --json
+```
+
+`records get` returns `relations` (records this one points to) and `related` (records pointing to it, e.g. a company's people and deals) plus `activityCount`.
+
+Soft delete keeps the record restorable (`records restore`) until `compact`; `--hard` removes at once (also asks for `--yes`).

package/plugin/skills/agentcrm-admin/references/schema.md

@@ -0,0 +1,59 @@
+# Data model, views, users, settings
+
+All schema commands need the admin role.
+
+## Objects
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 objects list --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 objects get deals --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 objects create --site acme --singular Project --plural Projects --icon folder --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 objects update projects --site acme --plural "Client projects" --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 objects delete projects --site acme --json
+```
+
+Deleting an object deletes all its records (plan first).
+
+## Fields
+
+Types: text, longText, number, currency, percent, date, datetime, boolean, select, multiSelect, email, phone, url, relation, user, rating, address, tags, image (one picture; the first one becomes the record avatar), files (attachments).
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 fields add --site acme --object deals --label "Contract type" --type select --options "New,Renewal,Upsell" --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 fields add --site acme --object projects --label Client --type relation --relation-object companies --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 fields update contractType --site acme --object deals --options "New,Renewal,Upsell,Cross-sell" --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 fields delete contractType --site acme --object deals --json
+```
+
+`fields update --type <t>` converts existing values (the result reports what could not be converted). Standard fields can't be deleted.
+
+## Views
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 views list --site acme --object deals --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 views create --site acme --object deals --name "Closing this month" --filter closeDate:withinDays:30 --sort closeDate --columns name,amount,stage,closeDate --shared --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 views create --site acme --object deals --name Board --type kanban --group-by stage --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 views delete <viewId> --site acme --json
+```
+
+## Users and roles
+
+Roles: `admin` (everything), `member` (records, activities, own views, import / export), `viewer` (read only).
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 users list --site acme --all --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 users add --site acme --email sam@acme.com --name "Sam Rivera" --role member --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 users role sam@acme.com admin --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 users disable sam@acme.com --site acme --json
+```
+
+Firebase / git-json sites: the login itself is created on that service (Firebase Authentication, a repository collaborator).
+
+## Settings
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 settings get --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 settings set --site acme --set name="Acme CRM" --set defaultCurrency=EUR --set locale=fr-FR --set staleDealDays=21 --json
+```
+
+Secrets are refused in settings.

package/plugin/skills/agentcrm-extensions/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: agentcrm-extensions
+description: Create, test and ship AgentCRM extensions - scaffold a module or theme project, write pages, record tabs, dashboard widgets, settings pages with module config, AI tools, automation actions and hooks against the @agent-crm/runtime API, validate the bundle exactly as the admin loads it, pack the ZIP and install / enable / disable / uninstall / export it on a CRM. Use when the user wants a new module or theme for AgentCRM, wants to change or debug one, or asks how AgentCRM extensions work.
+license: PolyForm-Noncommercial-1.0.0
+compatibility: Requires Node.js 20+ (npm for the extension project's own build).
+metadata:
+  version: "0.3.1"
+  repository: "https://github.com/fleox/agentcrm"
+allowed-tools: Bash Read Write Edit
+---
+
+# Build AgentCRM modules and themes
+
+**Language:** talk to the user in their language; code, comments, files and these instructions stay in English. Ship UI strings in English and French (`i18n: { en, fr }`).
+
+## How AgentCRM runs extensions (read this first)
+
+AgentCRM is a static CRM: the admin is a single-page app that runs in the browser, the CLI / MCP server run the same engine in Node. There is no server. An extension is **one ES module** (`bundle.js`) plus `manifest.json` (and an optional `style.css`), packed in a ZIP:
+
+- Installing stores the package **in the CRM's own data** (collection `extensions`, encrypted with the rest, shared by every user). No hosting, no rebuild.
+- When the admin starts (and when an extension is installed / enabled / upgraded, live), it `import()`s every enabled `bundle.js` and reads its **default export**: `defineModule({...})` or `defineTheme({...})`.
+- The bundle gets React, react-dom, react-i18next, lucide-react and the CRM API (`@agent-crm/runtime`) from the admin. These must stay **external** at build time (the scaffold's `vite.config.ts` does it). Any other import must be bundled in.
+- **Modules** add a Feature (routes + navigation, slots: record tabs / panels / actions, dashboard widgets, settings sections, overlays), a settings page (Settings, Modules, the module), AI tools (MCP, in-admin assistant, `agentcrm tools`), automation actions (automation editor) and hooks on CRM actions (`register(api)`). The module id is also its i18n namespace and its module-config key.
+- **Themes** are a set of appearance values (accent, neutral, radius, density, font, sidebar, buttons, contrast, default mode) plus optional CSS. They show up as presets in Settings, Appearance.
+- The CLI loads the same enabled modules in every session: their AI tools appear in `tools list` and the MCP server, their hooks see CLI writes, their automation actions run in `automations run`. `--safe` skips them.
+
+## Safety rules (always)
+
+- **Installing runs code with admin rights.** The bundle runs in the admin of every user who opens the CRM (admins included) and in CLI / MCP sessions. Before `ext install … --yes`, show the user the plan (id, version, author, upgrade or not, size, dependencies) and get an explicit yes. Never install a ZIP from an unknown source without saying so.
+- Every write in this skill prints a plan unless `--yes`: `ext install`, `ext enable`, `ext disable`, `ext uninstall`, `modules enable|disable|config set`, `appearance …`. Show the plan, ask, then re-run with `--yes`.
+- Never put secrets (API keys, tokens, passwords) in module config or in the bundle: they would be readable by every CRM user. `modules config set` refuses well-known secret keys.
+- If an extension breaks the admin: `ext disable <id> --yes` from the CLI, or open the admin with `?safe=1` (or hold Shift while it loads) to start without extensions.
+
+## The toolchain: `agentcrm ext`
+
+Every command is `npx -y @fleox-agent-crm/agentcrm@0.3.1 <command> … --json`. Read `error.hint` when `ok` is false.
+
+| Action | What it does |
+|---|---|
+| `ext new module\|theme <id> [--dir <path>] [--name "…"] [--description "…"] [--author "…"] [--force]` | Scaffolds a standalone project: `package.json` (scripts build / typecheck / check / pack), `vite.config.ts` (runtime specifiers external, one `bundle.js`), `tsconfig.json` mapped to `types/agentcrm-runtime.d.ts` (copied from the CLI), `manifest.json`, `src/index.tsx` (module: a page with a nav entry, a record tab, an AI tool, en + fr strings) or `src/index.ts` + `src/style.css` (theme), README. |
+| `ext check [<dir\|zip>] [--kind module\|theme] [--no-call]` | Validates manifest (id, kind, semver, apiVersion range, unknown keys), sizes, bundle imports (runtime specifiers only), default export, production JSX; then installs it in a throw-away demo CRM, loads it through the real loader and reports what it registers: routes, navigation, slots, settings page, i18n, AI tools (each one without required inputs is called once with `{}` on demo data), automation actions, hooks, theme values. Exit code 1 when `data.valid` is false. |
+| `ext pack [<dir>] [--out <zip>]` | Writes `<id>-<version>.zip` (manifest.json + bundle.js + style.css) for Settings, Modules, Install, or `ext install`. |
+| `ext install <zip\|dir> --site <alias> [--disabled] [--force] [--yes]` | First loads the bundle in a throw-away CRM like `ext check` (a package that fails is refused with `invalid-package` and nothing changes; `--force` skips this). Plan (install or upgrade, author, size, dependencies, warnings: downgrade, same version), then installs and loads it in the session (`load.status` must be `loaded`). Upgrades keep the enabled state and the module config. |
+| `ext list --site <alias>` | Installed extensions with version, enabled state and load status. |
+| `ext enable\|disable <id> --site <alias> [--cascade] [--yes]` | Switch it on or off without uninstalling. |
+| `ext uninstall <id> --site <alias> [--force] [--yes]` | Remove it (its module config is kept for a later re-install). |
+| `ext export <id> --site <alias> [--out <zip>]` | Download the installed package as a ZIP. |
+
+## Workflow
+
+1. **Understand the request.** A new look = a **theme**. New pages, widgets, record tabs, AI tools, automation steps or reactions to CRM events = a **module**. Pick an id: lowercase letters, digits and dashes, 3 to 50 characters, not a built-in module id (records, deals, dashboard, reports, forms, tasks, automations, integrations, assistant, search, settings, setup, customize) nor agentcrm, core, runtime, admin, app, custom, default. Prefix it with the company or product (`acme-quotes`).
+2. **Scaffold and install the toolchain:**
+   ```bash
+   npx -y @fleox-agent-crm/agentcrm@0.3.1 ext new module acme-quotes --author "Acme" --json
+   cd acme-quotes && npm install
+   ```
+3. **Read the scaffold**, then the reference for what you are building:
+   - [references/module-recipes.md](references/module-recipes.md): custom object + page, record tab, dashboard widget, AI tool, automation action, settings page with module config, hooks.
+   - [references/theme-recipes.md](references/theme-recipes.md): appearance values, CSS variables, brand themes.
+   - [references/runtime-api.md](references/runtime-api.md): everything `@agent-crm/runtime` exports. The authoritative signatures are in the project's `types/agentcrm-runtime.d.ts`.
+   - [references/testing.md](references/testing.md): build, check, pack, install, upgrade, debug, pitfalls.
+4. **Implement**, keeping the scaffold's build settings.
+5. **Verify after every meaningful change:**
+   ```bash
+   npm run typecheck
+   npm run build
+   npx -y @fleox-agent-crm/agentcrm@0.3.1 ext check . --json
+   ```
+   Fix every error; read the warnings (missing French strings, tool names without the module prefix, nav entries without a route).
+6. **Pack and install** (plan first, then `--yes` once the user agreed):
+   ```bash
+   npx -y @fleox-agent-crm/agentcrm@0.3.1 ext pack . --json
+   npx -y @fleox-agent-crm/agentcrm@0.3.1 ext install . --site acme --json
+   npx -y @fleox-agent-crm/agentcrm@0.3.1 ext install . --site acme --yes --json
+   npx -y @fleox-agent-crm/agentcrm@0.3.1 tools list --site acme --json
+   ```
+   For a new release, bump `version` in `manifest.json` (semver) and install again: it upgrades in place.
+
+## Golden rules
+
+- Import UI, data and helpers from `@agent-crm/runtime`, React from `react`, translations from `react-i18next`, icons from `lucide-react`. Never bundle a second React.
+- The default export's `id` and `apiVersion` must equal `manifest.json`'s.
+- All writes go through `ops.*` with the right context: `useOps()` in components, the `ctx` argument in AI tools, automation actions and hooks. Roles are enforced there (viewers can't write, only admins change modules / schema).
+- Prefix AI tool names with the module id in snake_case (`acme_quotes_list`), describe them so a model knows when to call them, set `mutating` honestly.
+- Automation action ids are `<moduleId>.<action>`.
+- `register(api)` must only register things (hooks, tools); never write data there. Hooks run in the process that made the change (the user's admin tab, or the CLI): keep them fast and idempotent.
+- Strings through `t("<moduleId>:key")` with `useTranslation("<moduleId>")`; ship `en` and `fr`.
+- Every `<form>` has `data-form-type="other"`.
+- Keep the bundle small (limit 1.5 MB, style.css 256 KB, ZIP 4 MB).
+
+## Without writing code
+
+Many requests need no extension at all: turning built-in modules off, changing the look, logo and colors, custom objects and fields. Use the `agentcrm-admin` skill (`modules`, `appearance`, `objects`, `fields`) first, and only build an extension when the CRM can't do it out of the box.

package/plugin/skills/agentcrm-extensions/references/module-recipes.md

@@ -0,0 +1,213 @@
+# Module recipes
+
+Every recipe is a fragment of `src/index.tsx` in a project made by `ext new module <id>`. They combine freely in one `defineModule({...})`. The module id (`ID` below) is also the i18n namespace (`t("<id>:key")`) and the module-config key.
+
+```tsx
+import { useTranslation } from "react-i18next";
+import { FolderKanban } from "lucide-react";
+import { defineModule, ops, type OpsContext, type ObjectDef } from "@agent-crm/runtime";
+
+const ID = "acme-projects";
+export default defineModule({
+  id: ID,
+  apiVersion: "1.0.0", // = manifest.json apiVersion
+  feature: { routes: [], navItems: [], i18n: { en, fr }, slots: {} },
+  settingsPage: SettingsPage,
+  aiTools: [],
+  automationActions: [],
+  register(api) { /* hooks */ },
+});
+```
+
+## 1. Custom object + its own page
+
+Objects are data, not code: create them once (an AI tool or a settings-page button), never in `register()`. The admin then lists them in the navigation with table / kanban views like any object. Add a page of your own for a dedicated view.
+
+```tsx
+// Typed views of ops that are not in RuntimeOps' typed subset.
+const createObject = ops.createObject as (ctx: OpsContext, input: {
+  id?: string; labelSingular: string; labelPlural: string; icon?: string; color?: string;
+  fields?: { id?: string; label: string; type: string; options?: string[]; relation?: { object: string; cardinality: "one" | "many" } }[];
+}) => Promise<ObjectDef>;
+
+async function ensureProjects(ctx: OpsContext): Promise<{ created: boolean }> {
+  if (ops.listObjects(ctx).some((o) => o.id === "projects")) return { created: false };
+  await createObject(ctx, {
+    id: "projects", labelSingular: "Project", labelPlural: "Projects", icon: "FolderKanban", color: "violet",
+    fields: [
+      { id: "status", label: "Status", type: "select", options: ["Planned", "Active", "Done"] },
+      { id: "client", label: "Client", type: "relation", relation: { object: "companies", cardinality: "one" } },
+      { id: "budget", label: "Budget", type: "currency" },
+    ],
+  });
+  return { created: true };
+}
+
+function ProjectsPage() {
+  const { t } = useTranslation(ID);
+  const projects = useRecords("projects");
+  const project = useObject("projects");
+  if (!project) return <EmptyState title={t("noObject")} description={t("noObjectHint")} />;
+  return (
+    <div>
+      <PageHeader title={t("title")} icon={<FolderKanban />} actions={<Link to={paths.objectList("projects")}>{t("openTable")}</Link>} />
+      <div className="grid gap-4 p-6 md:grid-cols-3">
+        {["planned", "active", "done"].map((status) => (
+          <Card key={status} title={t(`status.${status}`)}>
+            {projects.filter((r) => r.fields.status === status).map((r) => (
+              <Link key={r.id} to={paths.record("projects", r.id)} className="block py-1 text-sm">{recordLabel(project, r)}</Link>
+            ))}
+          </Card>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// feature:
+//   routes: [{ path: "/acme-projects", element: <ProjectsPage /> }],
+//   navItems: [{ id: ID, label: `${ID}:nav`, icon: FolderKanban, to: "/acme-projects", section: "workspace", order: 40 }],
+// aiTools: [{ name: "acme_projects_setup", description: "Creates the Projects object (status, client, budget) if it is missing.",
+//   inputSchema: { type: "object", properties: {} }, mutating: true, handler: (ctx) => ensureProjects(ctx) }],
+```
+
+- Select option ids are generated from the labels (`"Planned"` → `planned`); read `ops.listObjects(ctx)` for the exact ids.
+- Creating objects needs an admin (`schema.write`). From the CLI: `agentcrm tools call acme_projects_setup --site <alias> --input '{}'`.
+- Routes are paths of the admin's hash router (`#/acme-projects`). Use `paths.*` and `recordHref()` for links.
+
+## 2. Record tab, panel and action
+
+```tsx
+function InvoicesTab({ record, object }: RecordSlotProps) {
+  const { t } = useTranslation(ID);
+  const activities = useActivities(record.id);
+  return <div className="p-4 text-sm">{t("tabBody", { label: recordLabel(object, record), count: activities.length })}</div>;
+}
+
+// feature.slots:
+//   recordDetailTabs: [{ id: "invoices", label: `${ID}:tab`, icon: Receipt, order: 60, component: InvoicesTab, when: (o) => o.id === "companies" }],
+//   recordDetailPanels: [{ id: "health", order: 10, component: HealthPanel, when: (o) => o.id === "deals" }],
+//   recordActions: [{ id: "sync", label: `${ID}:sync`, icon: RefreshCw, onSelect: ({ record }) => toast.info(record.id) }],
+```
+
+`when(object)` limits a slot to some objects. Labels are i18n keys (`<id>:key`) or plain text.
+
+## 3. Dashboard widget
+
+```tsx
+function OpenDealsWidget() {
+  const { t } = useTranslation(ID);
+  const settings = useSettings();
+  const deals = useRecords("deals");
+  const enabled = useModuleEnabled("deals");
+  if (!enabled) return null; // the deals module can be switched off
+  const open = deals.filter((d) => !["won", "lost"].includes(String(d.fields.stage)));
+  const total = open.reduce((n, d) => n + Number(d.fields.amount ?? 0), 0);
+  return <Card title={t("widget")}><div className="text-2xl font-semibold tabular-nums">{formatCurrency(total, settings.defaultCurrency, intlLocale())}</div></Card>;
+}
+// feature.slots.dashboardWidgets: [{ id: "open-deals", order: 20, span: 4, component: OpenDealsWidget }]  // span 4 | 6 | 8 | 12
+```
+
+If the widget needs deals, declare `"dependsOn": ["deals"]` in `manifest.json`: the module can't be enabled while deals is off, and disabling deals asks to disable it too.
+
+## 4. AI tool
+
+```ts
+aiTools: [{
+  name: "acme_projects_at_risk",            // snake_case, prefixed, unique
+  description: "Active projects whose budget is above 80 000 or that have no activity for 30 days. Use to answer questions about project risk.",
+  inputSchema: { type: "object", properties: { days: { type: "number", description: "Inactivity threshold in days (default 30)." } } },
+  mutating: false,                          // true when it writes: MCP read-only mode hides it, the CLI takes the site lock
+  handler: (ctx, input) => {
+    const days = typeof input.days === "number" ? input.days : 30;
+    const page = ops.listRecords(ctx, "projects", { filters: [{ field: "status", op: "eq", value: "active" }], limit: 500 });
+    return { projects: page.items.filter((r) => Number(r.fields.budget ?? 0) > 80000 || ctx.now() - r.updatedAt > days * 86400000).map((r) => ({ id: r.id, name: r.fields.name })) };
+  },
+}],
+```
+
+Return plain JSON (small: the model reads it). Throw an `Error` with a clear message on bad input. The tool is in `agentcrm tools list`, `agentcrm tools call`, the MCP server's `tools/list` and the in-admin assistant as soon as the module is enabled.
+
+## 5. Automation action
+
+```ts
+const notifySlack: AutomationActionDef = {
+  id: `${ID}.flagRisk`,                     // "<moduleId>.<action>"
+  label: `${ID}:action.label`,
+  description: `${ID}:action.description`,
+  objects: ["projects"],                    // optional: only offered on these objects
+  params: [{ id: "note", label: `${ID}:action.note`, type: "text", template: true, placeholder: "{{name}} is at risk" }],
+  describe: ({ record }) => `Flag "${String(record.fields.name ?? record.id)}" as at risk`,
+  validate: (params) => (typeof params.note === "string" && params.note.length > 500 ? ["The note is too long."] : []),
+  async run(ctx, { params, record }) {
+    await ops.addNote(ctx, { object: record.object, id: record.id }, String(params.note || "At risk"), "Risk flag");
+    return "note added";                    // shown in the automation run log
+  },
+};
+// defineModule({ automationActions: [notifySlack], … })
+```
+
+The automation editor lists it next to the built-in actions; stored as `{ type: "extension", action: "acme-projects.flagRisk", params }`. It runs wherever automations run: in the admin on each write, and in `agentcrm automations run` (scheduled / inactivity triggers) because the CLI loads enabled modules. If the module is disabled, runs fail with "not available" (nothing else breaks).
+
+## 6. Settings page with module config
+
+Module config is a JSON document per module (`config/modules.config.<id>`, at most 256 KB, never secrets), shared by all users, written by admins.
+
+```tsx
+interface Config { budgetAlert: number }
+const readConfig = (raw: unknown): Config => ({ budgetAlert: Number((raw as Partial<Config> | undefined)?.budgetAlert ?? 80000) });
+
+function SettingsPage() {
+  const { t } = useTranslation(ID);
+  const ctx = useOps();
+  const canEdit = useCan("modules.write");
+  const config = readConfig(useModuleConfig(ID));
+  const [value, setValue] = useState(String(config.budgetAlert));
+  return (
+    <Card>
+      <form data-form-type="other" className="space-y-3" onSubmit={async (e) => {
+        e.preventDefault();
+        await ops.setModuleConfig(ctx, ID, { ...config, budgetAlert: Number(value) });
+        toast.success(t("saved"));
+      }}>
+        <FormField label={t("budgetAlert")}><Input type="number" value={value} disabled={!canEdit} onChange={(e) => setValue(e.target.value)} /></FormField>
+        {canEdit && <Button type="submit" variant="primary">{t("save")}</Button>}
+      </form>
+    </Card>
+  );
+}
+// defineModule({ settingsPage: SettingsPage, … })  → Settings → Modules → <module> → /settings/modules/<id>
+```
+
+In AI tools / actions read it with `readConfig(ops.getModuleConfig(ctx, ID))`. From the CLI:
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.1 modules config get acme-projects --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.1 modules config set acme-projects --value '{"budgetAlert":50000}' --site acme --json
+```
+
+(the second prints a plan; add `--yes`).
+
+## 7. Hooks on CRM actions
+
+```ts
+register(api) {
+  api.addAction("stage.changed", async (ctx, { record, to }) => {
+    if (record.object !== "deals" || to !== "won") return;
+    await ops.createTask(ctx as OpsContext, { title: `Kick-off for ${String(record.fields.name)}`, dueAt: ctx.now() + 3 * 86400000, targets: [{ object: "deals", id: record.id }] });
+  });
+  api.addFilter("myModule.value", (v: number) => v * 2);
+}
+```
+
+Actions: `record.created`, `record.updated` (`before`, `changed`), `record.deleted` (`hard`), `record.restored`, `stage.changed` (`pipelineId`, `from`, `to`), `activity.created`, `activity.updated`, `activity.completed`. The first argument is the context of the op that fired it (same user, same store). Everything registered through `api` is removed when the module is disabled or upgraded. A failing handler is logged and never blocks the write.
+
+## 8. Strings (en + fr)
+
+```ts
+const en = { nav: "Projects", title: "Projects board", status: { planned: "Planned", active: "Active", done: "Done" } };
+const fr: typeof en = { nav: "Projets", title: "Tableau des projets", status: { planned: "Prévu", active: "En cours", done: "Terminé" } };
+// feature.i18n: { en, fr }   (or addBundles(ID, { en, fr }) at the top level)
+```
+
+`const { t } = useTranslation(ID)` in components; labels in nav items, slots and automation actions are keys like `` `${ID}:nav` ``.