explorbot 0.1.29 → 0.1.31

package/boat/doc-collector/src/ai/documentarian.ts

@@ -45,7 +45,7 @@ class Documentarian {
     try {
       tag('info').log('Starting interactive exploration...');
 
-      const deterministicInteractions = await collectDocInteractions(this.explorer!, state, research);
+      const deterministicInteractions = await collectDocInteractions(this.explorer!, state, research, this.config);
       const meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
       if (meaningfulInteractions.length > 0) {
         tag('success').log(`Collected ${meaningfulInteractions.length} deterministic interactions`);
@@ -240,10 +240,15 @@ class Documentarian {
   }
 
   private normalizeDocumentation(documentation: PageDocumentation, _state: WebPageState, _research: string): PageDocumentation {
-    const qualityNotes = this.evaluateDocumentationQuality(documentation);
+    const normalized = { ...documentation };
+    if (!normalized.interactions) {
+      normalized.interactions = undefined;
+    }
+
+    const qualityNotes = this.evaluateDocumentationQuality(normalized);
 
     return {
-      ...documentation,
+      ...normalized,
       qualityNotes,
     };
   }
@@ -321,36 +326,55 @@ const stateTransitionSchema = z.object({
   action: z.string(),
   before: z.string(),
   after: z.string(),
-  targetUrl: z.string().optional(),
-  discoveredUrls: z.array(z.string()).optional(),
-  newCapabilities: z.array(z.string()).optional(),
+  targetUrl: z.string().nullable(),
+  discoveredUrls: z.array(z.string()).nullable(),
+  newCapabilities: z.array(z.string()).nullable(),
   element: z
     .object({
       role: z.string(),
       name: z.string(),
       section: z.string(),
-      container: z.string().optional(),
-      locator: z.string().optional(),
+      container: z.string().nullable(),
+      locator: z.string().nullable(),
     })
-    .optional(),
+    .nullable(),
   changes: z
     .object({
       urlChanged: z.boolean(),
       newElements: z.number(),
       removedElements: z.number(),
     })
-    .optional(),
+    .nullable(),
 });
 
 const pageDocumentationSchema = z.object({
   summary: z.string(),
   can: z.array(capabilitySchema),
   might: z.array(capabilitySchema),
-  interactions: z.array(stateTransitionSchema).optional(),
+  interactions: z.array(stateTransitionSchema).nullable(),
 });
 
-type StateTransition = z.infer<typeof stateTransitionSchema>;
-type PageDocumentation = z.infer<typeof pageDocumentationSchema> & {
+type StateTransition = {
+  action: string;
+  before: string;
+  after: string;
+  targetUrl?: string | null;
+  discoveredUrls?: string[] | null;
+  newCapabilities?: string[] | null;
+  element?: {
+    role: string;
+    name: string;
+    section: string;
+    container?: string | null;
+    locator?: string | null;
+  } | null;
+  changes?: {
+    urlChanged: boolean;
+    newElements: number;
+    removedElements: number;
+  } | null;
+};
+type PageDocumentation = Omit<z.infer<typeof pageDocumentationSchema>, 'interactions'> & {
   interactions?: StateTransition[];
   qualityNotes?: string[];
 };

package/boat/doc-collector/src/ai/tools.ts

@@ -1,6 +1,7 @@
 import { type ResearchElement, parseResearchSections } from '../../../../src/ai/researcher/parser.ts';
 import type Explorer from '../../../../src/explorer.ts';
 import type { WebPageState } from '../../../../src/state-manager.ts';
+import type { DocbotConfig } from '../config.ts';
 
 export interface DocStateTransition {
   action: string;
@@ -34,23 +35,25 @@ interface InteractionChanges {
   removedElements: number;
 }
 
-const MAX_PRIMARY_CANDIDATES = 3;
-const MAX_INTERACTIONS = 5;
+const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
+const DEFAULT_MAX_INTERACTIONS = 5;
 const MAX_LINKS = 15;
 const DEFAULT_WAIT_MS = 700;
 const TAB_WAIT_MS = 500;
+const DEFAULT_DENIED_ACTION_LABELS = ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'];
 
-export async function collectDocInteractions(explorer: Explorer, state: WebPageState, research: string): Promise<DocStateTransition[]> {
+export async function collectDocInteractions(explorer: Explorer, state: WebPageState, research: string, config: DocbotConfig = {}): Promise<DocStateTransition[]> {
   const sections = parseResearchSections(research);
   const transitions: DocStateTransition[] = [];
+  const maxInteractions = getPositiveConfigNumber(config.docs?.maxInteractions, DEFAULT_MAX_INTERACTIONS);
   const tabGroup = findTabGroup(sections);
 
   if (tabGroup) {
-    transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url)));
+    transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions)));
   }
 
-  for (const candidate of findActionCandidates(sections)) {
-    if (transitions.length >= MAX_INTERACTIONS) {
+  for (const candidate of findActionCandidates(sections, config)) {
+    if (transitions.length >= maxInteractions) {
       break;
     }
 
@@ -65,18 +68,22 @@ export async function collectDocInteractions(explorer: Explorer, state: WebPageS
   return transitions;
 }
 
-export function pickDocActionCandidates(research: string): Array<{ label: string; role: InteractionCandidate['role']; section: string }> {
-  return findActionCandidates(parseResearchSections(research)).map((candidate) => ({
+export function pickDocActionCandidates(research: string, config: DocbotConfig = {}): Array<{ label: string; role: InteractionCandidate['role']; section: string }> {
+  return findActionCandidates(parseResearchSections(research), config).map((candidate) => ({
     label: candidate.element.name.trim(),
     role: candidate.role,
     section: candidate.sectionName,
   }));
 }
 
-async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: ResearchElement[]; container?: string; sectionName: string }, restoreUrl: string): Promise<DocStateTransition[]> {
+async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: ResearchElement[]; container?: string; sectionName: string }, restoreUrl: string, maxInteractions: number): Promise<DocStateTransition[]> {
   const transitions: DocStateTransition[] = [];
 
   for (const element of tabGroup.elements) {
+    if (transitions.length >= maxInteractions) {
+      break;
+    }
+
     const transition = await executeInteraction(
       explorer,
       {
@@ -241,23 +248,21 @@ function findTabGroup(sections: ReturnType<typeof parseResearchSections>): { ele
   return null;
 }
 
-function findActionCandidates(sections: ReturnType<typeof parseResearchSections>): InteractionCandidate[] {
+function findActionCandidates(sections: ReturnType<typeof parseResearchSections>, config: DocbotConfig): InteractionCandidate[] {
   const candidates: InteractionCandidate[] = [];
   const seen = new Set<string>();
   const navigationLabels = collectNavigationLabels(sections);
+  const maxPrimaryCandidates = getPositiveConfigNumber(config.docs?.maxPrimaryCandidates, DEFAULT_MAX_PRIMARY_CANDIDATES);
 
   for (const section of sections) {
     const sectionName = section.name.toLowerCase();
     const container = section.containerCss?.toLowerCase() || '';
-    if (isOverlaySection(sectionName, container)) {
-      continue;
-    }
-    if (isNavigationSection(sectionName)) {
+    if (isIgnoredSection(sectionName, container)) {
       continue;
     }
 
     for (const element of section.elements) {
-      const candidate = toInteractionCandidate(element, section.name, section.containerCss, navigationLabels);
+      const candidate = toInteractionCandidate(element, section.name, section.containerCss, navigationLabels, config);
       if (!candidate) {
         continue;
       }
@@ -272,10 +277,10 @@ function findActionCandidates(sections: ReturnType<typeof parseResearchSections>
     }
   }
 
-  return candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a)).slice(0, MAX_PRIMARY_CANDIDATES);
+  return candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a)).slice(0, maxPrimaryCandidates);
 }
 
-function toInteractionCandidate(element: ResearchElement, sectionName: string, container: string | null | undefined, navigationLabels: Set<string>): InteractionCandidate | null {
+function toInteractionCandidate(element: ResearchElement, sectionName: string, container: string | null | undefined, navigationLabels: Set<string>, config: DocbotConfig): InteractionCandidate | null {
   const role = getElementRole(element);
   if (role !== 'link' && role !== 'button' && role !== 'tab') {
     return null;
@@ -283,7 +288,10 @@ function toInteractionCandidate(element: ResearchElement, sectionName: string, c
   if (!hasUsableName(element)) {
     return null;
   }
-  if (isShellLocator(element.css) || isShellLocator(element.xpath) || isShellLocator(container)) {
+  if (isPageShellContainer(element.css) || isPageShellContainer(element.xpath)) {
+    return null;
+  }
+  if (isDestructiveAction(element, config)) {
     return null;
   }
   if (role === 'link' && navigationLabels.has(normalizeCandidateLabel(element.name))) {
@@ -454,6 +462,20 @@ function isNavigationSection(sectionName: string): boolean {
   return /(navigation|menu|header|footer|breadcrumb)/i.test(sectionName);
 }
 
+function isContentControlSection(sectionName: string): boolean {
+  return /(content|control|filter|toolbar|action|list|data)/i.test(sectionName);
+}
+
+function isIgnoredSection(sectionName: string, container: string): boolean {
+  if (isOverlaySection(sectionName, container)) {
+    return true;
+  }
+  if (isContentControlSection(sectionName)) {
+    return false;
+  }
+  return isNavigationSection(sectionName) || isPageShellContainer(container);
+}
+
 function isOverlaySection(sectionName: string, container: string): boolean {
   return /(overlay|modal|popup|dialog)/i.test(sectionName) || /(overlay|modal|popup|dialog)/i.test(container);
 }
@@ -483,12 +505,12 @@ function scoreCandidate(candidate: InteractionCandidate): number {
   return score;
 }
 
-function isShellLocator(locator: string | null | undefined): boolean {
+function isPageShellContainer(locator: string | null | undefined): boolean {
   if (!locator) {
     return false;
   }
 
-  return /(nav\[role="navigation"\]|header|menu|breadcrumb|footer)/i.test(locator);
+  return /(^|[\s>+~,.#\[])(nav|navigation|mainnav|header|menu|breadcrumb|footer)([\s>+~,.#\]_-]|$)/i.test(locator);
 }
 
 function collectNavigationLabels(sections: ReturnType<typeof parseResearchSections>): Set<string> {
@@ -515,6 +537,24 @@ function normalizeCandidateLabel(label: string): string {
   return label.trim().toLowerCase();
 }
 
+function isDestructiveAction(element: ResearchElement, config: DocbotConfig): boolean {
+  const label = normalizeCandidateLabel(element.name);
+  const deniedLabels = config.docs?.deniedActionLabels || DEFAULT_DENIED_ACTION_LABELS;
+  if (deniedLabels.some((denied) => label.includes(normalizeCandidateLabel(denied)))) {
+    return true;
+  }
+
+  const locator = `${element.css || ''} ${element.xpath || ''}`.toLowerCase();
+  return deniedLabels.some((denied) => locator.includes(normalizeCandidateLabel(denied)));
+}
+
+function getPositiveConfigNumber(value: number | undefined, fallback: number): number {
+  if (!value || value <= 0) {
+    return fallback;
+  }
+  return value;
+}
+
 function limitInlineText(text: string, maxLength: number): string {
   const normalized = text.replace(/\s+/g, ' ').trim();
   if (normalized.length <= maxLength) {

package/boat/doc-collector/src/cli.ts

@@ -101,6 +101,9 @@ export function createDocsCommands(name = 'docs'): Command {
             includePaths: [],
             excludePaths: [],
             deniedPathSegments: ['callback', 'callbacks', 'logout', 'signout', 'sign_out', 'destroy', 'delete', 'remove'],
+            deniedActionLabels: ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'],
+            maxPrimaryCandidates: 3,
+            maxInteractions: 5,
             minCanActions: 1,
             minInteractiveElements: 3,
             // prompt: 'Add domain-specific documentation guidance here',

package/boat/doc-collector/src/config.ts

@@ -120,6 +120,9 @@ class DocbotConfigParser {
           includePaths: [],
           excludePaths: [],
           deniedPathSegments: ['callback', 'callbacks', 'logout', 'signout', 'sign_out', 'destroy', 'delete', 'remove'],
+          deniedActionLabels: ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'],
+          maxPrimaryCandidates: 3,
+          maxInteractions: 5,
           minCanActions: 1,
           minInteractiveElements: 3,
         },
@@ -154,6 +157,10 @@ interface DocbotConfig {
     includePaths?: string[];
     excludePaths?: string[];
     deniedPathSegments?: string[];
+    deniedActionLabels?: string[];
+    maxPrimaryCandidates?: number;
+    maxInteractions?: number;
+    maxSectionScreenshots?: number;
     minCanActions?: number;
     minInteractiveElements?: number;
     interactive?: boolean;

package/boat/doc-collector/src/docbot.ts

@@ -3,13 +3,14 @@ import path from 'node:path';
 import { ExplorBot, type ExplorBotOptions } from '../../../src/explorbot.ts';
 import type { Link, WebPageState } from '../../../src/state-manager.ts';
 import { normalizeUrl } from '../../../src/state-manager.ts';
-import { sanitizeFilename } from '../../../src/utils/strings.ts';
 import { tag } from '../../../src/utils/logger.ts';
+import { sanitizeFilename } from '../../../src/utils/strings.ts';
 import { Documentarian, type PageDocumentation } from './ai/documentarian.ts';
 import { type DocbotConfig, DocbotConfigParser } from './config.ts';
-import { type DocumentedPage, renderPageDocumentation, renderSpecIndex, type SkippedPage } from './docs-renderer.ts';
+import { type DocumentedPage, type SkippedPage, renderPageDocumentation, renderSpecIndex } from './docs-renderer.ts';
 import { getDocPageKey, shouldCrawlDocPath } from './path-filter.ts';
 import { extractResearchNavigationTargets } from './research-navigation.ts';
+import { type DocumentationScreenshot, captureDocumentationScreenshots } from './screenshots.ts';
 
 class DocBot {
   private explorBot: ExplorBot;
@@ -120,7 +121,7 @@ class DocBot {
           documented.add(pageKey);
           continue;
         }
-        const filePath = this.savePageDocumentation(state, documentation);
+        const filePath = await this.savePageDocumentation(state, documentation, research);
 
         pages.push({
           url: state.url,
@@ -397,12 +398,25 @@ class DocBot {
     return matches.reduce((sum, match) => sum + Number.parseInt(match[1], 10), 0);
   }
 
-  private savePageDocumentation(state: WebPageState, documentation: PageDocumentation): string {
+  private async savePageDocumentation(state: WebPageState, documentation: PageDocumentation, research: string): Promise<string> {
     const pagePath = this.getPageFilePath(state.url);
-    writeFileSync(pagePath, renderPageDocumentation(state, documentation), 'utf8');
+    const screenshots = await this.captureScreenshots(state, research, pagePath);
+    writeFileSync(pagePath, renderPageDocumentation(state, documentation, screenshots), 'utf8');
     return pagePath;
   }
 
+  private async captureScreenshots(state: WebPageState, research: string, pagePath: string): Promise<DocumentationScreenshot[]> {
+    if (!this.shouldUseScreenshots()) {
+      return [];
+    }
+
+    return captureDocumentationScreenshots(this.explorBot.getExplorer(), state, research, {
+      pageFilePath: pagePath,
+      screenshotsDir: this.getScreenshotsDir(),
+      config: this.config,
+    });
+  }
+
   private saveIndex(startPath: string, pages: DocumentedPage[], skipped: SkippedPage[], maxPages: number): string {
     const indexPath = path.join(this.configParser.getOutputDir(), 'spec.md');
     writeFileSync(indexPath, renderSpecIndex(this.configParser.getOutputDir(), startPath, pages, skipped, maxPages), 'utf8');
@@ -413,6 +427,10 @@ class DocBot {
     return path.join(this.configParser.getOutputDir(), 'pages');
   }
 
+  private getScreenshotsDir(): string {
+    return path.join(this.configParser.getOutputDir(), 'screenshots');
+  }
+
   private getPageFilePath(pageUrl: string): string {
     const normalized = normalizeUrl(pageUrl || '/');
     const baseName = sanitizeFilename(normalized || 'root');

package/boat/doc-collector/src/docs-renderer.ts

@@ -1,8 +1,9 @@
 import path from 'node:path';
 import type { WebPageState } from '../../../src/state-manager.ts';
 import type { PageDocumentation, StateTransition } from './ai/documentarian.ts';
+import type { DocumentationScreenshot } from './screenshots.ts';
 
-function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation): string {
+function renderPageDocumentation(state: WebPageState, documentation: PageDocumentation, screenshots: DocumentationScreenshot[] = []): string {
   const lines: string[] = [];
   lines.push(`# ${state.url}`);
   lines.push('');
@@ -17,6 +18,18 @@ function renderPageDocumentation(state: WebPageState, documentation: PageDocumen
   lines.push(ensureSentence(documentation.summary));
   lines.push('');
 
+  if (screenshots.length > 0) {
+    lines.push('## Screenshots');
+    lines.push('');
+    for (const screenshot of screenshots) {
+      lines.push(`![${normalizeInlineText(screenshot.title)}](${screenshot.relativePath})`);
+      if (screenshot.selector) {
+        lines.push(`Section: \`${screenshot.selector}\``);
+      }
+      lines.push('');
+    }
+  }
+
   const interactions = documentation.interactions;
   if (interactions && interactions.length > 0) {
     lines.push('## State Transitions');

package/boat/doc-collector/src/screenshots.ts

@@ -0,0 +1,126 @@
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { parseResearchSections } from '../../../src/ai/researcher/parser.ts';
+import type Explorer from '../../../src/explorer.ts';
+import type { WebPageState } from '../../../src/state-manager.ts';
+import { safeFilename, sanitizeFilename } from '../../../src/utils/strings.ts';
+import type { DocbotConfig } from './config.ts';
+
+const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
+
+export async function captureDocumentationScreenshots(explorer: Explorer, state: WebPageState, research: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot[]> {
+  const page = explorer.playwrightHelper?.page;
+  if (!page) {
+    return [];
+  }
+
+  mkdirSync(options.screenshotsDir, { recursive: true });
+
+  const screenshots: DocumentationScreenshot[] = [];
+  const pageName = sanitizeFilename(state.url || 'page') || 'page';
+  const fullPage = await captureFullPageScreenshot(page, pageName, options);
+  if (fullPage) {
+    screenshots.push(fullPage);
+  }
+
+  const maxSections = getMaxSectionScreenshots(options.config);
+  for (const section of getScreenshotSections(research).slice(0, maxSections)) {
+    const screenshot = await captureSectionScreenshot(page, pageName, section, options);
+    if (!screenshot) {
+      continue;
+    }
+    screenshots.push(screenshot);
+  }
+
+  return screenshots;
+}
+
+export function getScreenshotSections(research: string): ScreenshotSection[] {
+  const sections: ScreenshotSection[] = [];
+  const seen = new Set<string>();
+
+  for (const section of parseResearchSections(research)) {
+    if (!section.containerCss) {
+      continue;
+    }
+    if (section.elements.length === 0) {
+      continue;
+    }
+    if (seen.has(section.containerCss)) {
+      continue;
+    }
+    seen.add(section.containerCss);
+    sections.push({
+      title: section.name,
+      selector: section.containerCss,
+    });
+  }
+
+  return sections;
+}
+
+async function captureFullPageScreenshot(page: any, pageName: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
+  const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
+  try {
+    await page.screenshot({ path: filePath, fullPage: true });
+  } catch {
+    return null;
+  }
+
+  return {
+    title: 'Page screenshot',
+    path: filePath,
+    relativePath: toMarkdownPath(options.pageFilePath, filePath),
+    kind: 'page',
+  };
+}
+
+async function captureSectionScreenshot(page: any, pageName: string, section: ScreenshotSection, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
+  const sectionName = sanitizeFilename(section.title) || 'section';
+  const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${sectionName}`, '.png'));
+
+  try {
+    await page.locator(section.selector).first().screenshot({ path: filePath });
+  } catch {
+    return null;
+  }
+
+  return {
+    title: section.title,
+    path: filePath,
+    relativePath: toMarkdownPath(options.pageFilePath, filePath),
+    kind: 'section',
+    selector: section.selector,
+  };
+}
+
+function getMaxSectionScreenshots(config: DocbotConfig): number {
+  const configured = config.docs?.maxSectionScreenshots;
+  if (configured && configured > 0) {
+    return configured;
+  }
+  return DEFAULT_MAX_SECTION_SCREENSHOTS;
+}
+
+function toMarkdownPath(pageFilePath: string, assetPath: string): string {
+  return path.relative(path.dirname(pageFilePath), assetPath).replaceAll('\\', '/');
+}
+
+export interface DocumentationScreenshot {
+  title: string;
+  path: string;
+  relativePath: string;
+  kind: 'page' | 'section';
+  selector?: string;
+}
+
+interface DocumentationScreenshotOptions {
+  pageFilePath: string;
+  screenshotsDir: string;
+  config: DocbotConfig;
+}
+
+interface ScreenshotSection {
+  title: string;
+  selector: string;
+}

package/dist/boat/doc-collector/src/ai/documentarian.js

@@ -34,7 +34,7 @@ class Documentarian {
     async documentWithInteraction(state, research) {
         try {
             tag('info').log('Starting interactive exploration...');
-            const deterministicInteractions = await collectDocInteractions(this.explorer, state, research);
+            const deterministicInteractions = await collectDocInteractions(this.explorer, state, research, this.config);
             const meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
             if (meaningfulInteractions.length > 0) {
                 tag('success').log(`Collected ${meaningfulInteractions.length} deterministic interactions`);
@@ -210,9 +210,13 @@ class Documentarian {
         return message.includes('Failed to generate JSON') || message.includes('Failed to validate JSON') || message.includes('failed_generation') || message.includes('No object generated') || message.includes('response did not match schema');
     }
     normalizeDocumentation(documentation, _state, _research) {
-        const qualityNotes = this.evaluateDocumentationQuality(documentation);
+        const normalized = { ...documentation };
+        if (!normalized.interactions) {
+            normalized.interactions = undefined;
+        }
+        const qualityNotes = this.evaluateDocumentationQuality(normalized);
         return {
-            ...documentation,
+            ...normalized,
             qualityNotes,
         };
     }
@@ -277,30 +281,30 @@ const stateTransitionSchema = z.object({
     action: z.string(),
     before: z.string(),
     after: z.string(),
-    targetUrl: z.string().optional(),
-    discoveredUrls: z.array(z.string()).optional(),
-    newCapabilities: z.array(z.string()).optional(),
+    targetUrl: z.string().nullable(),
+    discoveredUrls: z.array(z.string()).nullable(),
+    newCapabilities: z.array(z.string()).nullable(),
     element: z
         .object({
         role: z.string(),
         name: z.string(),
         section: z.string(),
-        container: z.string().optional(),
-        locator: z.string().optional(),
+        container: z.string().nullable(),
+        locator: z.string().nullable(),
     })
-        .optional(),
+        .nullable(),
     changes: z
         .object({
         urlChanged: z.boolean(),
         newElements: z.number(),
         removedElements: z.number(),
     })
-        .optional(),
+        .nullable(),
 });
 const pageDocumentationSchema = z.object({
     summary: z.string(),
     can: z.array(capabilitySchema),
     might: z.array(capabilitySchema),
-    interactions: z.array(stateTransitionSchema).optional(),
+    interactions: z.array(stateTransitionSchema).nullable(),
 });
 export { Documentarian };