@lupinum/ginko-content 0.1.2 → 0.1.3

package/dist/module.d.mts

@@ -1,12 +1,11 @@
 import * as _nuxt_schema from '@nuxt/schema';
+import { ModuleOptions as ModuleOptions$1, ContentContext as ContentContext$1, ContentRevalidateOptions as ContentRevalidateOptions$1 } from '../dist/types/module';
+import { StorageValue } from 'unstorage';
 import { MarkdownOptions as MarkdownOptions$1, ParsedContent as ParsedContent$1 } from '../dist/types/content';
 import { ContentCollectionConfig as ContentCollectionConfig$1, ContentCollectionI18nConfig as ContentCollectionI18nConfig$1 } from '../dist/types/config';
-export { defineCollection, defineContentConfig, reference } from '../dist/types/config';
-import { StorageValue } from 'unstorage';
-import { ModuleOptions as ModuleOptions$1, ContentContext as ContentContext$1, ContentRevalidateOptions as ContentRevalidateOptions$1 } from '../dist/types/module';
+export { agentMetadataFields, defineAgentAppPage, defineAgentMarkdownPolicy, defineAgentMetadataFields, defineAgentSection, defineCollection, defineContentConfig, reference } from '../dist/types/config';
 import { ZodType, z } from 'zod';
 import { ContentSearchPublicRuntimeConfig as ContentSearchPublicRuntimeConfig$1 } from '../dist/types/search';
-import { ListenOptions } from 'listhen';
 
 /**
  * Locale settings for a collection that ships translated variants.
@@ -72,6 +71,67 @@ interface ContentCmsCollectionConfig {
     fields?: Record<string, ContentCmsFieldConfig>;
     settings?: unknown;
 }
+declare const agentMetadataFields: readonly ["title", "description", "url", "route", "locale", "section", "collection", "source", "updated"];
+type AgentMetadataField = typeof agentMetadataFields[number];
+type AgentMetadataFieldList = readonly AgentMetadataField[];
+interface ContentAgentMarkdownOptions {
+    includeInIndex?: boolean;
+    includeInFull?: boolean;
+    metadata?: AgentMetadataFieldList;
+}
+interface ContentAgentCollectionConfig {
+    section?: string;
+    markdown?: boolean | ContentAgentMarkdownOptions;
+}
+type ContentAgentLocalizedValue = string | Record<string, string>;
+interface ContentAgentSiteConfig {
+    title: ContentAgentLocalizedValue;
+    description: ContentAgentLocalizedValue;
+    url?: string;
+    defaultLocale?: string;
+    locales?: string[];
+    profile?: string;
+    contentSignals?: {
+        search?: boolean;
+        aiInput?: boolean;
+        aiTrain?: boolean;
+    };
+}
+interface ContentAgentMarkdownMetadataConfig {
+    enabled?: boolean;
+    defaultFields?: AgentMetadataFieldList;
+}
+interface ContentAgentMarkdownPolicyConfig {
+    metadata?: boolean | AgentMetadataFieldList | ContentAgentMarkdownMetadataConfig;
+}
+interface ContentAgentSectionConfig {
+    id: string;
+    title: ContentAgentLocalizedValue;
+    order?: number;
+}
+interface ContentAgentAppPageContext {
+    locale: string;
+    defaultLocale?: string;
+    siteUrl: string;
+}
+interface ContentAgentAppPageConfig {
+    id: string;
+    route: ContentAgentLocalizedValue;
+    section: string;
+    title: ContentAgentLocalizedValue | ((ctx: ContentAgentAppPageContext) => string | Promise<string>);
+    description: ContentAgentLocalizedValue | ((ctx: ContentAgentAppPageContext) => string | Promise<string>);
+    updated?: string;
+    includeInIndex?: boolean;
+    includeInFull?: boolean;
+    metadata?: AgentMetadataFieldList;
+    render: (ctx: ContentAgentAppPageContext) => string | Promise<string>;
+}
+interface ContentAgentConfig {
+    site?: ContentAgentSiteConfig;
+    markdown?: ContentAgentMarkdownPolicyConfig;
+    sections?: ContentAgentSectionConfig[];
+    pages?: ContentAgentAppPageConfig[];
+}
 /**
  * Object source shape accepted for Nuxt Content v3 migration.
  */
@@ -145,6 +205,12 @@ interface ContentCollectionConfig<TSchema extends ZodType | undefined = ZodType
      * source, i18n, and schema information.
      */
     cms?: ContentCmsCollectionConfig;
+    /**
+     * Agent-facing collection exposure. Collections declare only whether pages
+     * produce normalized markdown and which agent section they belong to. Root
+     * `agent` config owns site policy; the Ginko module owns route plumbing.
+     */
+    agent?: ContentAgentCollectionConfig;
 }
 type ContentProviderName = 'filesystem' | (string & {});
 type DefineCollectionOptions<TSchema extends ZodType | undefined = ZodType | undefined> = Omit<ContentCollectionConfig<TSchema>, 'source' | 'exclude'>;
@@ -176,6 +242,12 @@ interface ContentConfig<TCollections extends Record<string, ContentCollectionCon
      * modules register themselves, so app configs usually do not need this.
      */
     providers?: Record<string, string>;
+    /**
+     * Agent-facing site map and markdown output. Ginko owns the repetitive
+     * `/llms.txt`, raw markdown, and static route plumbing; apps provide site
+     * facts and app-owned page renderers here.
+     */
+    agent?: ContentAgentConfig;
     /**
      * Named content collections keyed by the identifier used at query time.
      */
@@ -594,123 +666,36 @@ interface ContentQueryCountResponse {
  */
 type ContentQueryResponse<T> = ContentQueryFindResponse<T> | ContentQueryFindOneResponse<T> | ContentQueryCountResponse;
 
-/**
- * Query
- */
 interface ContentQuerySortParams {
-    /**
-     * Locale specifier for sorting
-     * A string with a BCP 47 language tag
-     *
-     * @default undefined
-     */
     $locale?: string;
-    /**
-     * Whether numeric collation should be used, such that "1" < "2" < "10".
-     * Possible values are `true` and `false`;
-     *
-     * @default false
-     */
     $numeric?: boolean;
-    /**
-     * Whether upper case or lower case should sort first.
-     * Possible values are `"upper"`, `"lower"`, or `"false"`
-     *
-     * @default "depends on locale"
-     */
     $caseFirst?: 'upper' | 'lower' | 'false';
-    /**
-     * Which differences in the strings should lead to non-zero result values. Possible values are:
-     *  - "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A.
-     *  - "accent": Only strings that differ in base letters or accents and other diacritic marks compare as unequal. Examples: a ≠ b, a ≠ á, a = A.
-     *  - "case": Only strings that differ in base letters or case compare as unequal. Examples: a ≠ b, a = á, a ≠ A.
-     *  - "variant": Strings that differ in base letters, accents and other diacritic marks, or case compare as unequal. Other differences may also be taken into consideration. Examples: a ≠ b, a ≠ á, a ≠ A.
-     *
-     * @default "variant"
-     */
     $sensitivity?: 'base' | 'accent' | 'case' | 'variant';
 }
 interface ContentQuerySortFields {
     [field: string]: -1 | 1;
 }
 type ContentQuerySortOptions = ContentQuerySortParams | ContentQuerySortFields;
-/**
- * @internal
- */
 interface ContentQueryBuilderWhere extends Partial<Record<keyof ParsedContentInternalMeta, string | number | boolean | RegExp | ContentQueryBuilderWhere>> {
-    /**
-     * Match only if all nested conditions are true.
-     **/
     $and?: ContentQueryBuilderWhere[];
-    /**
-     * Match if any nested condition is true.
-     **/
     $or?: ContentQueryBuilderWhere[];
-    /**
-     * Match when the nested condition is false.
-     **/
     $not?: string | number | boolean | RegExp | ContentQueryBuilderWhere;
-    /**
-     * Match if item equals condition.
-     **/
     $eq?: string | number | boolean | RegExp;
-    /**
-     * Match if item does not equal condition.
-     **/
     $ne?: string | number | boolean | RegExp;
-    /**
-     * Check if item is greater than condition.
-     */
     $gt?: number | string;
-    /**
-     * Check if item is greater than or equal to condition.
-     */
     $gte?: number | string;
-    /**
-     * Check if item is less than condition.
-     */
     $lt?: number | string;
-    /**
-     * Check if item is less than or equal to condition.
-     */
     $lte?: number | string;
-    /**
-     * Provides regular expression capabilities for pattern matching strings.
-     */
     $regex?: RegExp | string;
-    /**
-     * Match when a string field starts with the given prefix.
-     */
     $prefix?: string;
-    /**
-     * Match if type of item equals condition.
-     */
     $type?: string;
-    /**
-     * Check key existence.
-     */
     $exists?: boolean;
-    /**
-     * Match if item contains every condition or every rule in the condition array.
-     **/
     $contains?: Array<string | number | boolean> | string | number | boolean;
-    /**
-     * Match if item contains at least one rule from the condition array.
-     */
     $containsAny?: Array<string | number | boolean>;
-    /**
-     * Ignore case when checking string containment.
-     **/
     $icontains?: string;
-    /**
-     * Match if item is in condition array.
-     **/
     $in?: Array<string | number | boolean>;
     [key: string]: string | number | boolean | RegExp | ContentQueryBuilderWhere | Array<string | number | boolean | ContentQueryBuilderWhere> | undefined;
 }
-/**
- * @internal
- */
 interface ContentQueryBuilderParams {
     collection?: string;
     first?: boolean;
@@ -746,284 +731,135 @@ type CollectionQueryOperator<T> = '=' | '!=' | 'EXISTS' | 'TYPE' | (ComparableVa
 type CollectionQueryValue<T, O extends CollectionQueryOperator<T>> = O extends '=' | '!=' ? EqualityValue<T> : O extends '>' | '>=' | '<' | '<=' ? ComparableValue<T> : O extends 'IN' | 'NOT IN' ? MembershipValue<T> : O extends 'CONTAINS' ? ContainsValue<T> : O extends 'CONTAINS_ANY' ? ContainsAnyValue<T> : O extends 'REGEX' ? RegexValue<T> : O extends 'ICONTAINS' ? IContainsValue<T> : O extends 'EXISTS' ? boolean | undefined : O extends 'TYPE' ? TypeValue : never;
 type QueryOrderDirection = 'ASC' | 'DESC';
 interface QueryOrderOptions {
-    /**
-     * BCP 47 locale passed to `Intl.Collator` for string ordering.
-     */
     locale?: string;
-    /**
-     * Enable numeric ordering so `"2"` sorts before `"10"`.
-     */
     numeric?: boolean;
-    /**
-     * Control whether upper- or lower-case letters sort first.
-     */
     caseFirst?: ContentQuerySortParams['$caseFirst'];
-    /**
-     * Collation sensitivity used by string comparison.
-     */
     sensitivity?: ContentQuerySortParams['$sensitivity'];
 }
-/**
- * Builder passed to grouped `andWhere` / `orWhere` callbacks.
- */
 interface QueryGroupBuilder<T = ParsedContentMeta> {
     where<K extends CollectionQueryField<T>, O extends CollectionQueryOperator<CollectionQueryFieldValue<T, K>>>(field: K, operator: O, value?: CollectionQueryValue<CollectionQueryFieldValue<T, K>, O>): QueryGroupBuilder<T>;
     andWhere(groupFactory: QueryGroupFunction<T>): QueryGroupBuilder<T>;
     orWhere(groupFactory: QueryGroupFunction<T>): QueryGroupBuilder<T>;
 }
-/**
- * Factory used to build grouped nested conditions.
- */
 type QueryGroupFunction<T = ParsedContentMeta> = (group: QueryGroupBuilder<T>) => QueryGroupBuilder<T>;
-/**
- * Options for locale-aware navigation queries.
- */
+interface ContentQueryBuilder<T = ParsedContentMeta> {
+    where<K extends CollectionQueryField<T>, O extends CollectionQueryOperator<CollectionQueryFieldValue<T, K>>>(field: K, operator: O, value?: CollectionQueryValue<CollectionQueryFieldValue<T, K>, O>): ContentQueryBuilder<T>;
+    andWhere(groupFactory: QueryGroupFunction<T>): ContentQueryBuilder<T>;
+    orWhere(groupFactory: QueryGroupFunction<T>): ContentQueryBuilder<T>;
+    select<const K extends readonly Extract<keyof T, string>[]>(...fields: K): ContentQueryBuilder<Pick<T, K[number]>>;
+    order<K extends CollectionQueryField<T>>(field: K, direction: QueryOrderDirection, options?: QueryOrderOptions): ContentQueryBuilder<T>;
+    limit(count: number): ContentQueryBuilder<T>;
+    skip(count: number): ContentQueryBuilder<T>;
+    params: () => ContentQueryBuilderParams;
+    locale(locale: string, options?: {
+        fallback?: boolean | string[];
+    }): ContentQueryBuilder<T>;
+    all(): Promise<Array<T>>;
+    first(): Promise<T | undefined>;
+    count(): Promise<number>;
+}
+interface CollectionQueryBuilder<T = ParsedContentMeta> extends ContentQueryBuilder<T> {
+    select<const K extends readonly Extract<keyof T, string>[]>(...fields: K): CollectionQueryBuilder<Pick<T, K[number]>>;
+}
+interface ContentQueryRequest {
+    params(): ContentQueryBuilderParams;
+}
+type ContentQueryFetcher<T> = (query: ContentQueryRequest) => Promise<ContentQueryResponse<T>>;
+type QueryMatchOperator = (item: unknown, condition: unknown) => boolean;
+
+declare global {
+    interface GinkoContentCollectionMap {
+    }
+    interface GinkoContentCollectionI18nMap {
+    }
+}
+interface ContentCollectionMap extends GinkoContentCollectionMap {
+}
+interface ContentCollectionI18nMap extends GinkoContentCollectionI18nMap {
+}
+type ContentCollectionName = keyof GinkoContentCollectionMap & string;
+type ContentCollectionItem<K extends ContentCollectionName> = ContentCollectionMap[K];
+type ContentCollectionStringName = [ContentCollectionName] extends [never] ? string : ContentCollectionName;
+type ContentCollectionTarget = ContentCollectionHandle | ContentCollectionStringName;
+
 interface ContentCollectionNavigationOptions<TField extends string = string> {
-    /**
-     * Extra document fields to merge onto each returned navigation item.
-     */
     fields?: TField[];
-    /**
-     * Locale to resolve against for translated collections.
-     */
     locale?: string;
-    /**
-     * When `true`, keep canonical paths instead of locale-prefixed paths.
-     */
     canonical?: boolean;
 }
-/**
- * Options for previous/next navigation helpers.
- */
 type ContentCollectionItemSurroundingsOptions<TField extends string = string> = ContentCollectionNavigationOptions<TField>;
-/**
- * Options for extracting searchable sections from collection pages.
- */
 interface ContentCollectionSearchSectionsOptions {
-    /**
-     * Tags ignored while flattening page content into search text.
-     */
     ignoredTags?: string[];
-    /**
-     * Extra top-level fields copied from each page onto every emitted section.
-     */
     extraFields?: string[];
-    /**
-     * Query predicate applied before extracting searchable sections.
-     */
     filterQuery?: ContentQueryBuilderWhere;
-    /**
-     * Lowest heading level that starts a new section.
-     */
     minHeading?: `h${1 | 2 | 3 | 4 | 5 | 6}`;
-    /**
-     * Highest heading level that starts a new section.
-     */
     maxHeading?: `h${1 | 2 | 3 | 4 | 5 | 6}`;
-    /**
-     * Locale to resolve against for translated collections.
-     */
     locale?: string;
-    /**
-     * When `true`, keep canonical paths instead of locale-prefixed paths.
-     */
     canonical?: boolean;
 }
-/**
- * Options for locale-aware page resolution.
- */
 interface ContentCollectionPageOptions {
-    /**
-     * Preferred locale to resolve.
-     */
     locale?: string;
-    /**
-     * Enable or customize locale fallback resolution.
-     *
-     * Pass `true` to use configured fallbacks, or an explicit locale list to
-     * override the configured chain for this query.
-     */
     fallback?: string[] | boolean;
-    /**
-     * When `true`, keep canonical paths in the returned route metadata.
-     */
+    exact?: boolean;
     canonical?: boolean;
 }
-/**
- * Options for route metadata resolution without loading full page content.
- */
 interface ContentCollectionRouteMetaOptions {
-    /**
-     * Preferred locale to resolve.
-     */
     locale?: string;
-    /**
-     * Enable or customize locale fallback resolution.
-     */
     fallback?: string[] | boolean;
+    exact?: boolean;
 }
-/**
- * Options for resolving an authored reference value into a document.
- */
 interface ResolveContentReferenceOptions {
-    /**
-     * Preferred locale to resolve.
-     */
     locale?: string;
-    /**
-     * Enable or customize locale fallback resolution.
-     */
     fallback?: string[] | boolean;
-    /**
-     * When `true`, require an exact locale match and skip fallback lookup.
-     */
     exact?: boolean;
-    /**
-     * Restrict resolution to a single collection.
-     */
     collection?: string;
 }
-/**
- * Locale variant entry returned by the internal locale-variant endpoint.
- */
 interface ContentLocaleEntry {
-    /**
-     * Stable locale-agnostic identity shared by every translated variant.
-     */
     canonicalKey: string;
-    /**
-     * Locale code for the matching variant.
-     */
     locale: string;
-    /**
-     * Resolved route path for the variant, when the variant is routable.
-     */
     path?: string;
 }
-/**
- * Route metadata for a single locale variant of a page.
- */
 interface ContentLocaleRoute {
     locale: string;
     path: string;
     canonicalPath: string;
 }
-/**
- * One entry in the per-locale path map attached to a localized document.
- *
- * `translated` is `true` when a concrete variant exists in that locale, `false`
- * when the resolver fell back to another locale's path. `fallback` names the
- * locale that supplied the path when `translated` is false.
- */
 interface LocalePathEntry {
-    /**
-     * Locale-prefixed route path (the URL the user navigates to).
-     */
     path: string;
-    /**
-     * `true` when this locale has its own variant; `false` when the path was
-     * supplied by a fallback locale.
-     */
     translated: boolean;
-    /**
-     * Locale that backed this entry when `translated` is `false`.
-     */
     fallback?: string;
 }
-/**
- * Public resolution metadata attached to localized content results.
- *
- * Internal `_requestedLocale`, `_resolvedLocale`, and `_fallback` fields remain
- * storage/query implementation details. UI code should read this object.
- */
 interface ContentResolvedMeta {
-    /**
-     * Locale of the concrete content variant that backed this result.
-     */
     locale: string;
-    /**
-     * Locale requested by the caller, when locale resolution was part of the
-     * query.
-     */
     requestedLocale?: string;
-    /**
-     * `true` when the concrete content variant came from a different locale than
-     * the requested locale.
-     */
     fallback: boolean;
-    /**
-     * Locale that supplied the content when `fallback` is true.
-     */
     fallbackLocale?: string;
-    /**
-     * Public route path returned to the user.
-     */
     path: string;
-    /**
-     * Requested route path before locale fallback, when known.
-     */
     requestedPath?: string;
-    /**
-     * Requested public route before locale fallback, when known.
-     */
     requestedRoute?: string;
-    /**
-     * Requested authored ref before locale fallback, when known.
-     */
     requestedRef?: string;
-    /**
-     * Locales that have concrete variants for this content identity.
-     */
     availableLocales: string[];
 }
-/**
- * Locale-aware routing metadata attached to route-backed page payloads.
- */
 interface ContentRouteMeta {
     locale: string;
     defaultLocale: string;
     path: string;
     canonicalPath: string;
     variants: ContentLocaleRoute[];
-    /**
-     * Map of every configured locale to its localized path. Includes a
-     * `translated` flag and a `fallback` source when a locale has no variant.
-     */
     localePaths: Record<string, LocalePathEntry>;
-    /**
-     * Public explanation of the locale/path resolution used for this result.
-     */
     resolved: ContentResolvedMeta;
 }
-/**
- * Full page payload returned by route-aware unified query helpers and internal route helpers.
- */
 type ContentPageResult<T = ParsedContentMeta> = T & ContentRouteMeta & {
-    /**
-     * Locale-agnostic path stem derived from the source file.
-     */
     stem: string;
-    /**
-     * Source file extension when it can be inferred.
-     */
     extension?: string;
 };
-/**
- * Alternate locale entry used in sitemap output.
- */
 interface ContentSitemapAlternative {
     hreflang: string;
     href: string;
 }
-/**
- * Sitemap image entry discovered from page content or metadata.
- */
 interface ContentSitemapImage {
     loc: string;
 }
-/**
- * Sitemap entry produced by `queryCollectionsSitemapEntries`.
- */
 interface ContentSitemapEntry {
     loc: string;
     _sitemap?: string;
@@ -1031,132 +867,15 @@ interface ContentSitemapEntry {
     alternatives?: ContentSitemapAlternative[];
     images?: ContentSitemapImage[];
 }
-/**
- * Searchable document section produced by the internal search-section builder.
- */
 interface ContentSearchSection {
-    /**
-     * Stable section id, usually the page path or path plus anchor hash.
-     */
     id: string;
-    /**
-     * Heading or page title for the section.
-     */
     title: string;
-    /**
-     * Ancestor heading trail leading to this section.
-     */
     titles: string[];
-    /**
-     * Heading depth that opened the section.
-     */
     level: number;
-    /**
-     * Flattened text content used by the search index.
-     */
     content: string;
     [key: string]: unknown;
 }
-interface ContentQueryBuilder<T = ParsedContentMeta> {
-    /**
-     * Filter results with an explicit field/operator/value clause.
-     */
-    where<K extends CollectionQueryField<T>, O extends CollectionQueryOperator<CollectionQueryFieldValue<T, K>>>(field: K, operator: O, value?: CollectionQueryValue<CollectionQueryFieldValue<T, K>, O>): ContentQueryBuilder<T>;
-    /**
-     * Add a grouped AND clause.
-     */
-    andWhere(groupFactory: QueryGroupFunction<T>): ContentQueryBuilder<T>;
-    /**
-     * Add a grouped OR clause.
-     */
-    orWhere(groupFactory: QueryGroupFunction<T>): ContentQueryBuilder<T>;
-    /**
-     * Select a subset of fields.
-     */
-    select<const K extends readonly Extract<keyof T, string>[]>(...fields: K): ContentQueryBuilder<Pick<T, K[number]>>;
-    /**
-     * Order the result set by a field.
-     */
-    order<K extends CollectionQueryField<T>>(field: K, direction: QueryOrderDirection, options?: QueryOrderOptions): ContentQueryBuilder<T>;
-    /**
-     * Limit number of results.
-     */
-    limit(count: number): ContentQueryBuilder<T>;
-    /**
-     * Skip number of results.
-     */
-    skip(count: number): ContentQueryBuilder<T>;
-    /**
-     * Retrieve query builder params.
-     * @internal
-     */
-    params: () => ContentQueryBuilderParams;
-    /**
-     * Filter contents based on locale.
-     */
-    locale(locale: string, options?: {
-        fallback?: boolean | string[];
-    }): ContentQueryBuilder<T>;
-    /**
-     * Fetch list of contents.
-     */
-    all(): Promise<Array<T>>;
-    /**
-     * Fetch the first matched content.
-     */
-    first(): Promise<T | undefined>;
-    /**
-     * Count matched contents.
-     */
-    count(): Promise<number>;
-}
-interface CollectionQueryBuilder<T = ParsedContentMeta> extends ContentQueryBuilder<T> {
-    select<const K extends readonly Extract<keyof T, string>[]>(...fields: K): CollectionQueryBuilder<Pick<T, K[number]>>;
-}
-/**
- * Minimal request shape consumed by the query transport.
- */
-interface ContentQueryRequest {
-    params(): ContentQueryBuilderParams;
-}
-/**
- * Internal transport used by the immutable query builder.
- */
-type ContentQueryFetcher<T> = (query: ContentQueryRequest) => Promise<ContentQueryResponse<T>>;
-type QueryMatchOperator = (item: unknown, condition: unknown) => boolean;
-declare global {
-    interface GinkoContentCollectionMap {
-    }
-    interface GinkoContentCollectionI18nMap {
-    }
-}
-interface ContentCollectionMap extends GinkoContentCollectionMap {
-}
-interface ContentCollectionI18nMap extends GinkoContentCollectionI18nMap {
-}
-type ContentCollectionName = keyof GinkoContentCollectionMap & string;
-type ContentCollectionItem<K extends ContentCollectionName> = ContentCollectionMap[K];
-type ContentCollectionStringName = [ContentCollectionName] extends [never] ? string : ContentCollectionName;
-type ContentCollectionTarget = ContentCollectionHandle | ContentCollectionStringName;
-/**
- * ============================================================================
- *  Unified Query API — public surface (ADR-0016)
- * ============================================================================
- *
- * The types below back the unified query API exposed via `one`, `many`,
- * `resolveOne`, `variants`, `tree`, `neighbors` and their `useContent*`
- * composable mirrors. The public vocabulary is deliberately split:
- *
- *   - `by` identifies exactly one document by route path or authored ref.
- *   - `where` filters a result set by document fields.
- *   - `resolveOne` returns diagnostics; `one` is the ergonomic doc-only view.
- */
-/**
- * MongoDB-style operator object applied to a single field. Mirrors the subset
- * of `ContentQueryBuilderWhere` operators that are safe for public use.
- *
- * @template TValue Concrete field value type (used to narrow operator operands).
- */
+
 interface QueryOperators<TValue = unknown> {
     $eq?: TValue;
     $ne?: TValue;
@@ -1174,11 +893,6 @@ interface QueryOperators<TValue = unknown> {
     $prefix?: TValue extends string ? string : never;
     $not?: TValue | QueryOperators<TValue>;
 }
-/**
- * Identify exactly one document. `path` is stored content `_path`, `route` is
- * public app URL, and `ref` is authored stable identity. They are mutually
- * exclusive at the type level.
- */
 type ContentSelector = {
     path: string;
     route?: never;
@@ -1194,10 +908,6 @@ type ContentSelector = {
 };
 type WhereValue<T> = T | QueryOperators<T>;
 type PathWhere = string | QueryOperators<string>;
-/**
- * MongoDB-style filter object generic on the document shape. `where.path` is a
- * documented route-path filter and compiles to the internal `_path` field.
- */
 type QueryWhere<T = ParsedContentMeta> = {
     path?: PathWhere;
     $and?: QueryWhere<T>[];
@@ -1206,42 +916,23 @@ type QueryWhere<T = ParsedContentMeta> = {
 } & {
     [K in Exclude<keyof T, 'path'>]?: WhereValue<NonNullable<T[K]>>;
 };
-/**
- * Sort spec: `asc` / `desc` are preferred; `1` / `-1` remain accepted because
- * they map directly to the transport shape.
- */
 type SortDirection = 'asc' | 'desc' | 1 | -1;
 type SortSpec<T = ParsedContentMeta> = string extends keyof T ? {
     [key: string]: SortDirection | undefined;
 } : {
     [K in keyof T]?: SortDirection;
 };
-/**
- * Schema of a collection handle (recovered from its `__schema` phantom).
- *
- * Uses `StrictParsedContentMeta` (no `[key: string]: unknown` index signature)
- * as the base so `keyof HandleSchema<H>` is a finite union of the user's
- * declared schema fields plus the internal `_*` meta fields. This is what
- * makes `QueryWhere<HandleSchema<H>>` reject typo'd field names at compile time.
- */
 type HandleSchema<H> = H extends {
     __schema: infer S;
 } ? S extends {
     _output: infer O;
 } ? O & StrictParsedContentMeta : StrictParsedContentMeta : H extends ContentCollectionName ? ContentCollectionMap[H] & StrictParsedContentMeta : StrictParsedContentMeta;
 type SelectFields<H> = string extends H ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof HandleSchema<H>, string>>;
-/**
- * Runtime document shape inferred from a collection handle.
- */
 type DocumentFromHandle<H> = H extends {
     __schema: {
         _output: infer O;
     };
 } ? O & StrictParsedContent : H extends ContentCollectionName ? ContentCollectionMap[H] : ParsedContent;
-/**
- * Explicit reference population map. Keys are fields on the source document;
- * values are target collection handles.
- */
 type PopulateSpec = Record<string, ContentCollectionTarget>;
 type PopulatedDocument<T, P> = P extends undefined ? T : P extends PopulateSpec ? string extends keyof P ? T : Omit<T, keyof P> & {
     [K in keyof P & keyof T]: T[K] extends ReadonlyArray<unknown> ? Array<LocalizedDoc<DocumentFromHandle<P[K]>>> : LocalizedDoc<DocumentFromHandle<P[K]>> | null;
@@ -1252,15 +943,9 @@ type PopulateFromOptions<O> = O extends {
 type PopulateOption<P extends PopulateSpec | undefined = undefined> = {
     populate?: P;
 };
-/**
- * Whether a collection handle declares i18n at the type level.
- */
 type HandleIsI18n<H> = H extends {
     __i18n: infer I;
-} ? I extends true ? true : false : H extends keyof GinkoContentCollectionI18nMap ? true : false;
-/**
- * Locale option made required when the handle is i18n.
- */
+} ? I extends true ? true : false : H extends keyof ContentCollectionI18nMap ? true : false;
 type LocaleOption<H, OptKey extends string = 'locale'> = HandleIsI18n<H> extends true ? {
     [K in OptKey]: string;
 } : {
@@ -1275,24 +960,15 @@ type BacklinksLocaleOption<Target, Source> = HandleIsI18n<Target> extends true ?
     locale?: string;
 };
 type LocaleFallback = false | true | 'default' | string | string[];
-/**
- * Document shape returned from `one`, `many` and `resolveOne`. Every doc carries the
- * route metadata (`path`, `localePaths`, `locale`, ...) the route resolver
- * already produces, so locale switching needs no extra round trip.
- */
-type LocalizedDoc<T = ParsedContentMeta> = T & ContentRouteMeta & {
-    /**
-     * Locale-agnostic path stem derived from the source file.
-     */
+type LocalizedContentDocument<T = ParsedContentMeta> = T & ContentRouteMeta & {
+    locale: string;
+    path: string;
+    canonicalPath: string;
+    localePaths: Record<string, LocalePathEntry>;
     stem?: string;
-    /**
-     * Source file extension when it can be inferred.
-     */
     extension?: string;
 };
-/**
- * Explain how `resolveOne` interpreted the request and what it matched.
- */
+type LocalizedDoc<T = ParsedContentMeta> = LocalizedContentDocument<T>;
 interface ResolutionEnvelope {
     requested: {
         collection: string;
@@ -1316,25 +992,16 @@ interface ResolutionEnvelope {
         locale?: string;
     };
 }
-/**
- * Result returned by `resolveOne`.
- */
 interface ResolveOneResult<T = ParsedContentMeta> {
     doc: LocalizedDoc<T> | null;
     explain: ResolutionEnvelope;
 }
-/**
- * Options accepted by `resolveOne(handle, options)` and `one(handle, options)`.
- */
 type ResolveOneOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = {
     by: ContentSelector;
     fallback?: LocaleFallback;
     select?: SelectFields<H>;
 } & LocaleOption<H> & PopulateOption<P>;
 type OneOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = ResolveOneOptions<H, P>;
-/**
- * Options accepted by `many(handle, options)`.
- */
 type ManyOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = {
     where?: QueryWhere<HandleSchema<H>>;
     sort?: SortSpec<HandleSchema<H>>;
@@ -1343,26 +1010,10 @@ type ManyOptions<H = unknown, P extends PopulateSpec | undefined = undefined> =
     fallback?: LocaleFallback;
     select?: SelectFields<H>;
 } & LocaleOption<H> & PopulateOption<P>;
-/**
- * Options accepted by `paginate(handle, options)`.
- */
 type PaginationOptions<H = unknown, P extends PopulateSpec | undefined = undefined> = Omit<ManyOptions<H, P>, 'skip' | 'limit'> & {
-    /**
-     * One-based page number.
-     *
-     * @default 1
-     */
     page?: number;
-    /**
-     * Number of documents per page.
-     *
-     * @default 10
-     */
     limit?: number;
 };
-/**
- * Result returned by `paginate()` and `useContentPagination()`.
- */
 interface PaginationResult<T = ParsedContentMeta> {
     data: Array<LocalizedDoc<T>>;
     page: number;
@@ -1380,22 +1031,9 @@ type SourceName<S> = S extends string ? S : S extends {
 } ? Extract<N, string> : string;
 type BacklinkFields<S = BacklinkSource | ReadonlyArray<BacklinkSource>> = ReadonlyArray<string> | Partial<Record<SourceName<S extends ReadonlyArray<infer I> ? I : S>, ReadonlyArray<string>>>;
 type DocumentFromSource<S> = S extends ReadonlyArray<infer I> ? DocumentFromHandle<I> : DocumentFromHandle<S>;
-/**
- * Options accepted by `backlinks(targetHandle, options)`.
- */
 type BacklinksOptions<Target = unknown, Source extends BacklinkSource | ReadonlyArray<BacklinkSource> = BacklinkSource | ReadonlyArray<BacklinkSource>, P extends PopulateSpec | undefined = undefined> = {
-    /**
-     * Target document to find incoming references for.
-     */
     by: ContentSelector;
-    /**
-     * Source collection handle(s) to scan for references.
-     */
     from: Source;
-    /**
-     * Explicit reference fields on the source collection(s). When omitted,
-     * fields are inferred from source handles that use `reference()`.
-     */
     fields?: BacklinkFields<Source>;
     sort?: SortSpec<DocumentFromSource<Source>>;
     limit?: number;
@@ -1404,38 +1042,23 @@ type BacklinksOptions<Target = unknown, Source extends BacklinkSource | Readonly
     select?: string extends Source ? ReadonlyArray<string> : ReadonlyArray<Extract<keyof DocumentFromSource<Source>, string>>;
 } & BacklinksLocaleOption<Target, Source> & PopulateOption<P>;
 type BacklinksResult<Source extends BacklinkSource | ReadonlyArray<BacklinkSource> = BacklinkSource | ReadonlyArray<BacklinkSource>, P extends PopulateSpec | undefined = undefined> = Array<LocalizedDoc<PopulatedDocument<DocumentFromSource<Source>, P>>>;
-/**
- * Options accepted by `variants(handle, options)`.
- */
 type VariantsOptions<H = unknown> = {
     by: ContentSelector;
-    /**
-     * Restrict to a subset of locales. Defaults to all configured locales.
-     */
     locales?: string[];
 } & LocaleOption<H>;
-/**
- * Variant entry returned by `variants()` and `useContentVariants()`.
- */
 interface ContentVariant<_T = ParsedContentMeta> {
     locale: string;
     path: string;
     translated: boolean;
     fallback?: string;
 }
-/**
- * Options accepted by `tree(handle, options)`.
- */
 type TreeOptions<H = unknown, Fields extends ReadonlyArray<keyof HandleSchema<H> | string> | undefined = undefined> = {
     where?: QueryWhere<HandleSchema<H>>;
     sort?: SortSpec<HandleSchema<H>>;
     fields?: Fields;
     fallback?: LocaleFallback;
-} & LocaleOption<H>;
-/**
- * Typed navigation item. Requested `fields` are preserved in the return type
- * without keeping the old open index signature.
- */
+    locale?: string;
+};
 type ContentTreeItem<T = ParsedContentMeta, Fields extends ReadonlyArray<keyof T | string> | undefined = undefined> = {
     title: string;
     path: string;
@@ -1443,20 +1066,11 @@ type ContentTreeItem<T = ParsedContentMeta, Fields extends ReadonlyArray<keyof T
     children?: Array<ContentTreeItem<T, Fields>>;
 } & (Fields extends ReadonlyArray<infer K> ? Pick<T, Extract<K, keyof T>> : Record<never, never>);
 
-/**
- * Options accepted by `neighbors(handle, options)`.
- *
- * Identifying the anchor document lives in `filter`, same as every other
- * verb. Only the reserved selectors `path` and `ref` are accepted.
- */
 type NeighborsOptions<H = unknown> = {
     by: ContentSelector;
     fallback?: LocaleFallback;
     fields?: SelectFields<H>;
 } & LocaleOption<H>;
-/**
- * Result of `neighbors()` and `useContentNeighbors()`.
- */
 interface NeighborsResult<T = ParsedContentMeta> {
     prev: ContentTreeItem<T> | null;
     next: ContentTreeItem<T> | null;
@@ -1791,6 +1405,12 @@ interface ContentRevalidateOptions {
      */
     allowUnsigned?: boolean;
 }
+interface ContentAgentRouteOptions {
+    routes?: boolean;
+    linkHeaders?: boolean;
+    markdownNegotiation?: boolean;
+    prerender?: boolean;
+}
 interface ModuleOptions {
     api: {
         /**
@@ -1834,6 +1454,10 @@ interface ModuleOptions {
      * `x-ginko-revalidate-token` or `authorization: Bearer <token>`.
      */
     revalidate?: false | ContentRevalidateOptions;
+    /**
+     * First-class agent markdown and LLM route features.
+     */
+    agent?: false | ContentAgentRouteOptions;
     /**
      * Optional server-side cache adapter module.
      *
@@ -1847,9 +1471,7 @@ interface ModuleOptions {
      *
      * @default true
      */
-    watch: false | {
-        ws: Partial<ListenOptions>;
-    };
+    watch: boolean;
     /**
      * Contents can be located in multiple places, in multiple directories or even in remote git repositories.
      * Using sources option you can tell Content module where to look for contents.
@@ -1985,6 +1607,9 @@ interface ContentContext extends ModuleOptions {
     translatedSlugs: boolean;
     strictTranslatedSlugs: boolean;
 }
+type ResolvedContentContext = Omit<ContentContext, 'markdown'> & {
+    markdown: MarkdownOptions;
+};
 
 interface ContentCacheArtifact<T = ParsedContent> {
     parsed: T;
@@ -2013,7 +1638,7 @@ interface ParseContentOptions {
     validate?: boolean;
     csv?: ModuleOptions['csv'];
     yaml?: ModuleOptions['yaml'];
-    markdown?: ModuleOptions['markdown'];
+    markdown?: ModuleOptions['markdown'] | MarkdownOptions;
     transformers?: ContentTransformer[];
     pathMeta?: {
         locales?: ContentContext['locales'];
@@ -2029,12 +1654,6 @@ type TransformContentSource = string | StorageValue;
 
 declare function createSearchRuntimeConfig(search: Exclude<ModuleOptions$1['search'], false>, apiBaseURL: string): ContentSearchPublicRuntimeConfig$1;
 
-declare const _default: _nuxt_schema.NuxtModule<ModuleOptions$1, ModuleOptions$1, false>;
-
-interface ModuleHooks {
-    'content:providers'(providers: Record<string, string>): void | Promise<void>;
-    'content:context'(ctx: ContentContext$1): void | Promise<void>;
-}
 interface ModulePublicRuntimeConfig {
     experimental: {
         stripQueryParameters: boolean;
@@ -2065,7 +1684,6 @@ interface ModulePublicRuntimeConfig {
     translatedSlugs: ContentContext$1['translatedSlugs'];
     strictTranslatedSlugs: ContentContext$1['strictTranslatedSlugs'];
     markdown: MarkdownOptions$1;
-    wsUrl?: string;
     navigation: ModuleOptions$1['navigation'];
     search: ReturnType<typeof createSearchRuntimeConfig> | false;
     contentHead: ModuleOptions$1['contentHead'];
@@ -2100,5 +1718,12 @@ declare module 'nitropack' {
     }
 }
 
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions$1, ModuleOptions$1, false>;
+
+interface ModuleHooks {
+    'content:providers'(providers: Record<string, string>): void | Promise<void>;
+    'content:context'(ctx: ContentContext$1): void | Promise<void>;
+}
+
 export { _default as default, normalizeContentConfigCollectionNames };
-export type { BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, CollectionQueryBuilder, CollectionQueryOperator, CollectionQueryValue, CollectionSchema, ContentCacheArtifact, ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionHandle, ContentCollectionI18nConfig, ContentCollectionI18nMap, ContentCollectionItem, ContentCollectionItemSurroundingsOptions, ContentCollectionKind, ContentCollectionMap, ContentCollectionName, ContentCollectionNavigationOptions, ContentCollectionPageOptions, ContentCollectionRouteConfig, ContentCollectionRouteMetaOptions, ContentCollectionSearchSectionsOptions, ContentCollectionSource, ContentCollectionSourceObject, ContentCollectionStringName, ContentCollectionTarget, ContentConfig, ContentContext, ContentI18nOptions, ContentLocaleEntry, ContentLocaleRoute, ContentManifest, ContentMiniSearchOptions, ContentNavigationItem, ContentPageResult, ContentPreviewOptions, ContentProviderName, ContentProviderSearchRequest, ContentQueryBuilder, ContentQueryBuilderParams, ContentQueryBuilderWhere, ContentQueryFetcher, ContentQueryRequest, ContentQuerySortFields, ContentQuerySortOptions, ContentQuerySortParams, ContentReferenceSchema, ContentResolvedMeta, ContentRevalidateOptions, ContentRouteMeta, ContentSearchEngine, ContentSearchIndexRecord, ContentSearchOptions, ContentSearchPublicRuntimeConfig, ContentSearchResult, ContentSearchSection, ContentSelector, ContentSeoImage, ContentSeoMeta, ContentSitemapAlternative, ContentSitemapAssertOptions, ContentSitemapAssertSitemapOptions, ContentSitemapEntry, ContentSitemapImage, ContentSitemapOptions, ContentTransformer, ContentTreeItem, ContentVariant, DefineCollectionObject, DefineCollectionOptions, DocumentFromHandle, LocaleFallback, LocalePathEntry, LocalizedDoc, ManifestVariant, ManyOptions, MarkdownNode, MarkdownOptions, MarkdownParsedContent, MarkdownPluginDescriptor, MarkdownPluginOptions, MarkdownRoot, ModuleHooks, ModuleOptions, MountOptions, NavItem, NeighborsOptions, NeighborsResult, OneOptions, PaginationOptions, PaginationResult, ParseContentOptions, ParsedContent, ParsedContentInternalMeta, ParsedContentMeta, PopulateFromOptions, PopulateSpec, PopulatedDocument, QueryGroupBuilder, QueryGroupFunction, QueryMatchOperator, QueryOperators, QueryOrderDirection, QueryOrderOptions, QueryWhere, ResolutionEnvelope, ResolveContentReferenceOptions, ResolveOneOptions, ResolveOneResult, ResolvedContentI18nOptions, ResolvedMarkdownPlugin, ResolvedVariant, SortDirection, SortSpec, StrictParsedContent, StrictParsedContentMeta, Toc, TocLink, TransformContentOptions, TransformContentSource, TreeOptions, VariantsOptions };
+export type { AgentMetadataField, AgentMetadataFieldList, BacklinkFields, BacklinkSource, BacklinksOptions, BacklinksResult, CollectionQueryBuilder, CollectionQueryField, CollectionQueryFieldValue, CollectionQueryKey, CollectionQueryOperator, CollectionQueryValue, CollectionSchema, ContentAgentAppPageConfig, ContentAgentAppPageContext, ContentAgentCollectionConfig, ContentAgentConfig, ContentAgentLocalizedValue, ContentAgentMarkdownMetadataConfig, ContentAgentMarkdownOptions, ContentAgentMarkdownPolicyConfig, ContentAgentRouteOptions, ContentAgentSectionConfig, ContentAgentSiteConfig, ContentCacheArtifact, ContentCmsCollectionConfig, ContentCmsFieldConfig, ContentCmsFieldType, ContentCmsRelationConfig, ContentCollectionConfig, ContentCollectionHandle, ContentCollectionI18nConfig, ContentCollectionI18nMap, ContentCollectionItem, ContentCollectionItemSurroundingsOptions, ContentCollectionKind, ContentCollectionMap, ContentCollectionName, ContentCollectionNavigationOptions, ContentCollectionPageOptions, ContentCollectionRouteConfig, ContentCollectionRouteMetaOptions, ContentCollectionSearchSectionsOptions, ContentCollectionSource, ContentCollectionSourceObject, ContentCollectionStringName, ContentCollectionTarget, ContentConfig, ContentContext, ContentI18nOptions, ContentLocaleEntry, ContentLocaleRoute, ContentManifest, ContentMiniSearchOptions, ContentNavigationItem, ContentPageResult, ContentPreviewOptions, ContentProviderName, ContentProviderSearchRequest, ContentQueryBuilder, ContentQueryBuilderParams, ContentQueryBuilderWhere, ContentQueryFetcher, ContentQueryRequest, ContentQuerySortFields, ContentQuerySortOptions, ContentQuerySortParams, ContentReferenceSchema, ContentResolvedMeta, ContentRevalidateOptions, ContentRouteMeta, ContentSearchEngine, ContentSearchIndexRecord, ContentSearchOptions, ContentSearchPublicRuntimeConfig, ContentSearchResult, ContentSearchSection, ContentSelector, ContentSeoImage, ContentSeoMeta, ContentSitemapAlternative, ContentSitemapAssertOptions, ContentSitemapAssertSitemapOptions, ContentSitemapEntry, ContentSitemapImage, ContentSitemapOptions, ContentTransformer, ContentTreeItem, ContentVariant, DefineCollectionObject, DefineCollectionOptions, DocumentFromHandle, LocaleFallback, LocalePathEntry, LocalizedContentDocument, LocalizedDoc, ManifestVariant, ManyOptions, MarkdownNode, MarkdownOptions, MarkdownParsedContent, MarkdownPluginDescriptor, MarkdownPluginOptions, MarkdownRoot, ModuleHooks, ModuleOptions, MountOptions, NavItem, NeighborsOptions, NeighborsResult, OneOptions, PaginationOptions, PaginationResult, ParseContentOptions, ParsedContent, ParsedContentInternalMeta, ParsedContentMeta, PopulateFromOptions, PopulateSpec, PopulatedDocument, QueryGroupBuilder, QueryGroupFunction, QueryMatchOperator, QueryOperators, QueryOrderDirection, QueryOrderOptions, QueryWhere, ResolutionEnvelope, ResolveContentReferenceOptions, ResolveOneOptions, ResolveOneResult, ResolvedContentContext, ResolvedContentI18nOptions, ResolvedMarkdownPlugin, ResolvedVariant, SortDirection, SortSpec, StrictParsedContent, StrictParsedContentMeta, Toc, TocLink, TransformContentOptions, TransformContentSource, TreeOptions, VariantsOptions };