@epsilon-asi/actors 0.0.3 → 0.0.5

package/.ai/generators/_template.ts

@@ -0,0 +1,37 @@
+export const config = {
+  "description": "Describe what this generator should create.",
+  "instructions": "Explain the generation rules here.\n- what patterns to copy\n- what not to invent\n- what files to inspect when uncertain",
+  "output": {
+    "pathTemplate": "src/path/to/{{entityKebab}}.ts",
+    "maxFiles": 1
+  },
+  "parameters": {
+    "entity": {
+      "description": "Example parameter.",
+      "required": true
+    }
+  },
+  "examples": [
+    "src/path/to/example-one.ts",
+    "src/path/to/example-two.ts"
+  ],
+  "context": [
+    {
+      "kind": "path",
+      "path": "src/entities/{{entityKebab}}.entity.ts",
+      "required": false
+    },
+    {
+      "kind": "pattern",
+      "pattern": "*{{entityKebab}}*.service.ts",
+      "limit": 3
+    }
+  ],
+  "tooling": {
+    "allowGetExistingCode": true,
+    "allowFindFiles": true,
+    "allowSearchRepo": true
+  }
+}
+
+export default config;

package/.ai/generators/abstract.ts

@@ -0,0 +1,24 @@
+const abstract = {
+  "abstract": true,
+  "description": "Generate or update files based on the given instructions provided by the user.",
+  "instructions": "FIRST you must thoroughly search the codebase for all possible relevant code before proceeding to creating the output that the user as requested.\nIf the user doesn't specify some details, you must infer that based on patterns shown in similar objects or files. For example, if the user asks for an Entity, you must look at other entities and see how they are defined before defining yours. \nGenerate or update files based on the given instructions provided by the user.\nThis file must match structure, imports, decorator usage, route naming, constructor style, DTO references, and service interaction patterns used by other similar files.\nIf you are replacing a file, you must copy it EXACTLY as it is, and then ONLY changing what you are asked to change or add.\n\nRules:\n- You must clearly define property types\n- You must properly type functions  \n- Do not map or expose any sensitive properties such as passwords. All other properties are fair game.\n- If you go against patterns shown in other files, you must leave comments explaining why",
+  "output": {
+    "pathTemplates": [],
+    "maxFiles": 5
+  },
+  "parameters": {
+    "instructions": {
+      "description": "Guidelines for the agent to know how to define the files or code. i.e its purpose or use",
+      "required": true
+    }
+  },
+  "examples": [],
+  "context": [],
+  "tooling": {
+    "allowGetExistingCode": true,
+    "allowFindFiles": true,
+    "allowSearchRepo": true
+  }
+}
+
+export default abstract;

package/.ai/generators/actor-task-form-filler.ts

@@ -0,0 +1,140 @@
+export default {
+  id: 'actor-task-form-filler',
+  description: 'Add or update a site actor task that uses defineFormTask/defineFormFillerTask to fill listed fields and submit forms from typed input.',
+  instructions: `
+Generate a form-filler actor task using the core task generator helper.
+
+Rules:
+- Define the task with defineFormTask or defineFormFillerTask from src/core/Actor.ts.
+- Keep the task inside actor.tasks on an existing site actor.
+- Use typed input/output interfaces in src/sites/{{siteKebab}}/{{siteKebab}}.types.ts.
+- Keep selectors in src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts.
+- Prefer declarative field mapping via inputKey and use value resolvers only when needed.
+- Mark optional fields with required: false.
+- Use submit.waitForNavigation when submit triggers a page transition.
+- Use onComplete to map final output when the task should return data.
+- Keep actor logic site-specific; do not modify src/core unless the request explicitly requires framework changes.
+- Add focused unit tests that verify field fill order, optional-field behavior, submit click, and completion output.
+
+DO NOT call Puppeteer directly for form-filling flows that can be expressed with the form-task definition.
+DO NOT hard-code credentials or secrets.
+`.trim(),
+  output: {
+    pathTemplates: [
+      {
+        key: 'actor',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
+        description: 'Site actor task definition using defineFormTask/defineFormFillerTask.'
+      },
+      {
+        key: 'selectors',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
+        description: 'Form selectors used by the generated task.'
+      },
+      {
+        key: 'types',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.types.ts',
+        description: 'Input/output interfaces for the form task.'
+      },
+      {
+        key: 'tests',
+        pathTemplate: 'tests/unit/sites/{{siteKebab}}.{{taskName}}.test.ts',
+        description: 'Focused form-task behavior tests.'
+      }
+    ],
+    maxFiles: 4
+  },
+  parameters: {
+    site: {
+      description: 'Existing site actor name.',
+      required: true
+    },
+    taskName: {
+      description: 'Task name to add or update, for example submitContactForm or applyToJob.',
+      required: true
+    },
+    instructions: {
+      description: 'Form URL, selectors, field mapping, optional fields, submit behavior, and expected output.',
+      required: false
+    }
+  },
+  examples: [
+    'src/core/Actor.ts',
+    'src/sites/example/example.actor.ts',
+    'src/sites/example/example.selectors.ts',
+    'src/sites/example/example.types.ts',
+    'tests/unit/core/defineActor.test.ts'
+  ],
+  context: [
+    {
+      kind: 'path',
+      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
+      description: 'Actor that owns the form task.',
+      required: true
+    },
+    {
+      kind: 'path',
+      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
+      description: 'Form selectors used by the task.',
+      required: false
+    },
+    {
+      kind: 'path',
+      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.types.ts',
+      description: 'Typed task input/output contracts.',
+      required: false
+    },
+    {
+      kind: 'path',
+      path: 'src/core/Actor.ts',
+      description: 'defineFormTask and defineFormFillerTask definitions.'
+    },
+    {
+      kind: 'path',
+      path: 'src/core/ActorContext.ts',
+      description: 'Context services available to tasks and resolvers.'
+    },
+    {
+      kind: 'path',
+      path: 'tests/fixtures/makeContext.ts',
+      description: 'Context fixture for deterministic unit tests.'
+    },
+    {
+      kind: 'path',
+      path: 'tests/fixtures/FakePage.ts',
+      description: 'Fake page fixture for selector and navigation assertions.'
+    },
+    {
+      kind: 'path',
+      path: 'tests/fixtures/FakeCursor.ts',
+      description: 'Fake cursor fixture for typed/click assertions.'
+    }
+  ],
+  keywordContexts: [
+    {
+      keywords: ['optional', 'required false', 'nullable'],
+      context: [
+        {
+          kind: 'path',
+          path: 'src/core/Actor.ts',
+          description: 'Form task required-field semantics.'
+        }
+      ]
+    },
+    {
+      keywords: ['navigation', 'waitForNavigation', 'submit'],
+      context: [
+        {
+          kind: 'path',
+          path: 'src/core/Actor.ts',
+          description: 'Submit behavior and navigation wait handling.'
+        }
+      ]
+    }
+  ],
+  tooling: {
+    allowGetExistingCode: true,
+    allowFindFiles: true,
+    allowSearchRepo: true
+  }
+};

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

@@ -0,0 +1,122 @@
+export default {
+  id: 'actor-task',
+  description: 'Add or update a task on an existing site actor, including selectors, types, extraction logic, and tests.',
+  instructions: `
+Add or revise an actor task for an existing site.
+
+Rules:
+- Add the task to the actor.tasks object without breaking existing tasks.
+- Use explicit input and output types in the site's .types.ts file.
+- Use context.nav for URL/path navigation.
+- Use context.forms and context.cursor for interactions.
+- Use context.extract and context.pagination for scraping/extraction.
+- Put new selectors in the site's .selectors.ts file and keep names descriptive.
+- Normalize returned data into typed objects rather than returning raw DOM strings when the task output is known.
+- Add unit tests for branching behavior, extraction logic, and pagination when applicable.
+- Keep tests deterministic by using FakePage, FakeCursor, FakeCredentialsProvider, and makeContext where useful.
+
+DO NOT call Puppeteer directly unless the PageAdapter/Extractor abstractions cannot express the operation.
+DO NOT add broad sleeps when selector waits or navigation waits are more precise.
+`.trim(),
+  output: {
+    pathTemplates: [
+      {
+        key: 'actor',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
+        description: 'The site actor to update with the new or changed task.'
+      },
+      {
+        key: 'selectors',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
+        description: 'Selectors used by the task.'
+      },
+      {
+        key: 'types',
+        pathTemplate: 'src/sites/{{siteKebab}}/{{siteKebab}}.types.ts',
+        description: 'Task input and output types.'
+      },
+      {
+        key: 'tests',
+        pathTemplate: 'tests/unit/sites/{{siteKebab}}.{{taskName}}.test.ts',
+        description: 'Focused unit tests for the new task.'
+      }
+    ],
+    maxFiles: 4
+  },
+  parameters: {
+    site: {
+      description: 'Existing site actor name.',
+      required: true
+    },
+    taskName: {
+      description: 'Task name to add or update, for example scrapeDashboard, scrapeListings, downloadInvoices.',
+      required: true
+    },
+    instructions: {
+      description: 'Detailed behavior, selectors, inputs, outputs, and edge cases for the task.',
+      required: false
+    }
+  },
+  examples: [
+    'src/sites/example/example.actor.ts',
+    'src/sites/example/example.selectors.ts',
+    'src/sites/example/example.types.ts',
+    'tests/unit/extraction/Extractor.test.ts',
+    'tests/unit/extraction/Pagination.test.ts'
+  ],
+  context: [
+    {
+      kind: 'path',
+      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.actor.ts',
+      description: 'Existing actor that owns the task.',
+      required: true
+    },
+    {
+      kind: 'path',
+      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.selectors.ts',
+      description: 'Existing site selectors.',
+      required: false
+    },
+    {
+      kind: 'path',
+      path: 'src/sites/{{siteKebab}}/{{siteKebab}}.types.ts',
+      description: 'Existing site task types.',
+      required: false
+    },
+    { kind: 'path', path: 'src/core/Actor.ts', description: 'Task contract.' },
+    { kind: 'path', path: 'src/core/ActorContext.ts', description: 'Context helpers exposed to the task.' },
+    { kind: 'path', path: 'src/extraction/Extractor.ts', description: 'Reusable extraction methods.' },
+    { kind: 'path', path: 'src/extraction/Pagination.ts', description: 'Reusable pagination methods.' },
+    { kind: 'path', path: 'src/interaction/Navigation.ts', description: 'Navigation helper.' },
+    { kind: 'path', path: 'src/interaction/Forms.ts', description: 'Form helper.' },
+    { kind: 'path', path: 'tests/fixtures/makeContext.ts', description: 'ActorContext factory for unit tests.' },
+    { kind: 'path', path: 'tests/fixtures/FakePage.ts', description: 'Fake page fixture for task tests.' },
+    { kind: 'path', path: 'tests/fixtures/FakeCursor.ts', description: 'Fake cursor fixture for task tests.' }
+  ],
+  keywordContexts: [
+    {
+      keywords: ['pagination', 'next page', 'maxPages', 'deduplicate'],
+      context: [
+        { kind: 'path', path: 'tests/unit/extraction/Pagination.test.ts', description: 'Pagination test patterns.' }
+      ]
+    },
+    {
+      keywords: ['table', 'jsonld', 'json-ld', 'href', 'attribute', 'textList'],
+      context: [
+        { kind: 'path', path: 'tests/unit/extraction/Extractor.test.ts', description: 'Extractor test patterns.' }
+      ]
+    },
+    {
+      keywords: ['login', 'auth', 'requires auth'],
+      context: [
+        { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Actor auth config available before tasks run.' },
+        { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Auth is ensured before task execution.' }
+      ]
+    }
+  ],
+  tooling: {
+    allowGetExistingCode: true,
+    allowFindFiles: true,
+    allowSearchRepo: true
+  }
+};

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

@@ -0,0 +1,126 @@
+export default {
+  id: 'auth-core',
+  description: 'Modify authentication infrastructure: credentials providers, auth state detection, login flow execution, session snapshots, and auth tests.',
+  instructions: `
+Modify the authentication layer while preserving the standardized site login API.
+
+Rules:
+- LoginFlowDefinition and LoginStep types are public-ish contracts for site authors; preserve compatibility when possible.
+- Keep credentials abstracted through CredentialsProvider.
+- Never log raw passwords, tokens, cookies, or secret values.
+- Use redact() for logging sensitive credential metadata.
+- Keep AuthStateDetector focused on deciding whether the current profile/session is already logged in.
+- Keep LoginFlow responsible for executing simple and multi-step flows.
+- If login step semantics change, update LoginFlow.types.ts and LoginFlow.test.ts.
+- If field typing/clearing behavior changes, coordinate with Forms, FieldClearer, and HumanTyping.
+- If session snapshots change, keep them optional because existing Chrome profile state is the primary session store.
+
+DO NOT add CAPTCHA bypass, 2FA bypass, or anti-bot circumvention.
+DO NOT store credentials in session snapshots.
+`.trim(),
+  output: {
+    pathTemplates: [
+      {
+        key: 'login-types',
+        pathTemplate: 'src/auth/LoginFlow.types.ts',
+        description: 'Login flow public types and config shape.'
+      },
+      {
+        key: 'login-flow',
+        pathTemplate: 'src/auth/LoginFlow.ts',
+        description: 'Login flow execution behavior.'
+      },
+      {
+        key: 'credentials',
+        pathTemplate: 'src/auth/CredentialsProvider.ts',
+        description: 'Credential providers and credential references.'
+      },
+      {
+        key: 'detector',
+        pathTemplate: 'src/auth/AuthStateDetector.ts',
+        description: 'Logged-in state detection.'
+      },
+      {
+        key: 'session-store',
+        pathTemplate: 'src/auth/SessionStore.ts',
+        description: 'Optional session snapshot abstraction.'
+      },
+      {
+        key: 'auth-index',
+        pathTemplate: 'src/auth/index.ts',
+        description: 'Auth barrel exports.'
+      },
+      {
+        key: 'tests',
+        pathTemplate: 'tests/unit/auth/{{componentPascal}}.test.ts',
+        description: 'Auth unit tests for changed behavior.'
+      },
+      {
+        key: 'fake-credentials',
+        pathTemplate: 'tests/fixtures/FakeCredentialsProvider.ts',
+        description: 'Test credential provider fixture.'
+      }
+    ],
+    maxFiles: 8
+  },
+  parameters: {
+    component: {
+      description: 'Auth component or behavior to edit, for example LoginFlow, multi-step steps, credentials, auth detection, or session store.',
+      required: true
+    },
+    instructions: {
+      description: 'Specific auth behavior, config shape, step semantics, or failure handling to implement.',
+      required: false
+    }
+  },
+  examples: [
+    'src/auth/LoginFlow.types.ts',
+    'src/auth/LoginFlow.ts',
+    'src/auth/CredentialsProvider.ts',
+    'tests/unit/auth/LoginFlow.test.ts',
+    'tests/unit/auth/AuthStateDetector.test.ts'
+  ],
+  context: [
+    { kind: 'path', path: 'src/auth/LoginFlow.types.ts', description: 'Auth config and login step types.' },
+    { kind: 'path', path: 'src/auth/LoginFlow.ts', description: 'Login execution.' },
+    { kind: 'path', path: 'src/auth/CredentialsProvider.ts', description: 'Credential provider model.' },
+    { kind: 'path', path: 'src/auth/AuthStateDetector.ts', description: 'Auth state detection.' },
+    { kind: 'path', path: 'src/auth/SessionStore.ts', description: 'Optional session store.' },
+    { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'Ensures auth before tasks.' },
+    { kind: 'path', path: 'src/core/ActorContext.ts', description: 'Auth controller available to actors.' },
+    { kind: 'path', path: 'src/utils/redact.ts', description: 'Sensitive data redaction.' },
+    { kind: 'path', path: 'src/interaction/Forms.ts', description: 'Login fill steps use FormFiller.' },
+    { kind: 'path', path: 'src/interaction/FieldClearer.ts', description: 'Field clearing used by login fills.' },
+    { kind: 'path', path: 'src/interaction/HumanTyping.ts', description: 'Typing options for login fills.' },
+    { kind: 'path', path: 'tests/unit/auth/LoginFlow.test.ts', description: 'Login flow tests.' },
+    { kind: 'path', path: 'tests/unit/auth/AuthStateDetector.test.ts', description: 'Detector tests.' },
+    { kind: 'path', path: 'tests/fixtures/makeContext.ts', description: 'Test context factory.' }
+  ],
+  keywordContexts: [
+    {
+      keywords: ['multi-step', 'multistep', 'steps', 'waitForSelector', 'hook'],
+      context: [
+        { kind: 'path', path: 'src/sites/example/example.actor.ts', description: 'Example login config shape.' }
+      ]
+    },
+    {
+      keywords: ['logging', 'redact', 'secret', 'password', 'token'],
+      context: [
+        { kind: 'path', path: 'tests/unit/logging/redact.test.ts', description: 'Redaction test expectations.' },
+        { kind: 'path', path: 'src/logging/Logger.ts', description: 'Logger interface.' }
+      ]
+    },
+    {
+      keywords: ['browser profile', 'existing profile', 'cookies', 'localStorage'],
+      context: [
+        { kind: 'path', path: 'src/browser/RuntimeConfig.ts', description: 'Existing Chrome profile config model.' },
+        { kind: 'path', path: 'src/browser/BrowserSession.ts', description: 'Browser session behavior.' }
+      ]
+    }
+  ],
+  tooling: {
+    allowGetExistingCode: true,
+    allowFindFiles: true,
+    allowSearchRepo: true
+  }
+};

package/.ai/generators/browser-runtime.ts

@@ -0,0 +1,114 @@
+export default {
+  id: 'browser-runtime',
+  description: 'Modify Chrome launch/connect/runtime configuration, existing profile handling, remote debugging attach, profile validation, or session lifecycle.',
+  instructions: `
+Update browser runtime behavior while preserving the existing-profile and remote-debugging modes.
+
+Rules:
+- Existing-profile mode must use userDataDir and optional --profile-directory.
+- Existing-profile mode must use browser.defaultBrowserContext(), not a new isolated context.
+- If a profile is already running and fallback is enabled, connect to the configured local DevTools endpoint.
+- Remote-debugging mode should disconnect by default, not close the shared Chrome process.
+- Keep RuntimeConfig normalized so defaults are centralized and tests are deterministic.
+- Keep BrowserFactory testable through PuppeteerLike abstractions.
+- Validate paths and endpoint configuration in profileValidation.ts.
+- Add or update BrowserFactory tests for every launch/connect branch and error path.
+- Update CLI env parsing and README examples when runtime config surface changes.
+
+DO NOT add code that binds Chrome debugging to a public network interface by default.
+DO NOT create incognito/isolated browser contexts for existing-profile mode.
+`.trim(),
+  output: {
+    pathTemplates: [
+      {
+        key: 'runtime-config',
+        pathTemplate: 'src/browser/RuntimeConfig.ts',
+        description: 'Runtime config types, defaults, and normalization.'
+      },
+      {
+        key: 'browser-factory',
+        pathTemplate: 'src/browser/BrowserFactory.ts',
+        description: 'Chrome launch/connect/session preparation logic.'
+      },
+      {
+        key: 'browser-session',
+        pathTemplate: 'src/browser/BrowserSession.ts',
+        description: 'Close/disconnect behavior for launched vs connected browsers.'
+      },
+      {
+        key: 'validation',
+        pathTemplate: 'src/browser/profileValidation.ts',
+        description: 'Profile directory and remote debugging endpoint validation.'
+      },
+      {
+        key: 'cli',
+        pathTemplate: 'src/cli/run.ts',
+        description: 'Environment variable parsing for runtime config.'
+      },
+      {
+        key: 'tests',
+        pathTemplate: 'tests/unit/browser/BrowserFactory.test.ts',
+        description: 'Unit tests for browser launch/connect behavior.'
+      },
+      {
+        key: 'docs',
+        pathTemplate: 'README.md',
+        description: 'Runtime setup and debug endpoint documentation.'
+      }
+    ],
+    maxFiles: 7
+  },
+  parameters: {
+    feature: {
+      description: 'Browser/runtime feature to add or change, for example remote-debugging, existing profile validation, tab reuse, or timeouts.',
+      required: true
+    },
+    instructions: {
+      description: 'Specific behavior, env vars, error handling, and compatibility constraints.',
+      required: false
+    }
+  },
+  examples: [
+    'src/browser/RuntimeConfig.ts',
+    'src/browser/BrowserFactory.ts',
+    'src/browser/BrowserSession.ts',
+    'src/browser/profileValidation.ts',
+    'tests/unit/browser/BrowserFactory.test.ts'
+  ],
+  context: [
+    { kind: 'path', path: 'src/browser/RuntimeConfig.ts', description: 'Runtime config model and normalization.' },
+    { kind: 'path', path: 'src/browser/BrowserFactory.ts', description: 'Launch/connect implementation.' },
+    { kind: 'path', path: 'src/browser/BrowserSession.ts', description: 'Session lifecycle behavior.' },
+    { kind: 'path', path: 'src/browser/profileValidation.ts', description: 'Validation helpers.' },
+    { kind: 'path', path: 'src/browser/PuppeteerLike.ts', description: 'Testable Puppeteer interfaces.' },
+    { kind: 'path', path: 'src/core/ActorRunner.ts', description: 'How BrowserFactory is invoked.' },
+    { kind: 'path', path: 'src/cli/run.ts', description: 'CLI runtime config construction.' },
+    { kind: 'path', path: 'tests/unit/browser/BrowserFactory.test.ts', description: 'Existing browser runtime tests.' }
+  ],
+  keywordContexts: [
+    {
+      keywords: ['cli', 'env', 'environment variable', 'CHROME_USER_DATA_DIR', 'CHROME_REMOTE_DEBUGGING_PORT'],
+      context: [
+        { kind: 'path', path: 'README.md', description: 'CLI/runtime docs that should remain accurate.' }
+      ]
+    },
+    {
+      keywords: ['actor runner', 'cleanup', 'close', 'disconnect'],
+      context: [
+        { kind: 'path', path: 'tests/unit/core/ActorRunner.test.ts', description: 'Runner cleanup behavior tests.' }
+      ]
+    },
+    {
+      keywords: ['typing', 'interaction', 'cursor'],
+      context: [
+        { kind: 'path', path: 'src/interaction/HumanTyping.ts', description: 'Interaction config nested in RuntimeConfig.' },
+        { kind: 'path', path: 'src/interaction/GhostCursorAdapter.ts', description: 'Runtime config is passed into interactor construction.' }
+      ]
+    }
+  ],
+  tooling: {
+    allowGetExistingCode: true,
+    allowFindFiles: true,
+    allowSearchRepo: true
+  }
+};

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

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