@agentcash/router 0.7.0 → 1.0.0

package/README.md

@@ -58,6 +58,8 @@ import { createRouter } from '@agentcash/router';
 
 export const router = createRouter({
   payeeAddress: process.env.X402_PAYEE_ADDRESS!,
+  baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
+  strictRoutes: true, // recommended
 });
 ```
 
@@ -70,7 +72,7 @@ export const router = createRouter({
 import { router } from '@/lib/routes';
 import { searchSchema, searchResponseSchema } from '@/lib/schemas';
 
-export const POST = router.route('search')
+export const POST = router.route({ path: 'search' })
   .paid('0.01')
   .body(searchSchema)
   .output(searchResponseSchema)
@@ -81,7 +83,7 @@ export const POST = router.route('search')
 **SIWX-authenticated route**
 
 ```typescript
-export const GET = router.route('inbox/status')
+export const GET = router.route({ path: 'inbox/status' })
   .siwx()
   .query(statusQuerySchema)
   .handler(async ({ query, wallet }) => getStatus(query, wallet));
@@ -90,7 +92,7 @@ export const GET = router.route('inbox/status')
 **Unprotected route**
 
 ```typescript
-export const GET = router.route('health')
+export const GET = router.route({ path: 'health' })
   .unprotected()
   .handler(async () => ({ status: 'ok' }));
 ```
@@ -101,7 +103,7 @@ export const GET = router.route('health')
 // app/.well-known/x402/route.ts
 import { router } from '@/lib/routes';
 import '@/lib/routes/barrel'; // ensures all routes are imported
-export const GET = router.wellKnown();
+export const GET = router.wellKnown({ methodHints: 'non-default' });
 
 // app/openapi.json/route.ts
 import { router } from '@/lib/routes';
@@ -129,11 +131,29 @@ Creates a `ServiceRouter` instance.
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `payeeAddress` | `string` | **required** | Wallet address to receive payments |
+| `baseUrl` | `string` | **required** | Service origin used for discovery/OpenAPI/realm |
 | `network` | `string` | `'eip155:8453'` | Blockchain network |
 | `plugin` | `RouterPlugin` | `undefined` | Observability plugin |
 | `prices` | `Record<string, string>` | `undefined` | Central pricing map (auto-applied) |
 | `siwx.nonceStore` | `NonceStore` | `MemoryNonceStore` | Custom nonce store |
 | `mpp` | `{ secretKey, currency, recipient? }` | `undefined` | MPP config |
+| `strictRoutes` | `boolean` | `false` | Enforce `route({ path })` and prevent key/path divergence |
+
+### Path-First Routing
+
+Use path-first route definitions to keep runtime, OpenAPI, and discovery aligned:
+
+```typescript
+router.route({ path: 'flightaware/airports/id/flights/arrivals', method: 'GET' })
+```
+
+If you need a custom internal key (legacy pricing map), you can pass:
+
+```typescript
+router.route({ path: 'public/path', key: 'legacy/key' })
+```
+
+In `strictRoutes` mode, custom keys are rejected to prevent discovery drift.
 
 ### Route Builder
 

package/dist/index.cjs

@@ -1456,7 +1456,15 @@ function createRedisEntitlementStore(client, options) {
 
 // src/discovery/well-known.ts
 var import_server3 = require("next/server");
-function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
+
+// src/discovery/utils/guidance.ts
+async function resolveGuidance(discovery) {
+  if (typeof discovery.guidance === "function") return discovery.guidance();
+  return discovery.guidance;
+}
+
+// src/discovery/well-known.ts
+function createWellKnownHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let validated = false;
   return async (_request) => {
@@ -1466,17 +1474,14 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
+    const methodHints = discovery.methodHints ?? "non-default";
     for (const [key, entry] of registry.entries()) {
       const url = `${normalizedBase}/api/${entry.path ?? key}`;
-      if (entry.authMode !== "unprotected") x402Set.add(url);
-      if (entry.protocols.includes("mpp")) mppSet.add(url);
-    }
-    let instructions;
-    if (typeof options.instructions === "function") {
-      instructions = await options.instructions();
-    } else if (typeof options.instructions === "string") {
-      instructions = options.instructions;
+      const resource = toDiscoveryResource(entry.method, url, methodHints);
+      if (entry.authMode !== "unprotected") x402Set.add(resource);
+      if (entry.protocols.includes("mpp")) mppSet.add(resource);
     }
+    const instructions = await resolveGuidance(discovery);
     const body = {
       version: 1,
       resources: Array.from(x402Set)
@@ -1485,11 +1490,11 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (mppResources.length > 0) {
       body.mppResources = mppResources;
     }
-    if (options.description) {
-      body.description = options.description;
+    if (discovery.description) {
+      body.description = discovery.description;
     }
-    if (options.ownershipProofs) {
-      body.ownershipProofs = options.ownershipProofs;
+    if (discovery.ownershipProofs) {
+      body.ownershipProofs = discovery.ownershipProofs;
     }
     if (instructions) {
       body.instructions = instructions;
@@ -1503,10 +1508,16 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     });
   };
 }
+function toDiscoveryResource(method, url, mode) {
+  if (mode === "off") return url;
+  if (mode === "always") return `${method} ${url}`;
+  const isDefaultProbeMethod = method === "GET" || method === "POST";
+  return isDefaultProbeMethod ? url : `${method} ${url}`;
+}
 
 // src/discovery/openapi.ts
 var import_server4 = require("next/server");
-function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
+function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let cached = null;
   let validated = false;
@@ -1547,21 +1558,20 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       };
     }
     const discoveryMetadata = {};
-    if (options.ownershipProofs && options.ownershipProofs.length > 0) {
-      discoveryMetadata.ownershipProofs = options.ownershipProofs;
-    }
-    if (options.llmsTxtUrl) {
-      discoveryMetadata.llmsTxtUrl = options.llmsTxtUrl;
+    if (discovery.ownershipProofs && discovery.ownershipProofs.length > 0) {
+      discoveryMetadata.ownershipProofs = discovery.ownershipProofs;
     }
+    const guidance = await resolveGuidance(discovery);
     const openApiDocument = {
       openapi: "3.1.0",
       info: {
-        title: options.title,
-        description: options.description,
-        version: options.version,
-        ...options.contact && { contact: options.contact }
+        title: discovery.title,
+        description: discovery.description,
+        version: discovery.version,
+        guidance,
+        ...discovery.contact && { contact: discovery.contact }
       },
-      servers: [{ url: (options.baseUrl ?? normalizedBase).replace(/\/+$/, "") }],
+      servers: [{ url: (discovery.serverUrl ?? normalizedBase).replace(/\/+$/, "") }],
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       ...Object.keys(securitySchemes).length > 0 ? {
         components: {
@@ -1681,6 +1691,20 @@ function buildPricingInfo(entry) {
   return void 0;
 }
 
+// src/discovery/llms-txt.ts
+var import_server5 = require("next/server");
+function createLlmsTxtHandler(discovery) {
+  return async (_request) => {
+    const guidance = await resolveGuidance(discovery) ?? "";
+    return new import_server5.NextResponse(guidance, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Access-Control-Allow-Origin": "*"
+      }
+    });
+  };
+}
+
 // src/index.ts
 function createRouter(config) {
   const registry = new RouteRegistry();
@@ -1783,19 +1807,40 @@ function createRouter(config) {
   })();
   const pricesKeys = config.prices ? Object.keys(config.prices) : void 0;
   return {
-    route(key) {
-      const builder = new RouteBuilder(key, registry, deps);
+    route(keyOrDefinition) {
+      const isDefinition = typeof keyOrDefinition !== "string";
+      if (config.strictRoutes && !isDefinition) {
+        throw new Error(
+          "[router] strictRoutes=true requires route({ path }) form. Replace route('my/key') with route({ path: 'my/key' })."
+        );
+      }
+      const definition = isDefinition ? keyOrDefinition : { path: keyOrDefinition, key: keyOrDefinition };
+      const normalizedPath = normalizePath(definition.path);
+      const key = definition.key ?? normalizedPath;
+      if (config.strictRoutes && definition.key && definition.key !== definition.path) {
+        throw new Error(
+          `[router] strictRoutes=true forbids key/path divergence for route '${definition.path}'. Remove custom \`key\` or make it equal to \`path\`.`
+        );
+      }
+      let builder = new RouteBuilder(key, registry, deps);
+      builder = builder.path(normalizedPath);
+      if (definition.method) {
+        builder = builder.method(definition.method);
+      }
       if (config.prices && key in config.prices) {
         const options = config.protocols ? { protocols: config.protocols } : void 0;
         return builder.paid(config.prices[key], options);
       }
       return builder;
     },
-    wellKnown(options) {
-      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    wellKnown() {
+      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
     },
-    openapi(options) {
-      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    openapi() {
+      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
+    },
+    llmsTxt() {
+      return createLlmsTxtHandler(config.discovery);
     },
     monitors() {
       const result = [];
@@ -1816,6 +1861,12 @@ function createRouter(config) {
     registry
   };
 }
+function normalizePath(path) {
+  let normalized = path.trim();
+  normalized = normalized.replace(/^\/+/, "");
+  normalized = normalized.replace(/^api\/+/, "");
+  return normalized.replace(/\/+$/, "");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HttpError,

package/dist/index.d.cts

@@ -185,6 +185,26 @@ interface X402Server {
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+type RouteMethod = 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+interface RouteDefinition<K extends string = string> {
+    /**
+     * Public API path segment (without `/api/` prefix).
+     * Example: `flightaware/airports/id/flights/arrivals`
+     */
+    path: K;
+    /**
+     * Internal route ID for pricing maps / analytics. Defaults to `path`.
+     *
+     * In `strictRoutes` mode, custom keys are disallowed to prevent discovery
+     * drift between internal IDs and advertised paths.
+     */
+    key?: string;
+    /**
+     * Optional explicit method. If omitted, defaults to builder behavior
+     * (`POST`, or `GET` when `.query()` is used).
+     */
+    method?: RouteMethod;
+}
 interface TierConfig {
     price: string;
     label?: string;
@@ -251,7 +271,7 @@ interface RouteEntry {
     outputSchema?: ZodType;
     description?: string;
     path?: string;
-    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    method: RouteMethod;
     maxPrice?: string;
     minPrice?: string;
     payTo?: string | ((request: Request) => string | Promise<string>);
@@ -260,6 +280,21 @@ interface RouteEntry {
     providerConfig?: ProviderConfig;
     validateFn?: (body: unknown) => void | Promise<void>;
 }
+interface DiscoveryConfig {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+    };
+    ownershipProofs?: string[];
+    methodHints?: 'off' | 'non-default' | 'always';
+    /** Natural language guidance for agents. Served as wellknown `instructions` and `/llms.txt`. */
+    guidance?: string | (() => string | Promise<string>);
+    /** Override the OpenAPI `servers` URL. Defaults to `RouterConfig.baseUrl`. Use when the public API hostname differs from the payment realm URL. */
+    serverUrl?: string;
+}
 interface RouterConfig {
     payeeAddress: string;
     /**
@@ -299,6 +334,17 @@ interface RouterConfig {
      * })
      */
     protocols?: ProtocolType[];
+    /**
+     * Enforce explicit, path-first route definitions.
+     *
+     * When enabled:
+     * - `.route('key')` is rejected; use `.route({ path })`.
+     * - custom `key` differing from `path` is rejected.
+     *
+     * This prevents discovery/openapi drift caused by shorthand internal keys.
+     */
+    strictRoutes?: boolean;
+    discovery: DiscoveryConfig;
 }
 
 declare class RouteRegistry {
@@ -311,25 +357,6 @@ declare class RouteRegistry {
     validate(expectedKeys?: string[]): void;
 }
 
-interface WellKnownOptions {
-    description?: string;
-    instructions?: string | (() => string | Promise<string>);
-    ownershipProofs?: string[];
-}
-
-interface OpenAPIOptions {
-    title: string;
-    version: string;
-    description?: string;
-    baseUrl?: string;
-    contact?: {
-        name?: string;
-        url?: string;
-    };
-    llmsTxtUrl?: string;
-    ownershipProofs?: string[];
-}
-
 interface OrchestrateDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
@@ -437,9 +464,10 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(key: K): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
-    wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
-    openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
+    wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    openapi(): (request: NextRequest) => Promise<NextResponse>;
+    llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -447,4 +475,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };

package/dist/index.d.ts

@@ -185,6 +185,26 @@ interface X402Server {
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
+type RouteMethod = 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+interface RouteDefinition<K extends string = string> {
+    /**
+     * Public API path segment (without `/api/` prefix).
+     * Example: `flightaware/airports/id/flights/arrivals`
+     */
+    path: K;
+    /**
+     * Internal route ID for pricing maps / analytics. Defaults to `path`.
+     *
+     * In `strictRoutes` mode, custom keys are disallowed to prevent discovery
+     * drift between internal IDs and advertised paths.
+     */
+    key?: string;
+    /**
+     * Optional explicit method. If omitted, defaults to builder behavior
+     * (`POST`, or `GET` when `.query()` is used).
+     */
+    method?: RouteMethod;
+}
 interface TierConfig {
     price: string;
     label?: string;
@@ -251,7 +271,7 @@ interface RouteEntry {
     outputSchema?: ZodType;
     description?: string;
     path?: string;
-    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
+    method: RouteMethod;
     maxPrice?: string;
     minPrice?: string;
     payTo?: string | ((request: Request) => string | Promise<string>);
@@ -260,6 +280,21 @@ interface RouteEntry {
     providerConfig?: ProviderConfig;
     validateFn?: (body: unknown) => void | Promise<void>;
 }
+interface DiscoveryConfig {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+    };
+    ownershipProofs?: string[];
+    methodHints?: 'off' | 'non-default' | 'always';
+    /** Natural language guidance for agents. Served as wellknown `instructions` and `/llms.txt`. */
+    guidance?: string | (() => string | Promise<string>);
+    /** Override the OpenAPI `servers` URL. Defaults to `RouterConfig.baseUrl`. Use when the public API hostname differs from the payment realm URL. */
+    serverUrl?: string;
+}
 interface RouterConfig {
     payeeAddress: string;
     /**
@@ -299,6 +334,17 @@ interface RouterConfig {
      * })
      */
     protocols?: ProtocolType[];
+    /**
+     * Enforce explicit, path-first route definitions.
+     *
+     * When enabled:
+     * - `.route('key')` is rejected; use `.route({ path })`.
+     * - custom `key` differing from `path` is rejected.
+     *
+     * This prevents discovery/openapi drift caused by shorthand internal keys.
+     */
+    strictRoutes?: boolean;
+    discovery: DiscoveryConfig;
 }
 
 declare class RouteRegistry {
@@ -311,25 +357,6 @@ declare class RouteRegistry {
     validate(expectedKeys?: string[]): void;
 }
 
-interface WellKnownOptions {
-    description?: string;
-    instructions?: string | (() => string | Promise<string>);
-    ownershipProofs?: string[];
-}
-
-interface OpenAPIOptions {
-    title: string;
-    version: string;
-    description?: string;
-    baseUrl?: string;
-    contact?: {
-        name?: string;
-        url?: string;
-    };
-    llmsTxtUrl?: string;
-    ownershipProofs?: string[];
-}
-
 interface OrchestrateDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
@@ -437,9 +464,10 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(key: K): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
-    wellKnown(options?: WellKnownOptions): (request: NextRequest) => Promise<NextResponse>;
-    openapi(options: OpenAPIOptions): (request: NextRequest) => Promise<NextResponse>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, false, false, false>;
+    wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    openapi(): (request: NextRequest) => Promise<NextResponse>;
+    llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -447,4 +475,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
     prices?: P;
 }): ServiceRouter<Extract<keyof P, string>>;
 
-export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };
+export { type AlertEvent, type AlertFn, type AlertLevel, type AuthEvent, type AuthMode, type DiscoveryConfig, type EntitlementStore, type ErrorEvent, type HandlerContext, HttpError, MemoryEntitlementStore, MemoryNonceStore, type MonitorEntry, type NonceStore, type OveragePolicy, type PaidOptions, type PaymentEvent, type PluginContext, type PricingConfig, type ProtocolType, type ProviderConfig, type ProviderQuotaEvent, type QuotaInfo, type QuotaLevel, type RedisEntitlementStoreOptions, type RedisNonceStoreOptions, type RequestMeta, type ResponseMeta, RouteBuilder, type RouteEntry, RouteRegistry, type RouterConfig, type RouterPlugin, SIWX_CHALLENGE_EXPIRY_MS, type ServiceRouter, type SettlementEvent, type TierConfig, type X402Server, consolePlugin, createRedisEntitlementStore, createRedisNonceStore, createRouter };

package/dist/index.js

@@ -1417,7 +1417,15 @@ function createRedisEntitlementStore(client, options) {
 
 // src/discovery/well-known.ts
 import { NextResponse as NextResponse3 } from "next/server";
-function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
+
+// src/discovery/utils/guidance.ts
+async function resolveGuidance(discovery) {
+  if (typeof discovery.guidance === "function") return discovery.guidance();
+  return discovery.guidance;
+}
+
+// src/discovery/well-known.ts
+function createWellKnownHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let validated = false;
   return async (_request) => {
@@ -1427,17 +1435,14 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
+    const methodHints = discovery.methodHints ?? "non-default";
     for (const [key, entry] of registry.entries()) {
       const url = `${normalizedBase}/api/${entry.path ?? key}`;
-      if (entry.authMode !== "unprotected") x402Set.add(url);
-      if (entry.protocols.includes("mpp")) mppSet.add(url);
-    }
-    let instructions;
-    if (typeof options.instructions === "function") {
-      instructions = await options.instructions();
-    } else if (typeof options.instructions === "string") {
-      instructions = options.instructions;
+      const resource = toDiscoveryResource(entry.method, url, methodHints);
+      if (entry.authMode !== "unprotected") x402Set.add(resource);
+      if (entry.protocols.includes("mpp")) mppSet.add(resource);
     }
+    const instructions = await resolveGuidance(discovery);
     const body = {
       version: 1,
       resources: Array.from(x402Set)
@@ -1446,11 +1451,11 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (mppResources.length > 0) {
       body.mppResources = mppResources;
     }
-    if (options.description) {
-      body.description = options.description;
+    if (discovery.description) {
+      body.description = discovery.description;
     }
-    if (options.ownershipProofs) {
-      body.ownershipProofs = options.ownershipProofs;
+    if (discovery.ownershipProofs) {
+      body.ownershipProofs = discovery.ownershipProofs;
     }
     if (instructions) {
       body.instructions = instructions;
@@ -1464,10 +1469,16 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     });
   };
 }
+function toDiscoveryResource(method, url, mode) {
+  if (mode === "off") return url;
+  if (mode === "always") return `${method} ${url}`;
+  const isDefaultProbeMethod = method === "GET" || method === "POST";
+  return isDefaultProbeMethod ? url : `${method} ${url}`;
+}
 
 // src/discovery/openapi.ts
 import { NextResponse as NextResponse4 } from "next/server";
-function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
+function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
   const normalizedBase = baseUrl.replace(/\/+$/, "");
   let cached = null;
   let validated = false;
@@ -1508,21 +1519,20 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       };
     }
     const discoveryMetadata = {};
-    if (options.ownershipProofs && options.ownershipProofs.length > 0) {
-      discoveryMetadata.ownershipProofs = options.ownershipProofs;
-    }
-    if (options.llmsTxtUrl) {
-      discoveryMetadata.llmsTxtUrl = options.llmsTxtUrl;
+    if (discovery.ownershipProofs && discovery.ownershipProofs.length > 0) {
+      discoveryMetadata.ownershipProofs = discovery.ownershipProofs;
     }
+    const guidance = await resolveGuidance(discovery);
     const openApiDocument = {
       openapi: "3.1.0",
       info: {
-        title: options.title,
-        description: options.description,
-        version: options.version,
-        ...options.contact && { contact: options.contact }
+        title: discovery.title,
+        description: discovery.description,
+        version: discovery.version,
+        guidance,
+        ...discovery.contact && { contact: discovery.contact }
       },
-      servers: [{ url: (options.baseUrl ?? normalizedBase).replace(/\/+$/, "") }],
+      servers: [{ url: (discovery.serverUrl ?? normalizedBase).replace(/\/+$/, "") }],
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       ...Object.keys(securitySchemes).length > 0 ? {
         components: {
@@ -1642,6 +1652,20 @@ function buildPricingInfo(entry) {
   return void 0;
 }
 
+// src/discovery/llms-txt.ts
+import { NextResponse as NextResponse5 } from "next/server";
+function createLlmsTxtHandler(discovery) {
+  return async (_request) => {
+    const guidance = await resolveGuidance(discovery) ?? "";
+    return new NextResponse5(guidance, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Access-Control-Allow-Origin": "*"
+      }
+    });
+  };
+}
+
 // src/index.ts
 function createRouter(config) {
   const registry = new RouteRegistry();
@@ -1744,19 +1768,40 @@ function createRouter(config) {
   })();
   const pricesKeys = config.prices ? Object.keys(config.prices) : void 0;
   return {
-    route(key) {
-      const builder = new RouteBuilder(key, registry, deps);
+    route(keyOrDefinition) {
+      const isDefinition = typeof keyOrDefinition !== "string";
+      if (config.strictRoutes && !isDefinition) {
+        throw new Error(
+          "[router] strictRoutes=true requires route({ path }) form. Replace route('my/key') with route({ path: 'my/key' })."
+        );
+      }
+      const definition = isDefinition ? keyOrDefinition : { path: keyOrDefinition, key: keyOrDefinition };
+      const normalizedPath = normalizePath(definition.path);
+      const key = definition.key ?? normalizedPath;
+      if (config.strictRoutes && definition.key && definition.key !== definition.path) {
+        throw new Error(
+          `[router] strictRoutes=true forbids key/path divergence for route '${definition.path}'. Remove custom \`key\` or make it equal to \`path\`.`
+        );
+      }
+      let builder = new RouteBuilder(key, registry, deps);
+      builder = builder.path(normalizedPath);
+      if (definition.method) {
+        builder = builder.method(definition.method);
+      }
       if (config.prices && key in config.prices) {
         const options = config.protocols ? { protocols: config.protocols } : void 0;
         return builder.paid(config.prices[key], options);
       }
       return builder;
     },
-    wellKnown(options) {
-      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    wellKnown() {
+      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
     },
-    openapi(options) {
-      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    openapi() {
+      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
+    },
+    llmsTxt() {
+      return createLlmsTxtHandler(config.discovery);
     },
     monitors() {
       const result = [];
@@ -1777,6 +1822,12 @@ function createRouter(config) {
     registry
   };
 }
+function normalizePath(path) {
+  let normalized = path.trim();
+  normalized = normalized.replace(/^\/+/, "");
+  normalized = normalized.replace(/^api\/+/, "");
+  return normalized.replace(/\/+$/, "");
+}
 export {
   HttpError,
   MemoryEntitlementStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.7.0",
+  "version": "1.0.0",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -48,7 +48,7 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "eslint": "^10.0.0",
-    "mppx": "^0.3.9",
+    "mppx": "^0.3.13",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
     "react": "^19.0.0",