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

package/plugin/skills/agentcrm-extensions/references/runtime-api.md

@@ -0,0 +1,41 @@
+# `@agent-crm/runtime` at a glance
+
+The full reference with every signature is `docs/runtime-api-reference.md` in the AgentCRM repository; the authoritative types are the project's `types/agentcrm-runtime.d.ts` (read it when in doubt, it is self-contained). Extension API version: 1.0.0. Besides this module a bundle may import only `react`, `react/jsx-runtime`, `react-dom`, `react-dom/client`, `react-i18next`, `lucide-react`.
+
+Hooks and components work only in React components the admin renders (pages, slots, settings pages). AI tools, automation actions and `register()` hooks also run in the CLI / MCP server (Node, no DOM): there, only use `ops.*` with the `ctx` argument.
+
+## Definitions
+
+- `defineModule({ id, apiVersion, feature?, register?(api), aiTools?, automationActions?, settingsPage? })`
+- `defineTheme({ id, apiVersion, name, description?, appearance, css? })`
+- `apiVersion`, `minApiVersion`: what the running admin accepts.
+- `feature`: `routes [{ path, element, roles? }]`, `navItems [{ id, label, icon, to, section: main|workspace|bottom, order?, roles? }]`, `i18n { en, fr }`, `slots { recordDetailTabs, recordDetailPanels, recordActions, dashboardWidgets, settingsSections, topBar, globalOverlays }`, `onStart?(env)`.
+- `register(api)`: `api.addAction(hook, fn)`, `api.addFilter(hook, fn)`, `api.registerAiTool(tool)`, `api.registerAutomationAction(def)`, `api.onDispose(fn)`, `api.moduleId`. Removed automatically on disable / upgrade.
+
+## Engine: `ops`
+
+Every op takes the context first: `useOps()` in components, `ctx` in tools / actions / hooks. Typed: `listRecords(ctx, objectId, { filters, sorts, search, limit })` → `{ items, total }`, `getRecord`, `createRecord(ctx, objectId, fields)`, `updateRecord(ctx, id, fields)`, `deleteRecord`, `listActivities(ctx, { target })`, `addNote(ctx, { object, id }, body, title?)`, `createTask(ctx, { title, dueAt?, assigneeId?, targets? })`, `completeTask`, `listPipelines`, `pipelineOfRecord`, `moveStage(ctx, recordId, stage)`, `forecast`, `listObjects`, `getSettings`, `listUsers`, `listModules`, `getModuleConfig(ctx, id)`, `setModuleConfig(ctx, id, value)`, `getAppearance`. Every other op of the engine (`createObject`, `createField`, `searchRecords`, `createAutomation`, `runReport`…) is there too, typed `unknown`: cast it to its signature.
+
+Filters: `{ field, op, value }` with op `eq, neq, contains, notContains, empty, notEmpty, gt, gte, lt, lte, in, notIn, before, after, withinDays`. Sorts: `{ field, dir: "asc" | "desc" }`.
+
+## Data hooks (live)
+
+`useCrm`, `useOps`, `useCan(action)`, `useCurrentUser`, `useCollection(name)`, `useObjects`, `useObject(id)`, `useRecords(objectId)`, `useRecord(id)`, `useActivities(recordId)`, `usePipelines(objectId)`, `useViews(objectId)`, `useUsers`, `useSettings`, `useModuleConfig(id)`, `useModuleEnabled(id)`, `useAppearance`.
+
+Permissions for `useCan`: `records.read`, `records.write`, `records.delete`, `activities.write`, `schema.write`, `settings.write`, `users.write`, `automations.write`, `modules.write`, `appearance.write`, `extensions.write`…
+
+## Router
+
+`useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `Link`, `NavLink`, `paths` (`dashboard()`, `objectList(objectId, viewId?)`, `record(objectId, recordId)`, `tasks()`, `automations()`, `forms()`, `reports()`, `settings(section?)`), `recordHref(objectId, recordId)`.
+
+## Plugin registry
+
+`addAction`, `removeAction`, `addFilter`, `removeFilter`, `doAction`, `applyFilters`, `registerAiTool`, `registerAutomationAction`. CRM actions: `record.created`, `record.updated`, `record.deleted`, `record.restored`, `stage.changed`, `activity.created`, `activity.updated`, `activity.completed` (handler: `(ctx, payload)`).
+
+## UI kit
+
+`Button`, `IconButton`, `Input`, `Textarea`, `Select`, `Label`, `FormField`, `Checkbox`, `Switch`, `Modal`, `Drawer`, `Card`, `Badge`, `Avatar`, `Tabs`, `Tooltip`, `Spinner`, `EmptyState`, `PageHeader`, `Kbd`, `Dropdown`, `Table`, `THead`, `TBody`, `Tr`, `Th`, `Td`, `FieldValue`, `FieldInput`, `ObjectIcon`, `Markdown`, `confirmDialog`, `toast`, `cn`, `newId`. Tailwind classes of the admin work (`text-surface-500`, `bg-accent-500`, `dark:`…) and follow the workspace appearance.
+
+## i18n and formatters
+
+`i18n`, `addBundles(ns, { en, fr })`, `activeLocale()`, `intlLocale()`; `formatFieldValue`, `formatCurrency(n, currency, locale, compact?)`, `formatNumber`, `formatDate`, `formatDateTime`, `formatRelative`, `recordLabel(object, record)`, `coerceFieldValue(field, raw)`, `isEmptyFieldValue`.

package/plugin/skills/agentcrm-extensions/references/testing.md

@@ -0,0 +1,76 @@
+# Test, pack, install, upgrade, debug
+
+## The loop
+
+```bash
+npm run typecheck                                            # tsc against types/agentcrm-runtime.d.ts
+npm run build                                                # vite build → dist/bundle.js
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext check . --json           # what the admin will see
+```
+
+`ext check` reads `manifest.json` + `dist/bundle.js` (+ `src/style.css` for themes declaring it) from a project, `manifest.json` + `bundle.js` from an unpacked folder, or a ZIP. Then:
+
+| Field | Meaning |
+|---|---|
+| `data.valid` | false = the admin would refuse or fail to load it (exit code 1). |
+| `data.errors[]` | `{ code, message, hint }`: `manifest`, `incompatibleApi`, `imports` (a bare import the admin doesn't provide), `noDefaultExport`, `devJsx`, `tooLarge`, `missingStyle`, `notBuilt`, `load` (the bundle threw or its default export is wrong), `appearance` (theme values). |
+| `data.warnings[]` | `i18n` (no French), `toolName`, `toolDescription`, `actionId`, `nav` (entry without a route), `empty`, `dependency`, `toolCall` (a tool failed when called with `{}` on demo data), `author`, `ignored`. |
+| `data.registered` | routes, navItems, slots (ids per slot), settingsPage, i18n key counts, aiTools, automationActions, hooks. |
+| `data.toolCalls` | each AI tool without required inputs, called once on a demo CRM (`--no-call` skips). |
+| `data.theme` | a theme's resolved values and CSS size. |
+
+The check runs the bundle in Node with the real loader and runtime, in a throw-away demo CRM (30 companies, 80 people, 40 deals): nothing reaches a real site. It does not render React components; open the admin for that (below).
+
+## Pack and install
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext pack . --json                         # → <id>-<version>.zip
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext install acme-quotes-0.1.0.zip --site acme --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext install acme-quotes-0.1.0.zip --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext list --site acme --json
+```
+
+- The plan (`needsConfirmation: true`) shows `id`, `kind`, `name`, `version`, `author`, `mode` (`install` / `upgrade` with `from`), `dependsOn`, `size`, `warnings` and the trust warning. **Show it to the user and ask before `--yes`.**
+- After `--yes`, `data.load.status` is `loaded` when the bundle ran in the CLI session. `error` comes with `data.load.error`.
+- A module whose dependencies are off is installed disabled (see `warnings`); enable them first or `ext enable <id> --cascade`.
+- `ext install <dir>` works on a built project too (no ZIP needed).
+- The admin alternative: Settings, Modules, Installed extensions, drop the ZIP, review, tick "I trust the author".
+
+## Upgrade
+
+Bump `version` in `manifest.json`, build, check, install again: `mode: "upgrade"`, `from: "<old>"`. The enabled state and the module config are kept; open admins reload the new bundle live.
+
+## Use it
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 tools list --site acme --json             # its AI tools (source: "extension")
+npx -y @fleox-agent-crm/agentcrm@0.3.0 tools call acme_quotes_list --site acme --input '{}' --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 modules list --site acme --json           # appears as a module (source: "extension")
+npx -y @fleox-agent-crm/agentcrm@0.3.0 automations run --site acme --json        # its automation actions run here too
+```
+
+To see the UI, open the CRM's admin (its hosted URL, see `site show`, or `npx -y @fleox-agent-crm/agentcrm@0.3.0 serve` for a local copy), and check the page, the tabs and widgets in light and dark mode and in French (language switcher in the user menu or the Cmd+K palette).
+
+## Disable, uninstall, export
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext disable acme-quotes --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext enable acme-quotes --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext uninstall acme-quotes --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext export acme-quotes --site acme --out backup.zip --json
+```
+
+Disabling keeps the package and its config; uninstalling keeps the config (a re-install restores it). Data the module created (records, objects, notes) is never deleted by either.
+
+## When it breaks
+
+| Symptom | Cause / fix |
+|---|---|
+| `imports` error: `react-router-dom`, `date-fns`… | Only react, react/jsx-runtime, react-dom, react-dom/client, react-i18next, lucide-react and @agent-crm/runtime are external. Use the runtime's router (`Link`, `useNavigate`, `paths`) and formatters (`formatDate`…), or let Vite bundle the library (remove it from `external`). |
+| `load`: "bundle id … doesn't match manifest id" | The default export's `id` must equal `manifest.json`'s. Same for `apiVersion`. |
+| `load`: "AI tool … already exists" | Tool names are global: prefix them with the module id. |
+| `devJsx` / "jsxDEV is not a function" | Build in production mode (the scaffold's `vite.config.ts` does). |
+| Hooks are invalid / "Invalid hook call" | A second React got bundled: keep `react` external. |
+| The admin is blank after installing | Open it with `?safe=1` (or hold Shift while it loads), then `ext disable <id> --yes`. |
+| A tool works in the admin but not in the CLI | The CLI has no DOM: keep `document` / `window` / `localStorage` out of AI tools, automation actions and hooks. |
+| `ext list` says `load: error` | `ext check` the same package; the error is in `loadError`. |

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

@@ -0,0 +1,65 @@
+# Theme recipes
+
+A theme (`ext new theme <id>`) is `src/index.ts` (`defineTheme`) + an optional `src/style.css` (declared as `"style": "style.css"` in `manifest.json`). Installed and enabled, it appears in Settings, Appearance as a preset; applying it (`appearance preset <id>`) selects it as `themeId`. Its values fill everything the workspace didn't set explicitly; a user can still override any value afterwards. Logo, favicon and custom CSS stay workspace settings.
+
+**First ask whether a theme is needed at all:** a brand color, a font, rounded corners or a dark sidebar are plain appearance settings (`agentcrm-admin` skill, `appearance set`). A theme is for a reusable, shareable look (several CRMs, a client, a marketplace) or for CSS that goes beyond the settings.
+
+## Values
+
+```ts
+import { defineTheme } from "@agent-crm/runtime";
+
+export default defineTheme({
+  id: "acme-brand",
+  apiVersion: "1.0.0",
+  name: "Acme",
+  description: "Acme green, warm grays, dark sidebar.",
+  appearance: {
+    accent: "#0f766e",        // any #rrggbb; a 50…950 scale is generated (500 = this color)
+    neutral: "stone",         // zinc | slate | stone | gray | neutral
+    radius: "lg",             // none | sm | md | lg | xl
+    density: "comfortable",   // compact | comfortable
+    font: "inter",            // system (no network) | 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
+    sidebar: "dark",          // default | dark | accent
+    buttons: "accent",        // neutral (near-black) | accent
+    contrast: "normal",       // normal | high
+    defaultMode: "system",    // system | light | dark (users who never toggled)
+  },
+});
+```
+
+Any subset works; unknown keys or bad values make `ext check` fail. Don't set `logo`, `favicon`, `preset` or `themeId` in a theme.
+
+## Brand from a logo or a hex
+
+1. Get the brand color: the user's hex, or the dominant non-gray color of their logo (read the SVG fill, or sample the PNG). Prefer a mid-tone (lightness 40 to 60 %): very light colors make unreadable buttons; the scale generator keeps the hue but white text needs contrast.
+2. Pick `neutral` by temperature: cool blues / teals → `slate`, warm oranges / reds / greens → `stone`, otherwise `zinc`.
+3. `buttons: "accent"` for a colorful brand, `"neutral"` for a sober one; `sidebar: "accent"` only for strong brands.
+4. Without a theme, the same values go straight to the workspace: `appearance set --accent … --neutral … --yes` and `appearance logo logo.svg --yes`.
+
+## CSS
+
+`style.css` (and `css` in `defineTheme`, same effect) is injected while the theme is selected, before the workspace's custom CSS. Style through the design tokens rather than class names, which can change:
+
+```css
+/* Colors are "r g b" triplets. */
+html:root {
+  --srf-50: 250 250 249;                 /* page background in light mode */
+}
+html:root .acrm-sidebar-accent {}        /* the colored sidebar */
+html[data-density="compact"] {}          /* density / contrast / radius / buttons / sidebar are data- attributes on <html> */
+.dark h1 { color: rgb(var(--acc-300)); } /* dark mode = .dark on <html> */
+```
+
+Variables: `--acc-50` … `--acc-950` (accent scale), `--srf-50` … `--srf-950` + `--srf-850` (neutral scale), `--acc-fg`, `--primary`, `--primary-hover`, `--primary-fg`, `--radius-scale` (multiplies every radius), `--font-sans`, `--row-h`, `--ctl-h`, `--card-pad`, `--card-head-py`, `--page-py`. Attributes on `<html>`: `data-density`, `data-sidebar`, `data-contrast`, `data-buttons`, `data-radius`. Limits: style.css 256 KB. No `@import` of remote fonts (the CRM loads Google Fonts only when `font` asks for one).
+
+## Test
+
+```bash
+npm run build
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext check . --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 ext install . --site acme --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 appearance preset acme-brand --site acme --json
+```
+
+`ext check` prints the resolved values (`data.theme.appearance`) and the CSS size. `appearance preset` prints the before / after plan; add `--yes` to apply. Open the admin to look at it (light and dark, a table and a record page).

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

@@ -0,0 +1,116 @@
+---
+name: agentcrm-install
+description: Install a new AgentCRM (static, AI-drivable CRM) for the user - ask where the CRM data lives (encrypted files on an S3-compatible bucket, a private GitHub / GitLab repo or a local folder, or Firebase / a private git repo as JSON), then where the admin app is hosted (S3, GitHub / GitLab / Cloudflare Pages, local folder), help create the keys and tokens without ever asking for secrets in the chat, write the install plan, install and verify with doctor. Use when the user wants to create, set up or install a CRM with AgentCRM.
+license: PolyForm-Noncommercial-1.0.0
+compatibility: Requires Node.js 20+ and network access to the chosen storage. Works in Claude Code and any agent that can run shell commands.
+metadata:
+  version: "0.3.0"
+  repository: "https://github.com/fleox/agentcrm"
+allowed-tools: Bash Read Write
+---
+
+# Install an AgentCRM
+
+AgentCRM is a HubSpot / Twenty-style CRM (companies, people, deals, pipelines, activities, tasks, custom objects, views, automations, lead forms, reports) that is 100% static: there is no AgentCRM server. The data lives on storage the user owns (encrypted by default); the admin is a static web app hosted anywhere; the `agentcrm` CLI and its MCP server drive the same engine headless.
+
+**Language:** talk to the user in their language; keep commands, files and plans in English.
+
+Every command is `npx -y @fleox-agent-crm/agentcrm@0.3.0 <command> --json` (Node.js 20+). Each prints ONE JSON object: `{"ok": true, "data": ...}` or `{"ok": false, "error": {"code", "message", "hint"}}`. When `ok` is false, read `error.hint` and act on it. Exit code 2 = a usage error in your command.
+
+## 1. Start with status and options
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 status --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 options --json
+```
+
+`status` shows CRMs this computer already manages (maybe the user wants `agentcrm-manage` instead). `options` lists backends, data locations, hostings, credential types and the plan format.
+
+## 2. Ask about the DATA first
+
+The CRM holds personal data (contacts, emails, phone numbers). Ask, in this order, and recommend the first answer:
+
+1. **Encrypted files on storage the user owns** (backend `journal`, the default). Where?
+   - an **S3-compatible bucket** (AWS S3, Cloudflare R2, OVHcloud, Scaleway, Backblaze, MinIO) - best for teams and speed. Must be a PRIVATE bucket, separate from the hosting bucket.
+   - a **private GitHub or GitLab repository** - simple if the user already lives on GitHub; one commit per write.
+   - a **folder on this computer** - single computer, no account. Advise backing it up.
+2. **Firebase** (backend `firebase`) - real-time teams with logins and per-user roles. See references/firebase.md.
+3. **A private git repo as readable JSON** (backend `git-json`) - readable history, but deleted records stay in the git history: warn the user.
+4. **This browser only** - for trying it: `npx -y @fleox-agent-crm/agentcrm@0.3.0 serve --json`, then "This browser" in the wizard. The CLI can't reach it.
+
+Encryption: the journal is encrypted with AES-256-GCM by default. A passphrase is generated at install and stored only on this computer. Never offer to turn it off unless the user insists and the location is strictly private.
+
+## 3. Then ask where the ADMIN is hosted
+
+The admin app holds no data and no secret (its `config.js` is public by design):
+
+- `s3` - a public bucket with static website hosting, behind HTTPS (CDN or the bucket's https endpoint).
+- `github-pages` - a GitHub repo served by Pages (`https://<owner>.github.io/<repo>`).
+- `gitlab-pages`, `cloudflare-pages` - same idea.
+- `local-folder` - a folder of this computer (serve it with `serve --dir`).
+- no hosting (`"hosting": false`) - the user runs `serve` when needed.
+
+HTTPS is required: browsers only allow the admin's request signing and encryption on secure pages.
+
+## 4. Credentials - never in the chat
+
+Secrets (keys, tokens, passwords, passphrases) are NEVER typed into the conversation and never written in a plan. The user stores each one in their own terminal; in Claude Code they type `! npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials set s3:main` (hidden prompt). Alternatives that keep secrets out of the chat:
+
+- `--from-env KEY_ID,SECRET` - variables the user already exported (CI, `.env`).
+- `--from-aws-profile <profile>` - an existing aws CLI profile (s3).
+- `--from-gh` - the token of the signed-in GitHub CLI (github).
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials list --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials types --json
+```
+
+How to create each key with least privilege: references/s3.md, references/github.md, references/firebase.md. One account can serve several CRMs (`s3:main` for both the data bucket and the hosting bucket is fine).
+
+## 5. Write the plan, dry-run, install
+
+Write `plan.json` (no secrets, only account ids):
+
+```json
+{
+  "alias": "acme-crm",
+  "name": "Acme CRM",
+  "owner": { "name": "Ada Lovelace", "email": "ada@acme.com" },
+  "data": {
+    "backend": "journal",
+    "location": { "type": "s3", "settings": { "endpoint": "https://s3.gra.io.cloud.ovh.net", "region": "gra", "bucket": "acme-crm-data" }, "credential": "s3:main" },
+    "root": "agentcrm"
+  },
+  "hosting": { "type": "s3", "settings": { "endpoint": "https://s3.gra.io.cloud.ovh.net", "region": "gra", "bucket": "acme-crm-admin", "siteUrl": "https://crm.acme.com", "publicRead": true }, "credential": "s3:main" },
+  "demo": false
+}
+```
+
+More examples (GitHub repo data + GitHub Pages, local folder, Firebase): references/plans.md. `owner` becomes the first CRM admin, and the CLI acts as that user. `demo: true` adds a realistic sample dataset - offer it for a first look, not for a production CRM.
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 install --plan plan.json --dry-run --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 install --plan plan.json --json
+```
+
+The dry run checks every access and writes nothing. Fix `check-failed` errors with their hint (permissions, names, CORS) before installing. An existing dataset in the same place is kept; only what's missing is seeded.
+
+## 6. Save the passphrase - blocking step
+
+When the result has `savePassphrase`, stop and do it with the user before anything else:
+
+1. `npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials copy passphrase:<alias> --json` puts it on the clipboard (never print it).
+2. The user pastes it into their password manager now.
+3. The user proves it: in their own terminal, `! npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials verify passphrase:<alias>`, pasting FROM the password manager. It must say "verified".
+
+Without the passphrase nobody can read the data, ever.
+
+## 7. Verify
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 doctor --site <alias> --json
+```
+
+Every failing check has a `fix`. The most common one on buckets is CORS: the result prints the exact JSON rule for the data bucket - help the user apply it (references/s3.md). Then give the user the admin URL (`data.adminUrl` of the install) and explain: each new browser asks once for the storage keys and the passphrase, which stay in that browser.
+
+Next: run the CRM with the `agentcrm-admin` skill, sales workflows with `agentcrm-sales`, health and updates with `agentcrm-manage`. To let Claude Desktop / Claude Code / Cursor use the CRM directly, see references/mcp.md.

package/plugin/skills/agentcrm-install/references/firebase.md

@@ -0,0 +1,18 @@
+# Firebase backend
+
+1. Create a Firebase project (console.firebase.google.com), add a Web app and copy its config (apiKey, authDomain, projectId, appId...). The web apiKey is public by design.
+2. Enable Authentication → Sign-in method → Email/Password (and Google if wanted).
+3. Create Firestore (production mode) and publish the AgentCRM security rules (see docs/firebase.md in the repository).
+4. Create the first admin account (Authentication → Users → Add user). The user stores its login: `! npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials set firebase:<name>` (email + password at hidden prompts).
+5. Plan:
+
+```json
+{
+  "alias": "team-crm",
+  "owner": { "name": "Ada", "email": "ada@acme.com" },
+  "data": { "backend": "firebase", "firebase": { "apiKey": "...", "authDomain": "acme.firebaseapp.com", "projectId": "acme", "appId": "1:..." }, "credential": "firebase:acme", "signInMethods": ["password", "google"] },
+  "hosting": { "type": "github-pages", "settings": { "owner": "acme", "repo": "crm" }, "credential": "github:acme" }
+}
+```
+
+Roles live in Firestore (`users/{uid}`) and are enforced by the rules.

package/plugin/skills/agentcrm-install/references/github.md

@@ -0,0 +1,20 @@
+# GitHub / GitLab for AgentCRM
+
+## Token
+
+Fine-grained personal access token: https://github.com/settings/personal-access-tokens/new
+
+- Repository access: only the data repository (PRIVATE) and, if used, the admin hosting repository.
+- Permissions: Contents read and write; Metadata read-only; Pages read and write (optional, lets the CLI enable Pages).
+
+The user stores it: `! npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials set github:<login>`, or reuses the GitHub CLI login: `npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials set github:<login> --from-gh --json`.
+
+GitLab: project → Settings → Access tokens, scope `api`, role Developer; store as `gitlab:<name>`.
+
+## Data repository
+
+Must be private: the install refuses a public data repository. Journal files are committed with `[skip ci]`. With `git-json`, every past value stays in the history (deleting a record does not erase it from git): tell the user.
+
+## Admin on GitHub Pages
+
+A second repository (it may be public: it only holds the app and a `config.js` without secrets). Plan: `"hosting": { "type": "github-pages", "settings": { "owner": "acme", "repo": "acme-crm" } }` - the credential defaults to the data one when both are on GitHub. Pages takes about a minute to serve a new commit; re-run `doctor` after that.

package/plugin/skills/agentcrm-install/references/mcp.md

@@ -0,0 +1,17 @@
+# Use the CRM from an MCP client
+
+`agentcrm mcp` is a stdio MCP server: tools = the AI tool catalog (search, list, get, create, update, delete, merge records, notes, activities, tasks, pipeline moves, reports, CSV import), resources = schema and pipelines, prompts = pipeline review, follow-up email, lead qualification. `--read-only` hides every tool that writes.
+
+Claude Code:
+
+```bash
+claude mcp add agentcrm -- npx -y @fleox-agent-crm/agentcrm@0.3.0 mcp --site <alias>
+```
+
+Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`):
+
+```json
+{ "mcpServers": { "agentcrm": { "command": "npx", "args": ["-y", "@fleox-agent-crm/agentcrm@0.3.0", "mcp", "--site", "<alias>"] } } }
+```
+
+The server uses the credentials of this computer (`~/.agentcrm`) and acts as the site's CLI user.

package/plugin/skills/agentcrm-install/references/plans.md

@@ -0,0 +1,45 @@
+# Install plan examples
+
+## Encrypted journal in a private GitHub repo, admin on GitHub Pages
+
+```json
+{
+  "alias": "acme",
+  "owner": { "name": "Ada Lovelace", "email": "ada@acme.com" },
+  "data": { "backend": "journal", "location": { "type": "github", "settings": { "owner": "acme", "repo": "acme-crm-data" }, "credential": "github:acme" } },
+  "hosting": { "type": "github-pages", "settings": { "owner": "acme", "repo": "acme-crm" } }
+}
+```
+
+## Local folder, no hosting (one computer)
+
+```json
+{
+  "alias": "solo",
+  "owner": { "name": "Me", "email": "me@example.com" },
+  "data": { "backend": "journal", "location": { "type": "local-folder", "settings": { "path": "/Users/me/Documents/crm" } } },
+  "hosting": false,
+  "demo": true
+}
+```
+
+Use it from the browser with `npx -y @fleox-agent-crm/agentcrm@0.3.0 serve --json` and the folder picker.
+
+## git-json in a private repo
+
+```json
+{
+  "alias": "team",
+  "owner": { "name": "Ada", "email": "ada@acme.com" },
+  "data": { "backend": "git-json", "git": { "provider": "github", "owner": "acme", "repo": "crm-json", "branch": "main" }, "credential": "github:acme" },
+  "hosting": { "type": "cloudflare-pages", "settings": { "provider": "github", "owner": "acme", "repo": "crm-admin", "siteUrl": "https://crm-admin.pages.dev" } }
+}
+```
+
+## Fields
+
+- `alias`: lower-case letters, digits, dashes.
+- `owner`: first admin (email required).
+- `data.encryption`: omitted = encrypted with a new passphrase `passphrase:<alias>`; `{ "credential": "passphrase:<name>" }` = existing passphrase (reuse a dataset); `false` = plain (discouraged).
+- `hosting.folder`: admin folder on the hosting, default `admin`.
+- `currency`, `locale`: defaults for money and dates.

package/plugin/skills/agentcrm-install/references/s3.md

@@ -0,0 +1,24 @@
+# S3-compatible storage for AgentCRM
+
+Use TWO buckets: a PRIVATE one for the data (journal backend) and a public one for the admin app. One access key can cover both.
+
+## Access key (least privilege)
+
+- **AWS**: IAM user with a policy on both buckets: `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject` on `arn:aws:s3:::<bucket>/*` and `s3:ListBucket` on `arn:aws:s3:::<bucket>`. Store it: `! npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials set s3:main`, or import a profile with `--from-aws-profile <name>`.
+- **Cloudflare R2**: R2 → Manage API tokens → Object Read & Write, scoped to the buckets. Endpoint `https://<account-id>.r2.cloudflarestorage.com`, region `auto`.
+- **OVHcloud**: Public Cloud → Object Storage → S3 users; endpoint `https://s3.<region>.io.cloud.ovh.net`. Set `publicRead: true` on the hosting bucket.
+- **Scaleway**: endpoint `https://s3.<region>.scw.cloud`.
+
+## CORS on the data bucket
+
+The browser admin reads and writes the data bucket directly, so the bucket needs a CORS rule for the admin's origin. `doctor` prints the exact JSON; it looks like:
+
+```json
+[{ "AllowedOrigins": ["https://crm.acme.com"], "AllowedMethods": ["GET", "PUT", "DELETE", "HEAD"], "AllowedHeaders": ["authorization", "content-type", "cache-control", "x-amz-*"], "ExposeHeaders": ["ETag"], "MaxAgeSeconds": 3600 }]
+```
+
+AWS: bucket → Permissions → CORS. R2: bucket → Settings → CORS policy. With the aws CLI: `aws s3api put-bucket-cors --bucket <bucket> --cors-configuration file://cors.json` (wrap the array as `{"CORSRules": [...]}`).
+
+## Hosting bucket
+
+Enable static website hosting (index document `index.html`) or put a CDN in front (CloudFront, Cloudflare) with HTTPS. `siteUrl` in the plan is that public HTTPS URL; the admin is served at `<siteUrl>/admin/`.

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

@@ -0,0 +1,108 @@
+---
+name: agentcrm-manage
+description: Check, repair and update existing AgentCRM CRMs - list the CRMs this computer manages, register one installed elsewhere (another computer, the setup wizard), attach credentials, run the health check (data access, passphrase, dataset, hosted admin, config.js, CORS, data exposure) and apply its fixes, detect newer AgentCRM releases and offer to update hosted admins, compact the data, set up scheduled automations. Use when the user asks about one of their CRMs, says something is broken, or wants to update.
+license: PolyForm-Noncommercial-1.0.0
+compatibility: Requires Node.js 20+.
+metadata:
+  version: "0.3.0"
+  repository: "https://github.com/fleox/agentcrm"
+allowed-tools: Bash Read Write
+---
+
+# Manage AgentCRM sites
+
+This skill covers the CRMs themselves (registry, health, updates, maintenance). To work with the data - records, pipelines, imports - use `agentcrm-admin`; for sales workflows, `agentcrm-sales`.
+
+**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.0 <command> --json` (Node.js 20+); read `error.hint` whenever `ok` is false.
+
+## Always start with status
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 status --json
+```
+
+- `data.tool.updateAvailable: true` -> tell the user AgentCRM `data.tool.latest` exists and offer to update the skills first (Claude Code: `/plugin marketplace update agentcrm`, then `/reload-plugins`).
+- A site with `state: "update"` -> summarise `update.changes` (breaking first), then offer `deploy-admin` (below). Never update silently.
+- `state: "newer"` -> the hosted admin is newer than this tool: update the skills / tool first.
+- `state: "unreachable"` -> run `doctor` for that site.
+- `data.advice` already phrases these; relay it.
+
+## Which CRM?
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 site list --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 site show <alias> --json
+```
+
+Commands take `--site <alias>`; always pass it. Without it the tool uses `AGENTCRM_SITE`, the folder's `agentcrm.json` (`{ "site": "<alias>" }`), the only site, or the default chosen with `site use <alias>` - otherwise it fails with `site-required`: ask the user which CRM. Say which CRM you are working on before changing anything.
+
+Registry commands: `site use <alias>`, `site rename <from> <to>`, `site forget <alias>` (local only - nothing is deleted online).
+
+## Register a CRM installed elsewhere
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 site add <alias> --admin-url https://crm.acme.com/admin/ --data-credential s3:main --passphrase-credential passphrase:acme --hosting-credential s3:main --json
+```
+
+- It reads the admin's public `config.js`, opens the data (proving the credentials) and reads the hosting from the dataset.
+- `--data-credential`: the data location key (journal), the git token (git-json) or the Firebase login.
+- `--passphrase-credential`: encrypted journals. The user stores the passphrase from their password manager: `! npx -y @fleox-agent-crm/agentcrm@0.3.0 credentials set passphrase:<alias>`.
+- `--user <email>`: the CRM user the CLI acts as (default: the first admin).
+- A CRM in a local folder without a hosted admin: `site add <alias> --runtime @config.json --data-path /path/to/folder`.
+- `warnings` lists what is still missing; fix later with `site credentials <alias> --hosting-credential <account>` (`""` removes one).
+- Errors `passphrase-required` / `passphrase-wrong`: store the right passphrase and retry.
+
+## Health check
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 doctor --site <alias> --json
+```
+
+`data.checks[]` has `id`, `status` (ok / warn / fail / skip), `message` and, for problems, `fix`. Exit code 1 when a check fails. Walk the user through each fix, most important first:
+
+- `data-access` fail -> credentials or passphrase (see `fix`).
+- `dataset` fail -> `doctor --site <alias> --repair --json` seeds what's missing (idempotent, keeps data).
+- `cors-data` warn -> the data bucket lacks a CORS rule for the admin origin; `fix` holds the exact JSON (see the `agentcrm-install` skill, references/s3.md).
+- `data-exposure` fail -> the unencrypted dataset is public: make it private NOW, then move it.
+- `config-js` fail with secrets -> revoke those keys immediately, then `deploy-admin`.
+- `https` fail -> the admin needs HTTPS.
+- `purge` / `journal` warn -> compaction (below).
+
+Details of every check: references/doctor.md.
+
+## Update a hosted admin
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 deploy-admin --site <alias> --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 deploy-admin --site <alias> --yes --json
+```
+
+Without `--yes` it prints the plan (`needsConfirmation: true`, versions, file count): show it, ask, then re-run with `--yes`. `--all` covers every CRM with a hosting. It refuses downgrades and admins that store a newer data format. GitHub / GitLab Pages need a minute before `doctor` sees the new version.
+
+## Compact (GDPR erasure)
+
+Deleted records stay restorable until compaction. To erase them physically and shrink the journal:
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 compact --site <alias> --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 compact --site <alias> --yes --json
+```
+
+Show the plan (records purged) and confirm first: it can't be undone. Run it from one place at a time.
+
+## Scheduled automations and lead forms (no server)
+
+Scheduled / inactivity automations and lead form ingestion run when the admin is open, or from a cron. The recommended cron is a GitHub Actions workflow in a private repo: references/cron.md. Locally:
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 automations run --site <alias> --yes --json
+npx -y @fleox-agent-crm/agentcrm@0.3.0 forms ingest --site <alias> --yes --json
+```
+
+## Overview of one CRM
+
+```bash
+npx -y @fleox-agent-crm/agentcrm@0.3.0 stats --site <alias> --json
+```

package/plugin/skills/agentcrm-manage/references/cron.md

@@ -0,0 +1,11 @@
+# Scheduled automations with GitHub Actions
+
+AgentCRM has no server, so time-based work (schedule / inactivity automations, ingesting lead form submissions) runs from a scheduled GitHub Actions workflow in a PRIVATE repository the user owns.
+
+1. Create a private repo (e.g. `acme/crm-cron`).
+2. Add repository secrets (Settings → Secrets and variables → Actions): `AGENTCRM_S3_KEY_ID`, `AGENTCRM_S3_SECRET`, `AGENTCRM_PASSPHRASE` (the dataset passphrase), and the site's public config as `AGENTCRM_RUNTIME` (the object of the admin's `config.js`, JSON).
+3. Copy `docs/templates/agentcrm-cron.yml` of the AgentCRM repository to `.github/workflows/agentcrm-cron.yml`.
+
+The workflow stores the credentials with `credentials set … --from-env`, registers the CRM with `site add --runtime`, then runs `automations run --yes` and `forms ingest --yes` every hour. Each run writes only journal segments (no conflict with users editing at the same time).
+
+Keep the passphrase secret strictly in the private repo; anyone with it can read the CRM.

package/plugin/skills/agentcrm-manage/references/doctor.md

@@ -0,0 +1,18 @@
+# doctor checks
+
+| id | What it proves | Typical fix |
+|---|---|---|
+| credential-data / -hosting / -passphrase | The accounts the site references are stored on this computer | The user runs `credentials set <account>` in their own terminal |
+| encryption | The journal is encrypted | Keep the location private; migrate with `export json` into a new encrypted install |
+| data-repo | The git data repo is private and writable | Make the repo private; check the token's Contents permission |
+| data-access | The dataset opens (keys, passphrase, network) | Follow the hint (passphrase-required / passphrase-wrong / storage) |
+| dataset | Standard objects, a pipeline, settings, an active admin exist | `doctor --repair` |
+| cli-user | The CLI acts as an admin | `site credentials <alias> --user <admin email>` |
+| purge | Soft-deleted records still stored | `compact` (plan, then `--yes`) |
+| journal | Segments since the last snapshot (loading speed) | `compact --yes` |
+| https | The admin is served over HTTPS | CDN / custom domain with TLS / Pages |
+| admin | The admin page is served | `deploy-admin --yes`; Pages: wait a minute |
+| admin-version | Hosted admin vs this release | `deploy-admin` (plan, then `--yes`) |
+| config-js | config.js exists, matches the backend and holds no secret | `deploy-admin --yes`; revoke leaked keys first |
+| cors-data | The data bucket answers a CORS preflight for the admin origin | Apply the printed CORS JSON to the bucket |
+| data-exposure | The dataset is not downloadable from the public site | Separate private bucket |