taurean.bryant.land
+75
CLAUDE.md
+75
CLAUDE.md
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Project Overview
6
+
7
+
This is an ATProtocol lexicon project for declaring automation and AI usage on Bluesky. It has three main components:
8
+
9
+
1. **Lexicon Definition** - The `studio.voyager.account.autonomy` schema in `lexicon/autonomy-declaration.json`
10
+
2. **JSR Package** - Published as `@voyager/autonomy-lexicon` for TypeScript consumers
11
+
3. **Web Client** - A single-page form for users to submit autonomy declarations to their PDS
12
+
13
+
## Key Architecture Concepts
14
+
15
+
### Lexicon Ownership and Publishing
16
+
17
+
The lexicon ID is `studio.voyager.account.autonomy`, which means it **must** be published from the `voyager.studio` account. The publishing script (`scripts/publish_lexicon.ts`) is hardcoded to use `voyager.studio` as the publisher handle - this is not configurable.
18
+
19
+
Schema publishing workflow:
20
+
1. Lexicon changes are made in `lexicon/autonomy-declaration.json`
21
+
2. The schema is published to ATProtocol via `com.atproto.repo.putRecord` with:
22
+
- Collection: `com.atproto.lexicon.schema`
23
+
- Rkey: `studio.voyager.account.autonomy`
24
+
- Record type: `com.atproto.lexicon.schema`
25
+
3. DNS TXT record at `_lexicon.account.voyager.studio` points to the publisher's DID
26
+
27
+
### Record Key: `literal:self`
28
+
29
+
The lexicon uses `"key": "literal:self"`, meaning each account can only have **one** autonomy declaration record (not a collection). When users submit via the web form, it creates/updates their single declaration record.
30
+
31
+
### Client-Side Record Creation
32
+
33
+
The web client (`client/app.js`) allows any Bluesky user to create their own autonomy declaration:
34
+
- Uses `BskyAgent` from `@atproto/api`
35
+
- Authenticates with user's handle + app password
36
+
- Creates record in collection `studio.voyager.account.autonomy` on their own PDS
37
+
- Only `createdAt` field is required; all others are optional
38
+
39
+
## Common Commands
40
+
41
+
**Run web form locally:**
42
+
```bash
43
+
deno task dev
44
+
# Serves client on http://localhost:8000
45
+
```
46
+
47
+
**Publish package to JSR:**
48
+
```bash
49
+
deno publish --dry-run # Preview
50
+
deno publish # Publish
51
+
```
52
+
53
+
**Publish schema (voyager.studio owner only):**
54
+
```bash
55
+
# Set VOYAGER_PASSWORD in .env first
56
+
deno task publish:lexicon
57
+
```
58
+
59
+
## Important Implementation Details
60
+
61
+
### Environment Variables
62
+
- The publish script uses `--env` flag to auto-load `.env` file
63
+
- Only requires `VOYAGER_PASSWORD` (voyager.studio app password)
64
+
- No username needed - hardcoded to `voyager.studio`
65
+
66
+
### Lexicon Structure
67
+
- All fields except `createdAt` are optional
68
+
- `automationLevel` has known values: human, assisted, collaborative, automated
69
+
- `responsibleParty` is a nested object with optional fields
70
+
- `externalServices` is an array (max 20 items, 200 chars each)
71
+
72
+
### Client Form Processing
73
+
- External services are entered one per line in a textarea
74
+
- Responsible party object is only included if at least one field is filled
75
+
- Empty optional fields are omitted from the record (not sent as null/empty)
+10
-30
README.md
+10
-30
README.md
···
1
1
# ATP Autonomy Declaration
2
2
3
-
A Deno project for managing and sharing an ATProtocol lexicon with accompanying tooling.
3
+
ATProtocol lexicon for declaring automation and AI usage on Bluesky.
4
4
5
-
## Project Structure
5
+
## Components
6
6
7
-
- `lexicon/` - ATProtocol lexicon definition (JSON)
8
-
- `mod.ts` - Main module exporting the lexicon (published to JSR)
9
-
- `client/` - Single-page web form for users to add records to their PDS
10
-
- `scripts/` - Utility scripts for publishing and managing the lexicon
7
+
- **Lexicon** (`lexicon/`) - `studio.voyager.account.autonomy` schema definition
8
+
- **JSR Package** (`mod.ts`) - Published as `@voyager/autonomy-lexicon`
9
+
- **Web Form** (`client/`) - Submit autonomy declarations to your PDS
10
+
- **Schema Publisher** (`scripts/`) - Publish schema updates (voyager.studio only)
11
11
12
12
## Usage
13
13
14
-
### Development
15
-
16
-
Run the client locally:
14
+
**Run web form locally:**
17
15
```bash
18
16
deno task dev
19
17
```
20
18
21
-
### Publish to JSR
22
-
23
-
Publish the lexicon package to JSR:
19
+
**Publish to JSR:**
24
20
```bash
25
21
deno publish
26
22
```
27
23
28
-
Or with dry-run to check first:
29
-
```bash
30
-
deno publish --dry-run
31
-
```
32
-
33
-
### Publish Lexicon to PDS
34
-
35
-
Publish the lexicon to the owning PDS:
24
+
**Publish schema (voyager.studio only):**
36
25
```bash
26
+
# Set VOYAGER_PASSWORD in .env
37
27
deno task publish:lexicon
38
28
```
39
-
40
-
Set up your credentials first:
41
-
```bash
42
-
export ATP_HANDLE=your-handle.bsky.social
43
-
export ATP_PASSWORD=your-app-password
44
-
```
45
-
46
-
## Requirements
47
-
48
-
- Deno 2.0+