@ductape/mcp 0.1.13 → 0.1.15

package/src/index.ts

@@ -166,7 +166,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   webhooks.events.list   [app_tag, webhook_tag]
 
 ━━━ MODULE: sessions ━━━
-  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: "string"|"number"|"boolean" } }]
+  sessions.create        [product_tag, data: { tag: string, name: string, description?: string, expiry: number, period: "seconds"|"minutes"|"hours"|"days", selector: string, schema: { fieldName: { type: "string"|"number"|"boolean"|"object"|"array", required?: boolean, description?: string } } }]
+  ← selector is the dot-path of the primary identifier field (e.g. "playerId"); it MUST exist in schema.
+  ← schema declares the shape of data encrypted in the JWT; actual values are passed at runtime via sessions.start.
   sessions.update        [product_tag, session_tag, data: { name?: string, description?: string, expiry?: number, period?: "seconds"|"minutes"|"hours"|"days", selector?: string, schema?: object }]
   sessions.fetch         [product_tag, session_tag]
   sessions.list          [product_tag]
@@ -302,8 +304,15 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   messageBrokers.fetch    [product_tag, broker_tag]
   messageBrokers.list     [product_tag]
   messageBrokers.delete   [product_tag, broker_tag]
-  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string, type: "producer"|"consumer"|"both" }]
-  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, type?: "producer"|"consumer"|"both" }]
+  messageBrokers.topics.create [product_tag, data: { tag: string, name: string, broker: string,
+    description?: string, sample?: object, idempotent?: boolean,
+    queueUrls?: [{ env_slug: string, url: string }]  // SQS only: per-env queue URL per topic
+  }]
+  ← A broker can have unlimited topics. Add one per logical event type.
+  ← For SQS: each topic needs queueUrls mapping env slug → the SQS queue URL for that topic+env.
+  ← For Pub/Sub and Service Bus: topic name resolves from the tag or broker env config; no queueUrls needed.
+  messageBrokers.topics.update [product_tag, topic_tag, data: { name?: string, description?: string,
+    sample?: object, idempotent?: boolean, queueUrls?: [{ env_slug: string, url: string }] }]
   messageBrokers.topics.fetch  [product_tag, topic_tag]
   messageBrokers.topics.list   [product_tag, broker_tag]
   messageBrokers.produce  [{ product, env, event: "broker_tag:topic_tag", message: { key: value }, session?, cache? }]  ← CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce", targets={broker, event})
@@ -383,6 +392,15 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.action.delete [action_tag]
   databases.action.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch", targets={database, action})
   databases.dispatch [{ product, env, database, action, input, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="database", method="dispatch")
+  databases.beginTransaction [{ product, env, database, isolationLevel?: "READ_COMMITTED"|"REPEATABLE_READ"|"SERIALIZABLE" }]
+    → returns a transaction object; pass it to insert/update/delete/upsert/query calls as the last argument.
+    Commit with: transaction.commit()   Rollback with: transaction.rollback()
+    BEFORE using transactions: ask the user which database type and tier they are running.
+    Transaction support varies by database — call ductape_docs({ topic: "transactions" }) for the full matrix.
+  databases.transaction [{ product, env, database, isolationLevel? }, async (tx) => { … }]
+    → managed transaction: commits automatically on success, rolls back on error.
+    Prefer this over beginTransaction when the callback is self-contained.
+    See ductape_docs({ topic: "transactions" }) for database/tier compatibility before proceeding.
 
 ━━━ MODULE: graph ━━━
   graph.create  [{ product, tag, name, description?, type: "neo4j"|"nebula"|"arangodb", envs: [{slug, connection_url, username?, password?}] }]
@@ -586,7 +604,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   caches.list    [product_tag]
   caches.delete  [product_tag, cache_tag]
   caches.get     [{ key: string }]
-  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: Date }]
+  caches.set     [{ product, cache, key, value: string, componentTag?, componentType?, expiry?: string (ISO 8601 absolute timestamp — NOT a duration; e.g. new Date(Date.now()+3600000).toISOString() for 1h TTL), env }]
   caches.clear   [{ key: string }]
   caches.clearAll [{ product, cache, env? }]
   caches.fetchValues [{ product, cache, env?, page?, limit?, expiryFilter?: "all"|"expiring"|"permanent"|"expired" }]
@@ -959,6 +977,1232 @@ function runCli(command: string): { success: boolean; output: string } {
   }
 }
 
+const docsInputSchema = z.object({
+  topic: z.string().describe(
+    'Feature topic to look up. Supported: ' +
+    'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
+    'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
+    'notifications, resilience, features, events, logs',
+  ),
+});
+
+const DOCS: Record<string, string> = {
+  transactions: `
+DUCTAPE DATABASE TRANSACTIONS
+
+Ask the user which database type and tier they are using before advising on transaction support.
+
+Support matrix:
+  PostgreSQL   — full ACID; all isolation levels (READ_UNCOMMITTED, READ_COMMITTED,
+                  REPEATABLE_READ, SERIALIZABLE). Always supported.
+  MySQL        — full ACID; same isolation levels as PostgreSQL.
+  MongoDB      — multi-document transactions require a replica set.
+                  Atlas M10+ (dedicated): supported.
+                  Atlas M0/M2/M5 (free/shared): NOT supported — all writes are
+                  single-document atomic only. Confirm tier with user before proceeding.
+                  Self-hosted: supported if replica set mode is enabled.
+  Cassandra    — does NOT support ACID transactions. Lightweight transactions (LWT)
+                  only for single-partition compare-and-set.
+  DynamoDB     — transactional API supported (TransactWrite) but NOT via Ductape's
+                  transaction abstraction; use single operations with condition expressions.
+
+Usage patterns:
+  // Managed (preferred) — auto-commit on success, auto-rollback on error:
+  await ductape.database.transaction(
+    { product, env, database, isolationLevel: 'READ_COMMITTED' },
+    async (tx) => {
+      await ductape.database.insert({ ..., transaction: tx });
+      await ductape.database.update({ ..., transaction: tx });
+    }
+  );
+
+  // Manual — commit/rollback yourself:
+  const tx = await ductape.database.beginTransaction({ product, env, database });
+  try {
+    await ductape.database.insert({ ..., transaction: tx });
+    await tx.commit();
+  } catch (e) {
+    await tx.rollback();
+    throw e;
+  }
+
+Via ductape_execute:
+  ductape_execute("databases.beginTransaction", [{ product, env, database, isolationLevel? }])
+  → returns a transaction reference you can pass to subsequent insert/update/delete calls.
+`.trim(),
+
+  presave: `
+DUCTAPE PRE-SAVE HOOKS
+
+Pre-save operations transform or validate data before it is written to the database.
+Pass a preSave array to insert or update operations. Operations run in priority order.
+
+Available operations (PreSaveOperationType):
+  encrypt         — AES-256 encrypt field (use for PII, secrets)
+  hash            — one-way hash (bcrypt/argon2 for passwords)
+  mask            — mask sensitive data (e.g. **** **** **** 1234)
+  trim            — strip leading/trailing whitespace
+  lowercase       — convert string to lowercase
+  uppercase       — convert string to uppercase
+  sanitize        — strip HTML/script tags
+  validate        — throw if field value fails a rule
+  transform       — apply a custom mapping function
+  uuid            — generate a UUID for the field
+  slug            — generate a URL slug from another field
+  timestamp       — set field to current timestamp (ISO 8601)
+  round           — round number to N decimal places
+  clamp           — clamp number to a min/max range
+  truncate        — truncate string to max length
+  default         — set a default value if null/undefined
+  normalizePhone  — normalise phone number format
+  normalizeEmail  — lowercase + trim email
+  parseJson       — parse JSON string to object
+  stringifyJson   — serialise object to JSON string
+  compute         — derive field value from other fields (runs before validate)
+
+Execution order is fixed regardless of declaration order:
+  default → compute → validate → trim → lowercase/uppercase/normalize* →
+  sanitize → truncate → slug → round/clamp → parseJson/stringifyJson → uuid/timestamp → transform
+
+Example:
+  await ductape.database.insert({
+    product, env, database: 'users', entity: 'users',
+    data: { email: '  User@Example.com  ', password: 'secret', username: 'My App User' },
+    preSave: [
+      { field: 'email',    operation: 'normalizeEmail' },
+      { field: 'password', operation: 'hash' },
+      { field: 'username', operation: 'slug', target: 'slug' },
+    ],
+  });
+`.trim(),
+
+  triggers: `
+DUCTAPE DATABASE TRIGGERS
+
+Triggers fire automatically in response to database write events.
+Defined via the Workbench UI or databases.trigger.create (admin SDK).
+
+Events (TriggerEvent):
+  beforeInsert / afterInsert
+  beforeUpdate / afterUpdate
+  beforeDelete / afterDelete
+  beforeWrite  / afterWrite  (any write)
+
+Timing (TriggerTiming):
+  sync    — block the write until trigger completes (adds latency)
+  async   — fire and forget (default for notifications, cache, broker)
+  queued  — enqueue for background processing
+
+Action types (TriggerActionType):
+  database.*    — insert/update/delete/query another collection
+  storage.*     — upload/delete/copy a file
+  notification.* — email/SMS/push/callback
+  broker.publish — publish to a message broker topic
+  cache.*       — set/invalidate/delete a cache key
+  feature.*     — execute or dispatch a Ductape feature
+  action.execute — call an app action
+  agent.run      — run an AI agent
+  quota.run / fallback.run / healthcheck.run
+  vector.upsert / vector.delete
+  session.revoke
+  log.create
+  custom.function / custom.http
+
+All triggers support an optional condition (field comparisons) to gate execution.
+All triggers support retry config: { maxAttempts, delay, backoff: "fixed"|"exponential" }.
+
+Triggers are admin-only configuration — they cannot be set at runtime via ductape_execute.
+Use ductape_cli with the Workbench or databases.trigger.create via the admin SDK.
+`.trim(),
+
+  aggregations: `
+DUCTAPE DATABASE AGGREGATIONS
+
+databases.aggregate [{ product, env, database, entity, aggregations, where?, groupBy? }]
+
+aggregations array — each entry:
+  { type: "count"|"sum"|"avg"|"min"|"max", field?: string, alias: string }
+
+Example — total revenue grouped by category:
+  ductape_execute("databases.aggregate", [{
+    product: "my-product",
+    env: "prd",
+    database: "sales-db",
+    entity: "orders",
+    aggregations: [
+      { type: "sum",   field: "amount",   alias: "totalRevenue" },
+      { type: "count",                    alias: "orderCount"   },
+      { type: "avg",   field: "amount",   alias: "avgOrderValue" },
+    ],
+    groupBy: ["category"],
+    where: { status: { $eq: "completed" } },
+  }])
+
+Supported where operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $like, $ilike
+groupBy: array of field names to group by (omit for global aggregation)
+`.trim(),
+
+  migrations: `
+DUCTAPE DATABASE MIGRATIONS
+
+Migrations are versioned SQL/NoSQL schema change scripts managed per database component.
+
+Create a migration:
+  ductape_execute("databases.migration.create", [{
+    product: "my-product",
+    database: "core-db",
+    data: {
+      name: "add users table",
+      tag: "001-add-users",
+      value: {
+        up:   ["CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE)"],
+        down: ["DROP TABLE users"],
+      },
+    },
+  }])
+
+Run migrations (applies all pending):
+  ductape_execute("databases.migration.run", [migrations, { env: "prd" }])
+
+Rollback:
+  ductape_execute("databases.migration.rollback", [migrations, 1])  // roll back 1
+
+Check status:
+  ductape_execute("databases.migration.status", [migrations])
+
+History:
+  ductape_execute("databases.migration.history", [])
+
+Via CLI:
+  ductape_cli("db migrate")              // run pending
+  ductape_cli("db migrate rollback")     // roll back last
+  ductape_cli("db migrate rollback -n 3")
+
+MongoDB: migrations run as raw Mongo shell commands in the up/down arrays.
+`.trim(),
+
+  indexes: `
+DUCTAPE DATABASE INDEXES
+
+Create an index:
+  ductape_execute("databases.schema.createIndex", [
+    "collection_name",
+    ["field1", "field2"],           // simple array of field names
+    { unique: true, name: "idx_email_unique" }   // options (optional)
+  ])
+
+  // Ordered index:
+  ductape_execute("databases.schema.createIndex", [
+    "orders",
+    [{ field: "createdAt", order: "DESC" }, { field: "userId", order: "ASC" }],
+    { name: "idx_orders_date_user" }
+  ])
+
+Drop an index:
+  ductape_execute("databases.schema.dropIndex", ["collection_name", "index_name"])
+
+List indexes on a collection:
+  ductape_execute("databases.schema.indexes", ["collection_name"])
+
+Performance guidance:
+  - Index fields used in WHERE clauses, JOIN conditions, and ORDER BY.
+  - Compound indexes: put high-cardinality fields first.
+  - Unique indexes enforce uniqueness at the database level.
+  - MongoDB: compound indexes support prefix queries; order matters.
+  - PostgreSQL/MySQL: B-tree indexes by default; use partial indexes for sparse columns.
+  - Avoid over-indexing writes-heavy collections — each index slows inserts/updates.
+
+Before adding an index ask the user which fields they query/filter on and expected data volume.
+`.trim(),
+
+  performance: `
+DUCTAPE DATABASE PERFORMANCE GUIDANCE
+
+1. Queries
+   - Always pass select: ["field1", "field2"] to avoid fetching unused columns.
+   - Use limit + offset for pagination; add an index on the ORDER BY field.
+   - Use count/sum/avg/aggregate instead of fetching all rows and computing in code.
+
+2. Indexes (see ductape_docs({ topic: "indexes" }) for syntax)
+   - Index every WHERE / ORDER BY field.
+   - Compound index order: equality fields first, range fields last.
+   - For MongoDB: covered queries (index holds all projected fields) skip the document read.
+
+3. Connections
+   - The SDK pools connections per product+env+database triple.
+   - Call databases.connect once per process; the pool reuses the connection.
+   - databases.disconnect releases the pool — call only on shutdown.
+
+4. Transactions (see ductape_docs({ topic: "transactions" }))
+   - Keep transactions short; long-lived transactions block row locks (PostgreSQL/MySQL).
+   - For MongoDB on M10+, use sessions for multi-document writes — not for reads.
+
+5. Caching
+   - For read-heavy, rarely-changing data use caches.get before databases.query.
+   - Invalidate cache keys in an afterWrite trigger (see ductape_docs({ topic: "triggers" })).
+`.trim(),
+
+  actions: `
+DUCTAPE DATABASE ACTIONS
+
+A database action is a saved query or mutation (SQL string or NoSQL command) stored
+on the Ductape product and executed by tag at runtime.
+
+Create an action (admin):
+  ductape_execute("databases.action.create", [{
+    product: "my-product",
+    database: "core-db",
+    data: {
+      tag: "get-active-users",
+      name: "Get active users",
+      description: "Returns all users with status=active",
+      type: "sql",                    // "sql" or "nosql"
+      query: "SELECT * FROM users WHERE status = :status",
+    },
+  }])
+
+Dispatch an action at runtime:
+  → CALL ductape_generate_payload FIRST to get the canonical input shape.
+  ductape_execute("databases.action.dispatch", [{
+    product: "my-product",
+    env: "prd",
+    database: "core-db",
+    action: "get-active-users",
+    input: { status: "active" },
+  }])
+
+List actions for a database:
+  ductape_execute("databases.action.list", ["database_tag"])
+
+Fetch / update / delete:
+  ductape_execute("databases.action.fetch",  ["action_tag"])
+  ductape_execute("databases.action.update", ["my-product", "action_tag", { query: "..." }])
+  ductape_execute("databases.action.delete", ["action_tag"])
+
+Actions are the preferred way to encapsulate complex or reused queries — they can be
+scheduled, dispatched with retries, and audited via logs.
+`.trim(),
+
+  graphs: `
+DUCTAPE GRAPH DATABASES
+
+Supported engines: neo4j | neptune | cosmos-gremlin | spanner-graph | arangodb | memgraph
+
+Registration (admin — ductape_cli):
+  ductape_cli("resources graphs create -f graph.json")
+  File: { name, tag, type, envs: [{ slug, connection_url, username?, password?, graphName?, region? }] }
+  Sensitive fields (connection_url, username, password) are auto-wrapped as $Secret{...} when
+  a productTag is supplied — do NOT pre-wrap them yourself.
+
+Node operations:
+  graph.createNode    [{ labels: string[], properties: { key: value } }, transaction?]
+  graph.findNodes     [{ labels?, where?, limit?, skip? }, transaction?]
+  graph.findNodeById  [id, transaction?]
+  graph.updateNode    [{ id, properties }, transaction?]
+  graph.deleteNode    [{ id, detach?: boolean }, transaction?]
+  graph.mergeNode     [{ labels, matchProps, setProps? }, transaction?]
+  graph.addLabels / removeLabels / setLabels  [{ id, labels }, transaction?]
+
+Relationship operations:
+  graph.createRelationship  [{ fromId, toId, type, properties? }, transaction?]
+  graph.findRelationships   [{ type?, where?, limit? }, transaction?]
+  graph.updateRelationship  [{ id, properties }, transaction?]
+  graph.deleteRelationship  [{ id }, transaction?]
+  graph.mergeRelationship   [{ fromId, toId, type, matchProps?, setProps? }, transaction?]
+
+Traversal:
+  graph.traverse            [{ startId, direction: "in"|"out"|"both", relationshipTypes?, maxDepth?, where? }]
+  graph.shortestPath        [{ fromId, toId, relationshipType?, maxDepth? }]
+  graph.allPaths            [{ fromId, toId, relationshipType?, maxDepth? }]
+  graph.getNeighborhood     [{ id, depth?, relationshipTypes? }]
+  graph.findConnectedComponents [{ labels? }]
+
+Raw query (provider-native Cypher/Gremlin):
+  graph.query [cypher_query: string, params?: { key: value }, transaction?]
+
+Full-text and vector search (where supported):
+  graph.fullTextSearch  [{ index, query, limit? }]
+  graph.vectorSearch    [{ index, vector: number[], topK? }]
+
+Transactions:
+  graph.beginTransaction     [options?: { isolationLevel?, timeout? }]  → transaction object
+  graph.commitTransaction    [transaction]
+  graph.rollbackTransaction  [transaction]
+  Or use withTransaction (managed — auto-commit/rollback):
+    graph.withTransaction [graphTag, env, callback, options?]
+  Transaction support varies by engine — ask the user which engine they use before enabling.
+  neo4j: full ACID; neptune: limited; arangodb: multi-document; memgraph: full ACID.
+
+Schema management:
+  graph.createNodeIndex      [{ label, field, type: "btree"|"fulltext"|"vector" }]
+  graph.createNodeConstraint [{ label, field, type: "unique"|"exists" }]
+  graph.dropIndex / dropConstraint / listIndexes / listConstraints
+
+Saved actions (parameterized queries stored on the product):
+  graph.createAction [{ graphTag, tag, name, query, params? }, productTag?]
+  graph.listActions  [graphTag?, productTag?]
+  graph.dispatch     [data]  ← call ductape_generate_payload FIRST
+
+Supported index types: btree | fulltext | vector | range | point | text
+Supported constraint types: UNIQUE | EXISTS | NODE_KEY
+`.trim(),
+
+  storage: `
+DUCTAPE FILE STORAGE
+
+Supported providers: aws (S3) | gcp (GCS) | azure (Blob Storage)
+
+Registration (admin — ductape_cli):
+  ductape_cli("resources storage create -f storage.json")
+  File: { name, tag, envs: [{ slug, type: "aws"|"gcp"|"azure", config: { ... } }] }
+  For cloud-linked envs: set config.cloud to the connection tag; omit raw credentials.
+  For all envs in the product must be covered — see ductape_docs({ topic: "cloud" }) for
+  import-persist-all workflow when connecting existing buckets.
+
+Operations (runtime):
+  storage.upload       [{ product, env, storage, fileName, buffer: string|Buffer, mimeType? }]
+  storage.download     [{ product, env, storage, fileName }]   → { content, size, mimeType }
+  storage.remove       [{ product, env, storage, fileName }]
+  storage.listFiles    [{ product, env, storage, prefix?, limit?, continuationToken? }]
+  storage.getSignedUrl [{ product, env, storage, fileName, expiresIn?: number, action?: "read"|"write" }]
+  storage.stats        [{ product, env, storage, prefix?, cache? }]   → file counts by type
+  storage.testConnection [{ product, env, storage }]
+
+Background dispatch (fire-and-forget):
+  storage.dispatch [{ product, env, storage, operation, input, schedule? }]
+  → CALL ductape_generate_payload FIRST (operation_family="storage", method="dispatch")
+  → Returns { jobId, status: "queued" } immediately; actual operation runs in background.
+  → schedule: { start_at?, cron?, every?, limit?, endDate?, tz? }
+
+Caching:
+  download, listFiles, getSignedUrl, and stats all support a cache option.
+  Pass cache: "cache_tag" to check the product cache before hitting the provider.
+  Cached results are stored fire-and-forget on miss.
+
+Notes:
+  - buffer can be a Node.js Buffer (server) or a base64 string (JSON proxy clients).
+  - Cloud-linked configs inject runtime credentials via the cloud connection; no plaintext keys stored.
+  - $Secret{} references in config are resolved at runtime if cloud-link resolution fails.
+`.trim(),
+
+  cloud: `
+DUCTAPE CLOUD CONNECTIONS
+
+Cloud connections link your workspace to an external cloud provider so Ductape can manage
+resources (databases, storage, brokers, graphs, vectors) on your behalf.
+
+Supported providers: aws | gcp | azure | mongodb_atlas | neo4j_aura
+Auth modes: iam_role | oauth | service_principal | workload_identity | api_key
+
+Create a connection (admin — ductape_cli):
+  ductape_cli("cloud connections create --provider aws --name my-aws-conn")
+  Returns: external_id, trust_policy, setup_instructions, setup_url
+  AWS: the caller must create an IAM role using the returned trust policy, then complete:
+    ductape_cli("cloud connections complete <tag> --role-arn arn:aws:iam::...")
+  GCP: complete with project_id, service_account_email, service_account_json
+  Azure: complete with tenant_id, subscription_id, client_id, client_secret, default_location
+  Atlas: complete with atlas_public_key, atlas_private_key
+  Aura (Neo4j): complete with aura_client_id, aura_client_secret, aura_instance_id
+
+Validate a connection:
+  ductape_cli("cloud connections validate <tag>")
+  → { valid, status, message?, tested_at? }
+
+List / fetch / delete:
+  ductape_cli("cloud connections list")
+  ductape_cli("cloud connections fetch <tag>")
+
+Discover resources on a connection:
+  ductape_cli("cloud resources list -f query.json --json")
+  File: { cloud: "<tag>", service: "gcs"|"s3"|"blob"|"rds"|"atlas-cluster"|..., region? }
+  → returns list of available resources (buckets, clusters, instances, etc.)
+
+Import an existing resource and register it on the product:
+  Use import-persist-all for multi-env products (required):
+    ductape_cli("cloud resources import-persist-all -f all-envs.json --json")
+  File is a JSON ARRAY — one entry per env, same product + component tag across all entries.
+  Each entry: { cloud, service, type, product, component, env, resource, region?, dbName? }
+  Supported service identifiers: s3, gcs, blob, rds, postgresql, cloudsql, sqs, pubsub,
+    servicebus, neptune, cosmos-gremlin, opensearch, azure-search, atlas-cluster, aura-instance
+
+Provision a brand-new resource and register it:
+  ductape_cli("cloud resources provision-persist-all -f all-envs.json --json")
+  Additional per-entry fields: tier, region/location, waitForReady.
+  List available tiers first: ductape_cli("cloud tiers --provider aws --type database --db-type postgresql --json")
+  NEVER infer region, tier, or cost — always list and confirm with the user first.
+  Atlas and Neo4j Aura are IMPORT-ONLY — provision is not supported for these providers.
+
+VPC connector (private networking):
+  ductape_cli("cloud connections vpc update <tag> --vpc-id vpc-xxx --subnet-ids subnet-1,subnet-2")
+  ductape_cli("cloud connections vpc status <tag>")
+  VPC connector enables Ductape to reach resources in a private VPC; agent_status:
+    pending → connected → disconnected
+
+Scopes a connection can cover: storage | broker | database | graph | vector | cache
+
+Component types accepted by import/provision:
+  storage | messageBrokers | databases | graphs | vectors | caches
+`.trim(),
+
+  vector: `
+DUCTAPE VECTOR DATABASES
+
+Supported adapters: pinecone | qdrant | weaviate | opensearch | azure-search | vertex-vector-search
+  (chroma, milvus, pgvector are declared but not yet implemented — do not use them)
+
+Registration (admin — ductape_cli):
+  ductape_cli("resources vectors create -f vector.json")
+  File: { name, tag, type, dimensions: number, metric?: "cosine"|"euclidean"|"dotproduct",
+          envs: [{ slug, endpoint?, apiKey?, region?, index?, namespace? }] }
+
+Runtime operations:
+  vector.upsert      [{ product, env, tag, vectors: [{id, values: number[], metadata?}], namespace? }]
+  vector.upsertOne   [{ product, env, tag, id, values: number[], metadata?, namespace? }]
+  vector.query       [{ product, env, tag, vector: number[], topK?, filter?, namespace?,
+                        includeValues?, includeMetadata? }]
+  vector.findSimilar [{ product, env, vector, values: number[], topK?, filter?, namespace? }]
+  vector.fetchOne    [{ product, env, vector, id, namespace? }]
+  vector.fetchVectors [{ product, env, vector, ids: string[], namespace? }]
+  vector.updateVector [{ product, env, vector, id, values?, setMetadata?, mergeMetadata?, namespace? }]
+  vector.updateMetadata [{ product, env, vector, id, metadata: { key: value }, merge?, namespace? }]
+    merge: true → deep-merges metadata rather than replacing it
+  vector.deleteByIds  [{ product, env, vector, ids: string[], namespace? }]
+  vector.deleteAll    [{ product, env, vector, namespace? }]
+  vector.count        [{ product, env, vector, namespace? }]
+
+Namespace management:
+  vector.listNamespaces  [{ product, env, vector }]
+  vector.deleteNamespace [{ product, env, vector, namespace }]
+
+Listing (paginated):
+  vector.listVectors    [{ product, env, vector, namespace?, prefix?, limit?, cursor? }]
+  vector.listAllVectors [{ product, env, vector, namespace?, prefix? }]
+    listAllVectors auto-paginates until cursor exhausted — avoid on large indexes.
+
+Index management:
+  vector.describeIndex  [{ product, env, vector }]
+  vector.getStats       [{ product, env, vector }]  → totalVectorCount per namespace
+  vector.createIndex    [{ product, env, vector, name, dimensions, metric?, replicas?, shards? }]
+  vector.deleteIndex    [{ product, env, vector, name }]
+  vector.listIndexes    [{ product, env, vector }]
+
+Distance metrics: cosine | euclidean | dotproduct | manhattan | hamming
+Index types: flat | ivf | hnsw | pq | ivf_pq | annoy
+Feature flags per adapter: metadata_filtering | namespaces | hybrid_search | batch_operations |
+  index_management | vector_updates | sparse_vectors | multi_vector | aggregations
+
+Call vector.supportsFeature(feature) or vector.getSupportedFeatures() to check what the
+chosen adapter supports before using a feature.
+`.trim(),
+
+  warehouse: `
+DUCTAPE WAREHOUSE
+
+The Warehouse is a unified query layer over the three structured data stores: Database, Graph, and Vector.
+It provides a single API for cross-store operations without having to address each service separately.
+
+Warehouse is available on the SDK instance as ductape.warehouse (TypeScript) or Warehouse (C#/Go/Java).
+It is NOT a separate Ductape resource — it wraps the existing database, graph, and vector components
+that are already registered on the product.
+
+Key use cases:
+  - Run a relational query, a graph traversal, and a vector similarity search in a single call.
+  - Build recommendation pipelines: graph neighbors → vector re-rank → database hydration.
+  - Federated search across multiple store types with a single await.
+
+Usage (TypeScript SDK):
+  const result = await ductape.warehouse.query({
+    product: "my-product",
+    env: "prd",
+    database: { tag: "core-db", entity: "products", where: { active: { $eq: true } }, select: ["id", "name"] },
+    graph:    { tag: "reco-graph", startId: userId, direction: "out", maxDepth: 2 },
+    vector:   { tag: "embedding-store", vector: queryEmbedding, topK: 10 },
+  });
+
+  result.database  → relational rows
+  result.graph     → traversal nodes/relationships
+  result.vector    → similarity hits with scores
+
+Warehouse context is set at SDK init time (env + workspaceId) and shared across all three stores.
+Underlying store calls use the same auth and product context; individual store errors are surfaced per store.
+
+Before using Warehouse:
+  1. Ensure the database, graph, and vector components are registered on the product.
+  2. Confirm the env slug exists on all three stores.
+  3. Each store can be queried independently — pass only the fields for the stores you need.
+
+Warehouse does not support writes — use the individual service APIs (database.insert, graph.createNode,
+vector.upsert) for mutations.
+`.trim(),
+
+  secrets: `
+DUCTAPE SECRETS
+
+Secrets are workspace-level encrypted key-value pairs. They are referenced in resource configs,
+connection URLs, and any string field using the $Secret{KEY_NAME} syntax.
+
+Create (admin — ductape_cli or ductape_execute):
+  ductape_execute("secrets.create", [{
+    key: "STRIPE_API_KEY",
+    value: "sk_live_...",          // plaintext — encrypted AES-256-GCM client-side before send
+    description: "Stripe live key",
+    token_type: "api",             // "api" | "password" | "certificate"
+    scope: ["my-product"],         // which products can read this secret
+    envs: ["prd"],                 // which env slugs can read this secret
+    expires_at: 1800000000,        // optional epoch ms
+  }])
+  The server never receives the plaintext value. Encryption uses the workspace private key.
+
+Fetch / resolve:
+  ductape_execute("secrets.fetch", ["STRIPE_API_KEY"])      → decrypted string value
+  ductape_execute("secrets.exists", ["STRIPE_API_KEY"])      → boolean
+  ductape_execute("secrets.validate", ["$Secret{STRIPE_API_KEY}"])  → { valid, missingKeys, existingKeys }
+  ductape_execute("secrets.resolve", ["$Secret{STRIPE_API_KEY}", { env: "prd" }])  → resolved string
+
+$Secret{} reference syntax:
+  - Embed anywhere a string is accepted: "postgresql://$Secret{DB_USER}:$Secret{DB_PASS}@host/db"
+  - Resolved at runtime before the value is used by the consuming service (storage, broker, graph, etc.)
+  - The in-memory cache stores the encrypted form only; decryption happens on each cache hit.
+  - Cache TTL: 5 minutes. Clear with: secrets.clearCache()
+
+Lifecycle:
+  ductape_execute("secrets.revoke", ["KEY"])   → disables without deleting (recoverable)
+  ductape_execute("secrets.delete", ["KEY"])   → permanent deletion (irreversible)
+  ductape_execute("secrets.update", ["KEY", { value: "new_value", expires_at: ... }])
+
+List all secrets (keys only — values are not returned in list):
+  ductape_execute("secrets.list", [])
+
+Important:
+  - Secrets are workspace-scoped, not product-scoped. scope[] and envs[] control access.
+  - Other services (storage, broker, graph, etc.) resolve $Secret{} references automatically
+    using the singleton secrets service — no manual resolution needed in most cases.
+  - Never log or return resolved secret values to end users.
+`.trim(),
+
+  apps: `
+DUCTAPE APPS
+
+An app is a versioned API integration definition. It contains environments (base URLs), actions
+(individual endpoint specs), auth schemes, webhooks, variables, and constants.
+
+Create an app (admin — ductape_cli):
+  ductape_cli("apps create --name \\"Email Service\\" --description \\"Transactional email\\"")
+  ductape_cli("app.init", ["app_tag"])       → loads app into builder state
+
+Import from a file:
+  ductape_cli("apps import <file.json> -t postman|openapi")
+  Supports Postman v2.1 collection and OpenAPI 3.0 spec.
+
+Manage environments (base URLs per stage):
+  ductape_execute("app.environments.create", [app_tag, { slug, env_name, base_url }])
+  ductape_execute("app.environments.list",   [app_tag])
+
+Manage actions (individual API endpoints):
+  ductape_execute("actions.create", [app_tag, {
+    tag, name, resource: "/users/{id}", method: "GET"|"POST"|"PUT"|"PATCH"|"DELETE",
+    body?: { fieldName: { type, required? } },
+    params?: { id: { type: "string" } },
+    query?: { filter: { type: "string" } },
+    headers?: { Authorization: { type: "string" } },
+    response?: { status_code: 200, success: true, body: { ... }, response_format: "json" },
+  }])
+  ductape_execute("actions.update", [app_tag, action_tag, data])
+  ductape_execute("actions.list",   [app_tag])
+  ductape_execute("actions.fetch",  [app_tag, action_tag])
+
+Run an action at runtime:
+  → CALL ductape_generate_payload FIRST (operation_family="action", method="run", targets={app, action})
+  ductape_execute("actions.run", [{ product, env, app, action, input: { "body:field": value } }])
+  ductape_execute("actions.dispatch", [{ product, env, app, action, input, schedule? }])
+
+Auth schemes (how the app authenticates outbound requests):
+  Setup types: header | bearer | basic | oauth2 | apikey
+  ductape_execute("auths.create", [app_tag, { tag, name, setup_type, expiry, period, action_tag? }])
+  ductape_execute("auths.list",   [app_tag])
+
+Webhooks (inbound events from the external service):
+  ductape_execute("webhooks.create", [app_tag, { tag, name, description, envs: [{ slug, registration_url?, method? }] }])
+  ductape_execute("webhooks.events.create", [app_tag, { tag, name, selector, description, sample }])
+
+Variables (per-env mutable values) and Constants (fixed values):
+  ductape_execute("app.variables.create", [app_tag, { key, value, env_slug }])
+  ductape_execute("app.constants.create", [app_tag, { key, value }])
+
+Connecting an app to a product (after creation):
+  ductape_execute("product.apps.add", [product_tag, {
+    access_tag: "app_access_tag",
+    envs: [{ app_env_slug: "production", product_env_slug: "prd",
+             variables: [{ key: "BASE_URL", value: "https://api.example.com" }],
+             auth: { auth_tag: "api-key-auth", data: "$Secret{API_KEY}" } }]
+  }])
+  ductape_execute("product.apps.list",   [product_tag])
+  ductape_execute("product.apps.fetch",  [product_tag, access_tag])
+`.trim(),
+
+  products: `
+DUCTAPE PRODUCTS
+
+A product is the top-level namespace for all Ductape infrastructure: apps, databases, graphs,
+vectors, storage, brokers, sessions, caches, notifications, resilience, features, jobs, and envs.
+Every SDK service call resolves within a product context.
+
+Create a product:
+  ductape_cli("products create --name \\"My App\\" --tag my-app")
+  ductape_execute("product.create", [{ name: "My App", tag: "my-app",
+    envs: [{ slug: "dev", name: "Development" }, { slug: "prd", name: "Production" }] }])
+
+Environments — every resource's envs array MUST cover all product env slugs:
+  ductape_execute("product.environments.create", [product_tag, { slug, env_name, description, active? }])
+  ductape_execute("product.environments.list",   [product_tag])
+  ductape_execute("product.environments.fetch",  [product_tag, slug])
+  BEFORE registering any resource, always run environments.list and collect all slugs.
+
+Fetch / update:
+  ductape_execute("product.fetch",  [product_tag])
+  ductape_execute("product.update", [product_tag, { name?, description? }])
+
+Connect apps to a product:
+  See ductape_docs({ topic: "apps" }) for product.apps.add / product.apps.list.
+
+Resource registration (all via ductape_cli or ductape_execute — see per-topic docs):
+  databases → ductape_docs({ topic: "transactions" })
+  storage   → ductape_docs({ topic: "storage" })
+  graphs    → ductape_docs({ topic: "graphs" })
+  vectors   → ductape_docs({ topic: "vector" })
+  events    → ductape_docs({ topic: "events" })
+  caches    → ductape_docs({ topic: "caches" })
+  notifications → ductape_docs({ topic: "notifications" })
+  sessions  → ductape_docs({ topic: "sessions" })
+  resilience → ductape_docs({ topic: "resilience" })
+  features  → ductape_docs({ topic: "features" })
+
+Product structure (IProduct fields):
+  _id, workspace_id, name, tag, description, private_key,
+  apps[], envs[], databases[], graphs[], vectors[], storage[], messageBrokers[],
+  caches[], sessions[], notifications[], quota[], fallback[], healthchecks[],
+  workflows[] (features), models[], agents[], jobs[]
+
+Bootstrap (single API call returning product context + component config + private key):
+  Each service makes a single bootstrap call at first use; results are cached in BootstrapCache
+  (Redis when available). This avoids repeated round-trips in high-frequency paths.
+`.trim(),
+
+  sessions: `
+DUCTAPE SESSIONS
+
+A session is a named JWT schema on a product. It defines:
+  - tag / name        — unique identifier and display name
+  - expiry + period   — how long each issued JWT is valid (duration, not an absolute date)
+  - selector          — the dot-path of the field inside the data object that is the PRIMARY
+                        user identifier (e.g. "playerId"). This field becomes the lookup key
+                        for revoke, list, and analytics. It MUST exist in the schema.
+  - schema            — the complete shape of data that will be embedded in the JWT payload.
+                        Each field is declared as { type, required?, description? }.
+                        This is a TYPE DECLARATION, not sample data. The actual values
+                        are passed at runtime when calling sessions.start.
+
+IMPORTANT — schema field format: { fieldName: { type, required?, description? } }
+  type values: "string" | "number" | "boolean" | "object" | "array"
+  Do NOT use the shorthand { fieldName: "string" } — pass the full object form.
+
+Example (game product — player identity in JWT):
+  ductape_execute("sessions.create", [product_tag, {
+    tag: "player-session",
+    name: "Player Session",
+    expiry: 24,
+    period: "hours",
+    selector: "playerId",               // primary identifier — must be in schema below
+    schema: {
+      playerId:  { type: "string",  required: true,  description: "Unique player ID" },
+      username:  { type: "string",  required: true,  description: "Player display name" },
+      role:      { type: "string",  required: false, description: "admin | player | guest" },
+      accountId: { type: "string",  required: false, description: "Linked account ID" },
+    },
+  }])
+
+Runtime — create a session (sign a JWT):
+  → CALL ductape_generate_payload FIRST (operation_family="session", method="start", targets={tag})
+    to discover the exact data field names accepted for this session tag.
+  ductape_execute("sessions.start", [{ product, env, tag: "player-session",
+    data: {
+      playerId:  "player_abc123",   // must match selector — used as the revocation/lookup key
+      username:  "ShadowBlade",
+      role:      "player",
+      accountId: "acct_xyz",
+    } }])
+  → returns token: "player-session:eyJ..."   ← format is always "session_tag:jwt"
+  The token embeds all schema fields in the JWT payload, signed with the product private key.
+
+Verify a token:
+  ductape_execute("sessions.verify", [{ product, env, tag: "user-session", token: "user-session:eyJ..." }])
+  → decodes JWT + checks revocation blacklist; throws if revoked or expired
+
+Refresh (atomic token rotation):
+  ductape_execute("sessions.refresh", [{ product, env, tag: "user-session", refreshToken: "..." }])
+  Old refresh token is invalidated server-side atomically — no partial state possible.
+  The refresh token is AES-encrypted JSON (NOT a JWT).
+
+Revoke:
+  ductape_execute("sessions.revoke", [{ product, env, tag, sessionId?, identifier? }])
+  Requires at least one of sessionId or identifier.
+  Revocation is enforced via a ProcessorAPI blacklist check on every verify() call.
+
+Analytics:
+  sessions.listActive        [{ product, env, tag, identifier?, page?, limit? }]
+  sessions.fetchUsers        [{ product, session, env?, page?, limit? }]
+  sessions.fetchUserDetails  [{ product, session, identifier, env? }]
+  sessions.fetchDashboard    [{ product, session, env? }]
+    → { DAU, WAU, MAU, activityTimeline, peakHours, environmentBreakdown, avgSessionDuration }
+
+Token format: "session_tag:jwt_token" — pass this format verbatim wherever session is expected.
+JWT is signed with the product private key (not a symmetric shared secret).
+`.trim(),
+
+  caches: `
+DUCTAPE CACHES
+
+Caches are product-level Redis (or in-memory) stores for temporary key-value data with optional TTL.
+
+Registration (admin — ductape_cli):
+  ductape_cli("resources caches create -f cache.json")
+  File: { name, tag, type: "redis"|"memcached"|"in-memory",
+          envs: [{ slug, connection_url }] }
+
+Operations:
+  caches.set   [{ product, cache, key, value: string, expiry?: string (ISO 8601), env }]
+    expiry is an ABSOLUTE TIMESTAMP (not a duration).
+    To expire in 1 hour: expiry = new Date(Date.now() + 3600_000).toISOString()
+    To expire in 24 hours: expiry = new Date(Date.now() + 86400_000).toISOString()
+    To never expire: omit expiry entirely.
+    Via MCP: pass an ISO 8601 string e.g. "2026-07-17T12:00:00.000Z"
+    → Writes to Redis synchronously, then fires remote API write in background (non-blocking).
+  caches.get   [{ key: string }]
+    → Checks Redis first; on miss falls through to remote API; on hit from API, populates Redis.
+    → Enforces TTL by comparing the stored expiry timestamp against current time (client-side check).
+  caches.clear [{ key: string }]
+    → Deletes from Redis and from remote API.
+  caches.clearAll [{ product, cache, env? }]
+    → Bulk delete via remote API only. Redis may still have stale keys until naturally evicted.
+  caches.fetchValues [{ product, cache, env?, page?, limit?,
+                        expiryFilter?: "all"|"expiring"|"permanent"|"expired" }]
+  caches.fetchDashboard [{ product, cache, env? }]
+    → { totalValues, activeValues, expiredValues, totalSize }
+
+Tier architecture (three tiers applied automatically):
+  Tier 1: in-process Map (SDK metadata cache, 5-min TTL — not for user data)
+  Tier 2: Redis hash (hSet/hGetAll) with optional EXPIRE
+  Tier 3: Remote Ductape API
+
+Practical examples:
+  // Cache a player leaderboard for 5 minutes:
+  { product, cache: "leaderboard-cache", key: "top-100", value: JSON.stringify(rows),
+    expiry: new Date(Date.now() + 300_000).toISOString(), env: "prd" }
+
+  // Cache a session token lookup for 1 hour:
+  { product, cache: "session-cache", key: "player:u_123", value: token,
+    expiry: new Date(Date.now() + 3_600_000).toISOString(), env: "prd" }
+
+Important:
+  - Redis is optional; without it all reads/writes go through the remote API.
+  - expiry is stored as a Date field, not a Redis TTL — the expiry check happens client-side on read.
+  - clearAll only clears via the remote API bulk endpoint; Redis may retain stale entries until evicted.
+  - Cache entries are stored as Redis hashes (not plain strings).
+  - Other services (storage, graph, notifications, sessions) also use CacheManager internally —
+    configure a shared Redis URL at SDK init to share the pool.
+`.trim(),
+
+  notifications: `
+DUCTAPE NOTIFICATIONS
+
+Notifications send messages across multiple channels: email, SMS, push, or HTTP callback.
+
+Create a notification (admin — ductape_execute):
+  ductape_execute("notifications.create", [product_tag, {
+    tag: "welcome-email",
+    name: "Welcome Email",
+    type: "email",   // optional hint; actual channels configured per env
+  }])
+
+Create a message template:
+  ductape_execute("notifications.messages.create", [product_tag, {
+    tag: "welcome-email:default",       // format: "notification_tag:message_tag"
+    notification: "welcome-email",
+    subject: { template: "Welcome, {{name}}!", data: { name: "" } },
+    body:    { template: "Hi {{name}}, thanks for signing up.", data: { name: "" } },
+  }])
+
+Send at runtime (one channel at a time):
+  → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
+  notifications.email.send    [{ product, env, notification, input: { recipients, subject?, template? } }]
+  notifications.push.send     [{ product, env, notification, input: { device_tokens, title?, body?, data? } }]
+  notifications.sms.send      [{ product, env, notification, input: { recipients, body? } }]
+  notifications.callback.send [{ product, env, notification, input: { query?, headers?, params?, body? } }]
+
+Multi-channel send (all channels in parallel):
+  notifications.send [{ product, env, event: "notif_tag:message_tag", input: { ... } }]
+  → success is true if at least one channel succeeds; channel failures do not abort siblings.
+
+Background dispatch with scheduling:
+  notifications.dispatch [{ product, env, notification, event, input,
+    schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
+  → Returns { job_id, status: "queued", scheduled_at, recurring, next_run_at }
+
+Query delivery logs:
+  notifications.getMessages [{ product_tag?, env?, notification_tag?, status?,
+    type?, start_date?, end_date?, page?, limit? }]
+  Status values: pending | sent | failed | reprocessing
+
+Supported providers:
+  Email:  smtp | mailgun | sendgrid | postmark | brevo
+  SMS:    twilio | nexmo | plivo | other
+  Push:   firebase | expo
+  Callback: any HTTP endpoint
+
+Channel configuration (envs per notification) is done in the Workbench UI, not via CLI.
+Notification tag and message tag are ALWAYS passed together as "notification_tag:message_tag".
+`.trim(),
+
+  resilience: `
+DUCTAPE RESILIENCE
+
+Resilience covers three mechanisms: quotas (rate-limited provider pools), fallbacks (automatic
+provider switching), and healthchecks (continuous probe monitoring with failure actions).
+
+QUOTAS — rate-limited multi-provider pools:
+  ductape_execute("quotas.create", [product_tag, {
+    tag: "sms-quota",
+    name: "SMS Provider Pool",
+    input: { to: { type: "string", required: true }, message: { type: "string" } },
+    options: [
+      { provider: "twilio", app: "twilio-app", type: "action", event: "send-sms",
+        quota: 1000, uses: 0, retries: 2,
+        input: { "body:to": "$Input{to}", "body:message": "$Input{message}" },
+        output: {} },
+      { provider: "nexmo", app: "nexmo-app", type: "action", event: "send-sms",
+        quota: 500, uses: 0, retries: 1,
+        input: { "body:to": "$Input{to}", "body:body": "$Input{message}" },
+        output: {} },
+    ],
+  }])
+  Providers are tried in order until quota is not exhausted.
+  quotas.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
+  quotas.dispatch [{ product, env, tag, input, schedule? }]
+
+FALLBACKS — automatic provider switching on failure:
+  Same schema as quotas but options are ordered: primary first, then fallback(s).
+  Primary is used first; on failure, the next provider is tried automatically.
+  ductape_execute("fallback.create", [product_tag, { tag, name, input: { ... }, options: [...] }])
+  fallback.run      [{ product, env, tag, input }]  ← CALL ductape_generate_payload FIRST
+  fallback.dispatch [{ product, env, tag, input, schedule? }]
+
+HEALTHCHECKS — continuous probe with failure notifications:
+  ductape_execute("health.create", [product_tag, {
+    tag: "payment-health",
+    name: "Payment Service Health",
+    probe: { type: "app", app: "stripe-app", event: "ping" },
+    interval: 30000,    // ms between checks
+    retries: 3,
+    envs: [{ slug: "prd", input: {} }],
+    onFailure: {
+      notifications: [{ notification: "ops-alerts", message: "payment-down",
+        channels: { email: { recipients: ["ops@example.com"] } } }],
+      webhooks: [{ url: "https://hooks.example.com/alert", method: "POST" }],
+    },
+  }])
+  health.run    [{ product, env, tag }]   → triggers an immediate probe
+  health.check  [{ product, env, tag }]   → same as run
+  health.status [{ product, env, tag }]   → current health status
+
+Probe types: app | database | feature | graph | message_broker | storage
+Failure actions: notification channels, HTTP webhooks, and/or message broker emit — all can
+  be configured simultaneously on the same healthcheck.
+Input template references: $Input{field} → maps declared input to the probe's action input.
+Provider status: available | unavailable
+`.trim(),
+
+  features: `
+DUCTAPE FEATURES
+
+A feature is an orchestrated workflow of durable steps. Steps can call app actions, database
+operations, graph queries, storage uploads, notifications, broker publishes, child features,
+quotas, fallbacks, and more. Features support rollback, signals, checkpoints, and sleep.
+
+Step types: action | database | graph | notification | storage | produce | quota | fallback |
+  vector | child_feature | sleep | wait_for_signal | checkpoint
+
+Create a feature (admin — ductape_execute):
+  ductape_execute("features.create", [product_tag, {
+    tag: "onboard-user",
+    name: "Onboard User",
+    input: { userId: { type: "string", required: true }, email: { type: "string" } },
+    steps: [
+      {
+        tag: "create-account",
+        type: "database",
+        database: "core-db",
+        event: "insert-user",
+        input: { "body:userId": "$Input{userId}", "body:email": "$Input{email}" },
+        options: { retries: 2, timeout: 5000 },
+      },
+      {
+        tag: "send-welcome",
+        type: "notification",
+        notification: "welcome-email",
+        event: "welcome-email:default",
+        input: { "body:email": "$Input{email}" },
+        dependsOn: ["create-account"],
+        options: { allow_fail: true },   // welcome email failure won't abort the feature
+      },
+    ],
+  }])
+
+Execute at runtime:
+  → CALL ductape_generate_payload FIRST (operation_family="features", method="execute", targets={tag})
+  features.execute [{ product, env, tag, input: { userId: "u_123", email: "..." },
+    idempotency_key?: string, retries?: number, timeout?: number }]
+
+Background dispatch with scheduling:
+  features.dispatch [{ product, env, feature, input,
+    schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
+  → Returns { job_id, status: "queued"|"scheduled", scheduled_at, next_run_at }
+
+Execution management:
+  features.status        [executionId]  → { status, current_step, completed_steps, output, error }
+  features.cancel        [executionId, reason?]  → triggers rollback of running steps
+  features.replay        [executionId, options?]  → re-run with original input
+  features.restart       [executionId]  → re-run with new input
+  features.resume        [executionId]  → continue from a checkpoint
+  features.replayFromStep [executionId, stepTag]  → replay from a specific step
+  features.history       [executionId]  → { events[], checkpoints[], replays[], restarts[] }
+  features.stepDetail    [executionId, stepTag]  → per-step input/output/error/timing
+
+Signals and queries (for long-running features):
+  features.signal [{ product, env, feature_id, signal: "payment-confirmed", payload? }]
+  features.query  [{ product, env, feature_id, query: "current-status", params? }]
+
+Step input references:
+  $Input{field}               → map from feature's declared input
+  $Step{stepTag}{field}       → output field from a prior step
+  $StepOutput{field}          → current step's own return value
+  $Concat([...parts], delim)  → string interpolation
+
+Rollback strategies: reverse_all | reverse_critical | compensate | none
+Feature statuses: pending | running | completed | failed | rolled_back | rolling_back | paused
+
+Code-first (define API — compiles async handler to JSON step schema):
+  features.define({ tag, name, input, handler: async (ctx) => { ... } })
+  ctx provides: ctx.step(), ctx.action.run(), ctx.database.query/insert(),
+    ctx.graph.execute(), ctx.notification.send(), ctx.storage.upload(),
+    ctx.messaging.produce(), ctx.quota.execute(), ctx.fallback.execute(),
+    ctx.sleep(), ctx.waitForSignal(), ctx.setState/getState(), ctx.feature()
+`.trim(),
+
+  events: `
+DUCTAPE EVENTS (MESSAGE BROKERS)
+
+ARCHITECTURE — always two separate steps:
+  Step 1: Register the BROKER COMPONENT (establishes the connection to the broker service).
+          The broker's envs[] holds connection credentials and host/project info, NOT topics.
+  Step 2: Create TOPIC DEFINITIONS on that broker (unlimited; each is a named subject or queue).
+          Topics are separate from the broker registration and added after.
+  A single broker component can have as many topics as needed.
+
+━━━ SUPPORTED BROKER TYPES ━━━
+
+Cloud-managed (provision OR import via cloud connection):
+  GCP Pub/Sub    → service: "pubsub",      type in envs: "google_pubsub"
+  AWS SQS        → service: "sqs",         type in envs: "aws_sqs"
+  Azure SvcBus   → service: "servicebus",  type in envs: "azure_servicebus"
+
+Self-hosted (import-only — supply connection URL manually):
+  Kafka          → type in envs: "kafka"
+  RabbitMQ       → type in envs: "rabbitmq"
+  Redis          → type in envs: "redis"
+  NATS           → type in envs: "nats"
+
+━━━ STEP 1A: REGISTER VIA CLOUD CONNECTION (cloud-managed brokers) ━━━
+
+Provision (create a NEW resource in the cloud):
+  ductape_cli("cloud resources provision-persist-all -f brokers.json --json")
+  File: JSON ARRAY — one entry per env, same product + component tag across all entries.
+  type field: "messageBrokers" (exact — not "messagebrokers" or "events")
+
+  GCP Pub/Sub — creates a new Pub/Sub topic in GCP, stores credentials in secrets:
+    [{"cloud":"gcp-snd","service":"pubsub","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "topicName":"my-product-notifications-snd"},
+     {"cloud":"gcp-prd","service":"pubsub","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "topicName":"my-product-notifications-prd"}]
+    If topicName is omitted a timestamped name is generated — always supply it explicitly.
+
+  AWS SQS — creates a new SQS queue per env:
+    [{"cloud":"aws-snd","service":"sqs","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "queueName":"my-product-notifications-snd"},
+     {"cloud":"aws-prd","service":"sqs","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "queueName":"my-product-notifications-prd"}]
+
+  Azure Service Bus — creates a namespace + queue per env:
+    [{"cloud":"azure-snd","service":"servicebus","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"snd",
+      "namespaceName":"myproduct-snd","queueName":"notifications"},
+     {"cloud":"azure-prd","service":"servicebus","type":"messageBrokers",
+      "product":"my-product","component":"notifications-broker","env":"prd",
+      "namespaceName":"myproduct-prd","queueName":"notifications"}]
+
+Import (register an EXISTING cloud resource):
+  Same as above but use import-persist-all and supply "resource" (the existing resource name/ID):
+    ductape_cli("cloud resources import-persist-all -f brokers.json --json")
+    Each entry: { cloud, service, type: "messageBrokers", product, component, env, resource: "<id>" }
+
+  IMPORTANT: Never share one cloud resource (topic/queue) across snd and prd envs — use
+  separate resources per env to avoid mixing sandbox and production events.
+
+━━━ STEP 1B: REGISTER SELF-HOSTED BROKER (no cloud connection needed) ━━━
+
+  ductape_cli("resources events create -f broker.json")
+  File: {
+    name: string, tag: string, description?: string,
+    envs: [
+      {
+        slug: "snd",
+        type: "kafka"|"rabbitmq"|"redis"|"nats",
+        config: <see config shapes below>
+      },
+      { slug: "prd", type: "kafka", config: { ... } }
+    ]
+  }
+
+  Config shapes per type:
+    kafka:    { brokers: ["host:9092"], clientId: "my-app", groupId?: "...",
+                ssl?: true, sasl?: { mechanism: "plain", username, password } }
+    rabbitmq: { url: "amqp://user:pass@host:5672/vhost" }
+    redis:    { host: "...", port: 6379, password?: "..." }
+    nats:     { servers: ["nats://host:4222"], token?: "...", user?: "...", pass?: "...", tls?: true }
+
+━━━ STEP 2: ADD TOPIC DEFINITIONS (all broker types — add as many as needed) ━━━
+
+  ductape_execute("messageBrokers.topics.create", [product_tag, {
+    tag: "player-joined",
+    name: "Player Joined",
+    broker: "notifications-broker",   // broker component tag
+    description?: string,
+    sample: { playerId: "string", username: "string" },  // example message shape
+    idempotent?: boolean,
+    // SQS only — map per-env queue URLs (each topic can be a different queue):
+    queueUrls?: [
+      { env_slug: "snd", url: "https://sqs.us-east-1.amazonaws.com/123456/my-product-player-joined-snd" },
+      { env_slug: "prd", url: "https://sqs.us-east-1.amazonaws.com/123456/my-product-player-joined-prd" }
+    ]
+  }])
+
+  For GCP Pub/Sub and Azure Service Bus, the SDK resolves the topic name from the topic tag (or
+  config.topicName on the env config). No extra per-topic URL mapping is needed beyond the tag.
+  For SQS, every topic definition needs queueUrls to point to the specific per-env queue.
+  Repeat this call for each logical event type — there is no limit on number of topics.
+
+  List topics on a broker:
+    ductape_execute("messageBrokers.topics.list", [product_tag, "broker-tag"])
+
+━━━ RUNTIME: PRODUCE AND CONSUME ━━━
+
+  Produce (publish a message):
+    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="produce")
+    messageBrokers.produce [{ product, env, event: "broker_tag:topic_tag", message: { key: value } }]
+    Idempotent publish (deduplicates by key, default TTL 86400 s):
+      messageBrokers.publishIdempotent [{ product, env, event, message, idempotency_key, ttl? }]
+
+  Consume (subscribe):
+    messageBrokers.consume [{ product, env, event: "broker_tag:topic_tag",
+      callback: async (message) => { ... } }]
+    Callback errors are re-thrown so the broker can nack/retry.
+
+  Background dispatch with scheduling:
+    messageBrokers.dispatch [{ product, env, broker, event, input: { message },
+      schedule?: { start_at?, cron?, every?, limit?, endDate?, tz? } }]
+    → CALL ductape_generate_payload FIRST (operation_family="messaging", method="dispatch")
+
+Event format string: "broker_tag:topic_tag" — always colon-separated.
+Message payload is AES-encrypted before the tracking API call — tracking never sees plaintext.
+
+━━━ OBSERVABILITY ━━━
+
+  messageBrokers.messages.query        [{ product, env, brokerTag, topicTag?, status?, page?, limit? }]
+  messageBrokers.messages.getStats     [{ product, env, brokerTag }]
+  messageBrokers.messages.getDashboard [{ product, env, brokerTag }]
+  messageBrokers.messages.getDeadLetters [{ product, env, brokerTag, topicTag?, limit? }]
+  messageBrokers.replayEvent           [{ product, env, eventId, force? }]
+  messageBrokers.reprocessDLQ         [{ product, env, brokerTag, topicTag?, messageIds?, limit? }]
+  messageBrokers.checkIdempotency      [{ product, env, brokerTag, idempotency_key }]
+`.trim(),
+
+  logs: `
+DUCTAPE LOGS
+
+Logs record every SDK operation — actions, features, database queries, notifications, sessions,
+brokers, storage, cache hits, graph, vector, and resilience events.
+
+Fetch logs (runtime — ductape_execute):
+  ductape_execute("logs.fetch", [{
+    app_id?: string,        // query by app (requires component: "app")
+    product_id?: string,    // query by product (requires component: "product")
+    env?: string,
+    start_date?: string,    // ISO 8601
+    end_date?: string,
+    page?: number,
+    limit?: number,
+  }])
+  component "app" or "product" is required — there is no default.
+  When component="app", tag is only valid with type: "actions".
+
+Log data fields (ILogData):
+  process_id, product_tag, env, type (LogEventType), status, data (encrypted if private key set)
+  message?, parent_tag?, child_tag?, app_id?, action?, method?,
+  cache_tag?, cache_key?, cache_status (true = hit),
+  start, end, latency (auto-calculated from start/end),
+  session_user_id?, session_id?, session_tag?, visitor_id?,
+  ip_address?, language?, data_encrypted?, successful_execution?, failed_execution?
+
+Log event types (LogEventTypes):
+  notifications | push | email | sms | callbacks | slack | discord |
+  database_actions | actions | functions | storage | webhook | jobs |
+  message_broker | producer | consumer | quota | fallback | database_migration |
+  feature | feature_step | database | graph | session | vector | cache | frontend
+
+Log statuses: success | fail | waiting | processing
+
+Encryption:
+  When workspace_private_key is provided at SDK init, each log entry's data field is
+  AES-encrypted client-side before transmission. data_encrypted: true is set on the entry.
+  The backend can decrypt when returning logs to the Workbench.
+
+Emit a log manually (SDK only — not via MCP):
+  logs.add({ process_id, product_tag, env, type, status, data, message?, ... })
+  logs.publish()  → flushes all buffered entries to the API in one call
+
+Notes:
+  - Every SDK service (storage, broker, feature, graph, notifications, sessions, vector, cache,
+    resilience) emits its own logs automatically — manual add/publish is only needed for custom logs.
+  - language defaults to "typescript" so the backend knows which SDK emitted the entry.
+  - Logs are batched in memory and sent in a single publish() call per operation.
+`.trim(),
+};
+
+const docsHandler = async (args: { topic: string }) => {
+  const key = args.topic.toLowerCase().trim();
+  const doc = DOCS[key];
+  if (!doc) {
+    const available = Object.keys(DOCS).join(', ');
+    return {
+      content: [{ type: 'text' as const, text: `Unknown topic "${args.topic}". Available topics: ${available}` }],
+    };
+  }
+  return { content: [{ type: 'text' as const, text: doc }] };
+};
+
 const cliInputSchema = z.object({
   command: z.string().describe(
     'The ductape CLI command to run, without the leading "ductape" word. ' +
@@ -1245,6 +2489,22 @@ async function main() {
       },
       schemaHandler,
     );
+    server.registerTool(
+      'ductape_docs',
+      {
+        title: 'Ductape Feature Docs',
+        description:
+          'Look up detailed documentation for a specific Ductape SDK feature.\n\n' +
+          'Call this when you need guidance on how a feature works before using it — ' +
+          'especially for features that require configuration decisions (tier, isolation level, ' +
+          'index strategy, operation types) that should be confirmed with the user first.\n\n' +
+          'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
+          'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
+          'notifications, resilience, features, events, logs',
+        inputSchema: docsInputSchema,
+      },
+      docsHandler,
+    );
     server.registerTool(
       'ductape_cli',
       {
@@ -1306,6 +2566,32 @@ async function main() {
           '    Supported service/component pairs include: rds→database, aurora→database, gcs→storage, s3→storage,\n' +
           '    azure-blob→storage, cloud-sql→database, neptune→graph, opensearch→vector. Attempting an unsupported pair\n' +
           '    will return an error; do not retry with a different tier — report the limitation to the user.\n' +
+          '  - Atlas (MongoDB Atlas) import flow — service identifier is "atlas-cluster" (required, not optional):\n' +
+          '    Step 1 — discover the cluster name:\n' +
+          '      ductape_cli("cloud resources list -f /tmp/atlas-list.json --json")\n' +
+          '      File: {"cloud": "<atlas-connection-tag>", "service": "atlas-cluster"}\n' +
+          '      Returns a list of clusters; note the "name" field (this is your resource identifier).\n' +
+          '    Step 2 — check if the database component already exists:\n' +
+          '      ductape_cli("resources databases list <product_tag> --json")\n' +
+          '      If a component already uses the same Atlas cluster, do NOT re-import — instead update it:\n' +
+          '        ductape_execute("databases.updateDatabase", [product_tag, db_tag, { envs: [...updated envs...] }])\n' +
+          '      Add or change the dbName in the env\'s connection_url to switch databases on the same cluster.\n' +
+          '    Step 3 — import (only if no existing component uses this cluster):\n' +
+          '      Use import-persist-all with one entry per product env. Required fields per entry:\n' +
+          '        cloud (connection tag), service: "atlas-cluster", type: "databases",\n' +
+          '        product, component (new tag), env, resource (cluster name from Step 1),\n' +
+          '        dbName (the MongoDB database name to connect to — required for Atlas).\n' +
+          '      Example: [{"cloud":"atlas-tag","service":"atlas-cluster","type":"databases",\n' +
+          '        "product":"my-product","component":"core-db","env":"snd","resource":"Cluster0","dbName":"myapp_snd"},\n' +
+          '        {"cloud":"atlas-tag","service":"atlas-cluster","type":"databases",\n' +
+          '        "product":"my-product","component":"core-db","env":"prd","resource":"Cluster0","dbName":"myapp_prd"}]\n' +
+          '  - Message broker / event broker import:\n' +
+          '    CLI accepts these aliases for the messageBrokers module: events, event, broker, brokers, message-brokers.\n' +
+          '    List existing brokers: ductape_cli("resources events list <product_tag> --json")\n' +
+          '    GCP Pub/Sub service identifier is "pubsub". AWS SQS is "sqs". Azure Service Bus is "servicebus".\n' +
+          '    Message brokers are import-only (no provision-persist). Import flow is the same as storage.\n' +
+          '    type field = "messageBrokers" (not "messagebrokers" or "events").\n' +
+          '    After importing, create topics via: ductape_execute("messageBrokers.topics.create", [product_tag, data])\n' +
           '  - Listing workspaces, products, secrets\n' +
           '  - Linking a project folder: "link --product <tag> --env <slug>"\n' +
           '  - Syncing sessions/notifications/events: "apply" or "apply sessions" etc.\n' +
@@ -1325,6 +2611,7 @@ async function main() {
     server.tool('ductape_generate_payload', payloadGenerateInputSchema.shape, payloadGenerateHandler);
     server.tool('ductape_generate_snippet', snippetGenerateInputSchema.shape, snippetGenerateHandler);
     server.tool('ductape_schema', schemaInputSchema.shape, schemaHandler);
+    server.tool('ductape_docs', docsInputSchema.shape, docsHandler);
     server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
   } else {
     console.error('MCP server does not expose .registerTool() or .tool()');