Feature: Actor add CLI uses YAML-first persistence path
  As a developer
  I want `agents actor add` to route through ActorRegistry.upsert_actor() with yaml_text
  So that the original YAML text, schema_version, and compiled_metadata
  are preserved in the database while all CLI flags are honoured

  Scenario: Actor add calls registry.upsert_actor() with raw yaml_text
    Given an actor CLI runner
    And I have an actor YAML-only config file
    When I run actor add via registry yaml-first path
    Then registry.upsert_actor() should be called with the raw yaml text

  Scenario: Actor add with --update flag calls registry.upsert_actor() with update_existing
    Given an actor CLI runner
    And I have an actor JSON config file
    When I run actor add with update flag via yaml-first path
    Then registry.upsert_actor() should be called with update=True

  Scenario: Actor add preserves yaml_text for YAML config files
    Given an actor CLI runner
    And I have an actor YAML-only config file
    When I run actor add via registry yaml-first path
    Then registry.upsert_actor() should receive the original yaml text content

  Scenario: Actor add preserves yaml_text for JSON config files
    Given an actor CLI runner
    And I have an actor JSON config file
    When I run actor add via registry yaml-first path
    Then registry.upsert_actor() should be called with the raw yaml text

  Scenario: Actor add with --set-default sets actor as default
    Given an actor CLI runner
    And I have an actor YAML-only config file
    When I run actor add with set-default flag via yaml-first path
    Then registry.upsert_actor() should be called with set_default=True

  Scenario: Actor add with --option applies option overrides
    Given an actor CLI runner
    And I have an actor YAML-only config file
    When I run actor add with option override via yaml-first path
    Then registry.upsert_actor() should be called with option_overrides containing the override