Codiris Documentation

Transform any website into an autonomous AI agent. Codiris gives every site an MCP server, natural language tools, and a planning engine that lets AI assistants browse, search, purchase, and manage on behalf of users.

Quickstart

Get your first AI agent running in three steps.

1. Install the CLI

bash

curl -fsSL https://codiris.app/install.sh | bash

2. Transform a website

bash

agentize transform stripe.com

3. Open in your editor

bash

agentize open stripe_com --cursor

Tip

You can also use the web interface at codiris.app — just paste a URL and interact with the generated agent in your browser.

Installation

Install the Agentize CLI to transform websites and manage agents from your terminal.

One-liner (Recommended)

bash

curl -fsSL https://codiris.app/install.sh | bash

npx (No Install)

bash

npx agentize-cli <command>

npm / pnpm

bash

npm install -g agentize-cli

bash

pnpm add -g agentize-cli

Requirements

Node.js 14+ — macOS, Linux, or Windows.

Commands

transform <url> — Transform any website into an AI agent. Alias: t
list — List all agents you've created. Alias: ls
open <slug> — Open an agent in your IDE (Cursor, Claude Code, VS Code, Zed, etc.). Alias: o
download <slug> — Download an agent to a local directory. Alias: dl
info <slug> — Show detailed agent information. Alias: i
serve <slug> — Start an MCP server for an agent (stdio or HTTP). Alias: s
plan <slug|url> "goal" — Run autonomous planning and execution. Alias: p
skills — Manage reusable skill templates (list, show, create, delete, search)
settings — Manage persistent CLI settings (list, get, set, reset)

Examples

bash

# Transform and open in Cursor
agentize transform stripe.com
agentize open stripe_com --cursor

# Transform and open with Claude Code
agentize transform docs.anthropic.com
agentize open docs_anthropic_com --claude

# Run with npx (no install needed)
npx agentize-cli open stripe_com --cursor

# Start MCP server over HTTP
agentize serve stripe_com --http --port 3100

# Autonomous planning
agentize plan stripe_com "Find the best payment solution for a SaaS startup"

# Plan with a built-in skill
agentize plan mystore_com --skill seo-audit

Planning & Execution

Agents can autonomously break down complex goals into concrete steps, execute them using available tools, adapt when things fail, and deliver a synthesized result — just like Claude Code's agentic loop.

How It Works

Decomposition — AI analyzes your goal and available tools, then creates a step-by-step plan.
Execution — Each step runs sequentially. Results from earlier steps can be referenced by later ones via {{step_N_result}}.
Adaptation — When a step fails (after retries), AI suggests an alternative approach and injects it into the plan.
Synthesis — After all steps complete, AI combines results into a coherent final answer.

CLI Usage

bash

# Plan and execute a goal
agentize plan stripe_com "Compare all pricing tiers and recommend the best for a startup"

# Use a built-in skill
agentize plan mystore_com --skill competitor-analysis

# Target a URL directly
agentize plan --target https://airbnb.com "Find pet-friendly stays in Tokyo under $100/night"

MCP Tool

Every MCP server exposes a plan_and_execute tool. Any AI client (ChatGPT, Claude, Cursor, etc.) can trigger autonomous planning by calling this tool:

json

{
  "name": "plan_and_execute",
  "arguments": {
    "goal": "Find the top 5 products under $50 and compare them"
  }
}

Auto-Detection

Complex multi-step requests are automatically detected using a heuristic that looks for patterns like "and then", "compare", "analyze all", and conjunctions linking multiple actions. When detected, planning kicks in automatically — no explicit tool call needed.

Limits

Plans are capped at 15 steps, with up to 2 retries per step and 3 adaptation rounds per plan. These can be configured via agentize settings set max_plan_steps 20.

Skills

Skills are reusable prompt templates — pre-built goals that agents can execute via the planning engine. Codiris ships with 10 built-in skills and supports custom ones.

Agentizer — Featured Skill

Turn any website into a deployed AI-powered agentfront with one command. Crawls the brand, rewrites copy per brand type, ships a real MCP endpoint, deploys to {brand}.codiris.app. Install with git clone https://github.com/Humiris/wwa-transform.git ~/.claude/skills/codiris-agentizer. See full install guide →

Built-in Skills

seo-audit — Comprehensive SEO and AI visibility analysis with top 5 issues and fixes
competitor-analysis — Research competitors, compare positioning, and assess AI/MCP readiness
product-catalog-review — Audit catalog for missing descriptions, inconsistent pricing, and gaps
inventory-health — Identify low-stock, out-of-stock, and overstocked items with reorder recommendations
marketing-campaign — Generate multi-channel campaigns with descriptions, discounts, and social posts
customer-insights — Analyze order patterns, top customers, AOV trends, and product combinations
pricing-optimizer — Compare prices with market, find bundle opportunities, suggest tiered pricing
store-setup — Verify store configuration: images, collections, shipping, SEO, policies
ai-readiness — Assess structured data, APIs, MCP server, and AI integration readiness
content-generator — Generate product descriptions, FAQs, About Us page, and social post templates

Using Skills

bash

# Run a built-in skill
agentize plan mystore_com --skill seo-audit

# List all skills
agentize skills list

# Show skill details
agentize skills show competitor-analysis

# Search skills
agentize skills search marketing

Custom Skills

bash

# Create a custom skill
agentize skills create my-audit \
  --name "Custom Audit" \
  --goal "Check all product images for alt text and optimize for accessibility" \
  --tags "audit,accessibility"

# Delete a custom skill
agentize skills delete my-audit

Tip

Custom skills are stored as JSON files in ~/.agentize/skills/. Built-in skills cannot be overwritten or deleted.

Settings

Persistent CLI configuration stored in ~/.agentize/config.json. Only non-default values are saved.

Setting	Default	Description
`api_base`	`https://codiris.app`	API base URL
`api_key`	—	API key for authenticated agents
`default_client`	`cursor`	Default MCP client (claude, cursor, vscode, zed, windsurf)
`default_transport`	`stdio`	Transport mode (stdio, http)
`default_port`	`3100`	HTTP port for MCP servers
`model`	`gemini-3.1-pro-preview`	AI model for planning
`max_plan_steps`	`15`	Maximum steps in autonomous plans
`plan_auto_detect`	`true`	Auto-detect when planning is needed
`verbose`	`false`	Show detailed debug output
`theme`	`default`	CLI color theme (default, minimal, none)

Usage

bash

# List all settings
agentize settings list

# Get a setting
agentize settings get model

# Set a setting
agentize settings set default_client claude

# Reset a single setting to default
agentize settings reset default_port

# Reset all settings
agentize settings reset --all

# Show config file path
agentize settings path

Browser Interface

The web-based agent interface is the quickest way to interact with a transformed site. Once generated, every agent gets a dedicated URL where you can:

Natural language — Execute complex tasks via conversational prompts
Real-time progress — Watch agents plan, think, and act step by step
Mode switching — Toggle between Autonomous and Manual execution modes

URL Pattern

codiris.app/sites/[your-site-slug]

Terminal Usage

Power users can transform sites and interact with agents directly from the terminal, or build automation pipelines.

bash

# Transform a site
npx agentize-cli transform https://tesla.com

# Start an MCP server and connect Claude
agentize serve tesla_com --claude

# Run a plan from the terminal
agentize plan tesla_com "Compare Model 3 and Model Y features and pricing"

IDE Integration

Use your transformed web agents as tools directly within AI-native IDEs. Codiris auto-detects installed editors and opens with MCP configuration ready.

Editor	Flag	Priority
Cursor	`--cursor`	1
Claude Code	`--claude`	2
Antigravity	`--antigravity`	3
Codex	`--codex`	4
Windsurf	`--windsurf`	5
VS Code	`--code`	6
Zed	`--zed`	7
Sublime Text	`--sublime`	—
Neovim	`--nvim`	—
Vim	`--vim`	—
Emacs	`--emacs`	—

bash

# Auto-detect best editor
agentize open stripe_com

# Open in a specific editor
agentize open stripe_com --cursor
agentize open stripe_com --claude
agentize open stripe_com --code

MCP Protocol

Every Codiris agent exposes an MCP (Model Context Protocol) server — a standardized JSON-RPC 2.0 interface that any AI client can connect to over stdio or HTTP.

Connecting

json

// Claude Desktop / Cursor / VS Code MCP config
{
  "mcpServers": {
    "my-agent": {
      "url": "https://codiris.app/api/sites/YOUR_SLUG/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

Local Server (stdio)

bash

agentize serve stripe_com

Local Server (HTTP)

bash

agentize serve stripe_com --http --port 3100

What is MCP?

MCP is an open protocol created by Anthropic for connecting AI assistants to external tools. It uses JSON-RPC 2.0 with methods like tools/list and tools/call. Learn more at modelcontextprotocol.io.

Tools Reference

Every agent gets a set of tools based on the transformed website. The following core tools are available on all agents:

plan_and_execute — Autonomous planning engine. Pass a complex goal and the agent plans, executes, and returns the result.
search_products — Full-text search across the product catalog by keyword.
get_product — Get detailed product info by handle (variants, images, pricing).
get_collections — List all product collections with counts.
filter_products — Faceted filtering by price, type, vendor, tags, stock status.
create_cart / add_to_cart / get_cart — Full shopping cart lifecycle.

Shopify-connected agents get an additional 30+ tools. See the section for the complete list.

Marketplace Integrations

Connect any SaaS marketplace platform to Codiris and expose it as an AI-ready agent. Codiris supports a unified adapter interface that normalizes products, orders, categories, sellers, and inventory across all platforms.

Unified API — One set of endpoints and MCP tools for all marketplace platforms
5 platforms — Sharetribe, Marketplacer, CS-Cart Multi-Vendor, Arcadier, and enterprise connectors
Product sync — Full catalog sync to local cache for sub-50ms search
Multi-seller — List sellers, inventory per seller, cross-seller analytics
MCP tools — 7 marketplace-specific tools available to any AI client
Encrypted credentials — API keys stored with AES-256-GCM encryption
Autonomous planning — Combine marketplace tools with planning engine for complex tasks

Supported Platforms

Platform	Type	API	Key Features
Enterprise Connector	Enterprise	REST	Large-scale multi-vendor marketplaces. Products, offers, shops, orders.
Sharetribe	No-code builder	REST + OAuth2	Rental, service, and product marketplaces. Listings, transactions, users, events.
Marketplacer	Enterprise	GraphQL	Multi-seller commerce (Myer, The Iconic, Woolworths). Adverts, taxons, invoices.
CS-Cart Multi-Vendor	Self-hosted	REST	500+ features. Products, categories, orders, vendors. Basic auth with API key.
Arcadier	SaaS builder	REST + OAuth2	B2B, B2C, and rental marketplaces. Items, categories, merchants, orders.

Connecting a Marketplace

1. Get Your API Credentials

Each platform provides API keys through its admin panel. For enterprise and CS-Cart connectors, you'll need an API key. For Sharetribe and Arcadier, you'll need OAuth2 client credentials. For Marketplacer, a GraphQL API token.

2. Connect via API

bash

curl -X POST https://your-domain.com/api/marketplace/connect \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "your-site-slug",
    "platform": "enterprise",
    "base_url": "https://your-marketplace.example.com",
    "api_key": "your-api-key",
    "shop_id": "optional-shop-id"
  }'

Supported Platforms

json

{
  "platform": "enterprise"    // Enterprise marketplace connector
  "platform": "sharetribe"    // Sharetribe (use secondary_key for client_secret)
  "platform": "marketplacer"  // Marketplacer
  "platform": "cscart"        // CS-Cart (use secondary_key for admin email)
  "platform": "arcadier"      // Arcadier (use secondary_key for client_secret)
}

Credential Security

All API keys and tokens are encrypted with AES-256-GCM before storage. The connection is tested before saving — invalid credentials are rejected immediately.

3. List Connections

bash

curl "https://your-domain.com/api/marketplace/connect?slug=your-site" \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Disconnect

bash

curl -X DELETE https://your-domain.com/api/marketplace/connect \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "your-site", "platform": "enterprise"}'

Product Sync

After connecting, trigger a full sync to cache all products locally for fast search. Products, categories, variants, images, and attributes are all normalized and stored.

bash

# Trigger sync
curl -X POST https://your-domain.com/api/marketplace/sync \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "your-site", "platform": "enterprise"}'

# Check sync status
curl "https://your-domain.com/api/marketplace/sync?slug=your-site" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Synced Products

bash

# Search by keyword
curl "https://your-domain.com/api/marketplace/products?slug=my-site&q=winter+jacket"

# Filter by category and price
curl "https://your-domain.com/api/marketplace/products?slug=my-site&category=clothing&min_price=20&max_price=100"

# Filter by brand, in-stock only
curl "https://your-domain.com/api/marketplace/products?slug=my-site&brand=Nike&in_stock=true"

Marketplace MCP Tools

When a marketplace is connected, 7 additional MCP tools become available to any AI client. These work across all platforms with the same interface.

Tool	Description
`marketplace_search_products`	Search products by keyword, category, price, brand, platform
`marketplace_get_product`	Get full product details by platform ID
`marketplace_get_categories`	List all marketplace categories (hierarchical)
`marketplace_get_orders`	Fetch orders with status and date filters
`marketplace_get_sellers`	List all sellers/vendors on the marketplace
`marketplace_get_inventory`	Check stock levels for a specific product
`marketplace_get_analytics`	Revenue, order count, top products, top sellers

Works with Planning

Marketplace tools integrate with the autonomous planning engine. Ask your agent to "analyze all sellers and compare their product pricing" and it will plan and execute the multi-step workflow automatically.

Marketplace API Reference

Method	Endpoint	Description
POST	`/api/marketplace/connect`	Connect a marketplace platform
GET	`/api/marketplace/connect`	List connections for a site
DELETE	`/api/marketplace/connect`	Disconnect a marketplace
POST	`/api/marketplace/sync`	Trigger product sync
GET	`/api/marketplace/sync`	Get sync status
GET	`/api/marketplace/products`	Search/list products from local cache
POST	`/api/marketplace/products`	Live search on platform
GET	`/api/marketplace/orders`	Fetch orders from marketplace
GET	`/api/marketplace/categories`	List marketplace categories
GET	`/api/marketplace/sellers`	List marketplace sellers
GET	`/api/marketplace/analytics`	Marketplace analytics
POST	`/api/marketplace/webhooks`	Webhook receiver

Database Schema

text

marketplace_connections  — Platform, base URL, encrypted API keys, shop ID, status
marketplace_products     — Normalized product cache (all platforms → same schema)
marketplace_categories   — Category hierarchy per platform
marketplace_sync_log     — Sync history with timing and error tracking

Shopify Integration

Transform any Shopify store into a fully AI-agent-ready commerce platform. Connect via OAuth 2.0, sync your entire catalog, and expose 30+ MCP tools for AI assistants to search, cart, order, and manage.

GraphQL-first — All calls use Shopify's modern GraphQL APIs (Storefront + Admin)
OAuth 2.0 — Secure token exchange, encrypted at rest with AES-256-GCM
Product sync — Full catalog cached locally for sub-50ms search
Real-time webhooks — Products, orders, and inventory stay fresh automatically
30+ MCP tools + CLI — Search, cart, orders, inventory, images, enrichment
4 AI agents — Shopping assistant, inventory manager, marketing agent, customer support
AI image generation — Product photos, lifestyle shots, marketing banners via Gemini Imagen
Semantic search — Natural language product discovery via embeddings + pgvector
AI enrichment — Auto-generate descriptions, SEO metadata, tags, translations

Architecture

text

Shopify Store
    |
    v
OAuth 2.0 (Admin + Storefront tokens)
    |
    v
GraphQL Client (rate-limited, retry-aware)
    |
    +---> Product Sync ---> Supabase (shopify_products)
    |                            |
    |                            +---> Full-text search
    |                            +---> Semantic search (pgvector)
    |
    +---> Webhook Receiver ---> Real-time updates
    |
    +---> MCP Server (/api/sites/[slug]/mcp)
    |         |
    |         +---> 12 Storefront tools
    |         +---> 8 Admin tools
    |         +---> 6 AI tools
    |         +---> plan_and_execute
    |
    +---> Agent Orchestrator
              |
              +---> Shopping Assistant
              +---> Inventory Manager
              +---> Marketing Agent
              +---> Customer Support

Setup & OAuth

1. Create a Shopify App

Go to Shopify Partners → Apps → Create app
Set your app URL to https://your-domain.com
Set redirect URL to https://your-domain.com/api/shopify/callback
Copy the Client ID and Client Secret

2. Environment Variables

env

SHOPIFY_API_KEY=your_shopify_app_client_id
SHOPIFY_API_SECRET=your_shopify_app_client_secret
SHOPIFY_ENCRYPTION_KEY=your_64_char_hex_key_here

3. Connect a Store

From the Dashboard, click Connect Catalog, enter the Shopify store domain (e.g. mystore.myshopify.com), and click Connect with Shopify. The OAuth flow handles everything automatically: consent screen, token exchange, webhook registration, and AES-256-GCM token encryption.

Required Scopes

Scope	Purpose
`read_products, write_products`	Catalog sync and AI enrichment
`read_orders`	Order tracking and analytics
`read_inventory, write_inventory`	Stock levels and adjustments
`read_customers`	Customer profiles for support agent
`read_fulfillments, write_fulfillments`	Shipment tracking
`read_discounts, write_discounts`	Promotional discount codes
`read_files, write_files`	AI-generated image uploads

Product Sync

After connecting, Codiris syncs your entire Shopify catalog to Supabase for fast search. Products, collections, images, variants, and metafields are all cached.

Type	When	How
Full sync	First connection, manual trigger	Cursor-paginated GraphQL (50/page)
Incremental	Manual trigger	Only products updated since last sync
Webhook	Real-time	Individual product/order/inventory updates

bash

# Full sync
curl -X POST https://your-domain.com/api/shopify/sync \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "your-site", "type": "full"}'

# Incremental sync
curl -X POST https://your-domain.com/api/shopify/sync \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "your-site", "type": "incremental"}'

Webhooks

Webhooks are automatically registered when you connect a store and keep your cache in sync.

Topic	Action
`products/create`	Insert new product into cache
`products/update`	Update product in cache
`products/delete`	Remove from cache
`orders/create`	Track new order
`orders/updated`	Update order status
`inventory_levels/update`	Update stock levels
`app/uninstalled`	Revoke connection

Security

All webhook payloads are verified using HMAC-SHA256 with the app secret before processing.

Shopify MCP Tools

Once connected, these tools are available to any AI client via MCP or CLI.

Storefront Tools

Tool	Type	Description
`search_products`	know	Full-text product search
`get_product`	know	Product details by handle
`get_collections`	know	List all collections
`get_collection_products`	know	Products in a collection
`get_product_recommendations`	know	AI-driven recommendations
`get_new_arrivals`	know	Recently added products
`check_availability`	know	Variant-level stock
`filter_products`	know	Faceted filter
`search_by_tag`	know	Find by tag
`create_cart`	do	Create shopping cart
`add_to_cart`	do	Add items to cart
`get_cart`	know	View cart + checkout URL

Admin Tools

Tool	Type	Description
`get_recent_orders`	know	Recent orders with line items
`get_order_status`	know	Single order by number
`get_inventory_levels`	know	Stock per location
`adjust_inventory`	do	Adjust variant stock
`get_order_analytics`	know	Revenue, AOV, order count

Connecting

json

{
  "mcpServers": {
    "your-store": {
      "url": "https://your-domain.com/api/sites/YOUR_SLUG/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

AI Image Generation

Generate professional product images using Gemini Imagen. Codiris auto-detects product categories and selects scene templates.

product_photo — Clean white background, studio lighting, 3/4 angle
lifestyle — Product in context (auto-detected scene by category)
marketing — Banner design with space for text overlay
background_removal — Remove background from existing image

bash

curl -X POST https://your-domain.com/api/shopify/images/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "your-site",
    "productTitle": "Organic Cotton T-Shirt",
    "style": "lifestyle",
    "scene": "worn by a model in a sunlit park"
  }'

Auto Scene Detection

Category	Scene
Clothing	Modern mannequin in a bright, airy boutique
Jewelry	Velvet display with dramatic close-up lighting
Electronics	Minimal desk with soft ambient lighting
Food	Rustic wooden table with fresh ingredients
Beauty	Marble vanity with golden hour lighting
Furniture	Scandinavian living room with natural light

AI Agents

Four specialized agents work through an orchestration layer. Messages are classified by intent and routed automatically. Agents can hand off conversations to each other.

Agent	Handles	Key Tools
Shopping Assistant	Search, recommendations, cart	search_products, create_cart, add_to_cart
Inventory Manager	Stock, adjustments, alerts	get_inventory_levels, adjust_inventory
Marketing Agent	Images, discounts, trending	generate_product_image, create_discount_code
Customer Support	Orders, returns, accounts	get_order_status, initiate_return

bash

# Auto-route by intent
curl -X POST https://your-domain.com/api/agents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "your-site",
    "sessionId": "session_abc123",
    "message": "Do you have any blue sneakers in stock?"
  }'

Agent Handoffs

When a customer starts asking about order tracking during a product search, the orchestrator detects the intent shift and hands off from Shopping Assistant to Customer Support, preserving the full conversation context.

AI Enrichment

Automatically improve product listings with better descriptions, SEO metadata, tags, categorization, and translations.

description — Generate compelling copy (tones: professional, casual, luxury, friendly, technical)
seo — Optimized title (max 60 chars) and meta description (max 155 chars)
tags — Auto-suggest 5-10 relevant tags from product attributes
category — Suggest product type and collections
translate — Translate title and description to any language

bash

# Generate a luxury-tone description
curl -X POST https://your-domain.com/api/shopify/enrich \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "your-site",
    "productId": "product-uuid",
    "type": "description",
    "tone": "luxury"
  }'

Semantic Search

Natural language product discovery via embeddings (Gemini text-embedding-004 + pgvector):

bash

# Semantic search
curl "https://your-domain.com/api/shopify/search?slug=my-store&q=warm+winter+jacket&mode=semantic"

# Full-text search
curl "https://your-domain.com/api/shopify/search?slug=my-store&q=wool+jacket&mode=fulltext"

# Hybrid (both, deduplicated)
curl "https://your-domain.com/api/shopify/search?slug=my-store&q=cozy+coat&mode=hybrid"

Analytics

Deep commerce insights including AI agent attribution at /dashboard/shopify.

Revenue — Total and per-period revenue, currency, average order value
Orders — Count, revenue by day chart
Products — Total, in-stock, out-of-stock, low-stock counts
AI Conversion — Agent sessions, purchases attributed to AI, conversion rate
Top Products — Bestsellers ranked by units and revenue
Agent Performance — Sessions per type, avg messages per session

bash

curl "https://your-domain.com/api/shopify/analytics?slug=my-store&period=30" \
  -H "Authorization: Bearer YOUR_TOKEN"

API Reference

Shopify Endpoints

Method	Endpoint	Description
GET	`/api/shopify/auth`	Initiate OAuth flow
GET	`/api/shopify/callback`	OAuth callback
POST	`/api/shopify/sync`	Trigger product sync
GET	`/api/shopify/sync`	Sync status
GET	`/api/shopify/products`	List/search products
POST	`/api/shopify/products`	Create product
PUT	`/api/shopify/products`	Update product
GET	`/api/shopify/search`	Semantic/fulltext search
POST	`/api/shopify/enrich`	AI enrichment
POST	`/api/shopify/images/generate`	Generate AI image
GET	`/api/shopify/analytics`	Commerce analytics
POST	`/api/shopify/webhooks`	Webhook receiver

Agent Endpoints

Method	Endpoint	Description
POST	`/api/agents`	Chat with agent or call tool
GET	`/api/agents`	Get session state
POST	`/api/agents/plan`	Autonomous planning endpoint
GET	`/api/agents/plan`	Check if message needs planning
POST	`/api/agents/handoff`	Agent handoff

MCP Endpoint

Method	Endpoint	Description
POST	`/api/sites/[slug]/mcp`	JSON-RPC 2.0 MCP server (tools/list, tools/call, etc.)

Database Schema

text

shopify_connections   — OAuth tokens (encrypted), scopes, shop domain
shopify_products      — Full product catalog cache with variants, images
shopify_collections   — Collections with product counts
shopify_sync_log      — Sync history and status
shopify_webhooks      — Registered webhook subscriptions
shopify_orders        — Order data from webhooks
shopify_generated_images — AI-generated image jobs and URLs
product_enrichments   — AI enrichment suggestions
agent_sessions        — Multi-agent conversation state
agent_handoffs        — Agent-to-agent handoff log
agent_conversions     — AI-attributed sales tracking
shopify_analytics     — Aggregated commerce metrics

Deployment

Standard — Free hosting on [agent-name].codiris.app
Custom Domain — Set up your own domain (e.g. ai.yourdomain.com) via CNAME

Environment Variables

Copy .env.local.example to .env.local and configure:

Variable	Required	Description
`GEMINI_API_KEY`	Yes	Google Gemini API key
`NEXT_PUBLIC_SUPABASE_URL`	Yes	Supabase project URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Yes	Supabase anonymous key
`SUPABASE_SERVICE_KEY`	Yes	Supabase service role key
`NEXTAUTH_URL`	Yes	Your app URL
`NEXTAUTH_SECRET`	Yes	Session encryption secret
`GOOGLE_CLIENT_ID`	Yes	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Yes	Google OAuth client secret
`SHOPIFY_API_KEY`	Shopify	Shopify app client ID
`SHOPIFY_API_SECRET`	Shopify	Shopify app client secret
`SHOPIFY_ENCRYPTION_KEY`	Shopify	64-char hex for AES-256-GCM token encryption