@memberjunction/cli 6.1.4 → 6.2.0-edge.1

package/dist/init-templates/citizen-builder/README.md

@@ -0,0 +1,259 @@
+# MemberJunction Citizen Agent Builder
+
+> **Instructions for AI Coding Agents (Claude Code, Antigravity, Cursor, Codex, Windsurf):**
+> If you are an AI coding agent reading this file, you have been tasked with setting up, authoring, testing, and packaging MemberJunction AI Agents for your user end-to-end.
+> Follow the numbered steps below. You have the tools to run the bash commands, inspect database traces, author declarative metadata, and package the final agent bundle without requiring your user to write code or manage database migrations.
+
+---
+
+## ⚡ Getting Started (Choose Your Path)
+
+### Option A: The Agent-Driven Path (Recommended — Zero Manual Setup)
+You don't need to manually run CLI commands, configure Docker files, or edit JSON files by hand. Simply create a new empty directory, open your favorite AI coding agent (**Claude Code**, **Antigravity**, **Cursor**, **Codex**, or **Windsurf**), and paste this prompt:
+
+```markdown
+Please review the MemberJunction Citizen Agent Builder guide at:
+https://github.com/MemberJunction/MJ/tree/next/citizen-builder
+
+Follow the instructions in that guide:
+1. Initialize a new MemberJunction agent builder workspace here using `npx @memberjunction/cli agent init .`
+2. Start the local Docker environment and verify services are running.
+3. Review available entities and actions in CAPABILITIES.md.
+4. Build me an AI agent that:
+   [Describe your business goal here — e.g. "analyzes customer order frequency and overdue invoices, flags accounts at risk of churning, and drafts personalized retention outreach emails."]
+5. Push the metadata, run test executions, verify the run traces in the database, and package the final distributable bundle for promotion.
+```
+
+Your coding agent will read the guide, scaffold the workspace, start the local database and API, author the declarative agent metadata, test it against local data, and hand you a packaged distribution `.zip` file with an `AGENT_MANIFEST.md` report.
+
+---
+
+### Option B: The Manual / Step-by-Step Path
+If you prefer to initialize the workspace and start the Docker environment yourself before handing off to an agent:
+
+1. **Scaffold the workspace**:
+   ```bash
+   npx @memberjunction/cli agent init ./my-agents
+   cd ./my-agents
+   ```
+2. **Add your LLM API Key**:
+   Open `.env` and add your OpenAI, Anthropic, Gemini, or Groq API key:
+   ```bash
+   OPENAI_API_KEY=sk-...
+   ```
+3. **Start the local Docker stack**:
+   ```bash
+   docker compose up -d
+   ```
+4. **Launch your coding agent**:
+   Open your coding agent in `./my-agents` and tell it what you want to build:
+   ```
+   "Build me an agent that monitors accounts receivable aging and drafts payment follow-ups."
+   ```
+   The coding agent will detect `AGENTS.md`, adhere to the 3-tier safety boundaries, and build the agent for you.
+
+---
+
+## 1. Overview & Architecture
+
+> **Product Principle:** *Make the human surface simple; keep the agent surface complete.*
+> The business-user experience is a straightforward chat. The agent experience is comprehensive — giving coding agents full machine-readable access to live entity metadata, actions, progressive CLI discovery, diagnostic probes, execution traces, and packaging.
+
+The **Citizen Agent Builder** provides an isolated, local MemberJunction environment that runs entirely inside Docker:
+* **`sqlserver` (Port 1433)**: Microsoft SQL Server 2022.
+* **`mj` (Ports 4000 & 4202)**: A Node 24 container that executes `mj install` on first boot, provisions the database schema, installs business context (More Cheese default, or enterprise apps like Blue Cypress), and serves:
+  * **MJAPI** at `http://localhost:4000` (GraphQL API and agent execution engine).
+  * **MJExplorer** at `http://localhost:4202` (Web UI for testing agents and viewing records; port 4202 is an authorized redirect URI for Auth0/MSAL).
+* **Metadata Directory (`./metadata`)**: Local JSON and Markdown files mapped into the container. Pushing metadata to the database is done with a single command (`./scripts/sync-metadata.sh`).
+
+### Available Agent Tools & CLI Commands
+
+Every tool and command in this workspace supports machine-readable output (`--format json`) for autonomous coding agents:
+
+| Tool / Command | What It Does |
+|---|---|
+| `./scripts/sync-metadata.sh` | Pushes declarative metadata files in `./metadata/` to the database, resolving `@lookup` and `@file` references. |
+| `./scripts/query-run-history.sh ["<Agent>"\|<ID>]` | Queries agent run history, step execution traces, and action logs via native CLI. |
+| `./scripts/generate-capabilities.sh` | Re-scans the live database and regenerates `CAPABILITIES.md` with current entities and actions. |
+| `docker compose exec -T mj mj doctor --format json` | Runs system diagnostics returning structured checks, failures, and auto-remediations. |
+| `docker compose exec -T mj mj doctor --format json --scope [ai\|runtime\|install]` | Filters diagnostics by specific subsystem (e.g. AI provider credentials or encryption keys). |
+| `docker compose exec -T mj mj ai actions list --format json` | Lists all available system and business actions with parameter schemas. |
+| `docker compose exec -T mj mj ai agents list --format json` | Lists all existing agents, agent types, and categories in the instance. |
+| `docker compose exec -T mj mj ai agents run -a "<Name>" -p "<Input>" --format json` | Executes an agent headlessly and emits structured execution results. |
+| `docker compose exec -T mj mj ai audit agent-run <ID> --format json` | Audits an agent run: step-by-step prompts, LLM completions, token counts, and tool calls. |
+
+---
+
+## 2. Documentation & Architecture References
+
+When authoring agents or researching MemberJunction APIs, consult these authoritative resources:
+
+### A. Official Documentation Portal (`docs.memberjunction.org`)
+Use your web search or fetch tools to research topics across the documentation portal:
+* **Documentation Portal**: [https://docs.memberjunction.org/](https://docs.memberjunction.org/)
+* **AI Agents Architecture**: [https://docs.memberjunction.org/ai/](https://docs.memberjunction.org/ai/) — Details on Agent Types (`Flow` deterministic step graphs vs `Loop` iterative tool-calling), Prompt bindings, model selection, execution lifecycles, and sub-agents.
+* **Actions Framework**: [https://docs.memberjunction.org/actions/](https://docs.memberjunction.org/actions/) — Available actions, parameter definitions, and result codes.
+* **Metadata Sync System**: [https://docs.memberjunction.org/developer-guide/metadata-sync/](https://docs.memberjunction.org/developer-guide/metadata-sync/) — Complete specification for declarative metadata files, reference resolution, and upsert mechanics.
+* **Entity Data Platform**: [https://docs.memberjunction.org/concepts/entities/](https://docs.memberjunction.org/concepts/entities/) — Core entities, schema relationships, permissions, and query patterns.
+
+### B. MemberJunction Repository Specifications
+If you have access to the repository (or view them on GitHub at `https://github.com/MemberJunction/MJ/blob/next/`):
+* [`metadata/CLAUDE.md`](https://github.com/MemberJunction/MJ/blob/next/metadata/CLAUDE.md): **The Definitive Metadata Specification**. Rules on `@lookup`, `@file`, `@parent`, native nested JSON objects, and `mj sync push` mechanics.
+* [`packages/Actions/CLAUDE.md`](https://github.com/MemberJunction/MJ/blob/next/packages/Actions/CLAUDE.md): Action authoring conventions and parameter schemas.
+* [`packages/AI/README.md`](https://github.com/MemberJunction/MJ/blob/next/packages/AI/README.md): AI Agent execution engine, state machines, and task graph dispatcher.
+
+---
+
+## 3. Step-by-Step Execution Guide for Coding Agents
+
+### Step 1: Initialize & Start the Environment
+
+1. **Verify Docker Status**:
+   Run `docker info` in the terminal.
+   * If running: proceed.
+   * If on macOS and Docker Desktop is stopped, run `open -a Docker` and wait 15–20 seconds for the daemon to start.
+   * If Docker is not installed, provide your user with the installation link: `https://www.docker.com/products/docker-desktop` (or `brew install --cask docker`).
+
+2. **Configure Environment Variables**:
+   If `.env` does not exist, copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+   Ask the user to supply their LLM API key (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY`) and set it in `.env`.
+
+3. **Start the Stack**:
+   Run:
+   ```bash
+   docker compose up -d
+   ```
+   *On first start, the container runs `mj install`, applies core migrations, installs the business context app (More Cheese), and launches both MJAPI and MJExplorer.*
+   Monitor startup until ready:
+   ```bash
+   docker compose logs -f mj
+   ```
+   Once the banner appears:
+   * **MJAPI is live at**: `http://localhost:4000`
+   * **MJExplorer is live at**: `http://localhost:4202`
+
+---
+
+### Step 2: Understand the 3-Tier Boundary & Guardrails
+
+Always enforce these constraints when authoring agents:
+
+| Tier | Classification | What You May Author | Human Approval Needed? |
+|---|---|---|---|
+| **Tier 1** | **Declarative Only** | Flows, Loops, prompts, step mappings, action bindings, and sub-agent composition. | No — auto-promotable |
+| **Tier 2** | **Runtime Code** | Sandboxed JavaScript **Runtime Actions** with explicit permission scopes. | Yes — admin code review |
+| **Tier 3** | **Schema Changes** | New database tables, columns, migrations, or entity CodeGen. | **Strictly Off-Limits** |
+
+#### Mandatory Defaults:
+1. **`ModelSelectionMode: "Agent Type"`**: Never hardcode specific provider models (`gpt-4o`, `claude-3-5-sonnet`). The destination environment maps models to Agent Types.
+2. **`ExposeAsAction: false`**: Do not set `true` unless the user explicitly wants other agents to call this agent as an action.
+3. **Dynamic Record Resolution**: Never hardcode record IDs or personal names. Use queries, parameters, or lookup actions.
+4. **Prefer `Flow` Agents**: Use `Flow` agents for predictable step-by-step tasks. Use `Loop` only for dynamic problem-solving with open-ended tool calling.
+
+---
+
+### Step 3: The Authoring Loop
+
+1. **Check Available Tools & Entities**:
+   Review `CAPABILITIES.md` (or run `./scripts/generate-capabilities.sh` to update it). This file contains the exact entity names, fields, and available actions in the running instance.
+
+2. **Metadata Formatting Rules (CRITICAL)**:
+   * **Native JSON Objects**: Fields storing JSON (such as `Configuration` or `Settings`) **MUST** be written as clean, native nested JSON objects. **NEVER** write escaped JSON strings (`"Configuration": "{\"Steps\":...}"`), as this breaks `@lookup` reference resolution!
+   * **No `sync` Blocks**: Do not author `sync` blocks (`lastModified`, `checksum`). `mj sync push` manages these automatically.
+   * **Assign Deterministic UUIDs**: Assign a fresh uppercase UUID for `primaryKey` (e.g. via CLI `uuidgen | tr '[:lower:]' '[:upper:]'`).
+   * **Use Dynamic References**:
+     - `@lookup:<EntityName>.<FieldName>=<Value>` for foreign keys (e.g. `@lookup:MJ: AI Agent Types.Name=Flow`).
+     - `@file:<relativePath>` for external template files (e.g. `@file:templates/<slug>.template.md`). Note that `@file:` paths are resolved at push time; running `./scripts/sync-metadata.sh` updates the database.
+     - `@parent:ID` for linking child records to parent records in nested structures.
+
+3. **Author Files**:
+   * Prompt Markdown template: `metadata/prompts/templates/<slug>.template.md`
+   * Prompt metadata JSON: `metadata/prompts/.<slug>-prompt.json`
+   * Agent metadata JSON: `metadata/agents/.<slug>-agent.json`
+   *(See `metadata/agents/.customer-insight-agent.json` for a reference Flow agent).*
+
+4. **Push to Local Database**:
+   ```bash
+   ./scripts/sync-metadata.sh
+   ```
+
+---
+
+### Step 4: Testing & Autonomous Diagnostics (The Dual Loop)
+
+1. **Interactive Testing (Explorer UI)**:
+   Invite the user to test in their browser at `http://localhost:4202`.
+
+2. **Headless Execution**:
+   You can trigger test runs directly via CLI with structured output:
+   ```bash
+   docker compose exec -T mj mj ai agents run -a "<Agent Name>" -p "<Test Input>" --format json
+   ```
+
+3. **Diagnosing Errors & Auditing Execution Traces**:
+   When an agent runs, **do not ask the user for console logs**. Audit execution traces directly via native CLI:
+   ```bash
+   # List recent runs for this agent
+   ./scripts/query-run-history.sh "<Agent Name>"
+
+   # View full machine-readable JSON trace for a specific run ID
+   ./scripts/query-run-history.sh <RunID> --format json
+
+   # Or drill down into specific steps or errors
+   ./scripts/query-run-history.sh <RunID> --step 1 --detail full
+   ./scripts/query-run-history.sh <RunID> --errors
+   ```
+   
+   **Trace Verification Assertions**:
+   * Verify that `actionsUsed` matches expected actions and tools.
+   * Verify that `actionsNotUsed` contains sensitive or dangerous actions.
+   * Check step prompts, outputs, and token counts to spot prompt drift or infinite loops.
+   
+   Analyze the trace, refine your prompt template or mapping, run `./scripts/sync-metadata.sh`, and re-test.
+
+---
+
+### Step 5: Packaging for Promotion
+
+When the user is satisfied, package the agent for promotion to staging or production:
+
+1. Validate that all Tier 1 guardrails are met (no secrets, no hardcoded IDs, `ModelSelectionMode: "Agent Type"`).
+2. Query the last successful run metrics using `./scripts/query-run-history.sh "<Agent Name>"`.
+3. Generate `AGENT_MANIFEST.md` detailing:
+   * Agent Name, Purpose, and Author.
+   * Tier Classification (Tier 1 vs Tier 2).
+   * Data Footprint (Entities Read vs Entities Written).
+   * Bound Tools and Actions.
+   * Sample Execution Trace Receipt.
+4. Create the distribution archive:
+   ```bash
+   mkdir -p dist
+   zip -r "dist/<agent-slug>-package.zip" \
+     AGENT_MANIFEST.md \
+     metadata/agents/.*"<agent-slug>"*.json \
+     metadata/prompts/.*"<agent-slug>"*.json \
+     metadata/prompts/templates/"<agent-slug>"*.md
+   ```
+5. Give the user the path to `dist/<agent-slug>-package.zip` and explain how their platform admin can review and deploy it (see `docs/PROMOTION_GUIDE.md`).
+
+---
+
+## 4. Enterprise Organization Setup (e.g. Blue Cypress)
+
+By default, the builder runs against **More Cheese** (a rich synthetic dataset covering 9 business apps).
+
+To build agents against your organization's **real schemas and synthetic records** (e.g. **Blue Cypress / BC**):
+1. In `.env`, set:
+   ```bash
+   OPEN_APP_INSTALL_URL=https://github.com/BlueCypress/bc-sampledata
+   GITHUB_TOKEN=ghp_yourReadOnlyTokenHere
+   ```
+2. Restart the container:
+   ```bash
+   docker compose down -v && docker compose up -d
+   ```
+3. Run `./scripts/generate-capabilities.sh` to refresh `CAPABILITIES.md` with your organization's custom entities and actions.
+👉 For complete enterprise details, see [docs/ENTERPRISE_ORG_SETUP.md](docs/ENTERPRISE_ORG_SETUP.md).

package/dist/init-templates/citizen-builder/docker/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:24-bullseye
+
+# Install essential native build dependencies and git
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    curl \
+    build-essential \
+    procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install MemberJunction CLI and process manager globally
+RUN npm install -g @memberjunction/cli pm2 pnpm
+
+WORKDIR /workspace
+
+EXPOSE 4000 4200

package/dist/init-templates/citizen-builder/docker-compose.yml

@@ -0,0 +1,59 @@
+name: mj-citizen-builder
+
+services:
+  sqlserver:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    platform: linux/amd64
+    restart: unless-stopped
+    environment:
+      ACCEPT_EULA: "Y"
+      MSSQL_SA_PASSWORD: "${DB_PASSWORD:-TestPassword123!}"
+    ports:
+      - "${DB_PORT:-1433}:1433"
+    healthcheck:
+      test: /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -Q "SELECT 1" -C -No
+      interval: 10s
+      timeout: 5s
+      retries: 15
+      start_period: 20s
+    volumes:
+      - sqlserver-data:/var/opt/mssql
+
+  mj:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+    platform: linux/amd64
+    restart: unless-stopped
+    depends_on:
+      sqlserver:
+        condition: service_healthy
+    ports:
+      - "${API_PORT:-4000}:4000"
+      - "${EXPLORER_PORT:-4202}:4200"
+    environment:
+      DB_HOST: "sqlserver"
+      DB_PORT: "1433"
+      DB_USERNAME: "sa"
+      DB_PASSWORD: "${DB_PASSWORD:-TestPassword123!}"
+      DB_DATABASE: "${DB_DATABASE:-MemberJunction}"
+      MJ_BASE_ENCRYPTION_KEY: "${MJ_BASE_ENCRYPTION_KEY:-0123456789abcdef0123456789abcdef}"
+      # LLM Provider API Keys
+      AI_VENDOR_API_KEY__OpenAILLM: "${OPENAI_API_KEY:-}"
+      AI_VENDOR_API_KEY__AnthropicLLM: "${ANTHROPIC_API_KEY:-}"
+      AI_VENDOR_API_KEY__GeminiLLM: "${GEMINI_API_KEY:-}"
+      AI_VENDOR_API_KEY__GroqLLM: "${GROQ_API_KEY:-}"
+      AI_VENDOR_API_KEY__MistralLLM: "${MISTRAL_API_KEY:-}"
+      # Business Context Open App (More Cheese default or custom enterprise app)
+      OPEN_APP_INSTALL_URL: "${OPEN_APP_INSTALL_URL:-https://github.com/MemberJunction/more-cheese}"
+      GITHUB_TOKEN: "${GITHUB_TOKEN:-}"
+    volumes:
+      - mj-workspace:/workspace
+      - ./metadata:/work/metadata
+      - ./scripts:/work/scripts
+      - ./dist:/work/dist
+    entrypoint: ["/bin/bash", "/work/scripts/docker-entrypoint.sh"]
+
+volumes:
+  sqlserver-data:
+  mj-workspace:

package/dist/init-templates/citizen-builder/docs/ENTERPRISE_ORG_SETUP.md

@@ -0,0 +1,73 @@
+# Enterprise Organization Setup: Real Schemas & Business Context
+
+This document explains how enterprise organizations—such as **Blue Cypress (BC)**—configure the MemberJunction Citizen Agent Builder so business users build agents against their **real entity schemas and business relationships** instead of generic defaults.
+
+---
+
+## 1. The Two-App Architecture
+
+To provide an accurate, realistic authoring environment without exposing production customer data to personal machines, organizations publish two Open Apps:
+
+| Application | Description | Carries |
+|---|---|---|
+| **`<org>-platform`** (e.g. `bc-platform`) | Core schema & business logic | Custom entities, fields, relationships, standard actions, and queries. |
+| **`<org>-sampledata`** (e.g. `bc-sampledata`) | Realistic synthetic data | Loom-generated synthetic records mirroring production shapes and relational integrity. Depends on `<org>-platform`. |
+
+When a citizen builder boots their environment and installs `<org>-sampledata`, MemberJunction's Open App dependency engine automatically resolves and installs `<org>-platform` leaf-first.
+
+### Why This Model Works:
+1. **Identical Entity Shapes:** Entity and field names match production exactly. An agent written against `bc-sampledata` works on production without renaming a single field or query.
+2. **Zero PII Risk:** The data is 100% synthetic by construction. Compliance and security reviews pass automatically.
+3. **Seamless Promotion:** Promotion is simply deploying the agent's metadata to the production instance; no code rewrites or schema remapping are needed.
+
+---
+
+## 2. Configuration for Citizen Builders
+
+### Option A: Private GitHub Repository Access (Recommended)
+If your organization hosts `<org>-sampledata` in a private GitHub organization (e.g. `github.com/BlueCypress/`):
+
+1. Provide the user with a fine-grained, read-only GitHub Personal Access Token (PAT) with `Contents: Read` permission on the sample data and platform repositories.
+2. In the user's `.env`:
+   ```bash
+   # Enterprise Open App Target
+   OPEN_APP_INSTALL_URL=https://github.com/BlueCypress/bc-sampledata
+   
+   # Read-only GitHub PAT for private repo authentication
+   GITHUB_TOKEN=ghp_exampleTokenWithReadOnlyAccess
+   ```
+3. Run the bootstrap script:
+   ```bash
+   docker compose exec api /work/scripts/bootstrap.sh
+   ```
+
+### Option B: Local Directory Mount (Zero Token)
+If the user or team already has a local checkout of the platform app on their machine:
+1. Create a `docker-compose.override.yml`:
+   ```yaml
+   services:
+     api:
+       volumes:
+         - /path/to/local/bc-platform:/work/apps/bc-platform:ro
+   ```
+2. Run `mj app install /work/apps/bc-platform` inside the container.
+
+---
+
+## 3. Automated Capabilities Cataloging
+
+Once your organization's Open App is installed, run:
+```bash
+./scripts/generate-capabilities.sh
+```
+This queries your local database's entity and action catalogs to update `CAPABILITIES.md`. Your coding agent immediately learns every custom entity, field, and action specific to your company (e.g. `BC: Association Members`, `BC: Committee Terms`, `BC: Invoices`).
+
+---
+
+## 4. Packaging and Upstream Release of Sample Data
+
+When updating your organization's synthetic dataset:
+1. Generate synthetic records using Loom.
+2. Push them to a staging database using `mj sync push`.
+3. Capture the differential SQL emitted by `packages/MetadataSync/src/lib/sql-logger.ts` as the next `V<timestamp>__v<version>_Metadata_Sync.sql` migration in `<org>-sampledata`.
+4. Publish a release of `<org>-sampledata`. All citizen builders will receive the updated synthetic records on their next bootstrap.

package/dist/init-templates/citizen-builder/docs/PROMOTION_GUIDE.md

@@ -0,0 +1,70 @@
+# Promotion & Governance Guide: Reviewing Packaged Agents
+
+This guide is for MemberJunction platform administrators, team leads, and review boards responsible for evaluating and deploying agents authored via the Citizen Agent Builder.
+
+---
+
+## 1. What Arrives at Promotion
+
+A citizen builder submits an export archive (e.g. `dist/InvoiceAuditAgent-package.zip`), which contains:
+
+1. **`AGENT_MANIFEST.md`**: An executive summary describing:
+   - What the agent does and who built it.
+   - Classification: **Tier 1 (Declarative)** vs **Tier 2 (Runtime Action)**.
+   - Data Footprint: Explicit list of entities read and entities modified.
+   - Sample Execution Receipt: Verification trace from a test run.
+2. **Metadata Files**:
+   - `metadata/agents/.*<name>*.json`
+   - `metadata/prompts/.*<name>*.json`
+   - `metadata/prompts/templates/<name>*.md`
+   - (If Tier 2) `metadata/actions/.*<name>*.json`
+
+---
+
+## 2. The Review Process
+
+### Tier 1 (Declarative Agents) — Fast Track (5-Minute Review)
+Tier 1 agents contain **zero executable code** and **zero schema changes**. Reviewing them is straightforward:
+
+1. **Check Defaults in Manifest**:
+   - `ModelSelectionMode` is `"Agent Type"` (no hardcoded models).
+   - `ExposeAsAction` is `false` (unless a valid business rationale is documented).
+2. **Scan Prompts**:
+   - Verify no credentials, tokens, or raw SQL queries are embedded in prompt templates.
+   - Verify no hardcoded record IDs or personal names are used.
+3. **Approve**:
+   - Tier 1 submissions that satisfy these checks can be approved and imported immediately.
+
+### Tier 2 (Runtime Actions) — Code Review Gate
+Tier 2 agents include custom JavaScript actions running in the MemberJunction sandboxed runtime:
+
+1. **Review JavaScript Logic**:
+   - Inspect the code inside the action's metadata definition.
+   - Ensure the logic is deterministic, handles errors, and contains no obfuscated operations or network calls.
+2. **Review & Narrow Permissions**:
+   - Verify that `allowedEntities` is an explicit, minimal list of required entities.
+   - **Reject any submission with `allowAnyEntity: true` or wildcard entity grants.**
+3. **Decide Graduation**:
+   - **Keep as Runtime Action**: Approve the action metadata for deployment as sandboxed JS.
+   - **Promote to Package**: If the action is mission-critical or widely reused, have an engineer reimplement it as a strongly-typed TypeScript action in an `@mj-biz-apps/*` package.
+
+---
+
+## 3. Deploying the Agent
+
+### Option 1: Commit to the Organization's Platform Repo (Recommended)
+1. Extract the metadata files into your organization's repository (e.g. `bc-platform/metadata/`).
+2. Commit and push the changes:
+   ```bash
+   git add metadata/
+   git commit -m "feat(agents): add InvoiceAuditAgent from citizen builder"
+   git push
+   ```
+3. Your CI/CD deployment pipeline will push the metadata to staging and production.
+
+### Option 2: Direct Sync Push to Target Instance
+If deploying directly to a staging or production instance via CLI:
+```bash
+mj sync push --dir /path/to/extracted/metadata
+```
+The agent is now active and ready for end users.

package/dist/init-templates/citizen-builder/metadata/.mj-sync.json

@@ -0,0 +1,7 @@
+{
+  "version": "1.0",
+  "directories": [
+    "agents",
+    "prompts"
+  ]
+}

package/dist/init-templates/citizen-builder/metadata/agents/.customer-insight-agent.json

@@ -0,0 +1,55 @@
+[
+  {
+    "fields": {
+      "Name": "Customer Insight Specialist",
+      "CategoryID": "@lookup:MJ: AI Agent Categories.Name=Assistant",
+      "Description": "Deterministic flow agent that summarizes customer activity, evaluates account standing, and suggests next actions.",
+      "TypeID": "@lookup:MJ: AI Agent Types.Name=Flow",
+      "Status": "Active",
+      "ExecutionOrder": 0,
+      "ExposeAsAction": false,
+      "IconClass": "mj-icon-user-check",
+      "ArtifactCreationMode": "None",
+      "PayloadDownstreamPaths": "*",
+      "PayloadUpstreamPaths": "*",
+      "EnableContextCompression": false,
+      "ModelSelectionMode": "Agent Type"
+    },
+    "relatedEntities": {
+      "MJ: AI Agent Prompts": [
+        {
+          "fields": {
+            "AgentID": "@parent:ID",
+            "PromptID": "@lookup:MJ: AI Prompts.Name=Customer Insight Specialist Prompt",
+            "Status": "Active",
+            "ExecutionOrder": 1
+          },
+          "primaryKey": {
+            "ID": "E9A0C381-645F-4D2A-883F-E19C69D3B511"
+          }
+        }
+      ],
+      "MJ: AI Agent Steps": [
+        {
+          "fields": {
+            "AgentID": "@parent:ID",
+            "Name": "Generate Customer Insights",
+            "Description": "Evaluates account data using the Customer Insight Specialist Prompt",
+            "StepType": "Prompt",
+            "StartingStep": true,
+            "PromptID": "@lookup:MJ: AI Prompts.Name=Customer Insight Specialist Prompt",
+            "Status": "Active",
+            "PositionX": 100,
+            "PositionY": 100
+          },
+          "primaryKey": {
+            "ID": "D2E49B18-091A-4832-B81E-A38C91307D55"
+          }
+        }
+      ]
+    },
+    "primaryKey": {
+      "ID": "A7F01234-8899-4A1B-89E2-7722BCDEF001"
+    }
+  }
+]

package/dist/init-templates/citizen-builder/metadata/agents/.mj-sync.json

@@ -0,0 +1,45 @@
+{
+  "entity": "MJ: AI Agents",
+  "filePattern": "**/.*.json",
+  "defaults": {
+    "TypeID": "@lookup:MJ: AI Agent Types.Name=Flow",
+    "ModelSelectionMode": "Agent Type",
+    "ExposeAsAction": false,
+    "Status": "Active"
+  },
+  "pull": {
+    "createNewFileIfNotFound": true,
+    "newFileName": ".agents.json",
+    "appendRecordsToExistingFile": true,
+    "updateExistingRecords": true,
+    "preserveFields": [],
+    "excludeFields": [],
+    "mergeStrategy": "merge",
+    "backupBeforeUpdate": true,
+    "backupDirectory": ".backups",
+    "lookupFields": {
+      "TypeID": {
+        "entity": "MJ: AI Agent Types",
+        "field": "Name"
+      },
+      "CategoryID": {
+        "entity": "MJ: AI Agent Categories",
+        "field": "Name"
+      }
+    },
+    "relatedEntities": {
+      "MJ: AI Agent Prompts": {
+        "entity": "MJ: AI Agent Prompts",
+        "foreignKey": "AgentID"
+      },
+      "MJ: AI Agent Actions": {
+        "entity": "MJ: AI Agent Actions",
+        "foreignKey": "AgentID"
+      },
+      "MJ: AI Agent Steps": {
+        "entity": "MJ: AI Agent Steps",
+        "foreignKey": "AgentID"
+      }
+    }
+  }
+}

package/dist/init-templates/citizen-builder/metadata/prompts/.customer-insight-prompt.json

@@ -0,0 +1,15 @@
+[
+  {
+    "fields": {
+      "Name": "Customer Insight Specialist Prompt",
+      "Description": "Analyzes customer profile data and recent orders to provide executive account insights.",
+      "CategoryID": "@lookup:MJ: AI Prompt Categories.Name=Agent Type System Prompts",
+      "TypeID": "@lookup:MJ: AI Prompt Types.Name=Chat",
+      "Status": "Active",
+      "TemplateText": "@file:templates/customer-insight.template.md"
+    },
+    "primaryKey": {
+      "ID": "B1C90D1A-9321-4E18-912A-6844917B3C10"
+    }
+  }
+]

package/dist/init-templates/citizen-builder/metadata/prompts/.mj-sync.json

@@ -0,0 +1,45 @@
+{
+  "entity": "MJ: AI Prompts",
+  "filePattern": "**/.*.json",
+  "defaults": {
+    "CategoryID": "@lookup:MJ: AI Prompt Categories.Name=Agent Type System Prompts?create&Description=Prompts for Custom Agents",
+    "TypeID": "@lookup:MJ: AI Prompt Types.Name=Chat"
+  },
+  "ignoreDirectories": [
+    "output",
+    "templates"
+  ],
+  "pull": {
+    "createNewFileIfNotFound": true,
+    "newFileName": ".prompts.json",
+    "appendRecordsToExistingFile": true,
+    "updateExistingRecords": true,
+    "ignoreNullFields": true,
+    "ignoreVirtualFields": true,
+    "preserveFields": [
+      "TemplateText"
+    ],
+    "excludeFields": [
+      "TemplateID"
+    ],
+    "mergeStrategy": "merge",
+    "backupBeforeUpdate": true,
+    "backupDirectory": ".backups",
+    "externalizeFields": [
+      {
+        "field": "TemplateText",
+        "pattern": "@file:templates/{Name}.template.md"
+      }
+    ],
+    "lookupFields": {
+      "CategoryID": {
+        "entity": "MJ: AI Prompt Categories",
+        "field": "Name"
+      },
+      "TypeID": {
+        "entity": "MJ: AI Prompt Types",
+        "field": "Name"
+      }
+    }
+  }
+}