Add AgentAd ad schemas as a LogicSRC primitive (#10)

* Add AgentAd ad schemas as a LogicSRC primitive

AgentAd is a disclosed, agent-readable advertising contract for CLI tools
and AI agents. LogicSRC owns the canonical schemas; cl1s.tech is the
reference network built on them.

- packages/schemas: agentad-{ad,placement,ad-request,ad-response,
  impression,click,campaign} schemas (id under schemas.logicsrc.com) +
  ad/placement fixtures, exported from @logicsrc/schemas
- packages/validators: register the 7 agentad kinds, wire fixture
  validation, add tests (disclosure.sponsored must be true)
- docs/agentad.md: the AgentAd spec
- README: list AgentAd under v1 priorities

Validators build clean; all fixtures validate; vitest 4/4 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Prepare @logicsrc/schemas for npm publish

Add license, repository, homepage, keywords, publishConfig (public),
and a package README covering both the logicsrc-* core schemas and the
agentad-* family.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

packages/schemas/schemas/agentad-ad-request.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-ad-request.schema.json",
+  "title": "AgentAd Ad Request",
+  "description": "A request from a CLI/agent for an ad to fill a placement, with optional runtime context for relevance.",
+  "type": "object",
+  "required": ["type", "version", "placement_id"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.ad_request" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "placement_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "publisher_did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
+    "consumer": {
+      "type": "string",
+      "enum": ["human", "agent"],
+      "description": "Who will read the ad. Agents SHOULD receive machine_readable payloads and clear disclosure."
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tool": { "type": "string", "description": "Host tool identifier, e.g. 'claude-code'." },
+        "keywords": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "language": { "type": "string" },
+        "locale": { "type": "string" }
+      }
+    },
+    "format_override": { "type": "string", "enum": ["text", "markdown", "ansi", "banner", "json"] },
+    "count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }
+  }
+}

packages/schemas/schemas/agentad-ad-response.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-ad-response.schema.json",
+  "title": "AgentAd Ad Response",
+  "description": "The network's response to an ad request: zero or more filled ads plus signed tracking tokens for impression/click events.",
+  "type": "object",
+  "required": ["type", "version", "request_id", "ads"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.ad_response" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "request_id": { "type": "string", "minLength": 1 },
+    "ads": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["ad", "impression_token"],
+        "additionalProperties": false,
+        "properties": {
+          "ad": { "type": "object", "description": "An agentad.ad document; validate separately against agentad-ad.schema.json." },
+          "impression_token": { "type": "string", "minLength": 1, "description": "Opaque token to confirm the impression and to mint a click token." },
+          "rendered": { "type": "string", "description": "Server-rendered representation in the requested format." }
+        }
+      }
+    },
+    "no_fill_reason": {
+      "type": "string",
+      "enum": ["no_inventory", "frequency_capped", "blocked_category", "invalid_request"]
+    }
+  }
+}

packages/schemas/schemas/agentad-ad.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-ad.schema.json",
+  "title": "AgentAd Ad",
+  "description": "A single advertising unit served to CLI tools and AI agents. Ads MUST be disclosed and SHOULD carry a machine-readable payload so agents can reason about them.",
+  "type": "object",
+  "required": ["type", "version", "id", "advertiser_did", "format", "title", "url", "disclosure"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.ad" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "id": { "$ref": "#/$defs/id" },
+    "campaign_id": { "$ref": "#/$defs/id" },
+    "advertiser_did": { "$ref": "#/$defs/did" },
+    "format": {
+      "type": "string",
+      "enum": ["text", "markdown", "ansi", "banner", "json"],
+      "description": "Render format. 'json' is the agent-native structured format; 'ansi'/'banner' target human CLI surfaces."
+    },
+    "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "body": { "type": "string", "maxLength": 2000 },
+    "url": { "type": "string", "format": "uri" },
+    "cta": { "type": "string", "maxLength": 60, "description": "Call to action label, e.g. 'Install' or 'Read docs'." },
+    "disclosure": {
+      "type": "object",
+      "description": "Transparency contract. Every ad is labeled as sponsored so humans and agents can distinguish it from organic output.",
+      "required": ["sponsored", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "sponsored": { "const": true },
+        "label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "Sponsored" },
+        "advertiser_name": { "type": "string", "maxLength": 120 }
+      }
+    },
+    "machine_readable": {
+      "type": "object",
+      "description": "Optional structured payload an agent can parse instead of (or alongside) the rendered text.",
+      "additionalProperties": true
+    },
+    "targeting": { "$ref": "#/$defs/targeting" },
+    "media": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ansi_art": { "type": "string", "description": "Pre-rendered ANSI/ASCII art for banner format." },
+        "icon": { "type": "string", "format": "uri" }
+      }
+    },
+    "pricing": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "model": { "type": "string", "enum": ["cpm", "cpc", "cpa", "flat"] },
+        "bid": { "type": "number", "minimum": 0 },
+        "currency": { "type": "string", "minLength": 2, "maxLength": 12 }
+      }
+    },
+    "expires_at": { "type": "string", "format": "date-time" }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$", "minLength": 1, "maxLength": 64 },
+    "did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
+    "targeting": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "surfaces": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["cli", "tui", "agent", "ci"] },
+          "uniqueItems": true
+        },
+        "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+        "tools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true, "description": "Host CLI/agent identifiers to target, e.g. 'claude-code', 'gh'." },
+        "languages": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "exclude_keywords": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    }
+  }
+}

packages/schemas/schemas/agentad-campaign.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-campaign.schema.json",
+  "title": "AgentAd Campaign",
+  "description": "An advertiser campaign grouping one or more ads under a shared budget, schedule, and targeting policy.",
+  "type": "object",
+  "required": ["type", "version", "id", "advertiser_did", "name", "budget"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.campaign" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$", "minLength": 1, "maxLength": 64 },
+    "advertiser_did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "status": { "type": "string", "enum": ["draft", "active", "paused", "completed"], "default": "draft" },
+    "budget": {
+      "type": "object",
+      "required": ["total", "currency"],
+      "additionalProperties": false,
+      "properties": {
+        "total": { "type": "number", "minimum": 0 },
+        "daily_cap": { "type": "number", "minimum": 0 },
+        "currency": { "type": "string", "minLength": 2, "maxLength": 12 }
+      }
+    },
+    "schedule": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "start_at": { "type": "string", "format": "date-time" },
+        "end_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "ad_ids": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+      "uniqueItems": true
+    }
+  }
+}

packages/schemas/schemas/agentad-click.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-click.schema.json",
+  "title": "AgentAd Click",
+  "description": "A consumer action on an ad (a click, install, or conversion). For agents, 'action' records the structured intent taken.",
+  "type": "object",
+  "required": ["type", "version", "click_token", "ad_id", "occurred_at"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.click" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "click_token": { "type": "string", "minLength": 1 },
+    "ad_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "placement_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "action": {
+      "type": "string",
+      "enum": ["click", "open_url", "copy_command", "install", "convert"],
+      "default": "click"
+    },
+    "consumer": { "type": "string", "enum": ["human", "agent"] },
+    "occurred_at": { "type": "string", "format": "date-time" }
+  }
+}

packages/schemas/schemas/agentad-impression.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-impression.schema.json",
+  "title": "AgentAd Impression",
+  "description": "A confirmed display of an ad. Recorded only after the ad was actually rendered to the consumer.",
+  "type": "object",
+  "required": ["type", "version", "impression_token", "ad_id", "occurred_at"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.impression" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "impression_token": { "type": "string", "minLength": 1 },
+    "ad_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "placement_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
+    "consumer": { "type": "string", "enum": ["human", "agent"] },
+    "occurred_at": { "type": "string", "format": "date-time" }
+  }
+}

packages/schemas/schemas/agentad-placement.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/agentad-placement.schema.json",
+  "title": "AgentAd Placement",
+  "description": "A slot registered by a publisher (a CLI tool or agent) where AgentAd units may be rendered.",
+  "type": "object",
+  "required": ["type", "version", "id", "publisher_did", "surface", "accepted_formats"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "agentad.placement" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$", "minLength": 1, "maxLength": 64 },
+    "publisher_did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
+    "surface": { "type": "string", "enum": ["cli", "tui", "agent", "ci"] },
+    "accepted_formats": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "enum": ["text", "markdown", "ansi", "banner", "json"] },
+      "uniqueItems": true
+    },
+    "dimensions": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_width": { "type": "integer", "minimum": 1, "description": "Max columns for text/ansi rendering." },
+        "max_lines": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "context_tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Keywords describing the host context, used for relevance matching."
+    },
+    "frequency_cap": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_per_session": { "type": "integer", "minimum": 0 },
+        "max_per_day": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "allow_categories": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "block_categories": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+  }
+}