@agentcash/router 0.7.1 → 1.0.1

package/dist/index.cjs

@@ -90,33 +90,46 @@ module.exports = __toCommonJS(index_exports);
 // src/registry.ts
 var RouteRegistry = class {
   routes = /* @__PURE__ */ new Map();
-  // Silently overwrites on duplicate key. Next.js module loading order is
-  // non-deterministic during build — discovery stubs and real handlers may
-  // register the same route key in either order. Last writer wins.
+  // Internal map key includes the HTTP method so that POST and DELETE on the
+  // same path coexist. Within the same path+method, last-write-wins is still
+  // intentional — Next.js module loading order is non-deterministic during
+  // build and discovery stubs may register the same route in either order.
   // Prior art: ElysiaJS uses the same pattern (silent overwrite in router.history).
+  mapKey(entry) {
+    return `${entry.key}:${entry.method}`;
+  }
   register(entry) {
-    if (this.routes.has(entry.key) && typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+    const k = this.mapKey(entry);
+    if (this.routes.has(k) && typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
       console.warn(
-        `[agentcash/router] route '${entry.key}' registered twice \u2014 overwriting (this is expected for discovery stubs during next build)`
+        `[agentcash/router] route '${entry.key}' (${entry.method}) registered twice \u2014 overwriting (this is expected for discovery stubs during next build)`
       );
     }
-    this.routes.set(entry.key, entry);
+    this.routes.set(k, entry);
   }
+  // Accepts either a compound key ("site/domain:DELETE") or a path-only key
+  // ("site/domain") — path-only returns the first registered method for that path.
   get(key) {
-    return this.routes.get(key);
+    const direct = this.routes.get(key);
+    if (direct) return direct;
+    for (const entry of this.routes.values()) {
+      if (entry.key === key) return entry;
+    }
+    return void 0;
   }
   entries() {
     return this.routes.entries();
   }
   has(key) {
-    return this.routes.has(key);
+    return this.get(key) !== void 0;
   }
   get size() {
     return this.routes.size;
   }
   validate(expectedKeys) {
     if (!expectedKeys) return;
-    const missing = expectedKeys.filter((k) => !this.routes.has(k));
+    const registeredPathKeys = new Set([...this.routes.values()].map((e) => e.key));
+    const missing = expectedKeys.filter((k) => !registeredPathKeys.has(k));
     if (missing.length > 0) {
       throw new Error(
         `route${missing.length > 1 ? "s" : ""} ${missing.map((k) => `'${k}'`).join(", ")} in prices map but not registered \u2014 add to barrel imports`
@@ -1456,7 +1469,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,19 +1487,14 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
-    const methodHints = options.methodHints ?? "non-default";
-    for (const [key, entry] of registry.entries()) {
-      const url = `${normalizedBase}/api/${entry.path ?? key}`;
+    const methodHints = discovery.methodHints ?? "non-default";
+    for (const [, entry] of registry.entries()) {
+      const url = `${normalizedBase}/api/${entry.path ?? entry.key}`;
       const resource = toDiscoveryResource(entry.method, url, methodHints);
       if (entry.authMode !== "unprotected") x402Set.add(resource);
       if (entry.protocols.includes("mpp")) mppSet.add(resource);
     }
-    let instructions;
-    if (typeof options.instructions === "function") {
-      instructions = await options.instructions();
-    } else if (typeof options.instructions === "string") {
-      instructions = options.instructions;
-    }
+    const instructions = await resolveGuidance(discovery);
     const body = {
       version: 1,
       resources: Array.from(x402Set)
@@ -1487,11 +1503,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;
@@ -1514,7 +1530,7 @@ function toDiscoveryResource(method, url, mode) {
 
 // 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;
@@ -1529,12 +1545,12 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
     const tagSet = /* @__PURE__ */ new Set();
     let requiresSiwxScheme = false;
     let requiresApiKeyScheme = false;
-    for (const [key, entry] of registry.entries()) {
-      const apiPath = `/api/${entry.path ?? key}`;
+    for (const [, entry] of registry.entries()) {
+      const apiPath = `/api/${entry.path ?? entry.key}`;
       const method = entry.method.toLowerCase();
-      const tag = deriveTag(key);
+      const tag = deriveTag(entry.key);
       tagSet.add(tag);
-      const built = buildOperation(key, entry, tag);
+      const built = buildOperation(entry.key, entry, tag);
       if (built.requiresSiwxScheme) requiresSiwxScheme = true;
       if (built.requiresApiKeyScheme) requiresApiKeyScheme = true;
       paths[apiPath] = { ...paths[apiPath], [method]: built.operation };
@@ -1555,21 +1571,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: {
@@ -1689,6 +1704,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();
@@ -1817,11 +1846,14 @@ function createRouter(config) {
       }
       return builder;
     },
-    wellKnown(options) {
-      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    wellKnown() {
+      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
+    },
+    openapi() {
+      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
     },
-    openapi(options) {
-      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    llmsTxt() {
+      return createLlmsTxtHandler(config.discovery);
     },
     monitors() {
       const result = [];

package/dist/index.d.cts

@@ -280,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;
     /**
@@ -329,10 +344,12 @@ interface RouterConfig {
      * This prevents discovery/openapi drift caused by shorthand internal keys.
      */
     strictRoutes?: boolean;
+    discovery: DiscoveryConfig;
 }
 
 declare class RouteRegistry {
     private routes;
+    private mapKey;
     register(entry: RouteEntry): void;
     get(key: string): RouteEntry | undefined;
     entries(): IterableIterator<[string, RouteEntry]>;
@@ -341,34 +358,6 @@ declare class RouteRegistry {
     validate(expectedKeys?: string[]): void;
 }
 
-interface WellKnownOptions {
-    description?: string;
-    instructions?: string | (() => string | Promise<string>);
-    ownershipProofs?: string[];
-    /**
-     * Whether to include explicit HTTP method prefixes in `resources`.
-     * - `off`: always emit plain URLs.
-     * - `non-default`: emit `METHOD url` for PUT/PATCH/DELETE routes.
-     * - `always`: emit `METHOD url` for all routes.
-     *
-     * @default 'non-default'
-     */
-    methodHints?: 'off' | 'non-default' | 'always';
-}
-
-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>;
@@ -477,8 +466,9 @@ interface MonitorEntry {
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
     route<K extends string>(keyOrDefinition: K | RouteDefinition<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>;
+    wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    openapi(): (request: NextRequest) => Promise<NextResponse>;
+    llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -486,4 +476,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

@@ -280,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;
     /**
@@ -329,10 +344,12 @@ interface RouterConfig {
      * This prevents discovery/openapi drift caused by shorthand internal keys.
      */
     strictRoutes?: boolean;
+    discovery: DiscoveryConfig;
 }
 
 declare class RouteRegistry {
     private routes;
+    private mapKey;
     register(entry: RouteEntry): void;
     get(key: string): RouteEntry | undefined;
     entries(): IterableIterator<[string, RouteEntry]>;
@@ -341,34 +358,6 @@ declare class RouteRegistry {
     validate(expectedKeys?: string[]): void;
 }
 
-interface WellKnownOptions {
-    description?: string;
-    instructions?: string | (() => string | Promise<string>);
-    ownershipProofs?: string[];
-    /**
-     * Whether to include explicit HTTP method prefixes in `resources`.
-     * - `off`: always emit plain URLs.
-     * - `non-default`: emit `METHOD url` for PUT/PATCH/DELETE routes.
-     * - `always`: emit `METHOD url` for all routes.
-     *
-     * @default 'non-default'
-     */
-    methodHints?: 'off' | 'non-default' | 'always';
-}
-
-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>;
@@ -477,8 +466,9 @@ interface MonitorEntry {
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
     route<K extends string>(keyOrDefinition: K | RouteDefinition<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>;
+    wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    openapi(): (request: NextRequest) => Promise<NextResponse>;
+    llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -486,4 +476,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

@@ -51,33 +51,46 @@ var init_server = __esm({
 // src/registry.ts
 var RouteRegistry = class {
   routes = /* @__PURE__ */ new Map();
-  // Silently overwrites on duplicate key. Next.js module loading order is
-  // non-deterministic during build — discovery stubs and real handlers may
-  // register the same route key in either order. Last writer wins.
+  // Internal map key includes the HTTP method so that POST and DELETE on the
+  // same path coexist. Within the same path+method, last-write-wins is still
+  // intentional — Next.js module loading order is non-deterministic during
+  // build and discovery stubs may register the same route in either order.
   // Prior art: ElysiaJS uses the same pattern (silent overwrite in router.history).
+  mapKey(entry) {
+    return `${entry.key}:${entry.method}`;
+  }
   register(entry) {
-    if (this.routes.has(entry.key) && typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+    const k = this.mapKey(entry);
+    if (this.routes.has(k) && typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
       console.warn(
-        `[agentcash/router] route '${entry.key}' registered twice \u2014 overwriting (this is expected for discovery stubs during next build)`
+        `[agentcash/router] route '${entry.key}' (${entry.method}) registered twice \u2014 overwriting (this is expected for discovery stubs during next build)`
       );
     }
-    this.routes.set(entry.key, entry);
+    this.routes.set(k, entry);
   }
+  // Accepts either a compound key ("site/domain:DELETE") or a path-only key
+  // ("site/domain") — path-only returns the first registered method for that path.
   get(key) {
-    return this.routes.get(key);
+    const direct = this.routes.get(key);
+    if (direct) return direct;
+    for (const entry of this.routes.values()) {
+      if (entry.key === key) return entry;
+    }
+    return void 0;
   }
   entries() {
     return this.routes.entries();
   }
   has(key) {
-    return this.routes.has(key);
+    return this.get(key) !== void 0;
   }
   get size() {
     return this.routes.size;
   }
   validate(expectedKeys) {
     if (!expectedKeys) return;
-    const missing = expectedKeys.filter((k) => !this.routes.has(k));
+    const registeredPathKeys = new Set([...this.routes.values()].map((e) => e.key));
+    const missing = expectedKeys.filter((k) => !registeredPathKeys.has(k));
     if (missing.length > 0) {
       throw new Error(
         `route${missing.length > 1 ? "s" : ""} ${missing.map((k) => `'${k}'`).join(", ")} in prices map but not registered \u2014 add to barrel imports`
@@ -1417,7 +1430,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,19 +1448,14 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     }
     const x402Set = /* @__PURE__ */ new Set();
     const mppSet = /* @__PURE__ */ new Set();
-    const methodHints = options.methodHints ?? "non-default";
-    for (const [key, entry] of registry.entries()) {
-      const url = `${normalizedBase}/api/${entry.path ?? key}`;
+    const methodHints = discovery.methodHints ?? "non-default";
+    for (const [, entry] of registry.entries()) {
+      const url = `${normalizedBase}/api/${entry.path ?? entry.key}`;
       const resource = toDiscoveryResource(entry.method, url, methodHints);
       if (entry.authMode !== "unprotected") x402Set.add(resource);
       if (entry.protocols.includes("mpp")) mppSet.add(resource);
     }
-    let instructions;
-    if (typeof options.instructions === "function") {
-      instructions = await options.instructions();
-    } else if (typeof options.instructions === "string") {
-      instructions = options.instructions;
-    }
+    const instructions = await resolveGuidance(discovery);
     const body = {
       version: 1,
       resources: Array.from(x402Set)
@@ -1448,11 +1464,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;
@@ -1475,7 +1491,7 @@ function toDiscoveryResource(method, url, mode) {
 
 // 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;
@@ -1490,12 +1506,12 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
     const tagSet = /* @__PURE__ */ new Set();
     let requiresSiwxScheme = false;
     let requiresApiKeyScheme = false;
-    for (const [key, entry] of registry.entries()) {
-      const apiPath = `/api/${entry.path ?? key}`;
+    for (const [, entry] of registry.entries()) {
+      const apiPath = `/api/${entry.path ?? entry.key}`;
       const method = entry.method.toLowerCase();
-      const tag = deriveTag(key);
+      const tag = deriveTag(entry.key);
       tagSet.add(tag);
-      const built = buildOperation(key, entry, tag);
+      const built = buildOperation(entry.key, entry, tag);
       if (built.requiresSiwxScheme) requiresSiwxScheme = true;
       if (built.requiresApiKeyScheme) requiresApiKeyScheme = true;
       paths[apiPath] = { ...paths[apiPath], [method]: built.operation };
@@ -1516,21 +1532,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: {
@@ -1650,6 +1665,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();
@@ -1778,11 +1807,14 @@ function createRouter(config) {
       }
       return builder;
     },
-    wellKnown(options) {
-      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    wellKnown() {
+      return createWellKnownHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
+    },
+    openapi() {
+      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, config.discovery);
     },
-    openapi(options) {
-      return createOpenAPIHandler(registry, resolvedBaseUrl, pricesKeys, options);
+    llmsTxt() {
+      return createLlmsTxtHandler(config.discovery);
     },
     monitors() {
       const result = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.7.1",
+  "version": "1.0.1",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {