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)

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):

SCHEMA_PUBLISHER_USERNAME=your.voyager.studio.handle
SCHEMA_PUBLISHER_PASSWORD=your-app-password

Then run:

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:

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:

   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 for complete schema documentation.