@epsilon-asi/actors 0.0.1 → 0.0.3

package/.ai/generators/cli-command.ts

@@ -1,96 +0,0 @@
-export default {
-  id: 'cli-command',
-  description: 'Modify CLI behavior, environment variable parsing, command inputs, actor registration, and CLI documentation.',
-  instructions: `
-Modify the CLI entrypoint in src/cli/run.ts.
-
-Rules:
-- Keep CLI config construction aligned with RuntimeConfig types.
-- Preserve JSON input parsing behavior unless explicitly changing it.
-- Keep environment variable names documented in README.
-- Validate ambiguous or conflicting env vars and fail with clear ConfigError messages.
-- When adding actor registration behavior, update ActorRegistry usage and site exports if needed.
-- If CLI can affect browser lifecycle, verify close/disconnect behavior matches BrowserSession and RuntimeConfig defaults.
-- Add tests if the change can be unit-tested without spawning Chrome.
-
-DO NOT hard-code machine-specific Chrome paths, credentials, or profile directories.
-DO NOT default remote debugging to a non-localhost address.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'cli',
-        pathTemplate: 'src/cli/run.ts',
-        description: 'CLI entrypoint and env/input parsing.'
-      },
-      {
-        key: 'runtime-config',
-        pathTemplate: 'src/browser/RuntimeConfig.ts',
-        description: 'Runtime config types if CLI config surface changes.'
-      },
-      {
-        key: 'actor-registry',
-        pathTemplate: 'src/core/ActorRegistry.ts',
-        description: 'Registry behavior if actor lookup changes.'
-      },
-      {
-        key: 'docs',
-        pathTemplate: 'README.md',
-        description: 'CLI usage and env var documentation.'
-      },
-      {
-        key: 'tests',
-        pathTemplate: 'tests/unit/cli/{{featureKebab}}.test.ts',
-        description: 'CLI unit tests for parser/config helpers when added.'
-      }
-    ],
-    maxFiles: 5
-  },
-  parameters: {
-    feature: {
-      description: 'CLI feature to implement, for example env var, input parsing, registry loading, or run mode.',
-      required: true
-    },
-    instructions: {
-      description: 'Detailed CLI behavior, examples, env vars, and failure cases.',
-      required: false
-    }
-  },
-  examples: [
-    'src/cli/run.ts',
-    'src/browser/RuntimeConfig.ts',
-    'src/core/ActorRegistry.ts',
-    'README.md'
-  ],
-  context: [
-    { kind: 'path', path: 'src/cli/run.ts', description: 'Current CLI implementation.' },
-    { kind: 'path', path: 'src/browser/RuntimeConfig.ts', description: 'Runtime config consumed by CLI.' },
-    { kind: 'path', path: 'src/core/ActorRegistry.ts', description: 'Actor registration and lookup.' },
-    { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Runner invoked by CLI.' },
-    { kind: 'path', path: 'src/sites/example/example.actor.ts', description: 'Example actor currently registered by CLI.' },
-    { kind: 'path', path: 'src/sites/index.ts', description: 'Site exports available to CLI.' },
-    { kind: 'path', path: 'src/errors/ConfigError.ts', description: 'Config error class for CLI validation failures.' },
-    { kind: 'path', path: 'README.md', description: 'Documentation that should match CLI behavior.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['browser', 'chrome', 'profile', 'remote debugging', 'debug endpoint'],
-      context: [
-        { kind: 'path', path: 'src/browser/BrowserFactory.ts', description: 'Browser launch/connect behavior that CLI config drives.' },
-        { kind: 'path', path: 'tests/unit/browser/BrowserFactory.test.ts', description: 'Runtime config behavior tests.' }
-      ]
-    },
-    {
-      keywords: ['site', 'actor', 'registry'],
-      context: [
-        { kind: 'path', path: 'src/core/Actor.ts', description: 'Actor contracts.' },
-        { kind: 'pattern', pattern: 'src/sites/**/*.actor.ts', description: 'Existing site actor modules.', limit: 5 }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/core-framework.ts

@@ -1,80 +0,0 @@
-export default {
-  id: 'core-framework',
-  description:
-    'Modify core actor framework behavior: ActorRunner, ActorContext, ActorRegistry, defineActor, hooks, context services, and execution lifecycle.',
-  instructions: `
-Make reusable framework changes in src/core unless another layer clearly owns the behavior.
-
-Rules:
-- ActorRunner coordinates browser session creation, auth, task execution, hooks, error wrapping, and cleanup.
-- ActorContext should expose stable services to site actors; avoid leaking low-level implementation details unless necessary.
-- Keep defineActor simple and type-preserving.
-- Keep ActorRegistry focused on registration and lookup.
-- Do not implement site-specific scraping in core.
-- Add unit tests for every lifecycle, auth, context, or hook behavior change.
-`.trim(),
-  output: {
-    pathTemplates: [
-      { key: 'actor', pathTemplate: 'src/core/Actor.ts', description: 'Actor/task/hook types.' },
-      { key: 'context', pathTemplate: 'src/core/ActorContext.ts', description: 'Task context services.' },
-      { key: 'runner', pathTemplate: 'src/core/ActorRunner.ts', description: 'Execution lifecycle implementation.' },
-      { key: 'registry', pathTemplate: 'src/core/ActorRegistry.ts', description: 'Actor registry implementation.' },
-      { key: 'define-actor', pathTemplate: 'src/core/defineActor.ts', description: 'Actor definition helper.' },
-      { key: 'core-index', pathTemplate: 'src/core/index.ts', description: 'Core barrel exports.' },
-      { key: 'runner-tests', pathTemplate: 'tests/unit/core/ActorRunner.test.ts', description: 'Runner lifecycle tests.' },
-      { key: 'define-tests', pathTemplate: 'tests/unit/core/defineActor.test.ts', description: 'defineActor type/runtime tests.' }
-    ],
-    maxFiles: 8
-  },
-  parameters: {
-    feature: {
-      description: 'Core framework feature to add or change, for example hooks, context service, actor lookup, or error wrapping.',
-      required: true
-    },
-    instructions: {
-      description: 'Detailed behavior, affected actors, lifecycle semantics, and test expectations.',
-      required: false
-    }
-  },
-  examples: [
-    'src/core/ActorRunner.ts',
-    'src/core/ActorContext.ts',
-    'src/core/ActorRegistry.ts',
-    'tests/unit/core/ActorRunner.test.ts'
-  ],
-  context: [
-    { kind: 'path', path: 'src/core/Actor.ts', description: 'Actor/task/hook types.' },
-    { kind: 'path', path: 'src/core/ActorContext.ts', description: 'Services exposed to tasks.' },
-    { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Execution lifecycle.' },
-    { kind: 'path', path: 'src/core/ActorRegistry.ts', description: 'Registry behavior.' },
-    { kind: 'path', path: 'src/core/defineActor.ts', description: 'Type-preserving actor helper.' },
-    { kind: 'path', path: 'src/browser/BrowserSession.ts', description: 'Session lifecycle consumed by ActorRunner.' },
-    { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Auth service used by ActorRunner.' },
-    { kind: 'path', path: 'src/errors/AutomationError.ts', description: 'Base error wrapper used by ActorRunner.' },
-    { kind: 'pattern', pattern: 'tests/unit/core/*.test.ts', description: 'Core unit tests.', limit: 5 },
-    { kind: 'path', path: 'tests/fixtures/makeContext.ts', description: 'ActorContext test fixture.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['browser', 'session', 'cleanup', 'close', 'disconnect'],
-      context: [
-        { kind: 'path', path: 'src/browser/BrowserFactory.ts', description: 'BrowserSession creation behavior.' },
-        { kind: 'path', path: 'src/browser/BrowserSession.ts', description: 'Close/disconnect behavior.' },
-        { kind: 'path', path: 'tests/unit/browser/BrowserFactory.test.ts', description: 'Browser lifecycle tests.' }
-      ]
-    },
-    {
-      keywords: ['auth', 'login', 'ensureAuthenticated', 'isLoggedIn'],
-      context: [
-        { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Auth execution consumed by ActorRunner.' },
-        { kind: 'path', path: 'src/auth/AuthStateDetector.ts', description: 'Logged-in detection consumed by context auth controller.' },
-        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Auth behavior tests.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/docs.ts

@@ -1,92 +0,0 @@
-export default {
-  id: 'docs',
-  description: 'Update README and usage documentation for framework features, site actors, CLI examples, browser setup, and auth/login examples.',
-  instructions: `
-Update documentation to match the actual code.
-
-Rules:
-- Keep examples consistent with RuntimeConfig, ActorRunner, LoginFlowDefinition, and CLI behavior.
-- Use the example actor only as a pattern; do not imply it scrapes a real site unless it does.
-- Include concrete command examples when documenting CLI behavior.
-- Include safe Chrome remote debugging examples bound to 127.0.0.1 when documenting running Chrome attach.
-- Document environment variables only if src/cli/run.ts supports them.
-- Avoid overstating test coverage or behavior not implemented in code.
-- Keep docs practical and concise.
-
-DO NOT include real credentials, cookies, tokens, or private local paths.
-DO NOT document CAPTCHA bypass or anti-bot circumvention.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'readme',
-        pathTemplate: 'README.md',
-        description: 'Primary project documentation.'
-      },
-      {
-        key: 'example-actor',
-        pathTemplate: 'src/sites/example/example.actor.ts',
-        description: 'Update only if documentation examples require the example actor to change.'
-      },
-      {
-        key: 'cli',
-        pathTemplate: 'src/cli/run.ts',
-        description: 'Update only if docs expose CLI behavior that code does not yet support.'
-      }
-    ],
-    maxFiles: 3
-  },
-  parameters: {
-    topic: {
-      description: 'Documentation topic, for example multi-step login, running Chrome attach, human typing, creating site actors, or CLI usage.',
-      required: true
-    },
-    instructions: {
-      description: 'Specific docs to add, change, or clarify.',
-      required: false
-    }
-  },
-  examples: [
-    'README.md',
-    'src/sites/example/example.actor.ts',
-    'src/cli/run.ts'
-  ],
-  context: [
-    { kind: 'path', path: 'README.md', description: 'Existing documentation.' },
-    { kind: 'path', path: 'package.json', description: 'Scripts, package name, binary name, and dependencies.' },
-    { kind: 'path', path: 'src/browser/RuntimeConfig.ts', description: 'Runtime config docs must match these types.' },
-    { kind: 'path', path: 'src/browser/BrowserFactory.ts', description: 'Launch/connect behavior docs must match this implementation.' },
-    { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Login examples must match these types.' },
-    { kind: 'path', path: 'src/interaction/HumanTyping.ts', description: 'Typing docs must match these options/defaults.' },
-    { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Runner examples must match constructor/run behavior.' },
-    { kind: 'path', path: 'src/cli/run.ts', description: 'CLI examples must match env parsing and command behavior.' },
-    { kind: 'path', path: 'src/sites/example/example.actor.ts', description: 'Example actor implementation.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['login', 'multi-step', 'auth', 'credentials'],
-      context: [
-        { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Login execution details.' },
-        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Behavior examples from tests.' }
-      ]
-    },
-    {
-      keywords: ['browser', 'chrome', 'debug endpoint', 'remote debugging', 'profile'],
-      context: [
-        { kind: 'path', path: 'tests/unit/browser/BrowserFactory.test.ts', description: 'Browser behavior examples from tests.' }
-      ]
-    },
-    {
-      keywords: ['site', 'actor', 'task', 'scrape'],
-      context: [
-        { kind: 'path', path: 'src/core/Actor.ts', description: 'Actor/task contracts.' },
-        { kind: 'path', path: 'src/extraction/Extractor.ts', description: 'Extraction helpers available to actor tasks.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/error-logging.ts

@@ -1,102 +0,0 @@
-export default {
-  id: 'error-logging',
-  description: 'Modify typed errors, logging implementations, metadata redaction, and diagnostics behavior.',
-  instructions: `
-Update error/logging behavior safely.
-
-Rules:
-- Keep AutomationError as the base class for framework-level errors.
-- Preserve useful metadata: actorId, taskName, url, selector, and cause where applicable.
-- Keep logging implementation independent from site-specific code.
-- Redact sensitive metadata recursively before writing logs.
-- Add tests for every new redaction key or error metadata behavior.
-- If a browser/auth/core module starts throwing a new typed error, update the relevant unit tests there too.
-- Prefer typed errors over plain Error for framework-level failures.
-
-DO NOT log raw passwords, tokens, authorization headers, cookies, or session secrets.
-DO NOT swallow causes; preserve them in metadata where feasible.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'error',
-        pathTemplate: 'src/errors/{{errorPascal}}.ts',
-        description: 'Typed error class. Use existing files when editing existing errors.'
-      },
-      {
-        key: 'errors-index',
-        pathTemplate: 'src/errors/index.ts',
-        description: 'Error barrel exports.'
-      },
-      {
-        key: 'logger',
-        pathTemplate: 'src/logging/{{loggerPascal}}.ts',
-        description: 'Logger interface or implementation. Use existing files when editing existing loggers.'
-      },
-      {
-        key: 'redact',
-        pathTemplate: 'src/utils/redact.ts',
-        description: 'Sensitive metadata redaction utility.'
-      },
-      {
-        key: 'tests',
-        pathTemplate: 'tests/unit/logging/{{subjectPascal}}.test.ts',
-        description: 'Logging/redaction unit tests.'
-      }
-    ],
-    maxFiles: 5
-  },
-  parameters: {
-    subject: {
-      description: 'Error/logging/redaction behavior to implement or update.',
-      required: true
-    },
-    instructions: {
-      description: 'Specific metadata, redaction keys, logger behavior, or error semantics.',
-      required: false
-    }
-  },
-  examples: [
-    'src/errors/AutomationError.ts',
-    'src/errors/AuthError.ts',
-    'src/logging/ConsoleLogger.ts',
-    'src/logging/MemoryLogger.ts',
-    'src/utils/redact.ts',
-    'tests/unit/logging/redact.test.ts'
-  ],
-  context: [
-    { kind: 'pattern', pattern: 'src/errors/*.ts', description: 'Existing typed errors and barrel export.', limit: 10 },
-    { kind: 'pattern', pattern: 'src/logging/*.ts', description: 'Logger interface and implementations.', limit: 10 },
-    { kind: 'path', path: 'src/utils/redact.ts', description: 'Sensitive metadata redaction utility.' },
-    { kind: 'path', path: 'tests/unit/logging/redact.test.ts', description: 'Existing redaction tests.' },
-    { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Auth error and redacted logging usage.' },
-    { kind: 'path', path: 'src/browser/BrowserFactory.ts', description: 'ConfigError metadata usage.' },
-    { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Error wrapping behavior.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['auth', 'login', 'credentials', 'password'],
-      context: [
-        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Auth tests may need error/log assertion updates.' }
-      ]
-    },
-    {
-      keywords: ['browser', 'chrome', 'profile', 'remote debugging'],
-      context: [
-        { kind: 'path', path: 'tests/unit/browser/BrowserFactory.test.ts', description: 'Browser error tests.' }
-      ]
-    },
-    {
-      keywords: ['selector', 'form', 'extraction'],
-      context: [
-        { kind: 'path', path: 'tests/unit/interaction/Forms.test.ts', description: 'Selector error behavior tests.' },
-        { kind: 'path', path: 'tests/unit/extraction/Extractor.test.ts', description: 'Extraction behavior tests.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/extraction-helper.ts

@@ -1,96 +0,0 @@
-export default {
-  id: 'extraction-helper',
-  description: 'Add or modify reusable extraction helpers, pagination behavior, data mapping utilities, and extraction tests.',
-  instructions: `
-Add or revise extraction utilities for reusable scraping behavior.
-
-Rules:
-- Keep extraction helpers generic and site-agnostic.
-- Use PageAdapter methods before reaching for raw Puppeteer APIs.
-- Preserve existing Extractor and Pagination behavior unless the user asks for a change.
-- Return normalized values where possible: trimmed text, null for missing optional attributes, arrays for lists.
-- Make missing-required-element behavior explicit in options rather than surprising callers.
-- Add unit tests using FakePage for every new extraction behavior.
-- Update src/extraction/index.ts when adding a new exported helper.
-- Update src/index.ts if the new helper is part of the public package API.
-
-DO NOT put site-specific selectors or actor-specific data shapes in generic extraction helpers.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'helper',
-        pathTemplate: 'src/extraction/{{helperPascal}}.ts',
-        description: 'New extraction helper. Use Extractor.ts or Pagination.ts directly when editing existing helpers.'
-      },
-      {
-        key: 'extraction-index',
-        pathTemplate: 'src/extraction/index.ts',
-        description: 'Extraction barrel export.'
-      },
-      {
-        key: 'root-index',
-        pathTemplate: 'src/index.ts',
-        description: 'Root package export when public API changes.'
-      },
-      {
-        key: 'tests',
-        pathTemplate: 'tests/unit/extraction/{{helperPascal}}.test.ts',
-        description: 'Unit tests for the extraction helper.'
-      },
-      {
-        key: 'fake-page',
-        pathTemplate: 'tests/fixtures/FakePage.ts',
-        description: 'Update when the helper requires new fake page behavior.'
-      }
-    ],
-    maxFiles: 5
-  },
-  parameters: {
-    helper: {
-      description: 'Extraction helper to add or modify, for example TableExtractor, Pagination, JsonLdExtractor, or Extractor.',
-      required: true
-    },
-    instructions: {
-      description: 'Specific selectors, data shape, normalization, pagination, or edge cases.',
-      required: false
-    }
-  },
-  examples: [
-    'src/extraction/Extractor.ts',
-    'src/extraction/Pagination.ts',
-    'tests/unit/extraction/Extractor.test.ts',
-    'tests/unit/extraction/Pagination.test.ts'
-  ],
-  context: [
-    { kind: 'path', path: 'src/extraction/Extractor.ts', description: 'Current extraction helper.' },
-    { kind: 'path', path: 'src/extraction/Pagination.ts', description: 'Current pagination helper.' },
-    { kind: 'path', path: 'src/extraction/index.ts', description: 'Extraction barrel export.' },
-    { kind: 'path', path: 'src/interaction/PageAdapter.ts', description: 'Page operations available to extraction helpers.' },
-    { kind: 'path', path: 'src/errors/ExtractionError.ts', description: 'Typed extraction error.' },
-    { kind: 'path', path: 'tests/unit/extraction/Extractor.test.ts', description: 'Extractor tests.' },
-    { kind: 'path', path: 'tests/unit/extraction/Pagination.test.ts', description: 'Pagination tests.' },
-    { kind: 'path', path: 'tests/fixtures/FakePage.ts', description: 'Fake page fixture.' },
-    { kind: 'path', path: 'tests/fixtures/FakeCursor.ts', description: 'Fake cursor for pagination click tests.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['actor', 'site', 'task', 'scraper'],
-      context: [
-        { kind: 'path', path: 'src/core/ActorContext.ts', description: 'Extraction helpers available in ActorContext.' },
-        { kind: 'path', path: 'src/sites/example/example.actor.ts', description: 'Example actor usage of extraction.' }
-      ]
-    },
-    {
-      keywords: ['selector', 'wait', 'page adapter', 'raw puppeteer'],
-      context: [
-        { kind: 'path', path: 'tests/unit/interaction/PageAdapter.test.ts', description: 'PageAdapter behavior tests.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};

package/.ai/generators/interaction-behavior.ts

@@ -1,129 +0,0 @@
-export default {
-  id: 'interaction-behavior',
-  description: 'Modify human interaction behavior: ghost-cursor adapter, native interactor, typing, field clearing, forms, navigation, waits, and page adapter behavior.',
-  instructions: `
-Modify the interaction layer while preserving the HumanInteractor abstraction.
-
-Rules:
-- Keep HumanInteractor as the contract that site actors and forms use.
-- Keep ghost-cursor-specific details inside GhostCursorAdapter.
-- Keep NativePuppeteerInteractor deterministic and suitable for tests/fallbacks.
-- Human-like typing should remain key-by-key unless explicitly disabled.
-- Field clearing should remain opt-in through options and login defaults, not forced globally for all interactions.
-- If PageAdapter gains a method, update PuppeteerPageAdapter and FakePage where appropriate.
-- If FormFiller behavior changes, update Forms tests and any affected LoginFlow tests.
-- If typing timing changes, update HumanTyping tests with deterministic random/sleep functions.
-
-DO NOT put site-specific selectors or auth flow logic in the interaction layer.
-DO NOT introduce sleeps where selector waits or navigation waits are more precise.
-`.trim(),
-  output: {
-    pathTemplates: [
-      {
-        key: 'human-interactor',
-        pathTemplate: 'src/interaction/HumanInteractor.ts',
-        description: 'Human interaction interface and shared options.'
-      },
-      {
-        key: 'ghost-adapter',
-        pathTemplate: 'src/interaction/GhostCursorAdapter.ts',
-        description: 'ghost-cursor-backed interactor implementation.'
-      },
-      {
-        key: 'native-adapter',
-        pathTemplate: 'src/interaction/NativePuppeteerInteractor.ts',
-        description: 'Puppeteer-native interactor implementation.'
-      },
-      {
-        key: 'typing',
-        pathTemplate: 'src/interaction/HumanTyping.ts',
-        description: 'Typing timing and key-by-key typing implementation.'
-      },
-      {
-        key: 'field-clearer',
-        pathTemplate: 'src/interaction/FieldClearer.ts',
-        description: 'Field clearing strategies.'
-      },
-      {
-        key: 'forms',
-        pathTemplate: 'src/interaction/Forms.ts',
-        description: 'Form filling helper.'
-      },
-      {
-        key: 'page-adapter',
-        pathTemplate: 'src/interaction/PageAdapter.ts',
-        description: 'Page adapter when new selector/page operations are needed.'
-      },
-      {
-        key: 'tests',
-        pathTemplate: 'tests/unit/interaction/{{componentPascal}}.test.ts',
-        description: 'Focused tests for the changed interaction component.'
-      },
-      {
-        key: 'fake-page',
-        pathTemplate: 'tests/fixtures/FakePage.ts',
-        description: 'Update when PageAdapter or keyboard/page behavior changes.'
-      },
-      {
-        key: 'fake-cursor',
-        pathTemplate: 'tests/fixtures/FakeCursor.ts',
-        description: 'Update when cursor behavior or recorded calls change.'
-      }
-    ],
-    maxFiles: 10
-  },
-  parameters: {
-    component: {
-      description: 'Interaction component or behavior to edit, for example typing, cursor, forms, field clearing, page adapter, or navigation.',
-      required: true
-    },
-    instructions: {
-      description: 'Specific behavior, options, timing, selectors, or compatibility requirements.',
-      required: false
-    }
-  },
-  examples: [
-    'src/interaction/HumanInteractor.ts',
-    'src/interaction/GhostCursorAdapter.ts',
-    'src/interaction/HumanTyping.ts',
-    'src/interaction/FieldClearer.ts',
-    'tests/unit/interaction/HumanTyping.test.ts',
-    'tests/fixtures/FakePage.ts'
-  ],
-  context: [
-    { kind: 'path', path: 'src/interaction/HumanInteractor.ts', description: 'Interaction contract.' },
-    { kind: 'path', path: 'src/interaction/GhostCursorAdapter.ts', description: 'ghost-cursor interactor.' },
-    { kind: 'path', path: 'src/interaction/NativePuppeteerInteractor.ts', description: 'Puppeteer-native interactor.' },
-    { kind: 'path', path: 'src/interaction/HumanTyping.ts', description: 'Human typing implementation.' },
-    { kind: 'path', path: 'src/interaction/FieldClearer.ts', description: 'Field clearing implementation.' },
-    { kind: 'path', path: 'src/interaction/Forms.ts', description: 'Form helper.' },
-    { kind: 'path', path: 'src/interaction/PageAdapter.ts', description: 'Page wrapper.' },
-    { kind: 'path', path: 'src/interaction/Navigation.ts', description: 'Navigation helper.' },
-    { kind: 'path', path: 'src/interaction/Waits.ts', description: 'Wait profiles.' },
-    { kind: 'path', path: 'src/browser/PuppeteerLike.ts', description: 'Keyboard/page/browser types used by interactors and tests.' },
-    { kind: 'pattern', pattern: 'tests/unit/interaction/*.test.ts', description: 'Existing interaction tests.', limit: 10 },
-    { kind: 'path', path: 'tests/fixtures/FakePage.ts', description: 'Fake page fixture.' },
-    { kind: 'path', path: 'tests/fixtures/FakeCursor.ts', description: 'Fake cursor fixture.' }
-  ],
-  keywordContexts: [
-    {
-      keywords: ['login', 'auth', 'clearFieldBeforeTyping'],
-      context: [
-        { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Login fill steps consume form/interactor options.' },
-        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Login tests may need updates after interaction changes.' }
-      ]
-    },
-    {
-      keywords: ['runtime config', 'default typing', 'config'],
-      context: [
-        { kind: 'path', path: 'src/browser/RuntimeConfig.ts', description: 'Global interaction typing config.' },
-        { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Passes typing config to GhostCursorAdapter.' }
-      ]
-    }
-  ],
-  tooling: {
-    allowGetExistingCode: true,
-    allowFindFiles: true,
-    allowSearchRepo: true
-  }
-};