graphjin 3.18.42 → 3.18.44

package/README.md

@@ -15,6 +15,7 @@ Works with PostgreSQL, MySQL, MongoDB, SQLite, Oracle, MSSQL, Snowflake, Redshif
 
 ## Why GraphJin For Agents
 
+- **A built-in agent, one call away** - POST one instruction to `/api/v1/agent` (or call the `ask_graphjin_agent` MCP tool) and GraphJin runs the discovery loop itself - as the caller, under the caller's permissions - and returns a typed, evidence-backed answer. See [Server-Side Agent](#server-side-agent).
 - **One governed surface for many systems** - Query operational databases, warehouses, MongoDB, object stores, local files, CodeSQL source indexes, workflows, and GraphJin system roots through GraphQL and MCP.
 - **Smart discovery before action** - Agents start with `query_catalog(search: "<user instruction>")`, `graphql_help`, relationship evidence, examples, config recipes, and safety notes before writing or running queries.
 - **Guarded action, not raw access** - Source-mode access, query allow-lists, read-only boundaries, policy-aware MCP tools, local encrypted secrets, and `gj_config` preview/apply keep changes auditable.
@@ -50,45 +51,58 @@ docker pull dosco/graphjin
 
 ## Try It Now
 
-This is a quick way to try out GraphJin. The `--demo` flag runs a curated local
-demo, creates local state under the example's `demo/` folder, and reuses that
-state on later starts. Delete `demo/` to reset from scratch.
+One command, no clone, no Docker. The binary ships with a built-in demo — a
+clinic scheduling app (patients, providers, appointments, waitlists) on
+SQLite with seeded data, saved queries, and workflows:
 
-Download the source which contains the `webshop` demo
+```bash
+graphjin serve --demo
 ```
-git clone https://github.com/dosco/graphjin
-cd graphjin
+
+The demo project is extracted to `./graphjin-demo`, and its state lives under
+`./graphjin-demo/demo/`. Delete the `demo/` folder to reset the data, or
+delete `./graphjin-demo` entirely for a fresh copy. You'll see output like
+this:
+
 ```
+GraphJin started
+───────────────────────
+  Web UI:      http://localhost:8083/
+  GraphQL:     http://localhost:8083/api/v1/graphql
+  REST API:    http://localhost:8083/api/v1/rest/
+  Workflows:   http://localhost:8083/api/v1/workflows/<name>
+  MCP:         http://localhost:8083/api/v1/mcp
+```
+
+**Ask the built-in agent**
+
+With a model API key in `./.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_APIKEY`), the same command switches into agentic mode and enables GraphJin's built-in agent - one instruction in, a typed, evidence-backed answer out:
 
-Now launch the Graphjin service that you installed using the install options above
 ```bash
-graphjin serve --demo --path examples/webshop
+curl -sS localhost:8083/api/v1/agent \
+  -H 'content-type: application/json' \
+  -d '{"instruction": "Who should get the next open cardiology slot?"}'
 ```
 
-For a larger agent-driven example with Postgres operations data, a BigQuery
-simulator for roast telemetry, CodeSQL over internal business code, and
-executable workflows:
+Answers come back as `{status, answer, data, evidence, actions, next}`, grounded by server-side protocol guards. You can also chat with it in the built-in web console at `localhost:8083/agent` — it streams every tool call live as it works. See [Server-Side Agent](#server-side-agent) below, [AGENTIC.md](AGENTIC.md#server-side-agent), and [graphjin.com/agentic/server-agent](https://graphjin.com/agentic/server-agent/).
+
+**More demo verticals**
+
+The bigger demos live in the repo — clone it and pass `--path`:
 
 ```bash
-graphjin serve --demo --path examples/coffee-roastery
+git clone https://github.com/dosco/graphjin
+cd graphjin
+graphjin serve --demo --path examples/webshop          # classic GraphQL starter (Postgres)
+graphjin serve --demo --path examples/coffee-roastery  # flagship agentic demo (Postgres + BigQuery-emu + CodeSQL)
 ```
 
-More demo verticals — a MySQL corrugated-box plant with JWT roles, a PCB fab
-spanning Postgres + Snowflake-emu + MongoDB + a file source + an OpenAPI
-supplier API, and a zero-Docker SQLite clinic scheduler — live in
+Each demo keeps its state under `<path>/demo/` and reuses it on later starts.
+A MySQL corrugated-box plant with JWT roles and a PCB fab spanning Postgres +
+Snowflake-emu + MongoDB + a file source + an OpenAPI supplier API live in
 [examples/](examples/README.md), each with an end-to-end smoke suite
-(`make smoke-all` runs them all).
-
-You'll see output like this:
-```
-GraphJin started
-───────────────────────
-  Web UI:      http://localhost:8080/
-  GraphQL:     http://localhost:8080/api/v1/graphql
-  REST API:    http://localhost:8080/api/v1/rest/
-  Workflows:   http://localhost:8080/api/v1/workflows/<name>
-  MCP:         http://localhost:8080/api/v1/mcp
-```
+(`make smoke-all` runs them all). The full tour is at
+<https://graphjin.com/start/demos/>.
 
 ## Add GraphJin To Your AI Client
 
@@ -581,7 +595,7 @@ Legacy prompts such as `write_query` and `fix_query_error` are available only wh
 Optional: instead of your client chaining `query_catalog` → `validate_where_clause` → `execute_saved_query`, let GraphJin run the catalog-first discovery loop for you. When enabled, GraphJin exposes one MCP tool `ask_graphjin_agent` and one REST endpoint `POST /api/v1/agent` that take a single instruction and return a typed, evidence-backed answer (`status`, `answer`, `data`, `evidence`, `actions`, `next`).
 
 - **Enable** by loading `agentic.yml` (`GO_ENV=agentic`) with `agent.enabled: true` plus a provider, model, and `api_key_env`.
-- **Modes:** `safe` (discovery + approved saved queries/mutations), `discovery_only` (read-only), `raw_allowed` (adds raw GraphQL when `agent.allow_raw_graphql` and `mcp.allow_raw_queries` are set).
+- **Execution control:** there are no per-request agent modes. `agent.read_only: true` forces the server-side agent to reject mutations, including saved-query mutations; otherwise core roles, row-level security, source/table `read_only`, and Go protocol guards decide what can run.
 - **Caller-scoped:** the agent runs as the caller, so core roles + row-level security enforce access. The caller's role only changes which *guidance* the agent follows, never what it can read or write.
 - **Grounded:** Go protocol guards keep every answer backed by real catalog/validation/execution evidence and downgrade to `blocked` (with evidence) when a step is skipped.
 - **Machine-actionable refusals:** blocked responses carry a structured `refusal` (code, reasons, unblock steps, `policy_final`/`retryable`) so a calling agent can course-correct in one step instead of guessing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphjin",
-  "version": "3.18.42",
+  "version": "3.18.44",
   "description": "GraphJin CLI - Build APIs in 5 minutes with GraphQL",
   "bin": {
     "graphjin": "bin/graphjin.js"