@agentskit/doc-bridge 0.1.0-alpha.3 → 1.0.0

package/dist/index.d.ts

@@ -25,6 +25,20 @@ declare const HandoffTargetSchema: z.ZodObject<{
     layer?: string | undefined;
 }>;
 type HandoffTarget = z.infer<typeof HandoffTargetSchema>;
+declare const HandoffBridgeSchema: z.ZodObject<{
+    humanDoc: z.ZodEnum<["linked", "missing", "external"]>;
+    action: z.ZodOptional<z.ZodString>;
+    bootstrap: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    humanDoc: "linked" | "missing" | "external";
+    action?: string | undefined;
+    bootstrap?: string | undefined;
+}, {
+    humanDoc: "linked" | "missing" | "external";
+    action?: string | undefined;
+    bootstrap?: string | undefined;
+}>;
+type HandoffBridge = z.infer<typeof HandoffBridgeSchema>;
 /** v1 — canonical AgentHandoff. Legacy payloads may omit schemaVersion. */
 declare const AgentHandoffV1Schema: z.ZodObject<{
     type: z.ZodLiteral<"agent-handoff">;
@@ -54,6 +68,19 @@ declare const AgentHandoffV1Schema: z.ZodObject<{
     editRoots: z.ZodArray<z.ZodString, "many">;
     checks: z.ZodArray<z.ZodString, "many">;
     humanDoc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bridge: z.ZodOptional<z.ZodObject<{
+        humanDoc: z.ZodEnum<["linked", "missing", "external"]>;
+        action: z.ZodOptional<z.ZodString>;
+        bootstrap: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    }, {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    }>>;
     playbookPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     notes: z.ZodArray<z.ZodString, "many">;
 }, "strict", z.ZodTypeAny, {
@@ -73,6 +100,11 @@ declare const AgentHandoffV1Schema: z.ZodObject<{
     editRoots: string[];
     notes: string[];
     humanDoc?: string | null | undefined;
+    bridge?: {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    } | undefined;
     playbookPatterns?: string[] | undefined;
 }, {
     type: "agent-handoff";
@@ -91,6 +123,11 @@ declare const AgentHandoffV1Schema: z.ZodObject<{
     notes: string[];
     humanDoc?: string | null | undefined;
     schemaVersion?: 1 | undefined;
+    bridge?: {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    } | undefined;
     playbookPatterns?: string[] | undefined;
 }>;
 type AgentHandoffV1 = z.infer<typeof AgentHandoffV1Schema>;
@@ -123,6 +160,19 @@ declare const AgentHandoffLegacySchema: z.ZodObject<Omit<{
     editRoots: z.ZodArray<z.ZodString, "many">;
     checks: z.ZodArray<z.ZodString, "many">;
     humanDoc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bridge: z.ZodOptional<z.ZodObject<{
+        humanDoc: z.ZodEnum<["linked", "missing", "external"]>;
+        action: z.ZodOptional<z.ZodString>;
+        bootstrap: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    }, {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    }>>;
     playbookPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     notes: z.ZodArray<z.ZodString, "many">;
 }, "schemaVersion"> & {
@@ -144,6 +194,11 @@ declare const AgentHandoffLegacySchema: z.ZodObject<Omit<{
     notes: string[];
     humanDoc?: string | null | undefined;
     schemaVersion?: 1 | undefined;
+    bridge?: {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    } | undefined;
     playbookPatterns?: string[] | undefined;
 }, {
     type: "agent-handoff";
@@ -162,6 +217,11 @@ declare const AgentHandoffLegacySchema: z.ZodObject<Omit<{
     notes: string[];
     humanDoc?: string | null | undefined;
     schemaVersion?: 1 | undefined;
+    bridge?: {
+        humanDoc: "linked" | "missing" | "external";
+        action?: string | undefined;
+        bootstrap?: string | undefined;
+    } | undefined;
     playbookPatterns?: string[] | undefined;
 }>;
 declare const AgentSearchV1Schema: z.ZodObject<{
@@ -396,6 +456,19 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         editRoots: z.ZodArray<z.ZodString, "many">;
         checks: z.ZodArray<z.ZodString, "many">;
         humanDoc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        bridge: z.ZodOptional<z.ZodObject<{
+            humanDoc: z.ZodEnum<["linked", "missing", "external"]>;
+            action: z.ZodOptional<z.ZodString>;
+            bootstrap: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            humanDoc: "linked" | "missing" | "external";
+            action?: string | undefined;
+            bootstrap?: string | undefined;
+        }, {
+            humanDoc: "linked" | "missing" | "external";
+            action?: string | undefined;
+            bootstrap?: string | undefined;
+        }>>;
         playbookPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         notes: z.ZodArray<z.ZodString, "many">;
     }, "schemaVersion"> & {
@@ -417,6 +490,11 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         notes: string[];
         humanDoc?: string | null | undefined;
         schemaVersion?: 1 | undefined;
+        bridge?: {
+            humanDoc: "linked" | "missing" | "external";
+            action?: string | undefined;
+            bootstrap?: string | undefined;
+        } | undefined;
         playbookPatterns?: string[] | undefined;
     }, {
         type: "agent-handoff";
@@ -435,6 +513,11 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         notes: string[];
         humanDoc?: string | null | undefined;
         schemaVersion?: 1 | undefined;
+        bridge?: {
+            humanDoc: "linked" | "missing" | "external";
+            action?: string | undefined;
+            bootstrap?: string | undefined;
+        } | undefined;
         playbookPatterns?: string[] | undefined;
     }>>>;
     lookup: z.ZodOptional<z.ZodObject<{
@@ -595,6 +678,11 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         notes: string[];
         humanDoc?: string | null | undefined;
         schemaVersion?: 1 | undefined;
+        bridge?: {
+            humanDoc: "linked" | "missing" | "external";
+            action?: string | undefined;
+            bootstrap?: string | undefined;
+        } | undefined;
         playbookPatterns?: string[] | undefined;
     }> | undefined;
     lookup?: {
@@ -669,6 +757,11 @@ declare const DocBridgeIndexV1Schema: z.ZodObject<{
         notes: string[];
         humanDoc?: string | null | undefined;
         schemaVersion?: 1 | undefined;
+        bridge?: {
+            humanDoc: "linked" | "missing" | "external";
+            action?: string | undefined;
+            bootstrap?: string | undefined;
+        } | undefined;
         playbookPatterns?: string[] | undefined;
     }> | undefined;
     lookup?: {
@@ -1441,6 +1534,124 @@ declare const MCP_TOOLS: readonly [{
 declare const handleMcpRequest: (ctx: McpContext, request: JsonRpcRequest) => unknown;
 declare const startMcpStdioServer: (ctx: McpContext) => void;
 
+type McpInstallTarget = 'cursor' | 'claude';
+type McpInstallResult = {
+    readonly ok: boolean;
+    readonly target: McpInstallTarget;
+    readonly configPath: string;
+    readonly created: boolean;
+    readonly serverName: string;
+    readonly nextSteps: readonly string[];
+};
+declare const installMcpConfig: (root: string, target: McpInstallTarget) => McpInstallResult;
+declare const mcpSnippet: (root: string) => string;
+
+type DoctorBadgeMetrics = {
+    readonly handoffPct: number;
+    readonly bridgePct: number;
+    readonly score: number;
+    readonly grade: DoctorReport['grade'];
+    readonly packages: number;
+};
+declare const doctorBadgeMetrics: (report: DoctorReport) => DoctorBadgeMetrics;
+declare const formatDoctorBadgeMarkdown: (metrics: DoctorBadgeMetrics) => string;
+declare const formatDoctorBadgeJson: (metrics: DoctorBadgeMetrics) => string;
+
+type DoctorIssue = {
+    readonly severity: 'error' | 'warn' | 'info';
+    readonly code: string;
+    readonly message: string;
+    readonly action?: string;
+};
+type DoctorCoverage = {
+    readonly packages: {
+        readonly total: number;
+        readonly withAgentDoc: number;
+        readonly withHumanDoc: number;
+        readonly missingAgentDoc: readonly string[];
+        readonly missingHumanDoc: readonly string[];
+    };
+    readonly agentDocs: {
+        readonly total: number;
+        readonly indexed: number;
+        readonly unindexed: readonly string[];
+    };
+    readonly freshness: {
+        readonly ok: boolean;
+        readonly message: string;
+        readonly hasIndex: boolean;
+    };
+    readonly gates: GateRunResult;
+};
+type DoctorReport = {
+    readonly ok: boolean;
+    readonly score: number;
+    readonly grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    readonly coverage: DoctorCoverage;
+    readonly badge: DoctorBadgeMetrics;
+    readonly issues: readonly DoctorIssue[];
+    readonly nextActions: readonly string[];
+};
+declare const runDoctor: (root: string, config: DocBridgeConfigV1) => DoctorReport;
+declare const formatDoctorText: (report: DoctorReport) => string[];
+
+type WatchIndexOptions = {
+    readonly root: string;
+    readonly config: DocBridgeConfigV1;
+    readonly configPath?: string;
+    readonly debounceMs?: number;
+    readonly onRebuild?: (summary: {
+        knowledgeCount: number;
+        handoffCount: number;
+        hash: string;
+    }) => void;
+};
+declare const watchDocBridgeIndex: (opts: WatchIndexOptions) => Promise<number>;
+
+type MemoryRoute = 'agent' | 'human' | 'playbook' | 'discard';
+type MemoryClassification = {
+    readonly candidate: MemoryCandidateV1;
+    readonly route: MemoryRoute;
+    readonly reason: string;
+    readonly target?: string;
+    readonly duplicateOf?: string;
+};
+type SafetyFinding = {
+    readonly candidateId: string;
+    readonly kind: 'secret' | 'private-email';
+    readonly message: string;
+};
+type MemoryPromotionDraft = {
+    readonly ok: boolean;
+    readonly title: string;
+    readonly body: string;
+    readonly findings: SafetyFinding[];
+    readonly classifications: MemoryClassification[];
+};
+declare const classifyMemoryCandidates: (candidates: readonly MemoryCandidateV1[], index: DocBridgeIndexV1) => MemoryClassification[];
+declare const scanMemorySafety: (classifications: readonly MemoryClassification[]) => SafetyFinding[];
+declare const draftMemoryPromotion: (classifications: readonly MemoryClassification[]) => MemoryPromotionDraft;
+
+type GithubPrOptions = {
+    readonly dryRun?: boolean;
+    readonly force?: boolean;
+    readonly branch?: string;
+    readonly base?: string;
+};
+type GithubPrResult = {
+    readonly ok: boolean;
+    readonly dryRun: boolean;
+    readonly draftPath: string;
+    readonly branch: string;
+    readonly prUrl?: string;
+    readonly previewUrl?: string;
+    readonly commands: readonly string[];
+    readonly message: string;
+};
+declare const defaultPromotionDraftPath: (root: string) => string;
+declare const writePromotionDraft: (root: string, draft: MemoryPromotionDraft, path?: string) => string;
+declare const promoteMemoryToGithubPr: (root: string, draft: MemoryPromotionDraft, options?: GithubPrOptions) => GithubPrResult;
+
 declare const sha256NormalizedV1: (payload: unknown) => string;
 
 declare class IndexNotFoundError extends Error {
@@ -1477,30 +1688,6 @@ declare const ingestCursorRules: (root: string) => MemoryCandidateV1[];
 declare const ingestAgentMemory: (root: string) => MemoryCandidateV1[];
 declare const ingestMemoryCandidates: (root: string) => MemoryCandidateV1[];
 
-type MemoryRoute = 'agent' | 'human' | 'playbook' | 'discard';
-type MemoryClassification = {
-    readonly candidate: MemoryCandidateV1;
-    readonly route: MemoryRoute;
-    readonly reason: string;
-    readonly target?: string;
-    readonly duplicateOf?: string;
-};
-type SafetyFinding = {
-    readonly candidateId: string;
-    readonly kind: 'secret' | 'private-email';
-    readonly message: string;
-};
-type MemoryPromotionDraft = {
-    readonly ok: boolean;
-    readonly title: string;
-    readonly body: string;
-    readonly findings: SafetyFinding[];
-    readonly classifications: MemoryClassification[];
-};
-declare const classifyMemoryCandidates: (candidates: readonly MemoryCandidateV1[], index: DocBridgeIndexV1) => MemoryClassification[];
-declare const scanMemorySafety: (classifications: readonly MemoryClassification[]) => SafetyFinding[];
-declare const draftMemoryPromotion: (classifications: readonly MemoryClassification[]) => MemoryPromotionDraft;
-
 type DocBridgeRetrieverOptions = {
     readonly property?: string;
     readonly limit?: number;
@@ -1535,7 +1722,7 @@ declare const chunksFromMarkdown: (property: string, raw: string, sourceUrl: str
 declare const loadFederatedChunks: (root: string, config: DocBridgeConfigV1, options?: FederatedRetrieverOptions) => Promise<DocBridgeRetrievedChunk[]>;
 declare const retrieveHybridChunks: (root: string, config: DocBridgeConfigV1, index: DocBridgeIndexV1, query: string, options?: FederatedRetrieverOptions) => Promise<DocBridgeRetrievedChunk[]>;
 
-declare const PACKAGE_VERSION = "0.1.0-alpha.3";
+declare const PACKAGE_VERSION = "1.0.0";
 
 type FrontmatterValue = string | boolean | readonly string[];
 type FrontmatterData = Record<string, FrontmatterValue>;
@@ -1624,4 +1811,29 @@ declare class PeerMissingError extends Error {
 }
 declare const layer1InstallHint: () => string;
 
-export { AgentHandoffLegacySchema, type AgentHandoffV1, AgentHandoffV1JsonSchema, AgentHandoffV1Schema, type AgentSearchV1, AgentSearchV1Schema, type BuildIndexOptions, type BuildIndexResult, DocBridgeConfigV1, type DocBridgeIndexV1, DocBridgeIndexV1JsonSchema, DocBridgeIndexV1Schema, DocBridgeJsonSchemas, type DocBridgeRetrievedChunk, type DocBridgeRetriever, type DocBridgeRetrieverOptions, type FederatedRetrieverOptions, type FetchText, type GateId, type GateResult, type GateRunResult, HANDOFF_SCHEMA_VERSION, type HandoffTarget, type HandoffTargetType, HandoffTargetTypeSchema, type HumanDocMap, type HumanDocRecord, INDEX_SCHEMA_VERSION, IndexNotFoundError, type KnowledgeEntry, KnowledgeEntrySchema, MCP_TOOLS, MEMORY_CANDIDATE_SCHEMA_VERSION, type MemoryCandidateV1, MemoryCandidateV1JsonSchema, MemoryCandidateV1Schema, type MemoryClassification, type MemoryPromotionDraft, type MemoryRoute, PACKAGE_VERSION, type ParseIssue, type ParseResult, PeerMissingError, type QueryKind, type QueryRequest, type QueryResult, type SafetyFinding, type SearchMatch, buildDocBridgeIndex, buildLookup, chunksFromMarkdown, classifyMemoryCandidates, collectPackages, createDocBridgeRag, createDocBridgeRetriever, draftMemoryPromotion, handleMcpRequest, indexFilePath, ingestAgentMemory, ingestCursorRules, ingestMemoryCandidates, layer1InstallHint, loadDocBridgeIndex, loadFederatedChunks, normalizeAgentHandoff, parseAgentHandoff, parseAgentSearch, parseDocBridgeConfig, parseDocBridgeIndex, parseLlmsTxtLinks, parseMemoryCandidate, resolveGateIds, resolveRoot, retrieveDocBridgeChunks, retrieveHybridChunks, runChatOnce, runGate, runGates, runQuery, safeParseAgentHandoff, scanHumanDocRecords, scanHumanDocs, scanMemorySafety, searchIndex, sha256NormalizedV1, startInkChat, startMcpStdioServer };
+declare const DOC_BRIDGE_PATTERN_ID: "doc-bridge-pattern";
+declare const DOC_BRIDGE_PATTERN_META: {
+    readonly id: "doc-bridge-pattern";
+    readonly title: "Doc Bridge Pattern";
+    readonly slug: "pillars/ai-collaboration/doc-bridge-pattern";
+    readonly license: "CC-BY-4.0";
+    readonly visibility: "public";
+    readonly playbookUrl: "https://playbook.agentskit.io/patterns/doc-bridge-pattern";
+    readonly npmPackage: "@agentskit/doc-bridge";
+    readonly cli: "ak-docs";
+};
+declare const docBridgePatternMarkdown: () => string;
+declare const docBridgePatternPayload: () => {
+    format: string;
+    body: string;
+    id: "doc-bridge-pattern";
+    title: "Doc Bridge Pattern";
+    slug: "pillars/ai-collaboration/doc-bridge-pattern";
+    license: "CC-BY-4.0";
+    visibility: "public";
+    playbookUrl: "https://playbook.agentskit.io/patterns/doc-bridge-pattern";
+    npmPackage: "@agentskit/doc-bridge";
+    cli: "ak-docs";
+};
+
+export { AgentHandoffLegacySchema, type AgentHandoffV1, AgentHandoffV1JsonSchema, AgentHandoffV1Schema, type AgentSearchV1, AgentSearchV1Schema, type BuildIndexOptions, type BuildIndexResult, DOC_BRIDGE_PATTERN_ID, DOC_BRIDGE_PATTERN_META, DocBridgeConfigV1, type DocBridgeIndexV1, DocBridgeIndexV1JsonSchema, DocBridgeIndexV1Schema, DocBridgeJsonSchemas, type DocBridgeRetrievedChunk, type DocBridgeRetriever, type DocBridgeRetrieverOptions, type DoctorBadgeMetrics, type DoctorCoverage, type DoctorIssue, type DoctorReport, type FederatedRetrieverOptions, type FetchText, type GateId, type GateResult, type GateRunResult, type GithubPrOptions, type GithubPrResult, HANDOFF_SCHEMA_VERSION, type HandoffBridge, HandoffBridgeSchema, type HandoffTarget, type HandoffTargetType, HandoffTargetTypeSchema, type HumanDocMap, type HumanDocRecord, INDEX_SCHEMA_VERSION, IndexNotFoundError, type KnowledgeEntry, KnowledgeEntrySchema, MCP_TOOLS, MEMORY_CANDIDATE_SCHEMA_VERSION, type McpInstallResult, type McpInstallTarget, type MemoryCandidateV1, MemoryCandidateV1JsonSchema, MemoryCandidateV1Schema, type MemoryClassification, type MemoryPromotionDraft, type MemoryRoute, PACKAGE_VERSION, type ParseIssue, type ParseResult, PeerMissingError, type QueryKind, type QueryRequest, type QueryResult, type SafetyFinding, type SearchMatch, type WatchIndexOptions, buildDocBridgeIndex, buildLookup, chunksFromMarkdown, classifyMemoryCandidates, collectPackages, createDocBridgeRag, createDocBridgeRetriever, defaultPromotionDraftPath, docBridgePatternMarkdown, docBridgePatternPayload, doctorBadgeMetrics, draftMemoryPromotion, formatDoctorBadgeJson, formatDoctorBadgeMarkdown, formatDoctorText, handleMcpRequest, indexFilePath, ingestAgentMemory, ingestCursorRules, ingestMemoryCandidates, installMcpConfig, layer1InstallHint, loadDocBridgeIndex, loadFederatedChunks, mcpSnippet, normalizeAgentHandoff, parseAgentHandoff, parseAgentSearch, parseDocBridgeConfig, parseDocBridgeIndex, parseLlmsTxtLinks, parseMemoryCandidate, promoteMemoryToGithubPr, resolveGateIds, resolveRoot, retrieveDocBridgeChunks, retrieveHybridChunks, runChatOnce, runDoctor, runGate, runGates, runQuery, safeParseAgentHandoff, scanHumanDocRecords, scanHumanDocs, scanMemorySafety, searchIndex, sha256NormalizedV1, startInkChat, startMcpStdioServer, watchDocBridgeIndex, writePromotionDraft };