me3-protocol 2.1.0 → 2.3.0

package/README.md

@@ -1,115 +1,126 @@
 # me3 Protocol (me.json)
 
-The **me3 Protocol** (`me.json`) is a minimal standard for portable personal websites.
+**The place machines check before acting on a person.**
 
-It treats your online identity as a **"Digital Business Card"**—a single JSON file that makes you discoverable by both humans and AI agents, without locking you into a specific platform.
+`me.json` is a minimal protocol that lets you declare what actions AI agents and services can take on your behalf—and how.
 
-## Why it exists (brief)
+## The Problem
 
-People increasingly ask AI to _find_ a person (to hire, collaborate with, or learn from). Scraping arbitrary personal sites is a failure mode for agents: it’s brittle, slow, and ambiguous. `me.json` is a small, predictable identity endpoint that makes discovery and summarization reliable.
+Machines are already making decisions about people:
 
-## 1. The Specification
+- "Should I book a meeting with this person?"
+- "Can I subscribe them to updates?"
+- "How should I introduce them?"
 
-### File Location & Discovery
+Without an authoritative source, they guess. They scrape. They get it wrong.
 
-To be compliant, your `me.json` file must be hosted at one of the following locations (in order of priority):
+Schema.org describes _pages_. `me.json` declares _people_—their identity, their preferences, and their **intents**.
 
-1.  **Primary**: `https://yourdomain.com/me.json`
-2.  **Fallback**: `https://yourdomain.com/.well-known/me`
+## The Solution: Intents
 
-### Transport & Security
+The core of `me.json` is the `intents` object—machine-readable declarations of what visitors and agents can do:
 
-- **HTTPS Only**: The file must be served over a secure connection.
-- **CORS (Cross-Origin Resource Sharing)**: You **MUST** serve the file with the following header:
-  ```http
-  Access-Control-Allow-Origin: *
-  ```
-  **Why?** This ensures that AI agents running in browsers (e.g., Chrome extensions, web-based assistants) can read your identity file even if they are running on a different domain. Without this, your digital business card is invisible to the tools that help people find you.
+```json
+{
+  "version": "0.1",
+  "name": "Jane Doe",
+  "bio": "Creative Director at Studio X",
+  "intents": {
+    "subscribe": {
+      "enabled": true,
+      "title": "Design Weekly",
+      "description": "Curated design links every Sunday",
+      "frequency": "weekly"
+    },
+    "book": {
+      "enabled": true,
+      "title": "30-min Consultation",
+      "description": "Let's discuss your project",
+      "duration": 30,
+      "url": "https://cal.com/janedoe"
+    }
+  }
+}
+```
 
-### Content Type
+**Without `me.json`**: An AI asked "Can I book a call with Jane?" has to guess, scrape her site, or fail.
 
-The file should be served with `application/json` content type.
+**With `me.json`**: The AI reads `intents.book`, confirms it's enabled, and knows exactly where to send the user.
 
-## 2. The Schema
+That's the protocol's value: **authority before action**.
 
-Your `me.json` defines who you are and where to find you. It is strictly typed to ensure compatibility across all readers.
+## Supported Intents
 
-### Core Structure (`Me3Profile`)
+| Intent      | Purpose                      | Key Fields                                           |
+| :---------- | :--------------------------- | :--------------------------------------------------- |
+| `subscribe` | Newsletter/updates signup    | `enabled`, `title`, `description`, `frequency`       |
+| `book`      | Meeting/consultation booking | `enabled`, `title`, `description`, `url`, `duration` |
 
-| Field      | Type     | Required | Description                                       |
-| :--------- | :------- | :------- | :------------------------------------------------ |
-| `version`  | `string` | **Yes**  | Protocol version (currently "0.1").               |
-| `name`     | `string` | **Yes**  | Your display name.                                |
-| `handle`   | `string` | No       | Your preferred username/handle.                   |
-| `bio`      | `string` | No       | Short bio (max 500 chars).                        |
-| `avatar`   | `string` | No       | URL to your profile picture.                      |
-| `banner`   | `string` | No       | URL to a header/banner image.                     |
-| `location` | `string` | No       | Freeform location string (e.g. "Remote").         |
-| `links`    | `object` | No       | Social links (website, github, twitter, etc.).    |
-| `buttons`  | `array`  | No       | Primary actions (e.g., "Book Call", "Subscribe"). |
-| `pages`    | `array`  | No       | Custom content pages.                             |
-| `footer`   | `object` | No       | Custom footer config (or `false` to hide).        |
+More intents (like `contact` for routing preferences) are planned.
 
-### Examples
+---
 
-Minimal:
+## Full Schema
 
-```json
-{
-  "version": "0.1",
-  "name": "Jane Doe",
-  "handle": "janedoe",
-  "bio": "Building the open web. Creative Director at Studio X.",
-  "location": "Berlin, Germany",
-  "avatar": "https://example.com/jane.jpg",
-  "links": {
-    "website": "https://janedoe.com",
-    "twitter": "janedoe",
-    "github": "janedoe"
-  },
-  "buttons": [
-    {
-      "text": "Hire Me",
-      "url": "https://cal.com/janedoe",
-      "style": "primary"
-    }
-  ]
-}
-```
+Beyond intents, `me.json` includes identity and presentation fields:
+
+| Field      | Type     | Required | Description                                          |
+| :--------- | :------- | :------- | :--------------------------------------------------- |
+| `version`  | `string` | **Yes**  | Protocol version (currently `"0.1"`).                |
+| `name`     | `string` | **Yes**  | Display name.                                        |
+| `handle`   | `string` | No       | Preferred username/handle.                           |
+| `bio`      | `string` | No       | Short bio (max 500 chars).                           |
+| `avatar`   | `string` | No       | Profile picture URL.                                 |
+| `banner`   | `string` | No       | Header/banner image URL.                             |
+| `location` | `string` | No       | Freeform location (e.g., "Berlin" or "Remote").      |
+| `links`    | `object` | No       | Social links (`website`, `github`, `twitter`, etc.). |
+| `buttons`  | `array`  | No       | Call-to-action buttons for human visitors.           |
+| `pages`    | `array`  | No       | Custom content pages (markdown).                     |
+| `intents`  | `object` | No       | Machine-actionable declarations (see above).         |
+| `footer`   | `object` | No       | Footer config (or `false` to hide).                  |
+
+See [`examples/full.json`](./examples/full.json) for a complete example.
+
+---
+
+## Hosting & Discovery
+
+Your `me.json` must be publicly accessible at:
 
-More complete examples live in [`examples/`](./examples/), including [`examples/simple.json`](./examples/simple.json) and [`examples/full.json`](./examples/full.json).
+1. **Primary**: `https://yourdomain.com/me.json`
+2. **Fallback**: `https://yourdomain.com/.well-known/me`
 
-## 3. What it is NOT
+### Requirements
 
-- **NOT Authentication**: `me.json` is public data. It does not handle logins, passwords, or private keys.
-- **NOT a Social Network**: There is no "feed", no "likes", and no central server. You own your data.
-- **NOT a Platform**: You can host this file on GitHub Pages, Vercel, WordPress, or your own server.
-- **NOT Reputation / Ranking**: No scoring, ranking, endorsements, verification, or algorithmic ordering.
+- **HTTPS only**
+- **CORS enabled**: Serve with `Access-Control-Allow-Origin: *` so browser-based agents can read it
+- **Content-Type**: `application/json`
 
-## 4. Guardrails & versioning
+---
 
-- **Current version**: `0.1` (see `version` field). Validators in this repo currently require `version === "0.1"`.
-- **Backwards compatibility**: `0.1` is intended to stay stable. Changes should be additive and conservative.
-- **Extensions**: top-level fields are intentionally strict. If you need custom keys, prefer placing them under `links` (e.g. `"links": { "mastodon": "...", "custom": "..." }`) until the protocol defines a first-class place for extensions.
+## What me.json is NOT
 
-## 5. Usage
+- **NOT authentication** — This is public data. No logins, no private keys.
+- **NOT a social network** — No feeds, no likes, no central server.
+- **NOT a platform** — Host it anywhere: GitHub Pages, Vercel, your own server.
+- **NOT reputation** — No scores, rankings, or verification.
 
-### For Developers
+---
 
-You can use this package to validate `me.json` files in your applications.
+## Usage
+
+### Install
 
 ```bash
 npm install me3-protocol
 ```
 
+### Validate
+
 ```typescript
 import { validateProfile, parseMe3Json } from "me3-protocol";
 
-// Validate an object
-const result = validateProfile(myProfileData);
-
-// Parse and validate a string
-const result = parseMe3Json(jsonString);
+const result = validateProfile(profileData);
 
 if (!result.valid) {
   console.error(result.errors);
@@ -118,4 +129,12 @@ if (!result.valid) {
 
 ### JSON Schema
 
-A standard JSON Schema is available in [schema.json](./schema.json) for non-TypeScript implementations.
+A standard JSON Schema is available at [`schema.json`](./schema.json).
+
+---
+
+## Versioning
+
+- **Current version**: `0.1`
+- **Stability**: Additive changes only. Breaking changes require a version bump.
+- **Extensions**: Custom fields should go under `links` until the protocol defines extension points.

package/dist/index.d.ts

@@ -47,6 +47,68 @@ export interface Me3Footer {
     /** Optional custom footer link */
     link?: Me3FooterLink;
 }
+/**
+ * Newsletter subscription intent.
+ * When enabled, the site accepts email subscriptions via POST /api/subscribe
+ */
+export interface Me3IntentSubscribe {
+    /** Whether newsletter signups are enabled */
+    enabled: boolean;
+    /** Newsletter title (e.g., "AI Weekly") - for agents to present context */
+    title?: string;
+    /** What subscribers will receive - for agents to explain the value */
+    description?: string;
+    /** How often subscribers will hear from you */
+    frequency?: "daily" | "weekly" | "monthly" | "irregular";
+}
+/**
+ * Availability windows for booking.
+ * Defines when the person is available for meetings.
+ */
+export interface Me3BookingAvailability {
+    /** Timezone for the availability windows (e.g., "America/New_York") */
+    timezone: string;
+    /** Weekly availability windows by day */
+    windows: {
+        monday?: string[];
+        tuesday?: string[];
+        wednesday?: string[];
+        thursday?: string[];
+        friday?: string[];
+        saturday?: string[];
+        sunday?: string[];
+    };
+}
+/**
+ * Booking/scheduling intent.
+ * Declares that the person accepts meeting bookings.
+ */
+export interface Me3IntentBook {
+    /** Whether booking is enabled */
+    enabled: boolean;
+    /** Meeting title (e.g., "30-min Consultation") */
+    title?: string;
+    /** What the meeting is about */
+    description?: string;
+    /** Meeting duration in minutes */
+    duration?: number;
+    /** Booking provider (e.g., "cal.com", "calendly") - for external providers */
+    provider?: string;
+    /** Direct booking URL - for external booking systems */
+    url?: string;
+    /** Availability windows - for native me3 booking */
+    availability?: Me3BookingAvailability;
+}
+/**
+ * Intents object - declares what actions visitors/agents can take.
+ * This is the machine-readable API contract for interacting with a person.
+ */
+export interface Me3Intents {
+    /** Newsletter subscription */
+    subscribe?: Me3IntentSubscribe;
+    /** Meeting booking */
+    book?: Me3IntentBook;
+}
 export interface Me3Profile {
     /** Protocol version */
     version: string;
@@ -74,6 +136,11 @@ export interface Me3Profile {
      * - `false`: hide footer (renderer may restrict this to Pro tiers)
      */
     footer?: Me3Footer | false;
+    /**
+     * Intents - machine-readable actions that visitors/agents can take.
+     * This is the API contract for interacting with the person.
+     */
+    intents?: Me3Intents;
 }
 export interface ValidationError {
     field: string;

package/dist/index.js

@@ -21,6 +21,9 @@ const VALID_BUTTON_STYLES = ["primary", "secondary", "outline"];
 const URL_REGEX = /^https?:\/\/.+/i;
 const MAX_FOOTER_TEXT_LENGTH = 200;
 const MAX_FOOTER_LINK_TEXT_LENGTH = 60;
+const MAX_INTENT_TITLE_LENGTH = 100;
+const MAX_INTENT_DESCRIPTION_LENGTH = 300;
+const VALID_FREQUENCIES = ["daily", "weekly", "monthly", "irregular"];
 /**
  * Validate a me3 profile object
  */
@@ -184,7 +187,10 @@ function validateProfile(data) {
             const footer = profile.footer;
             if (footer.text !== undefined) {
                 if (typeof footer.text !== "string") {
-                    errors.push({ field: "footer.text", message: "Footer text must be a string" });
+                    errors.push({
+                        field: "footer.text",
+                        message: "Footer text must be a string",
+                    });
                 }
                 else if (footer.text.length > MAX_FOOTER_TEXT_LENGTH) {
                     errors.push({
@@ -195,12 +201,18 @@ function validateProfile(data) {
             }
             if (footer.link !== undefined) {
                 if (typeof footer.link !== "object" || footer.link === null) {
-                    errors.push({ field: "footer.link", message: "Footer link must be an object" });
+                    errors.push({
+                        field: "footer.link",
+                        message: "Footer link must be an object",
+                    });
                 }
                 else {
                     const link = footer.link;
                     if (!link.text || typeof link.text !== "string") {
-                        errors.push({ field: "footer.link.text", message: "Footer link text is required" });
+                        errors.push({
+                            field: "footer.link.text",
+                            message: "Footer link text is required",
+                        });
                     }
                     else if (link.text.length > MAX_FOOTER_LINK_TEXT_LENGTH) {
                         errors.push({
@@ -209,7 +221,10 @@ function validateProfile(data) {
                         });
                     }
                     if (!link.url || typeof link.url !== "string") {
-                        errors.push({ field: "footer.link.url", message: "Footer link URL is required" });
+                        errors.push({
+                            field: "footer.link.url",
+                            message: "Footer link URL is required",
+                        });
                     }
                     else if (!URL_REGEX.test(link.url)) {
                         errors.push({
@@ -262,6 +277,218 @@ function validateProfile(data) {
             });
         }
     }
+    // Intents (optional)
+    if (profile.intents !== undefined) {
+        if (typeof profile.intents !== "object" || profile.intents === null) {
+            errors.push({ field: "intents", message: "Intents must be an object" });
+        }
+        else {
+            const intents = profile.intents;
+            // Validate subscribe intent
+            if (intents.subscribe !== undefined) {
+                if (typeof intents.subscribe !== "object" ||
+                    intents.subscribe === null) {
+                    errors.push({
+                        field: "intents.subscribe",
+                        message: "Subscribe intent must be an object",
+                    });
+                }
+                else {
+                    const subscribe = intents.subscribe;
+                    if (typeof subscribe.enabled !== "boolean") {
+                        errors.push({
+                            field: "intents.subscribe.enabled",
+                            message: "Subscribe enabled must be a boolean",
+                        });
+                    }
+                    if (subscribe.title !== undefined) {
+                        if (typeof subscribe.title !== "string") {
+                            errors.push({
+                                field: "intents.subscribe.title",
+                                message: "Subscribe title must be a string",
+                            });
+                        }
+                        else if (subscribe.title.length > MAX_INTENT_TITLE_LENGTH) {
+                            errors.push({
+                                field: "intents.subscribe.title",
+                                message: `Subscribe title must be ${MAX_INTENT_TITLE_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (subscribe.description !== undefined) {
+                        if (typeof subscribe.description !== "string") {
+                            errors.push({
+                                field: "intents.subscribe.description",
+                                message: "Subscribe description must be a string",
+                            });
+                        }
+                        else if (subscribe.description.length > MAX_INTENT_DESCRIPTION_LENGTH) {
+                            errors.push({
+                                field: "intents.subscribe.description",
+                                message: `Subscribe description must be ${MAX_INTENT_DESCRIPTION_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (subscribe.frequency !== undefined &&
+                        !VALID_FREQUENCIES.includes(subscribe.frequency)) {
+                        errors.push({
+                            field: "intents.subscribe.frequency",
+                            message: `Subscribe frequency must be one of: ${VALID_FREQUENCIES.join(", ")}`,
+                        });
+                    }
+                }
+            }
+            // Validate book intent
+            if (intents.book !== undefined) {
+                if (typeof intents.book !== "object" || intents.book === null) {
+                    errors.push({
+                        field: "intents.book",
+                        message: "Book intent must be an object",
+                    });
+                }
+                else {
+                    const book = intents.book;
+                    if (typeof book.enabled !== "boolean") {
+                        errors.push({
+                            field: "intents.book.enabled",
+                            message: "Book enabled must be a boolean",
+                        });
+                    }
+                    if (book.title !== undefined) {
+                        if (typeof book.title !== "string") {
+                            errors.push({
+                                field: "intents.book.title",
+                                message: "Book title must be a string",
+                            });
+                        }
+                        else if (book.title.length > MAX_INTENT_TITLE_LENGTH) {
+                            errors.push({
+                                field: "intents.book.title",
+                                message: `Book title must be ${MAX_INTENT_TITLE_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (book.description !== undefined) {
+                        if (typeof book.description !== "string") {
+                            errors.push({
+                                field: "intents.book.description",
+                                message: "Book description must be a string",
+                            });
+                        }
+                        else if (book.description.length > MAX_INTENT_DESCRIPTION_LENGTH) {
+                            errors.push({
+                                field: "intents.book.description",
+                                message: `Book description must be ${MAX_INTENT_DESCRIPTION_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (book.duration !== undefined &&
+                        typeof book.duration !== "number") {
+                        errors.push({
+                            field: "intents.book.duration",
+                            message: "Book duration must be a number (minutes)",
+                        });
+                    }
+                    if (book.provider !== undefined &&
+                        typeof book.provider !== "string") {
+                        errors.push({
+                            field: "intents.book.provider",
+                            message: "Book provider must be a string",
+                        });
+                    }
+                    // URL is optional if availability is set (native me3 booking)
+                    if (book.url !== undefined) {
+                        if (typeof book.url !== "string") {
+                            errors.push({
+                                field: "intents.book.url",
+                                message: "Book URL must be a string",
+                            });
+                        }
+                        else if (!URL_REGEX.test(book.url)) {
+                            errors.push({
+                                field: "intents.book.url",
+                                message: "Book URL must be a valid URL starting with http:// or https://",
+                            });
+                        }
+                    }
+                    // Validate availability if present
+                    if (book.availability !== undefined) {
+                        if (typeof book.availability !== "object" ||
+                            book.availability === null) {
+                            errors.push({
+                                field: "intents.book.availability",
+                                message: "Book availability must be an object",
+                            });
+                        }
+                        else {
+                            const availability = book.availability;
+                            if (!availability.timezone ||
+                                typeof availability.timezone !== "string") {
+                                errors.push({
+                                    field: "intents.book.availability.timezone",
+                                    message: "Availability timezone is required",
+                                });
+                            }
+                            if (availability.windows !== undefined) {
+                                if (typeof availability.windows !== "object" ||
+                                    availability.windows === null) {
+                                    errors.push({
+                                        field: "intents.book.availability.windows",
+                                        message: "Availability windows must be an object",
+                                    });
+                                }
+                                else {
+                                    const windows = availability.windows;
+                                    const validDays = [
+                                        "monday",
+                                        "tuesday",
+                                        "wednesday",
+                                        "thursday",
+                                        "friday",
+                                        "saturday",
+                                        "sunday",
+                                    ];
+                                    const timeWindowRegex = /^\d{2}:\d{2}-\d{2}:\d{2}$/;
+                                    for (const [day, value] of Object.entries(windows)) {
+                                        if (!validDays.includes(day)) {
+                                            errors.push({
+                                                field: `intents.book.availability.windows.${day}`,
+                                                message: `Invalid day: ${day}`,
+                                            });
+                                            continue;
+                                        }
+                                        if (!Array.isArray(value)) {
+                                            errors.push({
+                                                field: `intents.book.availability.windows.${day}`,
+                                                message: `Windows for ${day} must be an array`,
+                                            });
+                                            continue;
+                                        }
+                                        for (const window of value) {
+                                            if (typeof window !== "string" ||
+                                                !timeWindowRegex.test(window)) {
+                                                errors.push({
+                                                    field: `intents.book.availability.windows.${day}`,
+                                                    message: `Invalid time window format. Use HH:MM-HH:MM`,
+                                                });
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    // Either URL or availability must be set for booking to work
+                    if (!book.url && !book.availability) {
+                        errors.push({
+                            field: "intents.book",
+                            message: "Book intent requires either a URL (for external booking) or availability (for native booking)",
+                        });
+                    }
+                }
+            }
+        }
+    }
     if (errors.length > 0) {
         return { valid: false, errors };
     }

package/examples/full.json

@@ -27,5 +27,29 @@
   ],
   "pages": [
     { "slug": "about", "title": "About", "file": "about.md", "visible": true }
-  ]
+  ],
+  "intents": {
+    "subscribe": {
+      "enabled": true,
+      "title": "Weekly Insights",
+      "description": "Curated thoughts on design, tech, and creativity every Sunday",
+      "frequency": "weekly"
+    },
+    "book": {
+      "enabled": true,
+      "title": "30-min Consultation",
+      "description": "Let's discuss your project",
+      "duration": 30,
+      "availability": {
+        "timezone": "America/New_York",
+        "windows": {
+          "monday": ["09:00-12:00", "14:00-17:00"],
+          "tuesday": ["09:00-17:00"],
+          "wednesday": ["09:00-17:00"],
+          "thursday": ["09:00-17:00"],
+          "friday": ["09:00-12:00"]
+        }
+      }
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "me3-protocol",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/schema.json

@@ -2,6 +2,70 @@
   "$ref": "#/definitions/Me3Profile",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "Me3BookingAvailability": {
+      "additionalProperties": false,
+      "description": "Availability windows for booking. Defines when the person is available for meetings.",
+      "properties": {
+        "timezone": {
+          "description": "Timezone for the availability windows (e.g., \"America/New_York\")",
+          "type": "string"
+        },
+        "windows": {
+          "additionalProperties": false,
+          "description": "Weekly availability windows by day",
+          "properties": {
+            "friday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "monday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "saturday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "sunday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "thursday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "tuesday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "wednesday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "required": [
+        "timezone",
+        "windows"
+      ],
+      "type": "object"
+    },
     "Me3Button": {
       "additionalProperties": false,
       "properties": {
@@ -65,6 +129,91 @@
       ],
       "type": "object"
     },
+    "Me3IntentBook": {
+      "additionalProperties": false,
+      "description": "Booking/scheduling intent. Declares that the person accepts meeting bookings.",
+      "properties": {
+        "availability": {
+          "$ref": "#/definitions/Me3BookingAvailability",
+          "description": "Availability windows - for native me3 booking"
+        },
+        "description": {
+          "description": "What the meeting is about",
+          "type": "string"
+        },
+        "duration": {
+          "description": "Meeting duration in minutes",
+          "type": "number"
+        },
+        "enabled": {
+          "description": "Whether booking is enabled",
+          "type": "boolean"
+        },
+        "provider": {
+          "description": "Booking provider (e.g., \"cal.com\", \"calendly\") - for external providers",
+          "type": "string"
+        },
+        "title": {
+          "description": "Meeting title (e.g., \"30-min Consultation\")",
+          "type": "string"
+        },
+        "url": {
+          "description": "Direct booking URL - for external booking systems",
+          "type": "string"
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "type": "object"
+    },
+    "Me3IntentSubscribe": {
+      "additionalProperties": false,
+      "description": "Newsletter subscription intent. When enabled, the site accepts email subscriptions via POST /api/subscribe",
+      "properties": {
+        "description": {
+          "description": "What subscribers will receive - for agents to explain the value",
+          "type": "string"
+        },
+        "enabled": {
+          "description": "Whether newsletter signups are enabled",
+          "type": "boolean"
+        },
+        "frequency": {
+          "description": "How often subscribers will hear from you",
+          "enum": [
+            "daily",
+            "weekly",
+            "monthly",
+            "irregular"
+          ],
+          "type": "string"
+        },
+        "title": {
+          "description": "Newsletter title (e.g., \"AI Weekly\") - for agents to present context",
+          "type": "string"
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "type": "object"
+    },
+    "Me3Intents": {
+      "additionalProperties": false,
+      "description": "Intents object - declares what actions visitors/agents can take. This is the machine-readable API contract for interacting with a person.",
+      "properties": {
+        "book": {
+          "$ref": "#/definitions/Me3IntentBook",
+          "description": "Meeting booking"
+        },
+        "subscribe": {
+          "$ref": "#/definitions/Me3IntentSubscribe",
+          "description": "Newsletter subscription"
+        }
+      },
+      "type": "object"
+    },
     "Me3Links": {
       "additionalProperties": {
         "anyOf": [
@@ -171,6 +320,10 @@
           "description": "Username/handle",
           "type": "string"
         },
+        "intents": {
+          "$ref": "#/definitions/Me3Intents",
+          "description": "Intents - machine-readable actions that visitors/agents can take. This is the API contract for interacting with the person."
+        },
         "links": {
           "$ref": "#/definitions/Me3Links",
           "description": "Social and external links"