jetic-cli 0.2.0 → 0.2.2

package/README.md

@@ -1,583 +1,156 @@
 <p align="center">
-  <img src="public/jetic_white_bg.png" alt="Jetic Banner" width="160">
+  <img src="public/jetic_white_bg.png" alt="Jetic Banner" width="140">
 </p>
 
-<h1 align="center">Jetic </h1>
+<h1 align="center">Jetic CLI</h1>
 
 <p align="center">
-  <strong>AI-Native API Behavior Testing, Discovery & Observability Platform — Command-Line Interface</strong>
+  <strong>AI-Native API Behavior Testing, Discovery & Simulation Platform</strong>
 </p>
 
 <p align="center">
-  <em>Scan backend source code → Extract behavioral models → Synthesize & run stateful AI workflows → Inspect visual traces</em>
+  <em>Zero-config static source scanning → Behavioral model graph → Automated API simulations & Visual Traces</em>
 </p>
 
 <p align="center">
-  <a href="#-key-features">Features</a> •
-  <a href="#-how-jetic-works">How It Works</a> •
-  <a href="#-getting-started">Getting Started</a> •
-  <a href="#-demo">Demo</a> •
-  <a href="#-start-with-your-ai-ide-recommended-no-ai-key">AI IDE Setup</a> •
-  <a href="#-cli-command-reference">CLI Reference</a> •
-  <a href="#-jetic-studio-dashboard">Jetic Studio</a> •
-  <a href="#-artifact--file-schemas">File Schemas</a>
+  <a href="#-quickstart">Quickstart</a> •
+  <a href="#-the-4-phase-workflow">4-Phase Workflow</a> •
+  <a href="#-ai-ide-integration-mcp">AI IDE Setup</a> •
+  <a href="#-cli-commands">CLI Reference</a> •
+  <a href="#-jetic-studio">Jetic Studio</a>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/jetic-cli"><img src="https://img.shields.io/npm/v/jetic-cli.svg" alt="NPM Version"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen" alt="Node Version">
-  <img src="https://img.shields.io/badge/pnpm-%3E%3D9.0.0-orange" alt="PNPM Workspace">
   <img src="https://img.shields.io/badge/AST-ts--morph-blueviolet" alt="ts-morph">
   <img src="https://img.shields.io/badge/license-ISC-green.svg" alt="License">
 </p>
 
 ---
 
-## 🎬 Demo
+## ⚡ Quickstart
 
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=YOUR_VIDEO_ID">
-    <img src="../../screenshots/jetic_overview.JPG" alt="Watch the Jetic demo video" width="720">
-  </a>
-</p>
-
-<!-- TODO: paste the real demo video ID above (replace YOUR_VIDEO_ID).
-     Optionally swap the thumbnail for a dedicated screenshots/demo-thumbnail.png. -->
-
----
-
-## ⚡ The Problem
-
-Traditional API testing tools (Postman, Insomnia, generic test runners) force developers to manually write hundreds of repetitive test scripts, hardcode authorization tokens, guess parameter validation limits, and painstakingly string together sequential operations (*Register User → Login → Save Token → Create Resource → Update Resource → Delete Resource*).
-
-Furthermore, conventional HTTP runners only check if an endpoint returns a `200 OK`. They do **not** understand what your API is actually *supposed* to do, what business constraints govern your handlers, or how state flows across endpoint boundaries.
-
----
-
-## 💡 The Jetic Solution
-
-**`jetic-cli`** is an agentic, code-native developer platform that **automatically understands, models, simulates, and traces an application's API behavior directly from its backend source code.**
-
-1. 🔍 **Zero-Execution Source Code Scanning**: Jetic parses your TypeScript/Express Abstract Syntax Tree (AST via `ts-morph`) without running your server. It follows imports across controllers, services, middleware, and type declarations to discover routes, parameters, validation constraints, and auth schemes.
-2. 🧠 **Declarative Behavioral Graph (`model.json`)**: Generates a versioned, strongly-typed behavioral graph mapping paths, HTTP methods, request schemas, response shapes, and exact source code provenance (file + line numbers).
-3. 🤖 **AI-Driven Stateful Workflow Generation**: Uses AI to synthesize multi-step, end-to-end user journeys (`.jetic/workflows/*.json`).
-4. 💾 **Pre/Post State Capture & Dynamic Injection**: Captures input parameters (like faker-generated email/password) before HTTP calls and response fields (like JWT tokens and resource IDs via JSONPath) after HTTP calls into `.jetic/memory.json`, automatically injecting them into subsequent headers (e.g. `Authorization: Bearer {{workflow:accessToken}}`) or body fields.
-5. 📈 **Embedded Jetic Studio Dashboard**: Serves the local developer web IDE via `jetic dev` for visual API exploration, AST source code viewing, real-time SSE workflow execution, runtime memory editing, and ReactFlow trace graph visualizer.
-
-> [!NOTE]
-> **Framework & Language Support**: Automated AST source code scanning currently supports **Node.js & Express (TypeScript)** projects.
-> For backends built with other languages or frameworks (e.g., Python/FastAPI, Go, Rust, Java, NestJS), you can manually add and manage endpoints directly inside **Jetic Studio** on the **Behavioral Model** page (`/model`) using the **"Add Endpoint"** button.
-> **Easiest option for any stack**: use the [AI IDE setup below](#-start-with-your-ai-ide-recommended-no-ai-key) — your editor's AI reads the code and authors the model through Jetic MCP tools, no scanner or AI key required.
-
----
-
-## ✨ Key Features
-
-- 🔍 **AST Source Discovery**: Deeply inspects Express/TypeScript source code using `ts-morph`. Recursively resolves imported controllers, services, helpers, and types up to configurable depths.
-- 🧩 **Nested Router & Middleware Resolution**: Seamlessly flattens complex nested Express router chains (e.g. `app.use('/api/orders', ordersRouter)` $\rightarrow$ `router.post('/checkout')`).
-- 🧠 **Constraint & Business Logic Extraction**: Extracts validation logic directly from `if` statements (e.g. `if (password.length < 8)` $\rightarrow$ `minLength: 8`) and schema definitions, enabling intelligent data generation rather than blind fuzzing.
-- 🔗 **Stateful Workflow Engine**: Synthesizes and executes multi-step workflows with full variable interpolation, auto-generating dynamic test data via `@faker-js/faker`.
-- 📥 **Input & Output Memory Capture**:
-  - `captureInput`: Saves generated request body values (e.g. `admin_email`) to `.jetic/memory.json` *before* firing requests so subsequent steps can reuse them.
-  - `capture`: Saves response JSONPath fields (e.g. `data.accessToken`, `data.workspace.id`) to `.jetic/memory.json` *after* success.
-  - `inject`: Automatically injects memory values into headers (e.g. `header:Authorization = Bearer {{workflow:accessToken}}`) or body fields.
-- 🖥️ **Jetic Studio Dashboard**: Modern React 19 + Vite + TailwindCSS + ReactFlow local developer web IDE (`jetic dev`) for visual API exploration, AST source code viewing, real-time SSE workflow execution, runtime memory editing, and node-graph trace debugging.
-- 💻 **Feature-Rich CLI Command Suite**: Lightweight command-line interface bringing API intelligence, scanning, simulation, memory control, and config management straight to your terminal.
-
----
-
-## ⚙️ How Jetic Works
-
-```
- ┌────────────────────────┐
- │  Backend Source Code   │ (TypeScript / Express)
- └───────────┬────────────┘
-             │
-             ▼
- ┌────────────────────────┐
- │   packages/scanner     │ (AST parsing via ts-morph & ImportResolver)
- └───────────┬────────────┘
-             │
-             ▼
- ┌────────────────────────┐
- │  .jetic/model.json     │ (Behavioral Model: Endpoints, Schemas, Constraints, Auth, Source Provenance)
- └───────────┬────────────┘
-             │
-      ┌──────┴───────────────────────────┐
-      ▼                                  ▼
-┌──────────────┐             ┌────────────────────────┐
-│  jetic scan  │             │  jetic simulate        │ (Single-endpoint or AI Workflows)
-└──────────────┘             └───────────┬────────────┘
-                                         │
-                    ┌────────────────────┴───────────────────┐
-                    ▼                                        ▼
-      ┌─────────────────────────┐               ┌────────────────────────┐
-      │  .jetic/memory.json     │               │  Jetic Studio         │
-      │  (Capture & Inject State)│               │  (/traces Observability)│
-      └─────────────────────────┘               └────────────────────────┘
-```
-
-1. **Scan (`jetic scan`)**: `ExpressScanner` and `ImportResolver` inspect your project root and `tsconfig.json`. They extract route paths, parameters, middleware chains, controller logic, and TypeScript types.
-2. **Model (`.jetic/model.json`)**: Normalizes scanner output into a strongly typed `BehavioralModel` containing endpoint metadata, discovered constraints, expected request/response schemas, security schemes, and source references (`routes/auth.ts:42`).
-3. **Synthesize Workflows (`jetic simulate workflow`)**: AI analyzes `model.json` to create end-to-end integration workflows. Step dependencies, input/output captures, and header injections are configured automatically.
-4. **Run & Capture / Inject**: The simulator engine executes requests step-by-step. `captureInput` saves faker credentials pre-flight, `capture` reads response JSONPath fields post-flight, and `inject` dynamically constructs request headers/bodies for downstream steps.
-5. **Trace & Observe**: Results are persisted as execution trace records and rendered in **Jetic Studio** (`/traces`) as an interactive ReactFlow node graph.
-
-> [!TIP]
-> **No AI key? Any backend stack? Skip the terminal AI commands.** Connect [`jetic mcp`](#jetic-mcp) to your AI code editor and let the agent do the same flow conversationally — it reads your code, builds `model.json`, authors workflows, and runs them, using your editor's own model. See [Start with Your AI IDE](#-start-with-your-ai-ide-recommended-no-ai-key).
-
----
-
-## 🚀 Getting Started
-
-### Prerequisites
-
-- **Node.js**: `v20.0.0` or higher
-- **pnpm** / **npm** / **yarn**
-
-### Installation
-
-Install `jetic-cli` globally via npm:
+Get started in under **60 seconds** — **no AI keys or third-party provider setup required**.
 
+### 1. Install globally
 ```bash
 npm install -g jetic-cli
 ```
 
-Or run directly using `npx`:
-
-```bash
-npx jetic-cli --help
-```
-
-> [!NOTE]
-> **Package Name vs Executable Command**: The CLI package is published on NPM as **`jetic-cli`** (`npm install -g jetic-cli`). Once installed, npm registers the **`jetic`** binary executable command in your system `PATH` so you can directly run `jetic init`, `jetic scan`, `jetic dev`, etc.
-
-### Start with Your AI IDE (Recommended, No AI Key)
-
-The fastest way to use Jetic is **through the AI assistant already inside your code editor** — opencode, Antigravity, Cursor, Claude Code, Windsurf, or VS Code. Your editor's model drives Jetic's 18 MCP tools directly: **no OpenRouter/OpenAI key, no `jetic config ai`, and no `jetic scan` needed to begin**. This path also works for **any backend stack** (Express, FastAPI, Go, Java, NestJS…), because the AI reads your code and models it via MCP.
-
-#### Step 1 — Initialize your backend (10 seconds, once per project)
-
+### 2. Initialize & Scan your backend
+Navigate to your backend project directory (e.g., Express + TypeScript):
 ```bash
-cd path/to/your-backend
+# Scaffold .jetic/ directory
 jetic init
-```
-
-#### Step 2 — Connect the MCP server to your editor (once per editor)
-
-opencode (`opencode.json` — global or project root):
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "jetic": {
-      "type": "local",
-      "command": ["cmd", "/c", "jetic", "mcp"],
-      "cwd": "C:/path/to/your-backend",
-      "enabled": true
-    }
-  }
-}
-```
-
-> Windows needs `cmd /c` (npm shims are `.cmd` files); on macOS/Linux use `"command": ["jetic", "mcp"]`. Point `cwd` at your backend root so Jetic finds `.jetic/model.json`. Using Antigravity, Cursor, Claude Code/Desktop, Windsurf, or VS Code? Same `jetic mcp` server — per-editor snippets live in the [mcp-server guide](https://github.com/jeticlabs/Jetic/tree/main/packages/mcp-server).
-
-Restart the editor (or refresh its MCP panel) and confirm the `jetic_*` tools appear.
 
-#### Step 3 — Onboard with copy-paste prompts 💬
-
-Paste these into your editor's agent chat, in order:
-
-**1. Meet Jetic** — *first message in a fresh project:*
-> I've installed the Jetic MCP tools. Summarize what you can do with them, then read my project's model summary and tell me what's in it.
-
-**2. Re-analyse the whole project** — *builds your entire `model.json` from code:*
-> Help me re-analyse the whole project: find ALL API endpoints in this codebase — routes, controllers, middleware, auth guards, request/response shapes — and add every missing endpoint to my .jetic/model.json using the jetic tools. Include security, middleware chains, parameters, and response schemas. When done, run jetic_verify_model and fix all errors.
-
-**3. Zoom into one area** — *repeat per module until coverage is complete:*
-> Analyse ONLY src/modules/payments: add/update all of its endpoints in the model with full detail (middleware, auth, validation constraints), then verify.
-
-**4. Create a workflow** — *the agent validates before saving, then runs it:*
-> Help create a workflow called "Shopper checkout" with these steps: (1) register a user with a faker email and capture the credentials, (2) log in and capture the access token, (3) create an order with the Bearer token and expect 201. Validate it BEFORE saving, then save it and simulate it against http://localhost:3000.
-
-**5. Negative / conditional test** — *expect a specific status:*
-> Help create a workflow called "Forbidden admin action" where a normal non-admin user logs in and calls DELETE /api/admin/users/:id expecting 403. Validate, save, and simulate it.
-
-**6. Live-test & verify loop** — *anytime your API changes:*
-> Test POST /api/auth/login against my local server at http://localhost:4000 with a realistic payload and tell me whether the response matches the model. Then verify the whole model and fix any issues.
-
-Behind the scenes the agent follows the structured order — `jetic_init` (first time in a repo), `jetic_scan` for Express or `jetic_add_endpoint` per endpoint otherwise (middleware, security, constraints), `jetic_verify_model`, then `jetic_validate_workflow` → `jetic_create_workflow` → `jetic_simulate_workflow`. If a step fails, just paste the error back — the validation messages say exactly how to fix it.
-
-### Quickstart — Terminal Flow (Needs an AI Key)
-
-Prefer the terminal, or want Express auto-discovery? This flow uses `jetic scan` plus AI workflow generation, which requires your own AI provider key (`jetic config ai`). The [AI IDE path above](#-start-with-your-ai-ide-recommended-no-ai-key) needs no key.
-
-Navigate to your TypeScript/Express backend directory:
-
-```bash
-# 1. Initialize Jetic workspace directory (.jetic/)
-jetic init
-
-# 2. Configure AI credentials for workflow generation (OpenRouter or OpenAI)
-# Windows PowerShell: $env:OPENROUTER_API_KEY="your-key"
-# Linux/macOS: export OPENROUTER_API_KEY="your-key"
-jetic config ai --provider openrouter --model anthropic/claude-3.5-sonnet --key-env OPENROUTER_API_KEY
-
-# 3. Scan source code and generate .jetic/model.json
-jetic scan
-
-# 4. Inspect discovered API model and AST source code provenance
-jetic inspect
-
-# 5. Run AI workflow simulation against live local backend
-jetic simulate workflow --goal "Admin registers workspace, logs in, creates class and logs out"
-
-# 6. Launch Jetic Studio local web dashboard
-jetic dev
-```
-
----
-
-## 💻 CLI Command Reference
-
-### `jetic init`
-Initializes a `.jetic/` directory in the current working directory with a default `config.json`.
-
-```bash
-jetic init
-```
-
----
-
-### `jetic scan`
-Parses backend source code (via `tsconfig.json` and AST resolution), extracts endpoints, schemas, constraints, and source provenance, and writes `.jetic/model.json`.
-
-```bash
+# Static AST scan of backend source code to build .jetic/model.json
 jetic scan
 ```
 
----
-
-### `jetic inspect`
-Displays summary metrics or deep inspection details for discovered API endpoints.
-
-```bash
-# Display project summary (endpoint count, methods breakdown, security rules)
-jetic inspect
-
-# Inspect a specific endpoint (shows AST source provenance, parameters, response schema)
-jetic inspect endpoint GET /api/orders/:id
-```
-
----
-
-### `jetic simulate endpoint`
-Simulates single endpoints or the entire API model against a target environment server using generated data.
-
-```bash
-# Simulate all endpoints in model.json
-jetic simulate endpoint --all
-
-# Simulate a specific endpoint with detailed response logs
-jetic simulate endpoint POST /api/auth/login --verbose
-
-# Run simulations against a specific environment defined in model.json
-jetic simulate endpoint --all --env staging
-```
-
----
-
-### `jetic simulate workflow`
-Generates and executes multi-step AI-driven workflow integration tests with automatic state capture and header injection.
-
-```bash
-# Generate and run an AI workflow for a custom natural-language goal
-jetic simulate workflow --goal "User signs up, verifies email, creates project, and invites member"
-
-# List all saved workflows in .jetic/workflows/
-jetic simulate workflow --list
-
-# Execute an existing workflow JSON file
-jetic simulate workflow --workflow .jetic/workflows/user-onboarding.json
-
-# Generate workflow JSON without running HTTP requests
-jetic simulate workflow --goal "Create order and pay" --generate-only
-
-# Clear runtime memory before executing
-jetic simulate workflow --workflow .jetic/workflows/user-onboarding.json --clear-memory
-```
-
----
-
-### `jetic dev`
-Starts the **Jetic Studio** backend API server and serves the local web dashboard interface.
-
+### 3. Launch Jetic Studio or connect your AI IDE
 ```bash
-# Launch Jetic Studio on default port 8787
+# Option A: Launch the visual developer dashboard (http://localhost:8787)
 jetic dev
 
-# Launch Jetic Studio on a custom port
-jetic dev --port 9000
-```
-
----
-
-### `jetic memory`
-Views and manages key-value entries stored in `.jetic/memory.json`.
-
-```bash
-# List all stored memory keys and values across scopes
-jetic memory list
-
-# Get value for a key (defaults to global scope or specify scope:key)
-jetic memory get workflow:accessToken
-
-# Set a key-value entry
-jetic memory set workflow:accessToken "eyJhbGciOi..."
-
-# Delete a key
-jetic memory delete workflow:accessToken
-
-# Clear all stored memory
-jetic memory clear
-```
-
----
-
-### `jetic mcp`
-Launches the **Jetic Model Context Protocol (MCP) Server** over stdio, giving the AI assistant inside your code editor 18 typed tools to inspect, author, validate, and live-test endpoints and workflows — no AI key needed (the editor's own model is used).
-
-```bash
-# Launch MCP Server over stdio (uses current directory as project root)
+# Option B: Run MCP server for AI IDE assistant (Cursor, Antigravity, VS Code, opencode)
 jetic mcp
-
-# Pin to a project explicitly (same as JETIC_PROJECT_PATH env var)
-jetic mcp --project C:/path/to/your-backend
 ```
 
-> **Start here instead:** [Start with Your AI IDE](#-start-with-your-ai-ide-recommended-no-ai-key) — install, one `jetic init`, one editor config snippet, and copy-paste chat prompts. Per-editor configs (opencode, Antigravity, Cursor, Claude Code/Desktop, Windsurf, VS Code): [mcp-server guide](https://github.com/jeticlabs/Jetic/tree/main/packages/mcp-server).
-
-#### MCP Tools Provided to IDE Assistants (18 — structured order: init → model → simulate):
-- **Setup**: `jetic_init` (scaffold `.jetic/` for new repos, detects Express) · `jetic_scan` (keyless Express+TS auto-scan, merge keeps hand-added endpoints)
-- **Read**: `jetic_read_model` (full model or summary) · `jetic_list_endpoints` (filter by method/tag/resource/path) · `jetic_get_endpoint` (full structural detail) · `jetic_verify_model` (duplicates, unbound params, bad status codes, dangling sources) · `jetic_list_workflows`
-- **Author endpoints** (full fidelity: middleware chains, security, pagination, rate limits, ownership, produces/consumes, constraints): `jetic_add_endpoint` · `jetic_update_endpoint` · `jetic_delete_endpoint` · `jetic_manage_environment`
-- **Author workflows** (validate → create → simulate loop with memory data-flow checks): `jetic_validate_workflow` · `jetic_create_workflow` · `jetic_update_workflow` · `jetic_delete_workflow`
-- **Run live** (needs a running server): `jetic_test_endpoint` (custom headers/body/query supported) · `jetic_simulate_workflow` (+ `jetic_simulate` alias)
-
 ---
 
-### `jetic config`
-Configures AI providers, API key environment variables, and project settings.
+## 🔄 The 4-Phase Workflow
 
-```bash
-# Interactively or explicitly configure AI provider settings
-jetic config ai --provider openrouter --model anthropic/claude-3.5-sonnet --key-env OPENROUTER_API_KEY
+Jetic operates on a strict, predictable 4-phase lifecycle for total model fidelity:
 
-# View current configuration
-jetic config list
 ```
-
----
-
-### `jetic upgrade`
-Checks for updates and upgrades Jetic dependencies across the workspace.
-
-```bash
-jetic upgrade
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│ 1. INITIALIZE   │ ──► │ 2. SCAN & MODEL │ ──► │ 3. VERIFY       │ ──► │ 4. SIMULATE     │
+│ (jetic init)    │     │ (jetic scan)    │     │ (jetic verify)  │     │ (jetic simulate)│
+└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
 ```
 
----
-
-## 🖥️ Jetic Studio Dashboard
-
-**Jetic Studio** (`jetic dev`) is a sleek, dark-mode local web application designed specifically for visual API discovery, source provenance checking, AI workflow debugging, runtime memory control, and visual trace observability.
-
----
-
-### 1. 📊 Workspace Overview (`/overview`)
-The command center for your API model. Provides high-level metrics, endpoint distribution charts, security posture summaries, and quick links to recently discovered routes and workflow runs.
-
-- **Key Highlights**: Endpoint totals, method breakdown bar, secured route percentages, recent endpoint shortcuts, active workflow list, and top memory keys preview.
-
-![Jetic Studio - Workspace Overview](../../screenshots/jetic_overview.JPG)
-
----
-
-### 2. 🧩 Behavioral Model (`/model`)
-Interactive visual explorer for `.jetic/model.json`.
-
-- **Key Highlights**: HTTP method filtering (GET, POST, PUT, DELETE, PATCH), full-text search, request/response schema inspection cards, security badges (JWT, Bearer, API Keys), middleware lists, environment switcher, and instant **Inspect** trigger buttons.
-- **Manual Endpoint Creation ("Add Endpoint")**: For non-Express/TypeScript projects or custom routes, click the **"Add Endpoint"** button to manually define HTTP methods, paths, parameters, schemas, and authentication requirements directly from the interface.
-
-![Jetic Studio - Behavioral Model](../../screenshots/jetic_model_list.JPG)
-
-![Jetic Studio - Add Endpoint Modal Placeholder](../../screenshots/jetic_add_endpoint.JPG)
+1. **Phase 1 — Initialize (`jetic init`)**: Scaffolds the `.jetic/` directory and empty `model.json` in your project root.
+2. **Phase 2 — Scan & Model (`jetic scan`)**: Keyless AST scan parses routes, controllers, middleware, and TypeScript interfaces. For non-Express backends (FastAPI, Go, NestJS), endpoints can be added manually or via MCP.
+3. **Phase 3 — Verify (`jetic_verify_model`)**: Validates model structure and ensures all fields (descriptions, tags, parameter/response details) are complete and error-free.
+4. **Phase 4 — Simulate (`jetic simulate`)**: Executes multi-step workflows with dynamic state capture (`captureInput` / `capture`) and header injection (`Authorization: Bearer {{workflow:token}}`).
 
 ---
 
-### 3. 🔬 Endpoint Inspect (`/inspect`)
-Deep-dive inspection page for any single API endpoint.
-
-- **Key Highlights**:
-  - **AST Source Code Viewer**: Live preview of the backend handler source code centered on the exact line number (e.g. `routes/orders.ts:42`).
-  - **Related Files Navigator**: Automatically parses imports to show connected controllers, services, and type declaration files.
-  - **Schema Explorer**: Field-by-field breakdown of request body, query parameters, path params, response definitions, and discovered constraints.
-  - **Interactive REST Client**: Test live endpoints directly from the browser using real or auto-generated fake data with authorization header injection.
-
-![Jetic Studio - Endpoint Inspect](../../screenshots/jetic_endpoint_inspect.JPG)
-
----
+## 🤖 AI IDE Integration (MCP)
 
-### 4. 💎 AI Workflow Simulations (`/simulations`)
-Visual AI workflow builder and step-by-step runner.
+Jetic comes with a built-in **Model Context Protocol (MCP)** server so your editor's AI assistant (opencode, Antigravity, Cursor, Claude Code, VS Code) can manage your API model directly — **using your editor's own model with no API keys**.
 
-- **Key Highlights**:
-  - **Goal-Based Generation**: Type any prompt (e.g. *"Admin creates workspace, invites teacher, creates class, logs out"*) to synthesize full workflow graphs.
-  - **SSE Live Streaming**: Watch steps execute in real time via Server-Sent Events (SSE).
-  - **Payload & Injection Inspection**: Expand steps to inspect resolved body values, injected headers (`Authorization`), expected vs actual status codes, and captured variables.
+### Setup (e.g. `opencode.json` or Cursor `mcp.json`):
+```json
+{
+  "mcp": {
+    "jetic": {
+      "type": "local",
+      "command": ["jetic", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+*(On Windows, use `"command": ["cmd", "/c", "jetic", "mcp"]`)*
 
-![Jetic Studio - AI Workflow Simulations](../../screenshots/jetic_smulations_expandable.JPG)
+### Recommended Agent Prompts:
+> 1. *"Run `jetic_get_session_phase` and guide me through building the API model for this project."*  
+> 2. *"Scan the backend, check endpoint completeness, fill missing descriptions/tags, and run `jetic_verify_model`."*  
+> 3. *"What workflow or integration test would you like to simulate against local environment?"*
 
 ---
 
-### 5. 🗄️ Memory Inspector (`/memory`)
-Real-time state and key-value store inspector for `.jetic/memory.json`.
-
-- **Key Highlights**:
-  - View authorization tokens (JWTs, session cookies), user credentials, resource IDs, and custom variables.
-  - Add, edit, or delete entries across `workflow` and `global` memory scopes.
-  - Clear state between simulation runs.
+## 💻 CLI Commands
 
-![Jetic Studio - Memory Inspector](../../screenshots/jetic_memory.JPG)
+| Command | Description |
+|---|---|
+| `jetic init` | Scaffold `.jetic/` folder and initial configuration |
+| `jetic scan` | Static AST source code scan for Express/TypeScript backends |
+| `jetic inspect` | Inspect summary metrics or specific endpoint schemas in terminal |
+| `jetic simulate endpoint` | Test live HTTP endpoints against local/staging server |
+| `jetic simulate workflow` | Execute multi-step stateful workflows from `.jetic/workflows/` |
+| `jetic dev` | Launch local **Jetic Studio** dashboard UI on port `8787` |
+| `jetic memory` | View, set, or clear runtime variable memory (`.jetic/memory.json`) |
+| `jetic mcp` | Start stdio MCP server for AI IDE integration |
 
 ---
 
-### 6. 📈 Observability & Execution Traces (`/traces`)
-Interactive ReactFlow node-graph visualizer for workflow execution traces.
+## 🖥️ Jetic Studio
 
-- **Key Highlights**:
-  - **Node Graph Flow**: Visualizes steps as HTTP nodes connected by variable capture memory nodes.
-  - **Timeline Bar**: Proportional duration breakdown (ms) showing step latencies and pass/fail statuses.
-  - **Step Detail Drawer**: Click any node to open a side drawer detailing HTTP headers (injected vs standard), raw request body, JSON response body, expected status checks, and JSONPath capture rules.
+Run `jetic dev` to open the local web developer studio:
 
-![Jetic Studio - Execution Traces](../../screenshots/jetic_traces.JPG)
+- **Behavioral Model (`/model`)**: Explore endpoints, request/response schemas, and AST source code lines.
+- **AI Simulations (`/simulations`)**: Visual step-by-step workflow runner with real-time SSE execution logs.
+- **Memory Inspector (`/memory`)**: Edit captured tokens, fake test data, and session variables.
+- **Visual Traces (`/traces`)**: Interactive node-graph execution visualizer powered by ReactFlow.
 
 ---
 
-## 📄 Artifact & File Schemas
-
-### `.jetic/model.json` (Behavioral Model)
+## 📄 Behavioral Model Preview (`.jetic/model.json`)
 
 ```json
 {
   "version": "0.3",
-  "generatedAt": "2026-08-30T10:00:00.000Z",
-  "project": {
-    "name": "express-shop",
-    "language": "typescript",
-    "framework": "express"
-  },
-  "environments": [
-    { "name": "local", "baseUrl": "http://localhost:3000" }
-  ],
-  "securitySchemes": {
-    "bearerAuth": {
-      "type": "http",
-      "scheme": "bearer",
-      "obtainedFrom": {
-        "endpoint": "POST /api/auth/login",
-        "field": "data.accessToken"
-      }
-    }
-  },
+  "project": { "name": "my-api", "language": "typescript", "framework": "express" },
+  "environments": [{ "name": "local", "baseUrl": "http://localhost:3000" }],
   "endpoints": [
     {
       "id": "post-api-auth-login",
       "method": "POST",
       "path": "/api/auth/login",
-      "handlerName": "AuthController.login",
-      "source": {
-        "file": "src/routes/auth.routes.ts",
-        "line": 14
-      },
+      "description": "User authentication endpoint",
+      "tags": ["auth"],
       "requestBody": {
-        "contentType": "application/json",
         "fields": {
-          "user_email": { "type": "string", "format": "email", "required": true },
-          "user_password": { "type": "string", "minLength": 8, "required": true }
+          "email": { "type": "string", "format": "email", "required": true },
+          "password": { "type": "string", "minLength": 8, "required": true }
         }
       },
       "responses": {
-        "200": {
-          "description": "Login successful",
-          "schema": {
-            "data.accessToken": "string",
-            "data.user.id": "string"
-          }
-        }
-      },
-      "middleware": []
-    }
-  ]
-}
-```
-
----
-
-### `.jetic/workflows/admin-onboarding.json` (Workflow Definition)
-
-```json
-{
-  "name": "Admin creates workspace, creates class and logs out",
-  "generatedAt": "2026-08-30T10:15:00.000Z",
-  "steps": [
-    {
-      "name": "Admin setup workspace",
-      "method": "POST",
-      "path": "/api/workspaces/setup",
-      "description": "Register workspace and initial admin credentials",
-      "body": {
-        "workspace_name": "{{faker.company.name}}",
-        "admin_email": "{{faker.internet.email}}",
-        "admin_password": "{{faker.internet.password}}"
-      },
-      "captureInput": {
-        "workflow:adminEmail": "admin_email",
-        "workflow:adminPassword": "admin_password"
-      },
-      "capture": {
-        "workflow:workspaceID": "data.workspace.id"
-      },
-      "expectStatus": 201
-    },
-    {
-      "name": "Admin login",
-      "method": "POST",
-      "path": "/api/auth/login",
-      "description": "Authenticate using captured admin credentials",
-      "body": {
-        "user_email": "{{workflow:adminEmail}}",
-        "user_password": "{{workflow:adminPassword}}"
-      },
-      "capture": {
-        "workflow:accessToken": "data.accessToken"
-      },
-      "expectStatus": 200
-    },
-    {
-      "name": "Create class",
-      "method": "POST",
-      "path": "/api/classes",
-      "description": "Create class in workspace using Bearer token",
-      "inject": {
-        "header:Authorization": "Bearer {{workflow:accessToken}}"
-      },
-      "body": {
-        "name": "{{faker.word.noun}} Class",
-        "workspaceId": "{{workflow:workspaceID}}"
-      },
-      "expectStatus": 201
+        "200": { "description": "Returns JWT token", "schema": { "token": "string" } }
+      }
     }
   ]
 }
@@ -585,49 +158,7 @@ Interactive ReactFlow node-graph visualizer for workflow execution traces.
 
 ---
 
-### `.jetic/memory.json` (Runtime State)
-
-```json
-{
-  "workflow": {
-    "adminEmail": "admin_test_8421@example.com",
-    "adminPassword": "Password123!",
-    "workspaceID": "ws_98124712",
-    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-  },
-  "global": {
-    "baseUrl": "http://localhost:3000"
-  }
-}
-```
-
----
-
-## 🗺️ Roadmap & Vision
-
-- [x] **Zero-Execution AST Scanner**: Deep TypeScript/Express source parser via `ts-morph` with import resolver.
-- [x] **Declarative Behavioral Modeling**: Versioned `.jetic/model.json` schema with source code line references.
-- [x] **Stateful AI Workflow Engine**: Multi-step simulation generation with `captureInput`, `capture`, and `inject`.
-- [x] **Jetic Studio Local Dashboard**: React 19 IDE with REST simulator, AI builder, memory editor, and ReactFlow trace visualizer (`jetic dev`).
-- [ ] **State-Machine Transition Testing**: Automatic state transition verification (e.g. `payment.capture()` valid when `authorized`, invalid when `refunded`).
-- [ ] **Security & Authorization Vulnerability Auditor**: Automatic IDOR (Insecure Direct Object Reference) and privilege escalation scenario synthesizer.
-- [ ] **Plugin Ecosystem SDK**: Custom extensions for GraphQL, Webhooks, gRPC, and custom LLM tool-calling agent test suites.
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [CONTRIBUTING.md](../../CONTRIBUTING.md) guide for instructions on setting up your local development environment, running tests across monorepo packages, and submitting Pull Requests.
-
----
-
-## 📝 License
-
-This project is licensed under the [ISC License](../../LICENSE).
-
----
-
 <p align="center">
-  <i>Built with ❤️ by the Jetic Team. If you find Jetic useful, please consider giving us a ⭐ on GitHub!</i>
+  <i>Built with ❤️ by the Jetic Team.</i>
 </p>
 

package/dist/index.js

@@ -269018,17 +269018,87 @@ var require_validation_tools = __commonJS({
           }
         }
       }
+      const fieldCompleteness = {};
+      for (const ep of model.endpoints) {
+        const routeKey = `${ep.method.toUpperCase()} ${ep.path}`;
+        const missing = [];
+        if (!ep.description || ep.description.trim() === "") {
+          missing.push("description");
+          issues.push({
+            severity: "warning",
+            endpointId: ep.id,
+            route: routeKey,
+            code: "MISSING_FIELD_DESCRIPTION",
+            message: `Endpoint "${routeKey}" has no description.`,
+            recommendation: "Add a concise description of what this endpoint does."
+          });
+        }
+        if (!ep.tags || ep.tags.length === 0) {
+          missing.push("tags");
+          issues.push({
+            severity: "warning",
+            endpointId: ep.id,
+            route: routeKey,
+            code: "MISSING_FIELD_TAGS",
+            message: `Endpoint "${routeKey}" has no tags.`,
+            recommendation: 'Add at least one tag to group this endpoint (e.g. "auth", "users").'
+          });
+        }
+        if (ep.parameters) {
+          for (const p of ep.parameters) {
+            if (!p.description || p.description.trim() === "") {
+              const field = `parameters[${p.name}].description`;
+              missing.push(field);
+              issues.push({
+                severity: "warning",
+                endpointId: ep.id,
+                route: routeKey,
+                code: "MISSING_FIELD_PARAM_DESCRIPTION",
+                message: `Parameter "${p.name}" on "${routeKey}" has no description.`,
+                recommendation: `Add a description to parameter "${p.name}".`
+              });
+            }
+          }
+        }
+        if (ep.responses) {
+          for (const [statusCode, resp] of Object.entries(ep.responses)) {
+            const r = resp;
+            if (!r.description || String(r.description).trim() === "") {
+              const field = `responses[${statusCode}].description`;
+              missing.push(field);
+              issues.push({
+                severity: "warning",
+                endpointId: ep.id,
+                route: routeKey,
+                code: "MISSING_FIELD_RESPONSE_DESCRIPTION",
+                message: `Response "${statusCode}" on "${routeKey}" has no description.`,
+                recommendation: `Add a description to the ${statusCode} response (e.g. "User created successfully").`
+              });
+            }
+          }
+        }
+        if (missing.length > 0) {
+          fieldCompleteness[ep.id] = { missingFields: missing };
+        }
+      }
+      const allFieldsFilled = Object.keys(fieldCompleteness).length === 0;
       const errors = issues.filter((i) => i.severity === "error");
       const warnings = issues.filter((i) => i.severity === "warning");
       return {
         filePath,
         isValid: errors.length === 0,
+        allFieldsFilled,
         totalEndpoints: model.endpoints.length,
         summary: {
           errorsCount: errors.length,
           warningsCount: warnings.length
         },
-        issues
+        issues,
+        fieldCompleteness,
+        phaseGate: {
+          phase3Complete: errors.length === 0 && allFieldsFilled,
+          message: errors.length === 0 && allFieldsFilled ? "Model is valid and all fields are complete. You may advance to Phase 4 \u2014 ask the user what simulation or workflow they want to build." : "Fix all errors and fill missing fields before proceeding to Phase 4."
+        }
       };
     }
   }
@@ -284234,6 +284304,112 @@ var require_serial_transport = __commonJS({
   }
 });
 
+// ../../packages/mcp-server/dist/tools/session-tools.js
+var require_session_tools = __commonJS({
+  "../../packages/mcp-server/dist/tools/session-tools.js"(exports2) {
+    "use strict";
+    init_cjs_shims();
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.getSessionPhaseSchema = void 0;
+    exports2.handleGetSessionPhase = handleGetSessionPhase;
+    var zod_1 = require("zod");
+    var types_1 = require_types();
+    var validation_tools_1 = require_validation_tools();
+    exports2.getSessionPhaseSchema = zod_1.z.object({
+      projectPath: zod_1.z.string().optional().describe("Path to the project root or .jetic folder (defaults to JETIC_PROJECT_PATH / cwd)")
+    });
+    function checkAllFieldsFilled(model) {
+      let incompleteCount = 0;
+      for (const ep of model.endpoints) {
+        let incomplete = false;
+        if (!ep.description || ep.description.trim() === "")
+          incomplete = true;
+        if (!ep.tags || ep.tags.length === 0)
+          incomplete = true;
+        if (ep.parameters) {
+          for (const p of ep.parameters) {
+            if (!p.description || p.description.trim() === "") {
+              incomplete = true;
+              break;
+            }
+          }
+        }
+        if (ep.responses) {
+          for (const resp of Object.values(ep.responses)) {
+            const r = resp;
+            if (!r.description || String(r.description).trim() === "") {
+              incomplete = true;
+              break;
+            }
+          }
+        }
+        if (incomplete)
+          incompleteCount++;
+      }
+      return { allFilled: incompleteCount === 0, incompleteCount };
+    }
+    function handleGetSessionPhase(args) {
+      const { model, exists } = (0, types_1.loadModel)(args.projectPath);
+      if (!exists) {
+        return {
+          phase: 1,
+          phaseName: "init",
+          modelExists: false,
+          endpointsCount: 0,
+          modelIsValid: false,
+          allFieldsFilled: false,
+          nextAction: "PHASE 1 \u2014 INITIALIZE: No .jetic/model.json found. Call jetic_init now to scaffold the project. Do not proceed until modelExists is true."
+        };
+      }
+      const endpointsCount = model.endpoints?.length ?? 0;
+      if (endpointsCount === 0) {
+        return {
+          phase: 2,
+          phaseName: "scan",
+          modelExists: true,
+          endpointsCount: 0,
+          modelIsValid: false,
+          allFieldsFilled: false,
+          nextAction: "PHASE 2 \u2014 SCAN: Model exists but has no endpoints. If the project has tsconfig.json (Express+TypeScript), call jetic_scan. Otherwise read the source code and call jetic_add_endpoint for every API route. Do not proceed to Phase 3 until endpointsCount > 0."
+        };
+      }
+      let modelIsValid = false;
+      try {
+        const verification = (0, validation_tools_1.handleVerifyModel)({ projectPath: args.projectPath });
+        modelIsValid = verification.isValid;
+      } catch {
+        modelIsValid = false;
+      }
+      const { allFilled, incompleteCount } = checkAllFieldsFilled(model);
+      if (!modelIsValid || !allFilled) {
+        const reasons = [];
+        if (!modelIsValid)
+          reasons.push("model has validation errors (call jetic_verify_model to see them)");
+        if (!allFilled)
+          reasons.push(`${incompleteCount} endpoint(s) have incomplete fields (missing description, tags, parameter descriptions, or response descriptions \u2014 call jetic_verify_model to see the full list)`);
+        return {
+          phase: 3,
+          phaseName: "verify",
+          modelExists: true,
+          endpointsCount,
+          modelIsValid,
+          allFieldsFilled: allFilled,
+          nextAction: `PHASE 3 \u2014 VERIFY: ${reasons.join("; ")}. Fix all issues with jetic_update_endpoint / jetic_add_endpoint, then call jetic_verify_model until both modelIsValid and allFieldsFilled are true. Do not touch any workflow tool until Phase 4 is reached.`
+        };
+      }
+      return {
+        phase: 4,
+        phaseName: "simulate",
+        modelExists: true,
+        endpointsCount,
+        modelIsValid: true,
+        allFieldsFilled: true,
+        nextAction: 'PHASE 4 \u2014 SIMULATE: The model is valid and complete. ASK THE USER: "What simulation or workflow do you want to build?" Wait for their answer before calling any workflow tool. Do not invent a workflow goal \u2014 the user must specify it.'
+      };
+    }
+  }
+});
+
 // ../../packages/mcp-server/dist/server.js
 var require_server3 = __commonJS({
   "../../packages/mcp-server/dist/server.js"(exports2) {
@@ -284294,6 +284470,7 @@ var require_server3 = __commonJS({
     var workflow_tools_1 = require_workflow_tools();
     var workflow_authoring_tools_1 = require_workflow_authoring_tools();
     var project_tools_1 = require_project_tools();
+    var session_tools_1 = require_session_tools();
     exports2.JETIC_MCP_SERVER_NAME = "jetic-mcp-server";
     function getJeticMcpVersion() {
       try {
@@ -284306,13 +284483,37 @@ var require_server3 = __commonJS({
       return "0.1.0";
     }
     exports2.JETIC_MCP_INSTRUCTIONS = [
-      "Jetic MCP manages API behavioral models in `.jetic/`. Work in this structured order:",
-      "1. INITIALIZE: if there is no `.jetic/model.json` (read tools report modelExists:false), call `jetic_init` first. It scaffolds the folder + model and tells you whether auto-scan applies. Never invent a model file by hand.",
-      "2. MODEL: Express+TypeScript project with tsconfig.json \u2192 run `jetic_scan` (static, keyless) to fill model.json, then refine with `jetic_add_endpoint` / `jetic_update_endpoint`. Any other stack \u2014 or scan gaps \u2014 read the code and model each endpoint yourself with `jetic_add_endpoint` (full fidelity: middleware chains, security, constraints, pagination, produces/consumes). Run `jetic_verify_model` until clean.",
-      "3. SIMULATE (only when the user asks): author workflows with `jetic_validate_workflow` (dry run) \u2192 `jetic_create_workflow` \u2192 `jetic_simulate_workflow`. Chain steps with capture/captureInput (producer) + inject or {{workflow:key}} templates (consumer). Use {{human:key}} ONLY for values unknowable beforehand (OTP codes, real secrets) \u2014 runners pause for interactive input and the create response lists them under needsHuman so you can warn the user.",
-      "No AI-provider setup is needed for any of this: never ask for OpenRouter/OpenAI keys and never use `jetic config ai`.",
-      "Mutating tools (`jetic_add_endpoint`, `jetic_update_endpoint`, `jetic_delete_endpoint`, `jetic_manage_environment`, workflow create/update) write to disk \u2014 confirm intent with the user first when the change is destructive (delete/overwrite).",
-      "Project resolution: every tool accepts an optional `projectPath`. If omitted, the server uses the `JETIC_PROJECT_PATH` environment variable, falling back to its own working directory. Set one of them to the project root so the server edits the right `.jetic/model.json`."
+      "Jetic MCP manages API behavioral models in `.jetic/`. You MUST follow this strict 4-phase order. Never skip, reorder, or bypass any phase.",
+      "",
+      "\u2501\u2501 PHASE 1 \u2014 INITIALIZE \u2501\u2501",
+      "Call `jetic_get_session_phase` at the very start of every session. If phase=1 (modelExists:false), call `jetic_init` to scaffold .jetic/model.json.",
+      "Gate: DO NOT advance to Phase 2 until modelExists is true.",
+      "",
+      "\u2501\u2501 PHASE 2 \u2014 SCAN \u2501\u2501",
+      "Populate the model with endpoints:",
+      "  \u2022 Express+TypeScript (tsconfig.json present): call `jetic_scan` (static, keyless, no AI provider needed).",
+      "  \u2022 Any other stack or scan gaps: read the source code and call `jetic_add_endpoint` for every route (include middleware chains, security, constraints, pagination, produces/consumes).",
+      "Gate: DO NOT advance to Phase 3 until endpointsCount > 0.",
+      "",
+      "\u2501\u2501 PHASE 3 \u2014 VERIFY \u2501\u2501",
+      "Call `jetic_verify_model`. Fix every error AND every MISSING_FIELD_* warning:",
+      "  \u2022 Fill `description` on every endpoint.",
+      "  \u2022 Add at least one `tag` per endpoint.",
+      "  \u2022 Add `description` to every parameter.",
+      "  \u2022 Add `description` to every response status code.",
+      "Use `jetic_update_endpoint` to fill gaps. Call `jetic_verify_model` again after each batch of updates.",
+      "Gate: DO NOT advance to Phase 4 until jetic_get_session_phase returns phase=4 (modelIsValid AND allFieldsFilled both true).",
+      "",
+      "\u2501\u2501 PHASE 4 \u2014 SIMULATE \u2501\u2501",
+      'STOP. Ask the user: "What simulation or workflow do you want to build?"',
+      "Wait for their explicit answer. Then and only then: author the workflow with `jetic_validate_workflow` (dry run) \u2192 `jetic_create_workflow` \u2192 `jetic_simulate_workflow`.",
+      "Chain steps using capture/captureInput (producer) + inject or {{workflow:key}} (consumer). Use {{human:key}} ONLY for values unknowable beforehand (OTP codes, real secrets).",
+      "Never start Phase 4 without an explicit user-specified goal.",
+      "",
+      "\u2501\u2501 GENERAL RULES \u2501\u2501",
+      "No AI-provider setup is needed: never ask for OpenRouter/OpenAI keys and never use `jetic config ai`.",
+      "Mutating tools write to disk \u2014 confirm intent with the user before destructive operations (delete/overwrite).",
+      "Project resolution: every tool accepts an optional `projectPath`. If omitted, falls back to JETIC_PROJECT_PATH env var, then cwd."
     ].join("\n");
     var READ_ONLY = {
       readOnlyHint: true,
@@ -284360,7 +284561,10 @@ var require_server3 = __commonJS({
           }
         });
       };
-      register("jetic_read_model", "Read Jetic model", "Reads .jetic/model.json from the workspace and returns the full behavioral model or a metadata summary. Start here before any other Jetic tool.", model_tools_1.readModelSchema.shape, READ_ONLY, model_tools_1.handleReadModel);
+      register("jetic_get_session_phase", "Get session phase", "ALWAYS CALL THIS FIRST. Returns the current workflow phase (1=init, 2=scan, 3=verify, 4=simulate), gate conditions (modelExists, endpointsCount, modelIsValid, allFieldsFilled), and the exact nextAction the AI must take. Never skip phase gates.", session_tools_1.getSessionPhaseSchema.shape, READ_ONLY, session_tools_1.handleGetSessionPhase);
+      register("jetic_init", "Initialize Jetic project", "PHASE 1: Scaffolds .jetic/model.json (+ workflows/, config.json) for repos that have none. Refuses to clobber an existing model (pass overwrite:true to replace). Reports whether auto-scan applies (Express+TypeScript) and what to do next.", project_tools_1.initProjectSchema.shape, WRITES_MODEL, project_tools_1.handleInitProject);
+      register("jetic_scan", "Scan Express project", "PHASE 2 (Express+TypeScript only \u2014 requires tsconfig.json): Static AST scan that fills model.json with routes, middleware, and auth heuristics. Keyless \u2014 no AI provider involved. Default merge upserts scanned routes and keeps hand-added endpoints; overwrite replaces all endpoints. Fails with guidance for non-Express stacks (model those manually with jetic_add_endpoint).", project_tools_1.scanProjectSchema.shape, WRITES_MODEL, project_tools_1.handleScanProject);
+      register("jetic_read_model", "Read Jetic model", "Reads .jetic/model.json from the workspace and returns the full behavioral model or a metadata summary.", model_tools_1.readModelSchema.shape, READ_ONLY, model_tools_1.handleReadModel);
       register("jetic_list_endpoints", "List endpoints", "Lists API endpoints discovered in .jetic/model.json with optional filters by method, tag, resource, or path substring.", model_tools_1.listEndpointsSchema.shape, READ_ONLY, model_tools_1.handleListEndpoints);
       register("jetic_get_endpoint", "Get endpoint details", "Returns full structural details (parameters, request body, schemas, security, responses) of one endpoint, looked up by ID or by method + path.", model_tools_1.getEndpointSchema.shape, READ_ONLY, model_tools_1.handleGetEndpoint);
       register("jetic_add_endpoint", "Add endpoint", "Adds a new endpoint definition to .jetic/model.json (or updates the existing method+path route when overwriteIfExists is true, the default). Adheres to the Jetic Behavioral Model schema.", endpoint_tools_1.addEndpointSchema.shape, WRITES_MODEL, endpoint_tools_1.handleAddEndpoint);
@@ -284376,8 +284580,6 @@ var require_server3 = __commonJS({
       register("jetic_create_workflow", "Create workflow", "Creates a .jetic/workflows/<slug>.json workflow from ordered steps with capture/inject memory chaining. Refuses to save when validation errors exist (error messages say exactly how to fix); use validateOnly for a dry run. Can also migrate an embedded model.json workflow via fromModelWorkflow.", workflow_authoring_tools_1.createWorkflowSchema.shape, WRITES_MODEL, workflow_authoring_tools_1.handleCreateWorkflow);
       register("jetic_update_workflow", "Update workflow", "Updates a saved file workflow: rename, description/environment, full steps replacement, or appendSteps. Validates before writing and refuses to save on errors.", workflow_authoring_tools_1.updateWorkflowSchema.shape, WRITES_MODEL, workflow_authoring_tools_1.handleUpdateWorkflow);
       register("jetic_delete_workflow", "Delete workflow", "Deletes a saved .jetic/workflows/*.json workflow file by slug, name, or path. Destructive: confirm with the user before calling. Cannot delete model.json-embedded workflows.", workflow_authoring_tools_1.deleteWorkflowSchema.shape, DESTRUCTIVE, workflow_authoring_tools_1.handleDeleteWorkflow);
-      register("jetic_init", "Initialize Jetic project", "Step 1 of the structured order: scaffolds .jetic/model.json (+ workflows/, config.json) for repos that have none. Refuses to clobber an existing model (pass overwrite:true to replace). Reports whether auto-scan applies (Express+TypeScript) and what to do next.", project_tools_1.initProjectSchema.shape, WRITES_MODEL, project_tools_1.handleInitProject);
-      register("jetic_scan", "Scan Express project", "Step 2a for Express+TypeScript projects (requires tsconfig.json): static AST scan that fills model.json with routes, middleware, and auth heuristics. Keyless \u2014 no AI provider involved. Default merge upserts scanned routes and keeps hand-added endpoints; overwrite replaces all endpoints. Fails with guidance for non-Express stacks (model those manually).", project_tools_1.scanProjectSchema.shape, WRITES_MODEL, project_tools_1.handleScanProject);
       return server;
     }
     async function runMcpServer2() {
@@ -287274,7 +287476,7 @@ var mcpCommand = new import_commander10.Command("mcp").description("Launch Model
 
 // src/index.ts
 var program = new import_commander11.Command();
-program.name("jetic").description("AI-Native API Behavior Testing").version("0.1.9");
+program.name("jetic").description("AI-Native API Behavior Testing").version("0.2.1");
 program.addCommand(initCommand);
 program.addCommand(scanCommand);
 program.addCommand(inspectCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jetic-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AI-Native API Behavior Testing & Discovery Tool — CLI and Local Studio Dashboard",
   "main": "dist/index.js",
   "bin": {