Merge pull request #5 from taurean/refactor-lexicon-use

Update README to point to JSR lexicon package, pulls out publish sche…

README.md

···
 - Your agent creates its own **record** using this schema when you run `deno task mount`
 - The record lives in your agent's PDS and is discoverable by other AT Protocol services
 
-This promotes transparency and accountability for AI agents on Bluesky. For more details, see [SCHEMA.md](./SCHEMA.md).
+This promotes transparency and accountability for AI agents on Bluesky. For schema details, see [@voyager/autonomy-lexicon](https://jsr.io/@voyager/autonomy-lexicon).
 
 ## configurable variables:
 ### required

SCHEMA.md

···
-# AI Agent Autonomy Declaration Schema
-
-## Overview
-
-The `studio.voyager.account.autonomy` lexicon defines a standardized schema for AI agents to declare their automation practices on AT Protocol / Bluesky. This promotes transparency and accountability for automated accounts.
-
-## Schema Details
-
-- **NSID**: `studio.voyager.account.autonomy`
-- **Type**: Record
-- **Authority**: `account.voyager.studio`
-- **Record Key**: `literal:self` (always "self")
-
-## Purpose
-
-This schema allows AI agents and automated accounts to transparently declare:
-
-- Level of automation (human, assisted, collaborative, automated)
-- Use of generative AI (LLMs, image generation, etc.)
-- Who is responsible for the account's behavior
-- External services and tools being used
-- Where to find more information
-
-## Schema vs. Records
-
-**Important distinction**:
-
-- **The Schema** (published by voyager.studio): Defines the structure and validation rules - published once
-- **Records** (created by each agent): Individual autonomy declarations - each AI agent creates their own
-
-This is analogous to how Bluesky publishes the `app.bsky.feed.post` schema once, but millions of users create their own post records.
-
-## Field Definitions
-
-### Required Fields
-
-- `createdAt` (string, datetime): When this declaration was created
-
-### Optional Fields
-
-- `automationLevel` (string): Level of automation
-  - `human`: Fully human-controlled
-  - `assisted`: AI assists human decisions
-  - `collaborative`: Human and AI work together
-  - `automated`: Fully AI-controlled (recommended for AI agents)
-
-- `usesGenerativeAI` (boolean): Whether generative AI is used for content creation
-
-- `description` (string, max 300 graphemes): Plain language explanation of automation practices
-
-- `responsibleParty` (object): Information about who is accountable
-  - `type` (string): "person" or "organization"
-  - `name` (string, max 100 graphemes): Name of responsible party
-  - `contact` (string, max 300 bytes): Email, URL, handle, or DID
-  - `did` (string, DID format): AT Protocol DID of responsible party
-
-- `disclosureUrl` (string, URI): URL with additional information
-
-- `externalServices` (array of strings, max 20 items): External tools/services used
-  - Examples: "Letta", "Railway", "Google Gemini 2.5-pro"
-
-## Example Record
-
-```json
-{
-  "$type": "studio.voyager.account.autonomy",
-  "automationLevel": "automated",
-  "usesGenerativeAI": true,
-  "description": "An AI agent that discusses technology and answers questions about programming using Claude.",
-  "responsibleParty": {
-    "type": "person",
-    "name": "Jane Developer",
-    "contact": "[email protected]",
-    "did": "did:plc:abc123xyz"
-  },
-  "disclosureUrl": "https://example.com/ai-bot-policy",
-  "externalServices": [
-    "Letta",
-    "Anthropic Claude",
-    "Railway"
-  ],
-  "createdAt": "2025-01-15T10:30:00.000Z"
-}
-```
-
-## Usage in Cloudseeding
-
-The Cloudseeding template automatically creates an autonomy declaration record when you run `deno task mount`. Configuration is done via environment variables in `.env`:
-
-- `AUTOMATION_LEVEL`: "assisted", "collaborative", or "automated" (default)
-- `PROJECT_DESCRIPTION`: Maps to `description` field
-- `RESPONSIBLE_PARTY_NAME`: Required
-- `RESPONSIBLE_PARTY_CONTACT`: Required
-- `RESPONSIBLE_PARTY_TYPE`: "person" or "organization"
-- `RESPONSIBLE_PARTY_BSKY`: DID or handle of responsible party
-- `DISCLOSURE_URL`: Optional URL to policy/disclosure page
-- `EXTERNAL_SERVICES`: Comma-separated list of external services
-
-## Schema Evolution
-
-Following AT Protocol lexicon rules:
-
-- ✅ New optional fields can be added
-- ✅ Existing constraints can be tightened
-- ❌ Required fields cannot be removed
-- ❌ Field types cannot change
-- ❌ Constraints cannot be loosened
-
-Breaking changes require a new NSID (e.g., `studio.voyager.account.autonomy.v2`).
-
-## Schema Resolution
-
-The schema is published and discoverable via:
-
-1. **DNS TXT Record**: `_lexicon.account.voyager.studio` → DID of schema publisher
-2. **PDS Record**: `com.atproto.lexicon.schema` collection in publisher's repository
-3. **AT-URI**: `at://did:plc:*/com.atproto.lexicon.schema/studio.voyager.account.autonomy`
-
-## For Template Users
-
-**You do NOT need to publish the schema** - it's already published by voyager.studio. You only need to:
-
-1. Configure your `.env` file with your information
-2. Run `deno task mount` to create YOUR autonomy declaration record
-3. Your record will be stored in YOUR PDS, using the published schema
-
-## For Schema Maintainers
-
-To update the schema definition:
-
-1. Update `utils/declaration.ts` with schema changes
-2. Ensure changes follow evolution rules
-3. Run `deno task publish-schema` to publish updates
-4. Update this documentation
-
-## Resources
-
-- [AT Protocol Lexicon Specification](https://atproto.com/specs/lexicon)
-- [AT Protocol NSID Specification](https://atproto.com/specs/nsid)
-- [Cloudseeding Template Repository](https://github.com/taurean/cloudseeding)
-
-## Contributing
-
-If you have suggestions for improving this schema, please open an issue or pull request in the Cloudseeding repository. Please note that schema changes must follow strict evolution rules to maintain backwards compatibility.

deno.json

···
     "config": "deno run --allow-read --allow-write setup.ts",
     "mount": "deno run --allow-net --allow-env --allow-read --env mount.ts",
     "watch": "deno run --allow-net --allow-env --env --watch main.ts",
-    "start": "deno run --allow-net --allow-env --env main.ts",
-    "publish-schema": "deno run --allow-net --allow-env --env scripts/publishSchema.ts"
+    "start": "deno run --allow-net --allow-env --env main.ts"
   },
   "imports": {
     "@std/assert": "jsr:@std/assert@1",

scripts/README.md

···
-# Scripts
-
-This directory contains maintenance scripts for the Cloudseeding project.
-
-## publishSchema.ts
-
-**Purpose**: Publishes the `studio.voyager.account.autonomy` lexicon schema to AT Protocol.
-
-**Who should run this**: Only the voyager.studio domain owner (project maintainer).
-
-**When to run this**:
-- Initial schema publication
-- When the schema definition is updated in `utils/declaration.ts`
-
-**Template users do NOT need to run this script.** The schema is already published and discoverable. Template users only need to create their own autonomy declaration records (which happens automatically when running `deno task mount`).
-
-### Prerequisites
-
-1. Control of the `voyager.studio` domain
-2. DNS TXT record set up:
-   ```
-   Name: _lexicon.account.voyager.studio
-   Type: TXT
-   Value: did=did:plc:YOUR_DID
-   ```
-3. Credentials for a Bluesky account with a handle containing `voyager.studio`
-
-### Usage
-
-**Option 1: Environment variables (recommended)**
-
-```bash
-SCHEMA_PUBLISHER_USERNAME=your.voyager.studio.handle \
-SCHEMA_PUBLISHER_PASSWORD=your-app-password \
-deno task publish-schema
-```
-
-**Option 2: Add to .env file**
-
-Add these lines to `.env` (separate from your AI agent credentials):
-```bash
-SCHEMA_PUBLISHER_USERNAME=your.voyager.studio.handle
-SCHEMA_PUBLISHER_PASSWORD=your-app-password
-```
-
-Then run:
-```bash
-deno task publish-schema
-```
-
-**Note**: The script will verify that the logged-in account's handle contains `voyager.studio` before publishing.
-
-### What it does
-
-1. Logs into the voyager.studio account
-2. Creates/updates a record in the `com.atproto.lexicon.schema` collection
-3. Uses record key: `studio.voyager.account.autonomy`
-4. Makes the schema discoverable by AT Protocol resolvers
-
-### Schema vs. Records
-
-Understanding the distinction is important:
-
-| Schema | Records |
-|--------|---------|
-| Published once by domain owner | Created by each agent |
-| Defines structure and rules | Actual autonomy declarations |
-| Lives in voyager.studio PDS | Live in each agent's PDS |
-| One canonical definition | Many individual records |
-
-This is analogous to how Bluesky publishes the `app.bsky.feed.post` schema once, but millions of users create their own post records using that schema.
-
-### Verification
-
-After publishing, you can verify:
-
-1. **DNS Resolution**:
-   ```bash
-   dig TXT _lexicon.account.voyager.studio
-   ```
-
-2. **Schema Record**:
-   Visit your account's AT-URI:
-   ```
-   at://YOUR_DID/com.atproto.lexicon.schema/studio.voyager.account.autonomy
-   ```
-
-3. **PDS API** (if using bsky.social):
-   ```
-   https://bsky.social/xrpc/com.atproto.repo.getRecord?repo=YOUR_DID&collection=com.atproto.lexicon.schema&rkey=studio.voyager.account.autonomy
-   ```
-
-### Schema Evolution Rules
-
-When updating the schema, follow AT Protocol lexicon evolution rules:
-
-✅ **Allowed**:
-- Adding new optional fields
-- Tightening existing constraints
-- Adding to `knownValues` arrays
-
-❌ **Not Allowed**:
-- Removing required fields
-- Changing field types
-- Loosening constraints
-- Renaming fields
-
-Breaking changes require a new NSID (e.g., `studio.voyager.account.autonomy.v2`).
-
-See [SCHEMA.md](../SCHEMA.md) for complete schema documentation.

scripts/publishSchema.ts

···
-/**
- * Schema Publication Script
- *
- * This script publishes the studio.voyager.account.autonomy lexicon schema
- * to the voyager.studio PDS. This should only be run by the domain owner
- * to publish or update the canonical schema definition.
- *
- * Template users do NOT need to run this script - they just create records
- * using the published schema.
- *
- * Prerequisites:
- * 1. DNS TXT record: _lexicon.account.voyager.studio pointing to your DID
- * 2. SCHEMA_PUBLISHER_USERNAME: Bluesky handle for voyager.studio domain owner
- * 3. SCHEMA_PUBLISHER_PASSWORD: App password for that account
- *
- * Usage:
- *   SCHEMA_PUBLISHER_USERNAME=your.handle SCHEMA_PUBLISHER_PASSWORD=xxxx deno task publish-schema
- *
- * OR set these in .env (separate from your agent credentials):
- *   SCHEMA_PUBLISHER_USERNAME=...
- *   SCHEMA_PUBLISHER_PASSWORD=...
- */
-
-import { AtpAgent } from "@atproto/api";
-import { AUTONOMY_DECLARATION_LEXICON } from "@voyager/autonomy-lexicon";
-
-const publishSchema = async () => {
-  console.log("🔧 Publishing studio.voyager.account.autonomy schema...\n");
-
-  // Get credentials from environment - use separate vars from agent credentials
-  const username = Deno.env.get("SCHEMA_PUBLISHER_USERNAME") || Deno.env.get("BSKY_USERNAME");
-  const password = Deno.env.get("SCHEMA_PUBLISHER_PASSWORD") || Deno.env.get("BSKY_APP_PASSWORD");
-  const serviceUrl = Deno.env.get("BSKY_SERVICE_URL") || "https://bsky.social";
-  const expectedDomain = Deno.env.get("SCHEMA_DOMAIN") || "voyager.studio";
-
-  if (!username || !password) {
-    console.error(
-      "❌ Error: Schema publisher credentials not found.\n"
-    );
-    console.error("   Set SCHEMA_PUBLISHER_USERNAME and SCHEMA_PUBLISHER_PASSWORD");
-    console.error("   OR run with: SCHEMA_PUBLISHER_USERNAME=your.handle SCHEMA_PUBLISHER_PASSWORD=xxxx deno task publish-schema\n");
-    console.error("   ⚠️  Template users: You do NOT need to run this command!");
-    console.error("      The schema is already published by voyager.studio.\n");
-    Deno.exit(1);
-  }
-
-  // Initialize agent
-  const agent = new AtpAgent({ service: serviceUrl });
-
-  try {
-    // Login
-    console.log("🔐 Logging in...");
-    await agent.login({
-      identifier: username,
-      password: password,
-    });
-    console.log(`✅ Logged in as: ${agent.session?.handle} (${agent.session?.did})\n`);
-
-    // Verify domain ownership
-    const handle = agent.session?.handle || "";
-    if (!handle.includes(expectedDomain)) {
-      console.error(`❌ Error: This account does not appear to own ${expectedDomain}\n`);
-      console.error(`   Logged in as: ${handle}`);
-      console.error(`   Expected domain: ${expectedDomain}\n`);
-      console.error("   ⚠️  Template users: You do NOT need to publish the schema!");
-      console.error("      The schema is already published and discoverable.");
-      console.error("      You only create your own autonomy declaration record via 'deno task mount'.\n");
-      Deno.exit(1);
-    }
-
-    // Prepare schema record
-    const schemaRecord = {
-      $type: "com.atproto.lexicon.schema",
-      lexicon: AUTONOMY_DECLARATION_LEXICON.lexicon,
-      id: AUTONOMY_DECLARATION_LEXICON.id,
-      defs: AUTONOMY_DECLARATION_LEXICON.defs,
-      description:
-        "Lexicon for declaring AI agent autonomy and automation practices for transparency and accountability",
-    };
-
-    console.log(`📋 Schema Details:`);
-    console.log(`   NSID: ${schemaRecord.id}`);
-    console.log(`   Lexicon Version: ${schemaRecord.lexicon}`);
-    console.log(`   Definitions: ${Object.keys(schemaRecord.defs).join(", ")}\n`);
-
-    // Check if schema already exists
-    let existingSchema = null;
-    try {
-      const existing = await agent.com.atproto.repo.getRecord({
-        repo: agent.session?.did!,
-        collection: "com.atproto.lexicon.schema",
-        rkey: "studio.voyager.account.autonomy",
-      });
-      existingSchema = existing.data;
-      console.log("📄 Existing schema found - will update\n");
-    } catch (error: any) {
-      if (error?.status === 400 || error?.status === 404) {
-        console.log("📄 No existing schema found - will create new\n");
-      } else {
-        throw error;
-      }
-    }
-
-    // Publish schema
-    console.log("📤 Publishing schema...");
-    const result = await agent.com.atproto.repo.putRecord({
-      repo: agent.session?.did!,
-      collection: "com.atproto.lexicon.schema",
-      rkey: "studio.voyager.account.autonomy",
-      record: schemaRecord,
-    });
-
-    console.log(`✅ Schema ${existingSchema ? "updated" : "published"} successfully!\n`);
-    console.log(`📍 AT-URI: ${result.data.uri}`);
-    console.log(`🔗 CID: ${result.data.cid}\n`);
-
-    // Verify DNS setup
-    console.log("🔍 Next steps:");
-    console.log("   1. Verify DNS TXT record is set:");
-    console.log("      Name: _lexicon.account.voyager.studio");
-    console.log("      Type: TXT");
-    console.log(`      Value: did=${agent.session?.did}`);
-    console.log(
-      "\n   2. Test resolution (may take time for DNS to propagate):",
-    );
-    console.log(
-      `      dig TXT _lexicon.account.voyager.studio\n`,
-    );
-    console.log("✨ Schema is now discoverable by AT Protocol resolvers!");
-  } catch (error) {
-    console.error("❌ Error publishing schema:", error);
-    Deno.exit(1);
-  }
-};
-
-// Run if executed directly
-if (import.meta.main) {
-  publishSchema();
-}