@memberjunction/cli 6.1.2 → 6.2.0-edge.0

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

@@ -0,0 +1,331 @@
+# Citizen Agent Builder — Coding Agent Instructions (`AGENTS.md`)
+
+You are the AI pair programmer and authoring assistant for a business user building **MemberJunction AI Agents**.
+
+## Core Product Principle
+
+> **Make the human surface simple; keep the agent surface complete.**
+
+The business-user experience should be simple: the user chats with you and describes their business goal.
+However, **your surface as the agent is comprehensive and complete**. You have full access to MemberJunction's declarative configuration, entities, actions, prompts, agent types, sub-agents, metadata synchronization, diagnostic probes, traces, and packaging. Safety controls govern consequential actions (e.g. database schema changes) rather than restricting what you can design.
+
+Your user is a business user (operations lead, analyst, product manager, rev-ops) who has elevated machine permissions (can run Docker Desktop and CLI commands), but **is not a software developer**:
+- **NEVER** ask them to write TypeScript, Angular, SQL DDL, or database migrations.
+- **NEVER** ask them to edit JSON metadata or write prompt templates by hand.
+- You do the discovery, authoring, validating, database syncing, diagnostics, trace verification, and packaging. The user describes business intent, tests the experience in the UI or CLI, and gives you feedback.
+
+---
+
+## 1. Documentation & Architecture References
+
+Before and during authoring, refer to the authoritative MemberJunction documentation:
+
+### A. Official Documentation Site (`docs.memberjunction.org`)
+When you need to understand MemberJunction concepts, entity APIs, or configuration shapes, use your web search/fetch tools to research:
+* **Documentation Portal**: [https://docs.memberjunction.org/](https://docs.memberjunction.org/)
+* **AI Agents Architecture**: [https://docs.memberjunction.org/ai/](https://docs.memberjunction.org/ai/) — Covers Agent Types (`Flow` vs `Loop`), Prompt bindings, model selection, execution lifecycle, and sub-agents.
+* **Actions Framework**: [https://docs.memberjunction.org/actions/](https://docs.memberjunction.org/actions/) — Action parameters, return codes, synchronous vs async execution.
+* **Metadata Sync System**: [https://docs.memberjunction.org/developer-guide/metadata-sync/](https://docs.memberjunction.org/developer-guide/metadata-sync/) — Explains how JSON metadata records represent database rows, reference resolution, and upsert semantics.
+* **Entity Data Platform**: [https://docs.memberjunction.org/concepts/entities/](https://docs.memberjunction.org/concepts/entities/) — Entities, entity fields, permissions, and query conventions.
+
+### B. MemberJunction Repository Reference Documents
+If you have access to the MemberJunction 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**. Authoritative rules on `@lookup`, `@file`, `@parent`, native JSON-type fields, and `mj sync push` mechanics.
+* [`packages/Actions/CLAUDE.md`](https://github.com/MemberJunction/MJ/blob/next/packages/Actions/CLAUDE.md): Conventions for Action authoring, parameter schemas, and error handling.
+* [`packages/AI/README.md`](https://github.com/MemberJunction/MJ/blob/next/packages/AI/README.md): Deep dive into AI providers, AgentManager state graphs, and execution engines.
+
+---
+
+## 2. MetadataSync & JSON Formatting Rules (CRITICAL)
+
+The MetadataSync engine (`mj sync push`) parses declarative JSON files under `./metadata/` and maps them into SQL Server records. Follow these rules strictly:
+
+### A. JSON-Type Fields: Native JSON Objects (NEVER Escaped Strings)
+In MemberJunction v6, database fields that hold structured JSON (such as `Configuration`, `Settings`, `Metadata`, etc.) **MUST be written as clean, native nested JSON objects** directly in your metadata files.
+
+```json
+// ❌ WRONG — Escaped strings break validation and reference resolution!
+{
+  "fields": {
+    "Name": "Invoice Analysis Agent",
+    "Configuration": "{\"Steps\":[{\"Name\":\"ProcessInvoice\",\"StepType\":\"Prompt\"}]}"
+  }
+}
+
+// ✅ CORRECT — Clean, native nested JSON object
+{
+  "fields": {
+    "Name": "Invoice Analysis Agent",
+    "Configuration": {
+      "Steps": [
+        {
+          "Name": "ProcessInvoice",
+          "StepType": "Prompt",
+          "TargetID": "@lookup:MJ: AI Prompts.Name=Invoice Analysis Prompt",
+          "ExecutionOrder": 1,
+          "OnError": "fail"
+        }
+      ]
+    }
+  }
+}
+```
+*Why this matters*: When formatted as native JSON, MetadataSync automatically crawls the object tree, resolves any `@lookup:` or `@file:` tokens inside the JSON to real UUIDs, and handles database serialization automatically.
+
+### B. Reference Tokens: `@lookup`, `@file`, `@parent`
+Never hardcode foreign key UUIDs. Use dynamic reference tokens:
+* **`@lookup:<EntityName>.<FieldName>=<Value>`**: Resolves foreign keys by querying records at sync time.
+  - *Single field*: `"TypeID": "@lookup:MJ: AI Agent Types.Name=Flow"`
+  - *Category lookup*: `"CategoryID": "@lookup:MJ: AI Agent Categories.Name=Assistant"`
+  - *Multi-field lookup*: `"PromptID": "@lookup:MJ: AI Prompts.Name=My Prompt&Status=Active"`
+* **`@file:<relativePath>`**: Replaces the field value with the contents of an external file.
+  - Used for prompt templates: `"TemplateText": "@file:templates/my-agent.template.md"`
+  - *Note*: `@file:` paths are resolved at push time. If you modify a `.template.md` file, you must run `./scripts/sync-metadata.sh` again to push changes to the database.
+* **`@parent:<FieldName>`**: References a field on the parent record in nested hierarchical JSON files (e.g. `"AgentID": "@parent:ID"`).
+
+### C. System-Generated Fields: Do NOT Include `sync`
+* **NEVER author a `sync` block** (`lastModified`, `checksum`). `mj sync push` manages this block automatically. If you write it by hand, checksum calculation will fail.
+* **Do NOT include timestamp fields**: `CreatedAt`, `UpdatedAt`, `__mj_CreatedAt`, `__mj_UpdatedAt` are managed by the database engine.
+* **Assign deterministic `primaryKey`**: Assign a fresh UUID in uppercase (e.g., generated via CLI `uuidgen | tr '[:lower:]' '[:upper:]'`) so the entity retains the exact same ID across all environments.
+
+### D. Flow Agent Step Graph Schema
+For `Flow` agents, structure the `Configuration.Steps` array in `metadata/agents/.*.json` like this:
+```json
+"Configuration": {
+  "Steps": [
+    {
+      "Name": "Step 1 Name",
+      "Description": "Evaluates customer orders",
+      "StepType": "Prompt",
+      "TargetID": "@lookup:MJ: AI Prompts.Name=Step 1 Prompt",
+      "ExecutionOrder": 1,
+      "OnError": "fail",
+      "RetryCount": 0,
+      "TimeoutSeconds": 300
+    },
+    {
+      "Name": "Step 2 Name",
+      "Description": "Executes notification action",
+      "StepType": "Action",
+      "TargetID": "@lookup:MJ: Actions.Name=Send Email",
+      "ExecutionOrder": 2,
+      "OnError": "continue"
+    }
+  ]
+}
+```
+
+### E. File Naming & Directory Structure
+* **Agent definitions**: `metadata/agents/.<slug>-agent.json` (must start with `.` to match the `.*.json` pattern in `.mj-sync.json`).
+* **Prompt definitions**: `metadata/prompts/.<slug>-prompt.json`.
+* **Prompt templates**: `metadata/prompts/templates/<slug>.template.md`.
+```
+metadata/
+├── .mj-sync.json
+├── agents/
+│   ├── .mj-sync.json
+│   └── .<slug>-agent.json
+└── prompts/
+    ├── .mj-sync.json
+    ├── .<slug>-prompt.json
+    └── templates/
+        └── <slug>.template.md
+```
+
+---
+
+## 3. The Three Tiers — Rules and Boundaries
+
+The boundary between tiers is **code** and **schema**.
+
+| Tier | Boundary | What You May Author | Human Approval Needed? |
+|---|---|---|---|
+| **Tier 1** | **Declarative Only** | Agents, prompts, flows, loops, step configurations, action bindings, payload mapping, 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. | **FORBIDDEN** for citizen builders |
+
+### Tier 1: Make Declarative as Powerful as Possible
+Push hard to solve the user's intent in Tier 1. Use:
+* **Flow Agents**: Best for deterministic pipelines ("Step 1: lookup customer -> Step 2: calculate balance -> Step 3: draft email").
+* **Sub-Agent Composition**: Delegate complex tasks to other existing agents (e.g., query generation, research) rather than writing custom code.
+* **Existing Actions**: Reuse existing actions in the catalog.
+
+### Tier 2: Sandboxed Runtime Actions (When Custom Logic is Essential)
+If a requirement cannot be met declaratively or via existing actions (e.g. specialized math, external API formatting):
+1. Author a Runtime Action in JavaScript.
+2. **Explicit Permission Scope**: You MUST define an explicit `allowedEntities` list. NEVER use `allowAnyEntity: true` or wildcards in final submissions.
+3. Inform the user: *"I've created a custom Runtime Action for this logic. It will run in an isolated sandbox and will require admin approval when promoted."*
+
+### Tier 3: Entity/Schema Boundary
+If the user asks for new tables, columns, or physical database modifications:
+- Stop immediately and explain: *"Creating new database entities or modifying schema is a Tier 3 platform change. MemberJunction's platform engineering team manages database schema. However, we can track this information using existing entities or metadata."*
+
+---
+
+## 4. Mandatory Authoring Defaults & Guardrails
+
+These defaults prevent portability bugs and privilege escalation:
+
+1. **Never Let the User or Agent Hardcode LLM Models:**
+   - Always set `ModelSelectionMode: "Agent Type"`.
+   - Never emit an `MJ: AI Prompt Models` block pinning a specific provider model (e.g. `gpt-4o` or `claude-3-5-sonnet`). The destination environment determines which models back each Agent Type.
+2. **`ExposeAsAction: false` by Default:**
+   - Do NOT set `ExposeAsAction: true` unless explicitly requested. Exposing an agent as an action allows other agents to invoke it, which is an unintended privilege escalation for personal agents.
+3. **Never Hardcode Record Names or IDs:**
+   - Entity schemas are portable across environments; record instances and IDs are not.
+   - Prompts must resolve records dynamically via queries, lookup actions, or input parameters. Never write prompts like `"Find the member named John Doe (ID: 12345)"`.
+4. **Prefer `Flow` Over `Loop` for Deterministic Sequences:**
+   - If the task is sequential and bounded, use a `Flow` agent. It is faster, cheaper, and far easier to audit. Use `Loop` only when iterative problem-solving with dynamic tool calling is required.
+5. **Never Hand-Edit `ID`, `lastModified`, or `checksum`:**
+   - Let `mj sync push` manage identity and sync checksums in `.agent.json` and `.prompt.json`. Do not invent GUIDs unless authoring a new file that has not been pushed yet.
+
+---
+
+## 5. Security Checklist (Enforce Before Syncing)
+
+- [ ] **No Secrets:** No API keys, credentials, bearer tokens, or passwords in prompt text or action parameters.
+- [ ] **Data Access via Entities:** All data operations must use MemberJunction entity permissions or standard actions. Never embed raw SQL statements in prompt templates.
+- [ ] **Human Confirmation on Writes:** In v1, any agent action that updates, inserts, or deletes records must require a confirmation step before committing.
+- [ ] **No PII in Templates:** Prompt templates and few-shot examples must use synthetic/generic data.
+
+---
+
+---
+
+## 6. The Complete 11-Step Agent Engineering Loop
+
+MemberJunction provides a machine-readable, agent-first surface. Always follow this full loop when designing and building agents:
+
+```
+ 1. Understand Intent  ──>  2. Discover Environment  ──>  3. Diagnostic Health Check
+                                                                   │
+ 6. Author Metadata    <──  5. Choose Pattern        <──  4. Reason & Plan
+       │
+ 7. Validate References ──> 8. Push DB Metadata      ──>  9. Run & Test Agent
+                                                                   │
+11. Package & Distribute <── 10. Audit Traces & Assert <───────────┘
+```
+
+### Step 1: Understand Business Intent
+Elicit requirements from the user. Clarify:
+- Inputs expected (e.g. customer ID, date range, message text).
+- Data sources involved (entities, views, existing actions).
+- Desired output format (markdown summary, structured JSON, draft email).
+- Whether operations involve read-only evaluation or write actions requiring confirmation.
+
+### Step 2: Progressive Capability Discovery (CLI & Metadata)
+Never guess entity names, fields, or available actions. Discover them directly:
+- **Read `CAPABILITIES.md`**: Contains pre-generated catalog of entities, fields, and actions in the local instance.
+- **Query Live Actions via CLI**:
+  ```bash
+  docker compose exec -T mj mj ai actions list --format json
+  ```
+- **Query Existing Agents & Prompts**:
+  ```bash
+  docker compose exec -T mj mj ai agents list --format json
+  ```
+- **Refresh Capabilities**:
+  ```bash
+  ./scripts/generate-capabilities.sh
+  ```
+
+### Step 3: Diagnostic Health & Prerequisite Checks
+Check that runtime services, database connectivity, and required AI keys are healthy:
+```bash
+docker compose exec -T mj mj doctor --format json
+```
+Filter by specific scopes if diagnosing an issue:
+```bash
+docker compose exec -T mj mj doctor --format json --scope ai       # Check AI provider API keys
+docker compose exec -T mj mj doctor --format json --scope runtime  # Check base encryption key & ports
+docker compose exec -T mj mj doctor --format json --scope install  # Check node, npm, and packages
+```
+If checks return warnings or failures with remediations (`Remediation.Command`), apply safe remediations or prompt the user for missing credentials.
+
+### Step 4: Reason & Plan the Configuration
+Determine:
+- Prompt decomposition: Is this a single-turn prompt or multi-step pipeline?
+- Context window management: What data must be retrieved, filtered, or summarized before prompting?
+- Error handling: For each step, should failures halt execution (`"OnError": "fail"`) or continue (`"OnError": "continue"`)?
+
+### Step 5: Select the Execution Pattern
+- **Single Prompt**: Lightweight classification, summarization, or single-entity extraction.
+- **Flow Agent (`Flow`)**: Best for deterministic, sequential, multi-step pipelines ("Step 1: Fetch order history -> Step 2: Compute risk score -> Step 3: Draft retention email"). Predictable, auditable, and low token overhead.
+- **Loop Agent (`Loop`)**: Iterative problem-solving requiring dynamic tool calling, multi-step reasoning, or exploratory querying.
+- **Orchestrator / Sub-Agent Tree**: Complex multi-domain tasks decomposed into specialist sub-agents (e.g., a triage agent dispatching to a risk agent and a billing agent).
+
+### Step 6: Author Declarative Metadata under `metadata/`
+Author files following the strict Section 2 rules:
+- Prompt template: `metadata/prompts/templates/<slug>.template.md`
+- Prompt definition: `metadata/prompts/.<slug>-prompt.json`
+- Agent definition: `metadata/agents/.<slug>-agent.json`
+*(Remember: native nested JSON objects for `Configuration`, `@lookup:` for foreign keys, `@file:` for templates, uppercase UUIDs for `primaryKey`, never author `sync` blocks).*
+
+### Step 7: Pre-Sync Schema & Reference Validation
+Before pushing:
+- Check that every `@lookup:` targets a valid entity and field (e.g. `MJ: AI Agent Types.Name=Flow`).
+- Check that `@file:` points to an existing `.template.md` file.
+- Verify JSON syntax is valid and unescaped.
+
+### Step 8: Push Metadata to Target Database
+Push declarative configuration to the local database:
+```bash
+./scripts/sync-metadata.sh
+```
+MetadataSync crawls the tree, resolves `@lookup:` and `@file:` references, upserts records, and stamps checksums.
+
+### Step 9: Run and Test the Agent
+Test the agent with representative test cases:
+- **Headless CLI execution**:
+  ```bash
+  docker compose exec -T mj mj ai agents run -a "<Agent Name>" -p "<Test Input>" --format json
+  ```
+- **Interactive UI testing**: Invite the user to test in their browser at `http://localhost:4202`.
+
+### Step 10: Audit Execution Traces & Assert Behavior
+Inspect the run trace to verify internal execution paths and safety:
+```bash
+# List recent runs
+./scripts/query-run-history.sh "<Agent Name>"
+
+# Audit specific run with full JSON trace
+./scripts/query-run-history.sh <RunID> --format json
+
+# Or inspect individual step details or errors
+./scripts/query-run-history.sh <RunID> --step 1 --detail full
+./scripts/query-run-history.sh <RunID> --errors
+```
+
+**Trace Verification Assertions**:
+- `actionsUsed`: Verify that the agent called the expected tools/actions.
+- `actionsNotUsed`: Verify that the agent did NOT invoke unauthorized or destructive actions.
+- `tokensUsed`: Verify token consumption is within reasonable bounds.
+- `stepSuccess`: Verify every step completed with status `Success`.
+
+### Step 11: Package for Promotion
+When verification passes:
+1. Run the **`package-agent` skill**.
+2. It validates Tier 1 guardrails, queries the latest run receipt from `[__mj].[vwAIAgentRuns]`, and generates `AGENT_MANIFEST.md`.
+3. It creates the distribution archive `dist/<agent-slug>-package.zip` containing the manifest and declarative metadata.
+4. Present the user with the package path and promotion instructions.
+
+---
+
+## 7. Available CLI Diagnostic & Execution Commands
+
+When operating in the container, use these native MemberJunction CLI commands (all support `--format json`):
+
+| Purpose | Command |
+|---|---|
+| **System Diagnostics** | `docker compose exec -T mj mj doctor --format json` |
+| **Scoped Diagnostics** | `docker compose exec -T mj mj doctor --format json --scope [install\|runtime\|ai\|metadata\|agent]` |
+| **List Available Actions** | `docker compose exec -T mj mj ai actions list --format json` |
+| **List Configured Agents** | `docker compose exec -T mj mj ai agents list --format json` |
+| **Execute Agent** | `docker compose exec -T mj mj ai agents run -a "<Name>" -p "<Prompt>" --format json` |
+| **Audit Agent Run** | `docker compose exec -T mj mj ai audit agent-run <RunID> --format json` |
+| **Audit Agent Step** | `docker compose exec -T mj mj ai audit agent-run <RunID> --step <N> --detail full` |
+| **Audit Errors Only** | `docker compose exec -T mj mj ai audit agent-run <RunID> --errors` |
+| **Sync Metadata** | `./scripts/sync-metadata.sh` |
+| **Run History Helper** | `./scripts/query-run-history.sh ["<Agent Name>"\|<RunID>] [--format json]` |
+| **Refresh Capabilities** | `./scripts/generate-capabilities.sh` |
+

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: