@ductape/mcp 0.2.29 → 0.2.31

package/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ## Unreleased
 
+- Added `cli-authentication` guidance for automatic Google/GitHub browser OAuth, validated loopback callbacks, trusted-terminal handoff, credential non-disclosure, and external session refresh.
 - Added source-verified graph/vector projection guidance to the `features`, `events`, `graphs`, and `vector` docs topics, including exact graph/vector payloads, NestJS consumer routing, replay/idempotency, projection-state ordering, rebuild/drift repair, and an explicit stop condition for the currently missing code-first `ctx.vector` API.
 - Added read-only `ductape_events_topic_setup` and `ductape_events_validate_project` tools and made the canonical one-topic-per-file `ductape/events/<topic-tag>.topic.json` layout explicit and enforceable through the CLI.
 - Mark `ductape_function_setup` as read-only, non-destructive, idempotent, and closed-world in both MCP registration APIs so hosts do not incorrectly require mutation approval for its pure setup-plan generation.

package/dist/index.js

@@ -197,14 +197,14 @@ There are THREE categories of operations. Use the right tool for each:
   1. ASSET CREATION / UPDATE  (create, update, add, register… for ANY asset type)
        ALL creation and update operations require an access key and CANNOT go through ductape_execute.
        → Use ductape_cli for every create/update operation. Examples:
-           ductape_cli("apps create -f app.json")   # no --name/--description flags exist, only -f <file.json> or interactive TTY. body: { app_name, description, tag, envs?: [{ env_name, slug, description, base_url, active }] } — tag is REQUIRED.
+           ductape_cli("apps create -f ductape/apps/<app-tag>.app.json")   # no --name/--description flags exist, only -f <file.json> or interactive TTY. body: { app_name, description, tag, envs?: [{ env_name, slug, description, base_url, active }] } — tag is REQUIRED.
            ductape_cli("apps list")
            ductape_cli("resources storage list")
-           ductape_cli("resources database create -f db-config.json")
+           ductape_cli("resources database create -f ductape/databases/<database-tag>.database.json")
        This applies to: products, apps, and resources (databases, storage, caches, etc.),
        cloud connections, and secrets. Environments have their own CLI commands (see below);
        app actions have their own CLI commands too — ductape_cli("apps actions create --app <tag>
-       --action-file action.json") (NOT -f — that flag is claimed by the parent "apps" command, so
+       --action-file ductape/actions/<app-tag>/<action-tag>.action.json") (NOT -f — that flag is claimed by the parent "apps" command, so
        Commander resolves it against the ancestor and this subcommand never sees it; same fix as
        "products environments create/update" uses --env-file for the identical reason). Body: {
        tag, name, resource, method, request_type, description?, params?, query?, headers?, body?,
@@ -290,6 +290,16 @@ There are THREE categories of operations. Use the right tool for each:
        → Applies to: actions, features, sessions, notifications, databases, storage, graphs, vectors,
          quotas, fallbacks, jobs, and any other operation that executes against a pre-configured schema.
 
+       SAVED ACTION REUSE IS MANDATORY:
+       → Before creating a database, graph, or vector action, list the existing actions on that exact
+         component and inspect plausible matches with get/fetch.
+       → Reuse an existing action when its operation, target, template/query, parameters, and output
+         semantics satisfy the requested behavior. Invoke it by tag; do not create a duplicate merely
+         because the requested name differs.
+       → Create a new action only when no existing action provides the required behavior. Update an
+         existing action only for a compatible correction; do not mutate a shared action into different
+         semantics. State the evidence used to decide reuse versus creation.
+
   Skipping ductape_generate_payload for applicable runtime operations will produce incorrect or empty input payloads.
   Exception: messaging produce/consume/dispatch — the producer defines the schema, so infer from context instead.
 
@@ -483,8 +493,8 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
 
 ━━━ MODULE: actions (app actions) ━━━
   These are admin ops — go through ductape_cli, not ductape_execute:
-    ductape_cli("apps actions create --app <app_tag> --action-file action.json")
-    ductape_cli("apps actions update --app <app_tag> --action <action_tag> --action-file action.json")
+    ductape_cli("apps actions create --app <app_tag> --action-file ductape/actions/<app_tag>/<action_tag>.action.json")
+    ductape_cli("apps actions update --app <app_tag> --action <action_tag> --action-file ductape/actions/<app_tag>/<action_tag>.action.json")
     ductape_cli("apps actions list --app <app_tag> --json")
     ductape_cli("apps actions get --app <app_tag> --action <action_tag> --json")
     ductape_cli("apps actions delete --app <app_tag> --action <action_tag>")
@@ -782,7 +792,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   databases.migration.status [migrations]
   databases.action.create [{ tag: "product:database:action", name, description, tableName, operation: "query"|"insert"|"update"|"delete"|"aggregate"|"count", template, filterTemplate? }]
     ← ADMINISTRATIVE (access key required). FORBIDDEN via ductape_execute (publishable key) —
-      use ductape_cli("db actions create --action-file action.json") instead. tag MUST be fully qualified
+      use ductape_cli("db actions create --action-file ductape/database/actions/<action-tag>.action.json") instead. tag MUST be fully qualified
       "product_tag:database_tag:action_tag" — a 2-part "database:action" shorthand only resolves
       inside a long-lived process that already has that product's builder cached, never in a
       fresh CLI/MCP call. This is pure metadata registration; it never connects to the live
@@ -899,12 +909,13 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.deleteIndex    [{ product, env, vector, name }]
   vector.listIndexes    [{ product, env, vector }]
   vector.count          [{ product, env, vector, namespace? }]
-  vector.actions.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
-  vector.actions.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
-  vector.actions.fetch  [{ product, vector, actionTag }]
-  vector.actions.fetchAll [{ product, vector }]
-  vector.actions.delete [{ product, vector, actionTag }]
-  vector.actions.execute [{ product, env, vector, action, input }]
+  vector.action.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
+  vector.action.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
+  vector.action.fetch  [{ product, vector, actionTag }]
+  vector.action.fetchAll [{ product, vector }]
+  vector.action.delete [{ product, vector, actionTag }]
+  vector.action.execute [{ product, env, vector, action, input, session? }]
+    ← synchronous saved-action execution. Do not use vector.query for a saved action.
 
 ━━━ MODULE: features ━━━
   Feature definitions are code-first. Use features.define in application source; do not call
@@ -1490,6 +1501,7 @@ function runCli(command) {
                     'or use an OAuth flow:',
                     '  ductape login --browser google',
                     '  ductape login --browser github',
+                    'Browser OAuth returns to the CLI automatically through a validated 127.0.0.1 callback.',
                     '',
                     'Do not paste a password, OAuth callback token, or stored CLI credential into an agent prompt.',
                     'After login succeeds, retry the same ductape_cli command.',
@@ -1541,7 +1553,7 @@ 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, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
+        'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue'),
 });
 const eventsDiscoveryInputSchema = z.object({
     query: z.string().optional().describe('Capability or recovery search, including DLQ, dead letter, failed messages, retry, poison message, replay, or consumer failure.'),
@@ -1597,6 +1609,34 @@ const migrationInputSchema = z.object({
     write: z.boolean().optional().default(false).describe('Write redacted advisory artifacts only. This never writes application code or executable Ductape assets.'),
 });
 const DOCS = {
+    'cli-authentication': `
+DUCTAPE CLI AUTHENTICATION
+
+For an interactive local login, prefer browser OAuth:
+  ductape login --browser google
+  ductape login --browser github
+
+The CLI opens the provider in the user's browser, starts a temporary loopback listener on
+127.0.0.1, validates the returned OAuth state, exchanges the callback token, stores the resulting
+session in the local Ductape credential store, and then continues workspace selection. The user
+does not copy a callback token or share credentials with an agent.
+
+Run browser login only in the user's trusted local terminal. An MCP tool, agent subprocess, CI
+runner, container, SSH session, or remote development host may not own the browser's loopback
+interface. Do not invoke interactive login through ductape_cli and do not ask the user to paste a
+password, OAuth callback token, auth token, or stored credential into chat.
+
+Use email/password login only when the user deliberately chooses it in their own terminal:
+  ductape login
+
+Use --token only as a compatibility or automation fallback when the user already possesses a
+valid OAuth callback token through a trusted flow. Never solicit that token in an agent prompt.
+
+After login succeeds, retry the original ductape_cli operation. The MCP re-reads a previously
+missing or expired external CLI session without requiring an MCP restart. If a command returns
+HTTP 401 while workspace reads still succeed, treat it as endpoint authorization or command
+routing failure, not as a reason to re-authenticate.
+`.trim(),
     'portable-functions': `
 PORTABLE APPLICATION FUNCTIONS
 
@@ -2432,9 +2472,15 @@ ctx.database.execute inside a Feature step invokes a saved action through its \`
 Direct ctx.database.query/insert/update/delete calls retain their normal {table, where, data, ...}
 shape and do not resolve a saved action.
 
+REUSE BEFORE CREATE:
+  1. ductape_cli("db actions list --database product_tag:database_tag --json")
+  2. Inspect likely matches with ductape_cli("db actions get product_tag:database_tag:action_tag --json").
+  3. Reuse the matching tag with database.execute/ctx.database.execute when operation, table,
+     template, parameters, and result semantics match. Create only when no exact functional match exists.
+
 Create/update/delete are ADMINISTRATIVE (access key) — FORBIDDEN through ductape_execute
 (publishable key). Use ductape_cli, same as every other admin resource:
-  ductape_cli("db actions create --action-file action.json")
+  ductape_cli("db actions create --action-file ductape/database/actions/<action-tag>.action.json")
     File: { tag: "product:database:action", name, description, tableName,
              operation: "query"|"insert"|"update"|"delete"|"aggregate"|"count",
              template, filterTemplate? }
@@ -2478,6 +2524,10 @@ scheduled, dispatched with retries, and audited via logs.
     graphs: `
 DUCTAPE GRAPH DATABASES
 
+Before creating a graph action, list existing actions for the graph and inspect likely matches.
+Reuse an action whose query/operation, parameters, and result semantics already satisfy the task;
+create a new action only when no functional match exists.
+
 Supported engines: neo4j | neptune | cosmos-gremlin | spanner-graph | arangodb | memgraph
 
 Registration (admin — ductape_cli):
@@ -2531,10 +2581,12 @@ Schema management:
   graph.dropIndex / dropConstraint / listIndexes / listConstraints
 
 Saved actions (parameterized queries stored on the product):
-  graph.createAction [{ graphTag?, name, description?, operation, query, parameters: [{ name, type, required?, defaultValue?, description? }] }, productTag?]
-  graph.listActions  [graphTag?, productTag?]
-  graph.execute      [{ product, env, graph, action, input?, session?, cache? }]
-  graph.dispatch     [data]  ← call ductape_generate_payload FIRST
+  graph.action.create   [{ product, graph|graphTag, name, description?, operation, query, parameters? }]
+  graph.action.fetchAll [{ product, graph|graphTag }]
+  graph.action.fetch    [{ product, graph|graphTag, action|actionTag }]
+  graph.action.execute  [{ product, env, graph, action, input, session? }]
+  graph.action.dispatch [{ product, env, graph, event, input, schedule? }]  ← call ductape_generate_payload FIRST
+  Use graph.action.execute for a saved action. graph.query is only for a direct provider-native query.
 
 Supported index types: btree | fulltext | vector | range | point | text
 Supported constraint types: UNIQUE | EXISTS | NODE_KEY
@@ -2841,7 +2893,7 @@ action, connect it to the product) before writing the ctx.api.run call below.
 
 Create an app (admin — ductape_cli; no --name/--description flags exist, only -f <file.json> or
 interactive TTY):
-  ductape_cli("apps create -f app.json")   # body: { app_name, description, tag, envs?: [...] } — tag is REQUIRED
+  ductape_cli("apps create -f ductape/apps/<app-tag>.app.json")   # body: { app_name, description, tag, envs?: [...] } — tag is REQUIRED
   ductape_cli("app.init", ["app_tag"])       → loads app into builder state
 
 Import from a file:
@@ -2924,14 +2976,14 @@ Connecting an app to a product (after creation):
 
   FULL FLOW to make an app callable from a product — call ductape_integrate_endpoint for the
   ordered version of this with exact ask-the-user points; summary (all verified live):
-  1. Create the app:     ductape_cli("apps create -f app.json")
+  1. Create the app:     ductape_cli("apps create -f ductape/apps/<app-tag>.app.json")
                          body: { app_name, description, tag, envs: [{ env_name, slug, description,
                          base_url, active }, ...] } — tag is REQUIRED; every active env needs a base_url.
                          No --name/--description flags exist, only -f <file.json> or interactive TTY.
   2. Add environments:   Part of step 1's envs array, or later via ductape_cli("apps update --tag
-                         <app_tag> --proxy -f app.json") with an updated envs array.
+                         <app_tag> --proxy -f ductape/apps/<app-tag>.app.json") with an updated envs array.
   3. Configure auth:     Workbench (no CLI command).
-  4. Define actions:     ductape_cli("apps actions create --app <app_tag> --action-file action.json")
+  4. Define actions:     ductape_cli("apps actions create --app <app_tag> --action-file ductape/actions/<app_tag>/<action-tag>.action.json")
                          body: { tag, name, resource, method, request_type, description?, params?,
                          query?, headers?, body?, response? } — request_type is REQUIRED, one of
                          "application/json" | "application/x-www-form-urlencoded" |
@@ -4005,6 +4057,14 @@ When you call features.define({ handler }), the handler runs TWICE:
      For loops: supply recordInput and iterate ctx.sampleInput so all iterations are recorded.
      ctx.input is always the runtime operator surface and must never expose recordInput literals.
      For branches: use branchOverrides so each path is captured.
+     Never make an authorization, validation, tenancy, or other security decision by branching on
+     ctx.input during recording. Use ctx.sampleInput only to discover graph shape; enforce security
+     invariants inside a runtime portable Function or recorded step.
+
+     ductape features sync [filter] sets DUCTAPE_SYNC_MODE=1 and, when filtered,
+     DUCTAPE_FEATURE_FILTER=<filter>. This is an administrative catalogue-only lifecycle: framework
+     integrations and project readiness hooks must not start HTTP listeners, provider probes,
+     schedulers, or Event consumers. Apply the filter before booting unrelated service modules.
 
   2. EXECUTION PHASE (at runtime) — handler is called with a real ExecutionContext.
      ctx.step() actually executes. All real Ductape component calls happen.
@@ -5075,10 +5135,15 @@ EXACT CODE-FIRST VECTOR CONTEXT:
   them into the Feature definition. Note the deliberate naming: ctx.vector.query uses values for
   the embedding, while the lower-level ductape.vector.query runtime facade uses vector.
   Register reusable vector actions administratively, then read them back before compiling Features:
+    ductape vector actions list --vector <vector-tag> --json
     ductape vector actions create --action-file vector-action.json --json
     ductape vector actions get <action-tag> --vector <vector-tag> --json
-  Update/delete/list use the same \`ductape vector actions\` surface. At runtime the SDK namespace is
-  \`ductape.vector.actions.*\` (plural), while Feature reuse is singular \`ctx.vector.execute(...)\`.
+  Always list and inspect first. Reuse an existing action when operation, namespace/filter/template,
+  parameters, and output semantics match; do not create a duplicate action under a new name.
+  Update/delete/list use the same plural \`ductape vector actions\` CLI surface. Runtime SDK/MCP calls
+  use the singular \`ductape.vector.action.*\` namespace; execute saved actions with
+  \`ductape.vector.action.execute({ product, env, vector, action, input })\`. Feature handlers instead
+  use \`ctx.vector.execute({ vector, action, input })\` because product/env/session are inherited.
   Vertex AI Vector Search stores and searches supplied vectors. It does NOT generate embeddings.
   Do not claim that a Vertex Vector Search index embeds text.
 
@@ -5303,7 +5368,8 @@ const integrateEndpointHandler = async (args) => {
                 'Write a JSON body: { app_name, description, tag, envs: [{ env_name, slug, description, ' +
                     'base_url, active: true }, ...] }. tag is REQUIRED — derive a slug from app_name if the ' +
                     'user has not given one explicitly.',
-                'Run: ductape_cli("apps create -f <path-to-body.json> --json")',
+                'Persist it at ductape/apps/<app-tag>.app.json. Do not use a scratchpad, temporary file, or repository-root JSON.',
+                'Run: ductape_cli("apps create -f ductape/apps/<app-tag>.app.json --json")',
                 'The app tag is what you supplied, not something the response generates — use it as app_tag ' +
                     'in every later stage.',
             ],
@@ -5330,7 +5396,8 @@ const integrateEndpointHandler = async (args) => {
                 '"json"/"xml"/"form"). If response is included, response.status_code and ' +
                 'response.response_format use that same set of values, and status_code is a STRING (e.g. ' +
                 '"200", not the number 200).',
-            'Run: ductape_cli("apps actions create --app <app_tag> --action-file <path-to-action.json> ' +
+            'Persist it at ductape/actions/<app_tag>/<action-tag>.action.json. This canonical file must remain in the project after creation.',
+            'Run: ductape_cli("apps actions create --app <app_tag> --action-file ductape/actions/<app_tag>/<action-tag>.action.json ' +
                 '--json") — the flag is --action-file, not -f (that flag belongs to the parent "apps" ' +
                 'command and Commander resolves it there, so -f would silently be ignored here).',
         ],
@@ -5422,7 +5489,7 @@ const eventsProjectValidationHandler = async (args) => {
 const cliInputSchema = z.object({
     command: z.string().describe('The ductape CLI command to run, without the leading "ductape" word. ' +
         'Examples: "products list", "products create --name \\"My Product\\" --tag my-product", ' +
-        '"apps list", "apps create -f app.json", "resources storage list", ' +
+        '"apps list", "apps create -f ductape/apps/<app-tag>.app.json", "resources storage list", ' +
         '"events topics create -f topic.json", "events topics list --tag broker-tag", ' +
         '"cloud connections list", "link --product my-product --env dev".\n\n' +
         'Use this tool for administrative operations: creating or updating products, apps, ' +
@@ -5436,7 +5503,9 @@ const cliInputSchema = z.object({
         '"features sync" (runs the project\'s own "features:sync" npm script) — never call ' +
         'features.define from the app\'s normal startup path, since that blocks every boot on ' +
         'Ductape API reachability. See ductape_docs for the full convention.\n\n' +
-        'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
+        'The CLI uses the user\'s local logged-in session. Prefer browser OAuth in a trusted local terminal: ' +
+        'ductape login --browser google (or github). It returns automatically through a validated loopback callback. ' +
+        'Never invoke interactive login through MCP or ask the user for credentials.'),
 });
 async function loadMcpSdk() {
     try {
@@ -5492,6 +5561,16 @@ function handleCliFlags() {
 // Surfaced to every connected agent at initialize time, before any tool is called.
 // Keep this short — it is ambient, unconditional overhead on every session.
 // The full doctrine with concrete API shapes lives in the "ductape-first-approach" prompt below.
+const DUCTAPE_ASSET_FILE_POLICY = 'Canonical asset-file policy: every JSON file used by the CLI to create, update, import, ' +
+    'provision, or apply a Ductape asset must be kept inside the target project\'s ductape/ folder, ' +
+    'under the matching asset-type directory (for example ductape/apps/, ductape/actions/, ' +
+    'ductape/databases/, ductape/quotas/, ductape/fallbacks/, or ductape/healthchecks/). Use a ' +
+    'stable tag-based filename such as <tag>.<asset-type>.json. Never create authoritative asset ' +
+    'JSON in /tmp, a scratchpad, the repository root, or another disposable location and then pass ' +
+    'that path to the CLI. Preserve established specialized layouts such as ' +
+    'ductape/database/schema.json, ductape/database/migrations/, ductape/graphs/<graph-tag>/actions/, ' +
+    'and ductape/events/<topic-tag>.topic.json. The ductape/ copy is the source-controlled source of ' +
+    'truth and must remain after the CLI command completes.';
 const DUCTAPE_FIRST_INSTRUCTIONS = 'Ductape-first: before writing custom code for a capability, check whether Ductape already ' +
     'provides it (databases, storage, notifications, events, sessions, caches, actions, quotas, ' +
     'fallback, health). Model any multi-step or externally-risky operation as a Feature ' +
@@ -5504,7 +5583,7 @@ const DUCTAPE_FIRST_INSTRUCTIONS = 'Ductape-first: before writing custom code fo
     'to be defined once and reused across products and environments — check what already exists ' +
     'before creating something new. Treat the ductape/ folder (features/, database/schema.json, ' +
     'notifications.json, events/) as the source of truth: define there first, sync/apply, then ' +
-    'write application code against it — never the reverse. Invoke the "ductape-first-approach" ' +
+    'write application code against it — never the reverse. ' + DUCTAPE_ASSET_FILE_POLICY + ' Invoke the "ductape-first-approach" ' +
     'prompt for the full doctrine with concrete API shapes before scaffolding a new backend.';
 // The detailed doctrine, invoked on demand via the "ductape-first-approach" prompt rather than
 // forced onto every session. Grounded in the actual module contracts this server exposes
@@ -5525,7 +5604,7 @@ const DUCTAPE_FIRST_DOCTRINE = 'Follow this checklist before defaulting to plain
     '"ductape features sync", ductape/database/schema.json + "ductape db schema generate/migrate", ' +
     'ductape/notifications.json + "ductape apply notifications", ductape/events/*.topic.json + ' +
     '"ductape apply events". Define the capability there first, then write application code that ' +
-    'calls into it — never duplicate the logic inline.\n\n' +
+    'calls into it — never duplicate the logic inline. ' + DUCTAPE_ASSET_FILE_POLICY + '\n\n' +
     '5. Secrets never live in code or plain config. Store every credential with secrets.create ' +
     '(scoped and env-aware), then reference it as $Secret{KEY} wherever a credential is needed — ' +
     'action auth headers, database/storage connection config, notification provider config. ' +
@@ -5591,6 +5670,25 @@ async function main() {
         const isLocalMigrationGuidance = (firstWord === 'migrate-codebase' && !args.command.includes('--ensure-product')) ||
             firstWord.startsWith('migration-');
         const isDiagnostic = firstWord === 'doctor';
+        if (firstWord === 'login') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            'Ductape login must be completed by the user in a trusted local terminal, not through an MCP tool process.',
+                            '',
+                            'Preferred browser OAuth:',
+                            '  ductape login --browser google',
+                            '  ductape login --browser github',
+                            '',
+                            'The browser returns to the CLI automatically through a validated 127.0.0.1 callback; no token copying is required.',
+                            'Never ask the user to paste a password, OAuth callback token, auth token, or stored CLI credential into the agent.',
+                            'After login succeeds, retry the original ductape_cli operation. The MCP will detect the new session.',
+                        ].join('\n'),
+                    }],
+                isError: true,
+            };
+        }
         if (!isAuthCommand && !isLocalMigrationGuidance && !isDiagnostic) {
             // Cache successful authentication, but re-check a missing/expired session on every call.
             // The user may complete `ductape login` in another terminal while this MCP process remains
@@ -5613,6 +5711,7 @@ async function main() {
                                 'or:',
                                 `  ductape login --browser google${wsFlag}`,
                                 `  ductape login --browser github${wsFlag}`,
+                                'Browser OAuth returns to the CLI automatically through a validated 127.0.0.1 callback.',
                                 '',
                                 'Never ask the user to paste their password, OAuth callback token, or stored CLI credential into the agent.',
                                 'After login succeeds, retry the original ductape_cli command.',
@@ -6047,7 +6146,7 @@ async function main() {
                 '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, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue',
+                'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
         server.registerTool('ductape_events_discover', {
@@ -6144,6 +6243,7 @@ async function main() {
         server.registerTool('ductape_cli', {
             title: 'Ductape CLI',
             description: 'Run a Ductape CLI command for administrative operations.\n\n' +
+                DUCTAPE_ASSET_FILE_POLICY + '\n\n' +
                 'USE THIS TOOL for any operation that creates or modifies platform configuration:\n' +
                 '  - Creating or updating products (products create/update) and apps (apps create/update)\n' +
                 '  - Importing an app from a Postman v2.1 or OpenAPI 3.0 file: "apps import <file> -t postman|openapi"\n' +

package/docs/TOOLS.md

@@ -1,5 +1,25 @@
 # MCP Tools Reference
 
+## Canonical asset files
+
+Every JSON document used by the CLI to create, update, import, provision, or apply an asset is a
+project asset, not a temporary command payload. Store it beneath `<project-root>/ductape/` in the
+matching asset-type directory and keep it after the command completes. For example:
+
+```text
+ductape/apps/paystack.app.json
+ductape/actions/paystack/initialize-transaction.action.json
+ductape/databases/orders.database.json
+ductape/quotas/payment-gateway.quota.json
+ductape/fallbacks/payment-gateway.fallback.json
+ductape/healthchecks/paystack.healthcheck.json
+```
+
+Never place authoritative asset JSON in `/tmp`, a scratchpad, the repository root, or another
+disposable directory. Established specialized layouts remain authoritative, including
+`ductape/database/schema.json`, `ductape/database/migrations/`,
+`ductape/graphs/<graph-tag>/actions/`, and `ductape/events/<topic-tag>.topic.json`.
+
 The Ductape MCP server exposes proxy, CLI, discovery, documentation, migration, and portable-function setup tools.
 
 ## Tool: `ductape_integrate_endpoint`
@@ -12,11 +32,12 @@ It is read-only guidance — it runs no CLI command itself and returns the order
    decide. If new: `ductape_cli("apps create -f app.json")`, body `{ app_name, description, tag,
    envs: [...] }` (`tag` is REQUIRED — no `--name`/`--description` flags exist, only `-f
    <file.json>` or interactive TTY), collecting an environment + base URL for each environment the
-   app needs; every active environment needs a `base_url` before its action can be called.
+   app needs; every active environment needs a `base_url` before its action can be called. Persist
+   the body at `ductape/apps/<app-tag>.app.json`.
 2. **Define the action** — the HTTP method and the endpoint's path *relative to the app's base_url*
    (e.g. `/v1/users/{id}`, never a full URL — Ductape joins `base_url + resource` per environment at
    call time), plus only the params/headers/body/response fields relevant to that endpoint. Then
-   `ductape_cli("apps actions create --app <tag> --action-file action.json")` — the flag is
+   `ductape_cli("apps actions create --app <tag> --action-file ductape/actions/<app-tag>/<action-tag>.action.json")` — the flag is
    `--action-file`, **not** `-f`/`--file` (that flag belongs to the parent `apps` command; Commander
    resolves a flag shared by an ancestor and a descendant against the ancestor, so `-f` here is
    silently ignored — same fix `products environments create/update` uses `--env-file` for).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },