@epsilon-asi/actors 0.0.3 → 0.0.5

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

@@ -0,0 +1,80 @@
+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

@@ -0,0 +1,92 @@
+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

@@ -0,0 +1,102 @@
+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

@@ -0,0 +1,96 @@
+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

@@ -0,0 +1,129 @@
+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
+  }
+};

package/.ai/generators/site-actor.ts

@@ -0,0 +1,125 @@
+export default {
+  id: 'site-actor',
+  description: 'Create or update a website-specific actor, selector map, types, barrel exports, and focused unit tests.',
+  instructions: `
+Generate a site actor that follows the existing framework conventions.
+
+Rules:
+- Use defineActor from src/core/defineActor.ts.
+- Keep selectors in src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts.
+- Keep task input/output types in src/sites/{{siteKebab}}/{{siteKebab}}.types.ts.
+- Export the site through src/sites/{{siteKebab}}/index.ts and src/sites/index.ts.
+- Prefer context.nav, context.forms, context.cursor, context.extract, and context.pagination over raw Puppeteer APIs.
+- Use context.page.raw() only when the abstraction does not support the needed operation.
+- Never hard-code credentials or secrets.
+- If login is required, use defineLoginFlow and the typed LoginFlowDefinition shape.
+- If the task scrapes data, use Extractor/Pagination helpers before inventing new extraction logic.
+- Add or update focused unit tests when behavior is non-trivial.
+- Keep actor tasks small and named by what they do, for example scrapeDashboard or scrapeListings.
+- Update barrel exports when adding a new site.
+
+DO NOT INVENT selectors that were not supplied by the user unless the instructions explicitly say to make placeholders.
+DO NOT add CAPTCHA bypass, anti-bot evasion, or credential harvesting behavior.
+`.trim(),
+  output: {
+    pathTemplates: [
+      {
+        key: 'actor',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
+        description: 'The site actor with auth definition, hooks, and task implementations.'
+      },
+      {
+        key: 'selectors',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
+        description: 'Site-specific CSS selector constants grouped by page/flow.'
+      },
+      {
+        key: 'types',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.types.ts',
+        description: 'Task input/output types for this site.'
+      },
+      {
+        key: 'site-index',
+        pathTemplate: 'src/sites/{{siteKebab}}/index.ts',
+        description: 'Per-site barrel exports.'
+      },
+      {
+        key: 'sites-index',
+        pathTemplate: 'src/sites/index.ts',
+        description: 'Global sites barrel export; add this site export if needed.'
+      },
+      {
+        key: 'tests',
+        pathTemplate: 'tests/unit/sites/{{siteKebab}}.actor.test.ts',
+        description: 'Focused unit tests for task behavior or auth config when useful.'
+      }
+    ],
+    maxFiles: 6
+  },
+  parameters: {
+    site: {
+      description: 'The website/site name, for example Apple, Upwork, Example Marketplace, or Acme Dashboard.',
+      required: true
+    },
+    actorId: {
+      description: 'Actor id used at runtime. Defaults to the kebab-case site name when omitted.',
+      required: false
+    },
+    baseUrl: {
+      description: 'The site base URL, for example https://example.com.',
+      required: false
+    },
+    instructions: {
+      description: 'Specific login, task, selector, or scraping behavior to implement.',
+      required: false
+    }
+  },
+  examples: [
+    'src/sites/example/example.actor.ts',
+    'src/sites/example/example.selectors.ts',
+    'src/sites/example/example.types.ts',
+    'src/sites/example/index.ts',
+    'src/sites/index.ts'
+  ],
+  context: [
+    { kind: 'path', path: 'src/core/defineActor.ts', description: 'Helper used to define actors.' },
+    { kind: 'path', path: 'src/core/Actor.ts', description: 'Actor/task/hook contracts.' },
+    { kind: 'path', path: 'src/core/ActorContext.ts', description: 'Task context available to actor implementations.' },
+    { kind: 'path', path: 'src/sites/example/example.actor.ts', description: 'Canonical example actor.' },
+    { kind: 'path', path: 'src/sites/example/example.selectors.ts', description: 'Canonical selector map.' },
+    { kind: 'path', path: 'src/sites/example/example.types.ts', description: 'Canonical site task types.' },
+    { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Auth/login configuration types.' },
+    { kind: 'path', path: 'src/extraction/Extractor.ts', description: 'Reusable extraction helper.' },
+    { kind: 'path', path: 'src/extraction/Pagination.ts', description: 'Reusable pagination helper.' },
+    { kind: 'path', path: 'src/sites/index.ts', description: 'Global site export pattern.' }
+  ],
+  keywordContexts: [
+    {
+      keywords: ['login', 'auth', 'sign in', 'signin', 'multi-step', 'username', 'password'],
+      context: [
+        { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Login execution behavior.' },
+        { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Login config/test examples.' }
+      ]
+    },
+    {
+      keywords: ['scrape', 'extract', 'pagination', 'next page', 'table', 'href', 'jsonld'],
+      context: [
+        { kind: 'path', path: 'tests/unit/extraction/Extractor.test.ts', description: 'Extractor behavior examples.' },
+        { kind: 'path', path: 'tests/unit/extraction/Pagination.test.ts', description: 'Pagination behavior examples.' }
+      ]
+    },
+    {
+      keywords: ['form', 'type', 'click', 'navigation', 'wait', 'selector'],
+      context: [
+        { kind: 'path', path: 'src/interaction/Forms.ts', description: 'Form filler helper.' },
+        { kind: 'path', path: 'src/interaction/Navigation.ts', description: 'Navigation helper.' },
+        { kind: 'path', path: 'src/interaction/PageAdapter.ts', description: 'Page wrapper methods available to actors.' }
+      ]
+    }
+  ],
+  tooling: {
+    allowGetExistingCode: true,
+    allowFindFiles: true,
+    allowSearchRepo: true
+  }
+};