ashxtrem · Mar 21, 2026 · Mar 21, 2026 · Mar 21, 2026 · Mar 21, 2026
diff --git a/.cursor/rules/automflows.mdc b/.cursor/rules/automflows.mdc
@@ -0,0 +1,29 @@
+---
+description: AutoMFlows monorepo layout, Playwright install, workflow fixtures, link to AGENTS.md
+alwaysApply: true
+---
+
+# AutoMFlows (Cursor)
+
+**Operating contract:** read [AGENTS.md](../../AGENTS.md) first (install, verify commands, secrets, PR checklist).
+
+## Monorepo (npm workspaces)
+
+Root [package.json](../../package.json) workspaces: `backend`, `frontend`, `shared`, `mcp-server`. Prefer root scripts: `npm run lint`, `npm run type-check`, `npm test`, `npm run build`, `npm start`.
+
+Root `npm run type-check` builds `@automflows/shared` first (types come from `shared/dist`). If you run `tsc` / `type-check` only inside `backend`, `frontend`, or `mcp-server`, run `npm run build --workspace=shared` beforehand.
+
+## Playwright / postinstall
+
+[backend/package.json](../../backend/package.json) defines `postinstall`: `npx playwright install chromium`. It runs when backend dependencies install (e.g. root `npm ci`). The backend execution engine uses Playwright; integration tests may assume Chromium is available.
+
+## Workflow JSON and test resources
+
+- **Workflow fixtures:** primarily under `tests/workflows/` (e.g. `tests/workflows/demo/*.json`).
+- **Supporting data:** `tests/resources/` (JSON, CSV, env samples, etc.).
+
+Do not commit real secrets; use [`.env.example`](../../.env.example) for variable names only.
+
+## Deeper docs
+
+Topic index: [docs/agent/](../../docs/agent/) (repo map, testing, security, workflow, code style).
diff --git a/.env.example b/.env.example
@@ -0,0 +1,28 @@
+# Copy to .env and adjust locally. Do not commit real values.
+# See AGENTS.md and README.md for run instructions.
+#
+# Audit: backend (process.env), frontend (Vite + import.meta.env), mcp-server (process.env).
+# Only VITE_* keys are exposed to the browser bundle; everything else is server-side.
+
+# --- Backend (backend/) — process.env ---
+# NODE_ENV=development
+# PORT=3003
+# HOST=0.0.0.0
+# SWAGGER_ENABLED=true
+# API_BASE_URL=http://localhost:3000
+
+# --- Frontend (frontend/) — Vite ---
+# Used in vite.config.ts (process.env) and client code (import.meta.env.VITE_*).
+# VITE_BACKEND_PORT=3003
+#
+# Built into Vite (do not define in .env): import.meta.env.DEV, PROD, MODE, SSR, etc.
+
+# --- MCP server (mcp-server/) — process.env ---
+# AUTOMFLOWS_BACKEND_URL=http://localhost:3003
+# AUTOMFLOWS_WORKFLOWS_PATH=
+# AUTOMFLOWS_VERBOSE=false
+# LLM_PROVIDER=none
+# OPENAI_API_KEY=
+# OPENAI_MODEL=gpt-4
+# LOCAL_LLM_BASE_URL=http://localhost:11434
+# LOCAL_LLM_MODEL=llama3
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What does this PR change and why? -->
+
+## How to verify
+
+<!-- Commands you ran, e.g. npm run lint, npm test, manual steps -->
+
+- [ ] `npm run lint`
+- [ ] `npm run type-check`
+- [ ] `npm test` (or scoped tests if justified below)
+- [ ] `npm run build` (if types/build graph affected)
+
+## Notes
+
+<!-- Breaking changes, new env vars (update .env.example), security considerations -->
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run type-check
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
diff --git a/.gitignore b/.gitignore
@@ -5,7 +5,6 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
-package-lock.json
 yarn.lock
 pnpm-lock.yaml
 
@@ -43,8 +42,10 @@ blob-report/
 .env.production.local
 .env*.local
 
-# IDE
-.cursor/
+# IDE — track shared Cursor rules; ignore other local .cursor state
+.cursor/*
+!.cursor/rules/
+!.cursor/rules/**
 .vscode/
 .idea/
 *.swp

diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,2 @@
+npx lint-staged
+npm run type-check
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,88 @@
+# Agent and contributor guide
+
+This file is the operating contract for AI coding agents and humans working in this repo. For deeper topics, see [`docs/agent/`](docs/agent/) (read only what matches your task).
+
+## Core rules
+
+- Never commit secrets, API keys, or real `.env` files. Use [`.env.example`](.env.example) for variable names only.
+- Match existing code style — read neighboring files before adding new code.
+- Prefer small, reviewable changes with a clear way to verify (see commands below).
+- Run **lint → type-check → test → build** before opening a PR when your change affects code paths those checks cover.
+
+## Repository layout
+
+| Path | Role |
+|------|------|
+| `backend/` | Express API, Playwright execution engine, plugins |
+| `frontend/` | React + Vite + React Flow editor |
+| `shared/` | Shared TypeScript types and utilities (`@automflows/shared`) |
+| `mcp-server/` | Model Context Protocol server for IDE/AI integration |
+| `plugins/` | Optional plugin sources referenced by the frontend |
+| `tests/` | Workflow JSON fixtures and related test resources |
+| `scripts/` | Cross-platform start scripts (`npm start`) |
+
+Swagger / API docs (when enabled): backend serves `/api-docs` (see `SWAGGER_ENABLED` in [`.env.example`](.env.example)).
+
+## Install
+
+Reproducible install from the committed lockfile:
+
+```bash
+npm ci
+```
+
+Build shared (required before backend/frontend consume types from `shared`):
+
+```bash
+npm run build --workspace=shared
+```
+
+Or from repo root after `npm ci`:
+
+```bash
+cd shared && npm run build && cd ..
+```
+
+## Verify (non-interactive)
+
+Run from the **repository root**:
+
+| Step | Command |
+|------|---------|
+| Lint | `npm run lint` |
+| Lint with ESLint `--fix` (whole tree) | `npm run lint:fix` |
+| Typecheck (all workspaces) | `npm run type-check` (builds `@automflows/shared` first so `dist` types exist) |
+| Tests (workspaces that define `test`) | `npm test` |
+| Build (all workspaces) | `npm run build` |
+| Dependency audit (report) | `npm run audit` |
+| Dependency audit (safe fixes) | `npm run audit:fix` |
+
+**Git hooks:** `npm ci` runs `prepare`, which installs [Husky](https://typicode.github.io/husky/). On each commit, `.husky/pre-commit` runs [lint-staged](https://github.com/lint-staged/lint-staged) (ESLint with `--fix` on staged `backend|frontend|shared|mcp-server` `src/**/*.ts(x)` files), then `npm run type-check`.
+
+Workspace-only examples:
+
+- Backend tests: `npm run test --workspace=backend`
+- Frontend tests (watch during dev): `npm run test:watch --workspace=frontend`
+- Frontend one-shot tests: `npm run test --workspace=frontend`
+
+## Run the app
+
+```bash
+npm start
+```
+
+See [`README.md`](README.md) for ports, Docker, and LAN options.
+
+## Where to read more
+
+| Topic | Doc |
+|-------|-----|
+| Repo map and boundaries | [`docs/agent/repo-map.md`](docs/agent/repo-map.md) |
+| Tests and tooling | [`docs/agent/testing.md`](docs/agent/testing.md) |
+| Security-sensitive changes | [`docs/agent/security.md`](docs/agent/security.md) |
+| Branch / PR workflow | [`docs/agent/workflow.md`](docs/agent/workflow.md) |
+| Style and structure | [`docs/agent/code-style.md`](docs/agent/code-style.md) |
+| Agent workflow sequence | [`docs/agent/agent-protocol.md`](docs/agent/agent-protocol.md) |
+| Score audit & backlog | [`docs/agent/SCORE_REPORT.md`](docs/agent/SCORE_REPORT.md), [`docs/agent/TASKS.md`](docs/agent/TASKS.md) |
+
+Human-focused contribution conventions: [`CONTRIBUTING.md`](CONTRIBUTING.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,31 @@
+# Contributing to AutoMFlows
+
+Thank you for contributing. This document complements [`AGENTS.md`](AGENTS.md), which is the primary guide for agents and day-to-day development commands.
+
+## Getting started
+
+1. Fork and clone the repository.
+2. Install dependencies: `npm ci` (uses the committed lockfile).
+3. Build shared types: `npm run build --workspace=shared`.
+4. Run the app: `npm start` — see [`README.md`](README.md) for details.
+
+## Development workflow
+
+- Create a branch from `main` (or the default development branch) with a clear name.
+- Keep commits focused; write messages that explain *why*, not only *what*.
+- Before opening a PR, run the checks in [`AGENTS.md`](AGENTS.md) (`lint`, `type-check`, `test`, `build` as appropriate).
+
+## Pull requests
+
+- Use the [pull request template](.github/pull_request_template.md).
+- Describe user-visible changes and the verification steps you ran.
+- Update documentation (`README`, `AGENTS`, or `docs/agent/`) when behavior or env vars change.
+
+## Code review
+
+- Respond to review feedback with additional commits or comments as needed.
+- Avoid force-pushing unless coordinated with reviewers.
+
+## Security
+
+- Do not commit secrets. Follow [`docs/agent/security.md`](docs/agent/security.md).
diff --git a/README.md b/README.md
@@ -78,10 +78,10 @@ git clone https://github.com/ashxtrem/AutoMFlows.git
 cd AutoMFlows
 ```
 
-2. Install dependencies:
+2. Install dependencies (use `npm ci` for a reproducible install from the committed lockfile; use `npm install` when adding or updating dependencies):
 
 ```bash
-npm install
+npm ci
 ```
 
 3. Build shared package:
@@ -159,6 +159,11 @@ AutoMFlows supports plugins for custom nodes. Built-in plugins include:
 
 See [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md) for details.
 
+## Contributing
+
+- **[AGENTS.md](AGENTS.md)** — commands, layout, and verification for contributors and coding agents.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — workflow and PR expectations.
+
 ## Repository
 
 - **GitHub**: [https://github.com/ashxtrem/AutoMFlows](https://github.com/ashxtrem/AutoMFlows)

diff --git a/backend/package.json b/backend/package.json
@@ -29,7 +29,7 @@
     "ioredis": "^5.4.1",
     "mongodb": "^6.3.0",
     "mssql": "^11.0.1",
-    "multer": "^2.0.2",
+    "multer": "^2.1.1",
     "mysql2": "^3.9.0",
     "nodemailer": "^8.0.1",
     "oracledb": "^6.7.0",

diff --git a/docs/agent/SCORE_LOG.md b/docs/agent/SCORE_LOG.md
@@ -0,0 +1,12 @@
+# Score log (Foundry-style dimensions)
+
+One row per audit. Re-score without Foundry CLI: see [`SCORE_REPORT.md`](./SCORE_REPORT.md).
+
+| Date | Overall /10 | Agent docs | Cursor rules | Verify | Types | PR/docs | Lockfile | Pre-commit | CI | Env | ESLint hygiene | Lint coverage | Security doc | Notes |
+|------|-------------|------------|--------------|--------|-------|---------|----------|------------|----|-----|----------------|---------------|--------------|--------|
+| 2026-03-21 | 8.3 | strong | weak | strong | strong | strong | strong | strong | strong | partial | partial | partial | weak | [`SCORE_REPORT.md`](./SCORE_REPORT.md), [`TASKS.md`](./TASKS.md) |
+
+### Legend
+
+- **strong / partial / weak** — qualitative band from the AI-readiness style rubric.
+- **Overall** — informal composite (not from automated tooling).
diff --git a/docs/agent/SCORE_REPORT.md b/docs/agent/SCORE_REPORT.md
@@ -0,0 +1,56 @@
+# AutoMFlows — AI readiness score report
+
+**Method:** Manual audit aligned with Foundry’s `ai_readiness` rubric (`foundry_og/.../scoring/rules/legacy/ai_readiness/ai_readiness-llm-deep.md`). **No Foundry CLI.**
+
+**Audit date:** 2026-03-21
+
+## Summary
+
+| Metric | Value |
+|--------|--------|
+| **Overall (informal)** | **8.3 / 10** — strong agent contract, verify commands, CI, lockfile; follow-ups below. |
+| **Baseline (pre-improvements)** | ~5.5 / 10 (no `AGENTS.md`, no root `test`, lockfile ignored, no CI). |
+
+## Dimension scores
+
+Ratings: **strong** / **partial** / **weak**. Informal 1–10 in parentheses for trend tracking.
+
+| # | Dimension | Rating | /10 | Evidence |
+|---|-----------|--------|-----|----------|
+| 1 | Agent instructions (`AGENTS.md`, topic docs) | strong | 9 | [`AGENTS.md`](../../AGENTS.md), [`docs/agent/`](./) |
+| 2 | Editor-specific rules (e.g. `.cursor/rules`) | weak | 4 | None yet; optional |
+| 3 | Non-interactive verify (`lint`, `type-check`, `test`, `build`) | strong | 9 | Root [`package.json`](../../package.json), documented in `AGENTS.md` |
+| 4 | Type safety (TS strict + ESLint project) | strong | 9 | `tsconfig`, [`frontend/tsconfig.eslint.json`](../../frontend/tsconfig.eslint.json) |
+| 5 | Contribution / PR clarity | strong | 9 | [`CONTRIBUTING.md`](../../CONTRIBUTING.md), [PR template](../../.github/pull_request_template.md) |
+| 6 | Reproducible dependencies | strong | 9 | [`package-lock.json`](../../package-lock.json) committed; `npm ci` in README |
+| 7 | Pre-commit gates | strong | 8 | `lint` + `type-check` (tests not on every commit — intentional) |
+| 8 | CI | strong | 9 | [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) |
+| 9 | Env / secrets documentation | partial | 7 | [`.env.example`](../../.env.example); needs maintenance as code adds vars |
+| 10 | ESLint signal-to-noise | partial | 6 | ~1300+ warnings, 0 errors; agents see noisy output |
+| 11 | Lint coverage of all packages | partial | 6 | ESLint targets `backend/src`, `frontend/src` only — not `mcp-server/`, `shared/` |
+| 12 | Security disclosure process | weak | 5 | No `SECURITY.md` / reporting template |
+
+## Strengths
+
+- Single place to start ([`AGENTS.md`](../../AGENTS.md)) and repeatable verify line: `npm run lint && npm run type-check && npm test && npm run build`.
+- CI mirrors local checks.
+- Lockfile gives deterministic installs for agents and CI.
+
+## Gaps (drive [TASKS.md](./TASKS.md))
+
+1. Optional **Cursor** rules for monorepo/Playwright conventions.
+2. **ESLint warnings** — reduce over time (especially `no-explicit-any` hotspots).
+3. **`.env.example`** — keep aligned with `process.env` usage (audit when touching config).
+4. **ESLint** — extend to `shared/` and `mcp-server/` or document why excluded.
+5. **`SECURITY.md`** — vulnerability reporting for a public OSS repo (optional).
+
+## How to re-score (no Foundry CLI)
+
+1. Walk the Markdown rubrics in `foundry_og` manually, or  
+2. Paste a rubric into an AI chat with “audit this repo with file citations,” or  
+3. Append a row to [`SCORE_LOG.md`](./SCORE_LOG.md) after changes.
+
+## References (external)
+
+- `foundry_og/src/foundry/scoring/rules/legacy/ai_readiness/ai_readiness-llm-deep.md`
+- Other dimensions: `testing`, `security`, `cicd`, `documentation`, etc.
diff --git a/docs/agent/TASKS.md b/docs/agent/TASKS.md
@@ -0,0 +1,39 @@
+# Task backlog (post–score improvements)
+
+Prioritized follow-ups from [`SCORE_REPORT.md`](./SCORE_REPORT.md). Check items off as you complete them.
+
+## P1 — High value for agents and maintainers
+
+- [x] **Add `.cursor/rules`** (or equivalent) with AutoMFlows-specific notes: monorepo workspaces, Playwright/postinstall, where workflow JSON lives, link to `AGENTS.md`.
+- [x] **Audit `process.env` / `import.meta.env`** usage and update [`.env.example`](../../.env.example) so every supported variable is listed (commented).
+- [x] **ESLint coverage:** extend [`eslint.config.js`](../../eslint.config.js) to include `shared/src` and `mcp-server/src` (or document in [`code-style.md`](./code-style.md) why they are excluded and add a scoped script).
+
+## P2 — Quality and noise reduction
+
+- [ ] **Reduce ESLint warnings** in batches (e.g. by folder or rule): start with `no-explicit-any` in `frontend/src/utils` or high-churn modules.
+- [ ] **Optional:** add `npm run lint -- --max-warnings <N>` in CI once warnings drop below a threshold (or keep 0 errors only).
+- [ ] Run **`npm audit`** (or `npm audit fix` where safe) and document any accepted risks in PR notes.
+
+## P3 — Security and community
+
+- [ ] Add root **`SECURITY.md`** with supported versions and how to report vulnerabilities (even if email/GitHub Security Advisories only).
+- [ ] **Optional:** enable **Dependabot** or **Renovate** for `package-lock.json` (`.github/dependabot.yml`).
+
+## P4 — Deeper Foundry-style rubrics (periodic)
+
+- [x] Run through **`testing`** `testing-llm-deep.md` in `foundry_og` (knowledge base only; no Foundry CLI) — gaps filed below.
+- [ ] Run through **`security`** rubric after any auth/execution/plugin change.
+
+### Foundry `testing-llm-deep.md` — filed gaps (AutoMFlows)
+
+Rubric source: `foundry_og/src/foundry/scoring/rules/legacy/testing/testing-llm-deep.md`. **Strengths:** many `__tests__` suites (backend Jest + frontend Vitest + RTL), route and Playwright-backed integration tests under `backend/src/__tests__/integration/`, `jest.config.js` / `vitest.config.ts` present, frontend **coverage thresholds** (80%) defined in Vitest config.
+
+- [ ] **P4-T1 — Enforce coverage in CI** — Default `npm test` runs Jest/Vitest without coverage; frontend thresholds in `frontend/vitest.config.ts` only apply when using `test:coverage`. CI (`.github/workflows/ci.yml`) does not run coverage or fail on gates. *Rubric:* “Coverage report in CI artifacts without a threshold is measurement only.”
+- [ ] **P4-T2 — Backend Jest coverage gate** — `backend/jest.config.js` sets `coverageReporters` but no `coverageThreshold`; `test:coverage` is opt-in. *Rubric:* prefer `--cov-fail-under` / `coverageThreshold`-style enforcement aligned with product goals (can ratchet over time).
+- [ ] **P4-T3 — Tests for `shared/` and `mcp-server`** — Workspaces have no `test` script; monorepo tests skip them silently. *Rubric:* meaningful automated tests appropriate for package type (even small unit tests for exported helpers/types).
+- [ ] **P4-T4 — Document or add full-stack E2E** — Playwright is used for engine/handler tests with HTML fixtures, not for “start API + browser UI” product E2E. *Rubric:* e2e may live elsewhere — document in `README` / `docs/agent/testing.md` if intentional, or add a minimal smoke path later.
+- [ ] **P4-T5 — Optional frontend depth** — No Storybook interaction tests or visual regression (Percy/Chromatic). *Rubric:* nice-to-have for frontends; skip or backlog explicitly if out of scope.
+
+---
+
+*Last synced with score audit: 2026-03-21*