{
  "schema_version": "1.0",
  "name": "solvotix-agent-entrypoint",
  "language": "en",
  "audience": "autonomous-coding-agent",
  "status": "live",
  "resources": {
    "html_guide": "https://solvotix.net/ai-first/agent-guide",
    "raw_markdown": "https://solvotix.net/ai-first/agent-guide.md",
    "openapi": "https://backend.solvotix.org/v3/api-docs",
    "swagger": "https://backend.solvotix.org/swagger-ui/index.html",
    "api_base": "https://backend.solvotix.org"
  },
  "read_order": [
    "structured_manifest",
    "raw_markdown",
    "openapi",
    "project_local_conventions"
  ],
  "authentication": {
    "provider": "Solvotix API user",
    "identity_type": "machine",
    "scheme": "bearer",
    "token_type": "long-lived tenant-bound API token",
    "token_prefix": "sat_",
    "header": "Authorization",
    "value_format": "Bearer sat_<TOKEN>",
    "runtime_interactive_login_required": false,
    "browser_usage_forbidden": true,
    "create_system_url": "https://portal.solvotix.org/login",
    "create_api_user_url": "https://portal.solvotix.org/home/settings#system-users",
    "plaintext_token_visibility": "creation-or-rotation-response-only"
  },
  "tenant_context": {
    "source": "tenant selected when API user is created",
    "header": "Tenant",
    "header_recommended": true,
    "derived_from_token_when_omitted": true,
    "mismatch_result": "401 Unauthorized",
    "token_belongs_to_tenants": "exactly-one"
  },
  "openapi_policy": {
    "authoritative_for": [
      "paths",
      "methods",
      "parameters",
      "request_schemas",
      "response_schemas",
      "documented_status_codes"
    ],
    "on_conflict": "stop-and-report",
    "invent_missing_fields": false
  },
  "physical_command_policy": {
    "http_success_means": "accepted-or-queued",
    "http_success_confirms_physical_completion": false,
    "automatic_retry": false,
    "verification_sources": [
      "tenant_queue",
      "device_queue",
      "gateway_queue",
      "events",
      "current_device_state"
    ],
    "allowed_reported_states": [
      "requested",
      "queued",
      "delivered",
      "confirmed",
      "failed",
      "unknown"
    ]
  },
  "risk_classes": {
    "read_only": {
      "approval": "not-required-by-default",
      "examples": ["inventory", "state", "history", "metering", "queues"]
    },
    "reversible": {
      "approval": "confirm-target-and-bounds",
      "examples": ["temperature-target", "ordinary-short-pulse"]
    },
    "security_sensitive": {
      "approval": "explicit-required",
      "examples": ["access-codes", "users", "permissions"]
    },
    "destructive": {
      "approval": "explicit-confirmation-required",
      "examples": ["delete-device", "delete-tenant", "delete-all-codes", "delete-queue-data"]
    },
    "ownership_changing": {
      "approval": "explicit-required",
      "examples": ["claim-gateway", "claim-device"]
    },
    "operationally_dangerous": {
      "approval": "purpose-safe-conditions-and-explicit-approval-required",
      "examples": ["persistent-relay", "persistent-lock", "wifi-change", "firmware-update"]
    }
  },
  "discovery_sequence": [
    "GET /api/gateways",
    "GET /api/sensor",
    "GET /api/gateways/{gatewayId}/sensors",
    "GET /api/sensor/{deviceId}/pairings"
  ],
  "verification_endpoints": {
    "tenant_queue": "GET /api/gateways/getqueue",
    "device_queue": "GET /api/gateways/queue/device/{deviceId}",
    "gateway_queue": "GET /api/gateways/{gatewayId}/gwqueue",
    "tenant_events": "GET /api/events",
    "device_events": "GET /api/events/sensor/{sensorId}",
    "room_events": "GET /api/events/byRoom/{roomId}"
  },
  "forbidden_secret_output": [
    "solvotix_sat_api_token",
    "private_key",
    "session_cookie",
    "wifi_password",
    "smart_lock_access_code",
    "any_internal_api_token"
  ],
  "api_user_lifecycle": {
    "managed_by": "authenticated regular user through Solvotix portal",
    "management_url": "https://portal.solvotix.org/home/settings#system-users",
    "api_user_can_manage_api_users": false,
    "rotate_invalidates_old_token_immediately": true,
    "revoked_token_result": "401 Unauthorized",
    "scopes_supported": false,
    "access_level": "normal authenticated access within bound tenant"
  },
  "token_storage": {
    "permitted": ["secrets-manager", "protected-server-environment-variable"],
    "forbidden": ["browser-code", "git", "url", "logs", "analytics", "error-reports"],
    "on_exposure": "rotate-immediately"
  }
}