Update project positioning

Author: dinpd

README.md

@@ -1,24 +1,24 @@
 # AgentID
 
-**AgentID** is a lightweight open-source toolkit for declaring, validating, reviewing, and auditing AI agent authority.
+**AgentID** is an open-source authorization layer for AI agent tool calls.
 
-The primary use case is an enterprise-owned authorization boundary for agent
-tool calls across internal systems, SaaS APIs, MCP servers, cloud control
-planes, databases, and provider-hosted tools.
+It helps teams declare, validate, and enforce what agents are allowed to do
+across SaaS apps, internal systems, cloud control planes, databases,
+provider-hosted tools, and MCP gateways.
 
 ![AI Agents Need Eligibility Contracts](docs/AIAgentsNeedEligibilityContracts.png)
 
 The core idea is simple:
 
 > Every production agent should have an authority contract that says who it is, who owns it, what it can request, when authority should be issued just in time, where data can flow, when it needs approval, and how it can be stopped.
 
-AgentID does **not** replace IAM, OAuth, MCP gateways, OPA, Cedar, or enterprise security tools. It sits one layer above them as a portable declaration format for agent identity, delegation, tool access, intent confirmation, just-in-time authorization, data-flow boundaries, approval rules, runtime enforcement expectations, audit behavior, and kill-switch behavior.
+AgentID does **not** replace IAM, OAuth, MCP gateways, OPA, Cedar, or enterprise security tools. It sits one layer above them as a portable authorization contract for agent identity, delegation, tool access, intent confirmation, just-in-time authorization, data-flow boundaries, approval rules, runtime enforcement expectations, audit behavior, and kill-switch behavior.
 
 For gateway deployments, AgentID is meant to run at an enterprise-controlled
 boundary:
 
 ```text
-Enterprise Agent -> Enterprise Gateway -> AgentID Check -> Internal or External Tool
+Enterprise Agent -> Enterprise Gateway or App Runtime -> AgentID Check -> Internal, SaaS, or MCP Tool
 ```
 
 ---
@@ -49,10 +49,10 @@ For scoped agent-to-agent delegation, see [`docs/agent-to-agent-delegation.md`](
 
 ## Why this exists
 
-Most agent projects define tools and credentials in ad hoc config files.
-MCP servers and tool APIs make this sharper: an enterprise agent can suddenly
-call internal systems, SaaS APIs, cloud control planes, databases, or provider
-tools unless there is a local policy checkpoint.
+Most agent projects define tools and credentials in ad hoc config files. As
+agents move into production, those tools span internal services, SaaS APIs, MCP
+servers, cloud control planes, databases, and provider-hosted capabilities.
+AgentID gives teams a local policy checkpoint before those calls execute.
 
 What is often missing is a clear answer to:
 
@@ -130,14 +130,14 @@ the tool.
 ## CLI
 
 ```bash
-agentid validate examples/customer-support-refund-agent.yaml
-agentid explain examples/customer-support-refund-agent.yaml
-agentid risk-score examples/customer-support-refund-agent.yaml
-agentid generate-policy examples/customer-support-refund-agent.yaml --target opa
+agentid validate examples/provider-mcp-support-agent.yaml
+agentid explain examples/provider-mcp-support-agent.yaml
+agentid risk-score examples/provider-mcp-support-agent.yaml
+agentid generate-policy examples/provider-mcp-support-agent.yaml --target opa
 agentid audit examples/sample-tool-log.json --manifest examples/customer-support-refund-agent.yaml
 agentid schema > schema/agentid.schema.json
 agentid config-ui --output agentid-policy-builder.html
-agentid gateway examples/customer-support-refund-agent.yaml --host 127.0.0.1 --port 8787
+agentid gateway examples/provider-mcp-support-agent.yaml --host 127.0.0.1 --port 8787
 ```
 
 `config-ui` writes a self-contained browser UI for building an AgentID manifest and starter OPA policy.
@@ -166,7 +166,7 @@ jobs:
           max-risk: "75"
 ```
 
-For SaaS runtime integration, see the TypeScript helper in
+For application and gateway runtime integration, see the TypeScript helper in
 [`sdk/typescript/`](sdk/typescript/). It provides `authorizeToolCall`,
 `requestJitGrant`, and `assertAllowed` wrappers for the gateway API.
 For architecture guidance, see
@@ -175,7 +175,8 @@ For MCP server calls, including internal and provider-hosted servers, see
 [`docs/mcp-gateway-integration.md`](docs/mcp-gateway-integration.md).
 For a reference adapter, see [`mcp-gateway-adapter/`](mcp-gateway-adapter/).
 
-`gateway` starts a lightweight HTTP authorization gateway for SaaS integration. The gateway exposes:
+`gateway` starts a lightweight HTTP authorization gateway for agent tool-call
+integration. The gateway exposes:
 
 | Endpoint | Purpose |
 |---|---|
@@ -220,25 +221,25 @@ for the enterprise gateway pattern.
 
 The hosted gateway-control demo is available at
 [`agentid-refund-demo.drisw.workers.dev`](https://agentid-refund-demo.drisw.workers.dev/).
-It shows a SaaS support app consulting AgentID before refund actions, including
-customer refund-history checks, human notification for escalations, and JIT
-authority before Stripe refund execution. It also includes a visible MCP
-gateway flow that filters provider tools, allows a declared CRM read, denies a
-CRM write without JIT, and then allows the write after a scoped grant. The demo
-Worker mints a short-lived OIDC-style JWT server-side, and the gateway validates
-its claims against the tenant manifest. Demo source lives in [`demo/`](demo/).
+It shows the broader AgentID model in two concrete flows: a SaaS support app
+consulting AgentID before refund actions, and an MCP gateway checking provider
+CRM tool calls before forwarding them. The MCP flow filters provider tools,
+allows a declared CRM read, denies a CRM write without JIT, and then allows the
+write after a scoped grant. The demo Worker mints a short-lived OIDC-style JWT
+server-side, and the gateway validates its claims against the tenant manifest.
+Demo source lives in [`demo/`](demo/).
 
-![AgentID Refund Control Demo](docs/AgentIDRefundControlDemo.png)
+![AgentID Gateway Control Demo](docs/AgentIDRefundControlDemo.png)
 
 ```mermaid
 sequenceDiagram
     participant User
-    participant App as SaaS App / Agent Runtime
+    participant App as App / Agent Runtime / MCP Gateway
     participant IdP as Customer IdP
     participant Gateway as AgentID Gateway
     participant KV as Tenant Manifest Store
     participant DO as JIT Grant Store
-    participant Tool as SaaS Tool
+    participant Tool as Downstream Tool
 
     User->>App: Run agent workflow
     App->>IdP: Obtain OIDC/OAuth access token
@@ -321,7 +322,7 @@ Implemented:
 - Reference MCP gateway adapter for `tools/list` and `tools/call`
 - MCP gateway adapter demo with mock provider server
 - MCP gateway integration guide and enterprise/provider MCP example manifest
-- Hosted refund-control demo
+- Hosted gateway-control demo with SaaS and MCP flows
 - CI checks for tests, schema validation, manifest risk, and TypeScript SDK
 
 Next:

action.yml

@@ -1,5 +1,5 @@
 name: AgentID Manifest Check
-description: Validate AgentID manifests and optionally fail above a risk threshold.
+description: Validate AgentID agent tool-call authorization manifests and optionally fail above a risk threshold.
 inputs:
   manifests:
     description: Space-separated manifest paths or glob patterns.

cloudflare/README.md

@@ -1,6 +1,8 @@
 # AgentID Cloudflare Gateway
 
-This Worker exposes the AgentID gateway API on Cloudflare Workers:
+This Worker exposes the AgentID gateway API on Cloudflare Workers. It can sit
+behind a SaaS app, internal agent platform, or MCP gateway and return
+allow/deny/JIT decisions before tool execution:
 
 | Endpoint | Purpose |
 |---|---|
@@ -57,8 +59,9 @@ RS256 JWT signatures against the matching JWKS `kid`, then enforces issuer,
 audience, tenant, agent, and scope checks from the manifest.
 
 For a single-tenant deployment, set `AGENTID_MANIFEST_JSON` as a Worker variable.
-For SaaS multi-tenancy, bind a KV namespace named `AGENTID_MANIFESTS` and store
-each tenant manifest as JSON under the tenant ID used in `/tenants/<tenant-id>/...`.
+For multi-tenant SaaS, internal platform, or MCP gateway deployments, bind a KV
+namespace named `AGENTID_MANIFESTS` and store each tenant or environment
+manifest as JSON under the ID used in `/tenants/<tenant-id>/...`.
 
 ## GitHub Actions
 

demo/README.md

@@ -1,10 +1,11 @@
 # AgentID Gateway Control Demo
 
-This Cloudflare Worker hosts a small SaaS runtime demo that calls the live
-AgentID gateway through a Cloudflare Service Binding. The browser never sees the
-gateway bearer token. For the self-contained demo, the Worker mints a short-lived
-HS256-signed OIDC-style JWT and the gateway validates it against the tenant
-manifest.
+This Cloudflare Worker hosts a small gateway-control demo that calls the live
+AgentID gateway through a Cloudflare Service Binding. It shows AgentID
+authorizing both a SaaS refund workflow and an MCP provider-tool workflow before
+tool execution. The browser never sees the gateway bearer token. For the
+self-contained demo, the Worker mints a short-lived HS256-signed OIDC-style JWT
+and the gateway validates it against the tenant manifest.
 
 Live demo:
 

demo/package-lock.json

@@ -1,5 +1,5 @@
 {
-  "name": "agentid-refund-demo",
+  "name": "agentid-gateway-control-demo",
   "private": true,
   "type": "module",
   "scripts": {

demo/package.json

@@ -1,7 +1,8 @@
 # Getting Started with AgentID
 
-This walkthrough shows how to use AgentID as an authority contract for an AI
-agent and how to put checks in front of tool execution.
+This walkthrough shows how to use AgentID as an authorization contract for AI
+agent tool calls across app runtimes, internal systems, SaaS APIs, and MCP
+gateways.
 
 ## 1. Install
 
@@ -13,12 +14,12 @@ python -m pip install -e ".[dev]"
 
 ## 2. Validate a Manifest
 
-Start with the included ecommerce-style support/refund manifest:
+Start with the included provider MCP support manifest:
 
 ```bash
-agentid validate examples/customer-support-refund-agent.yaml
-agentid explain examples/customer-support-refund-agent.yaml
-agentid risk-score examples/customer-support-refund-agent.yaml
+agentid validate examples/provider-mcp-support-agent.yaml
+agentid explain examples/provider-mcp-support-agent.yaml
+agentid risk-score examples/provider-mcp-support-agent.yaml
 ```
 
 The manifest declares:
@@ -49,7 +50,7 @@ $schema: https://raw.githubusercontent.com/dinpd/AgentID/main/schema/agentid.sch
 Generate starter OPA/Rego policy from a manifest:
 
 ```bash
-agentid generate-policy examples/customer-support-refund-agent.yaml --target opa
+agentid generate-policy examples/provider-mcp-support-agent.yaml --target opa
 ```
 
 The manifest remains the portable source of truth. OPA is one target runtime
@@ -73,7 +74,7 @@ requests.
 ## 6. Run the Gateway Locally
 
 ```bash
-agentid gateway examples/customer-support-refund-agent.yaml --host 127.0.0.1 --port 8787
+agentid gateway examples/provider-mcp-support-agent.yaml --host 127.0.0.1 --port 8787
 ```
 
 Then authorize a tool call:
@@ -82,11 +83,15 @@ Then authorize a tool call:
 curl -s http://127.0.0.1:8787/authorize \
   -H 'content-type: application/json' \
   -d '{
-    "agent_id": "customer-support-refund-agent",
-    "tool": "zendesk.search_tickets",
+    "agent_id": "enterprise-support-agent",
+    "job_id": "support_case_resolution",
+    "case_id": "case-1042",
+    "customer_id": "cus_123",
+    "tool": "provider.crm.search_customer",
     "action": "read",
-    "data_from": "zendesk",
-    "data_to": "stripe"
+    "resource": "provider/customer/cus_123",
+    "data_from": "provider_crm",
+    "data_to": "agent_context"
   }'
 ```
 
@@ -129,10 +134,14 @@ const agentid = new AgentIdClient({
 });
 
 await agentid.assertAllowed("tenant-a", {
-  agent_id: "refund-agent",
-  tool: "zendesk.search_tickets",
+  agent_id: "enterprise-support-agent",
+  job_id: "support_case_resolution",
+  case_id: "case-1042",
+  customer_id: "cus_123",
+  tool: "provider.crm.search_customer",
   action: "read",
-  data_from: "zendesk",
+  resource: "provider/customer/cus_123",
+  data_from: "provider_crm",
   data_to: "agent_context",
 });
 ```
@@ -141,18 +150,24 @@ For sensitive actions, request a JIT grant before executing the tool:
 
 ```ts
 const grant = await agentid.requestJitGrant("tenant-a", {
-  tool: "stripe.create_refund",
+  tool: "provider.crm.update_customer",
   action: "write",
-  resource: "refund/case-1042",
+  resource: "provider/customer/cus_123",
+  job_id: "support_case_resolution",
+  case_id: "case-1042",
+  customer_id: "cus_123",
   approval_id: "approval-123",
   user_id: "support-rep-17",
 });
 
 await agentid.assertAllowed("tenant-a", {
-  agent_id: "refund-agent",
-  tool: "stripe.create_refund",
+  agent_id: "enterprise-support-agent",
+  tool: "provider.crm.update_customer",
   action: "write",
-  resource: "refund/case-1042",
+  resource: "provider/customer/cus_123",
+  job_id: "support_case_resolution",
+  case_id: "case-1042",
+  customer_id: "cus_123",
   approved: true,
   jit_grant_id: grant.jit_grant_id,
 });