@atproto/bsky 0.0.29 → 0.0.30

package/src/lexicon/lexicons.ts

@@ -1912,7 +1912,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Provides the DID of a repo.',
+        description: 'Resolves a handle (domain name) to a DID.',
         parameters: {
           type: 'params',
           required: ['handle'],
@@ -1946,7 +1946,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Updates the handle of the account.',
+        description:
+          "Updates the current account's handle. Verifies handle validity, and updates did:plc document if necessary. Implemented by PDS, and requires auth.",
         input: {
           encoding: 'application/json',
           schema: {
@@ -1956,6 +1957,7 @@ export const schemaDict = {
               handle: {
                 type: 'string',
                 format: 'handle',
+                description: 'The new handle.',
               },
             },
           },
@@ -2046,7 +2048,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Find labels relevant to the provided URI patterns.',
+        description:
+          'Find labels relevant to the provided AT-URI patterns. Public endpoint for moderation services, though may return different or additional results with auth.',
         parameters: {
           type: 'params',
           required: ['uriPatterns'],
@@ -2107,13 +2110,14 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'subscription',
-        description: 'Subscribe to label updates.',
+        description:
+          'Subscribe to stream of labels (and negations). Public endpoint implemented by mod services. Uses same sequencing scheme as repo event stream.',
         parameters: {
           type: 'params',
           properties: {
             cursor: {
               type: 'integer',
-              description: 'The last known event to backfill from.',
+              description: 'The last known event seq number to backfill from.',
             },
           },
         },
@@ -2169,7 +2173,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Report a repo or a record.',
+        description:
+          'Submit a moderation report regarding an atproto account or record. Implemented by moderation services (with PDS proxying), and requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -2178,10 +2183,14 @@ export const schemaDict = {
             properties: {
               reasonType: {
                 type: 'ref',
+                description:
+                  'Indicates the broad category of violation the report is for.',
                 ref: 'lex:com.atproto.moderation.defs#reasonType',
               },
               reason: {
                 type: 'string',
+                description:
+                  'Additional context about the content and violation.',
               },
               subject: {
                 type: 'union',
@@ -2292,7 +2301,7 @@ export const schemaDict = {
       main: {
         type: 'procedure',
         description:
-          'Apply a batch transaction of creates, updates, and deletes.',
+          'Apply a batch transaction of repository creates, updates, and deletes. Requires auth, implemented by PDS.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -2302,12 +2311,14 @@ export const schemaDict = {
               repo: {
                 type: 'string',
                 format: 'at-identifier',
-                description: 'The handle or DID of the repo.',
+                description:
+                  'The handle or DID of the repo (aka, current account).',
               },
               validate: {
                 type: 'boolean',
                 default: true,
-                description: 'Flag for validating the records.',
+                description:
+                  "Can be set to 'false' to skip Lexicon schema validation of record data, for all operations.",
               },
               writes: {
                 type: 'array',
@@ -2323,6 +2334,8 @@ export const schemaDict = {
               },
               swapCommit: {
                 type: 'string',
+                description:
+                  'If provided, the entire operation will fail if the current repo commit CID does not match this value. Used to prevent conflicting repo mutations.',
                 format: 'cid',
               },
             },
@@ -2331,12 +2344,14 @@ export const schemaDict = {
         errors: [
           {
             name: 'InvalidSwap',
+            description:
+              "Indicates that the 'swapCommit' parameter did not match current commit.",
           },
         ],
       },
       create: {
         type: 'object',
-        description: 'Create a new record.',
+        description: 'Operation which creates a new record.',
         required: ['collection', 'value'],
         properties: {
           collection: {
@@ -2354,7 +2369,7 @@ export const schemaDict = {
       },
       update: {
         type: 'object',
-        description: 'Update an existing record.',
+        description: 'Operation which updates an existing record.',
         required: ['collection', 'rkey', 'value'],
         properties: {
           collection: {
@@ -2371,7 +2386,7 @@ export const schemaDict = {
       },
       delete: {
         type: 'object',
-        description: 'Delete an existing record.',
+        description: 'Operation which deletes an existing record.',
         required: ['collection', 'rkey'],
         properties: {
           collection: {
@@ -2391,7 +2406,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Create a new record.',
+        description:
+          'Create a single new repository record. Requires auth, implemented by PDS.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -2401,7 +2417,8 @@ export const schemaDict = {
               repo: {
                 type: 'string',
                 format: 'at-identifier',
-                description: 'The handle or DID of the repo.',
+                description:
+                  'The handle or DID of the repo (aka, current account).',
               },
               collection: {
                 type: 'string',
@@ -2410,17 +2427,18 @@ export const schemaDict = {
               },
               rkey: {
                 type: 'string',
-                description: 'The key of the record.',
+                description: 'The Record Key.',
                 maxLength: 15,
               },
               validate: {
                 type: 'boolean',
                 default: true,
-                description: 'Flag for validating the record.',
+                description:
+                  "Can be set to 'false' to skip Lexicon schema validation of record data.",
               },
               record: {
                 type: 'unknown',
-                description: 'The record to create.',
+                description: 'The record itself. Must contain a $type field.',
               },
               swapCommit: {
                 type: 'string',
@@ -2451,6 +2469,8 @@ export const schemaDict = {
         errors: [
           {
             name: 'InvalidSwap',
+            description:
+              "Indicates that 'swapCommit' didn't match current repo commit.",
           },
         ],
       },
@@ -2462,7 +2482,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: "Delete a record, or ensure it doesn't exist.",
+        description:
+          "Delete a repository record, or ensure it doesn't exist. Requires auth, implemented by PDS.",
         input: {
           encoding: 'application/json',
           schema: {
@@ -2472,7 +2493,8 @@ export const schemaDict = {
               repo: {
                 type: 'string',
                 format: 'at-identifier',
-                description: 'The handle or DID of the repo.',
+                description:
+                  'The handle or DID of the repo (aka, current account).',
               },
               collection: {
                 type: 'string',
@@ -2481,7 +2503,7 @@ export const schemaDict = {
               },
               rkey: {
                 type: 'string',
-                description: 'The key of the record.',
+                description: 'The Record Key.',
               },
               swapRecord: {
                 type: 'string',
@@ -2513,7 +2535,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          'Get information about the repo, including the list of collections.',
+          'Get information about an account and repository, including the list of collections. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['repo'],
@@ -2547,9 +2569,12 @@ export const schemaDict = {
               },
               didDoc: {
                 type: 'unknown',
+                description: 'The complete DID document for this account.',
               },
               collections: {
                 type: 'array',
+                description:
+                  'List of all the collections (NSIDs) for which this repo contains at least one record.',
                 items: {
                   type: 'string',
                   format: 'nsid',
@@ -2557,6 +2582,8 @@ export const schemaDict = {
               },
               handleIsCorrect: {
                 type: 'boolean',
+                description:
+                  'Indicates if handle is currently valid (resolves bi-directionally)',
               },
             },
           },
@@ -2570,7 +2597,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a record.',
+        description:
+          'Get a single record from a repository. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['repo', 'collection', 'rkey'],
@@ -2587,7 +2615,7 @@ export const schemaDict = {
             },
             rkey: {
               type: 'string',
-              description: 'The key of the record.',
+              description: 'The Record Key.',
             },
             cid: {
               type: 'string',
@@ -2626,7 +2654,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'List a range of records in a collection.',
+        description:
+          'List a range of records in a repository, matching a specific collection. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['repo', 'collection'],
@@ -2712,7 +2741,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Write a record, creating or updating it as needed.',
+        description:
+          'Write a repository record, creating or updating it as needed. Requires auth, implemented by PDS.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -2723,7 +2753,8 @@ export const schemaDict = {
               repo: {
                 type: 'string',
                 format: 'at-identifier',
-                description: 'The handle or DID of the repo.',
+                description:
+                  'The handle or DID of the repo (aka, current account).',
               },
               collection: {
                 type: 'string',
@@ -2732,13 +2763,14 @@ export const schemaDict = {
               },
               rkey: {
                 type: 'string',
-                description: 'The key of the record.',
+                description: 'The Record Key.',
                 maxLength: 15,
               },
               validate: {
                 type: 'boolean',
                 default: true,
-                description: 'Flag for validating the record.',
+                description:
+                  "Can be set to 'false' to skip Lexicon schema validation of record data.",
               },
               record: {
                 type: 'unknown',
@@ -2748,7 +2780,7 @@ export const schemaDict = {
                 type: 'string',
                 format: 'cid',
                 description:
-                  'Compare and swap with the previous record by CID.',
+                  'Compare and swap with the previous record by CID. WARNING: nullable and optional field; may cause problems with golang implementation',
               },
               swapCommit: {
                 type: 'string',
@@ -2812,7 +2844,7 @@ export const schemaDict = {
       main: {
         type: 'procedure',
         description:
-          'Upload a new blob to be added to repo in a later request.',
+          'Upload a new blob, to be referenced from a repository record. The blob will be deleted if it is not referenced within a time window (eg, minutes). Blob restrictions (mimetype, size, etc) are enforced when the reference is created. Requires auth, implemented by PDS.',
         input: {
           encoding: '*/*',
         },
@@ -2877,7 +2909,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Create an account.',
+        description: 'Create an account. Implemented by PDS.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -2890,10 +2922,13 @@ export const schemaDict = {
               handle: {
                 type: 'string',
                 format: 'handle',
+                description: 'Requested handle for the account.',
               },
               did: {
                 type: 'string',
                 format: 'did',
+                description:
+                  'Pre-existing atproto DID, being imported to a new account.',
               },
               inviteCode: {
                 type: 'string',
@@ -2906,12 +2941,18 @@ export const schemaDict = {
               },
               password: {
                 type: 'string',
+                description:
+                  'Initial account password. May need to meet instance-specific password strength requirements.',
               },
               recoveryKey: {
                 type: 'string',
+                description:
+                  'DID PLC rotation key (aka, recovery key) to be included in PLC creation operation.',
               },
               plcOp: {
                 type: 'unknown',
+                description:
+                  'A signed DID PLC operation to be submitted as part of importing an existing account to this instance. NOTE: this optional field may be updated when full account migration is implemented.',
               },
             },
           },
@@ -2920,6 +2961,8 @@ export const schemaDict = {
           encoding: 'application/json',
           schema: {
             type: 'object',
+            description:
+              'Account login session returned on successful account creation.',
             required: ['accessJwt', 'refreshJwt', 'handle', 'did'],
             properties: {
               accessJwt: {
@@ -2935,9 +2978,11 @@ export const schemaDict = {
               did: {
                 type: 'string',
                 format: 'did',
+                description: 'The DID of the new account.',
               },
               didDoc: {
                 type: 'unknown',
+                description: 'Complete DID document.',
               },
             },
           },
@@ -2983,6 +3028,8 @@ export const schemaDict = {
             properties: {
               name: {
                 type: 'string',
+                description:
+                  'A short name for the App Password, to help distinguish them.',
               },
             },
           },
@@ -3250,7 +3297,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: "Delete an actor's account with a token and password.",
+        description:
+          "Delete an actor's account with a token and password. Can only be called after requesting a deletion token. Requires auth.",
         input: {
           encoding: 'application/json',
           schema: {
@@ -3287,7 +3335,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Delete the current session.',
+        description: 'Delete the current session. Requires auth.',
       },
     },
   },
@@ -3298,7 +3346,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          "Get a document describing the service's accounts configuration.",
+          "Describes the server's account creation requirements and capabilities. Implemented by PDS.",
         output: {
           encoding: 'application/json',
           schema: {
@@ -3307,18 +3355,25 @@ export const schemaDict = {
             properties: {
               inviteCodeRequired: {
                 type: 'boolean',
+                description:
+                  'If true, an invite code must be supplied to create an account on this instance.',
               },
               phoneVerificationRequired: {
                 type: 'boolean',
+                description:
+                  'If true, a phone verification token must be supplied to create an account on this instance.',
               },
               availableUserDomains: {
                 type: 'array',
+                description:
+                  'List of domain suffixes that can be used in account handles.',
                 items: {
                   type: 'string',
                 },
               },
               links: {
                 type: 'ref',
+                description: 'URLs of service policy documents.',
                 ref: 'lex:com.atproto.server.describeServer#links',
               },
             },
@@ -3344,7 +3399,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get all invite codes for a given account.',
+        description:
+          'Get all invite codes for the current account. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -3355,6 +3411,8 @@ export const schemaDict = {
             createAvailable: {
               type: 'boolean',
               default: true,
+              description:
+                "Controls whether any new 'earned' but not 'created' invites should be created.",
             },
           },
         },
@@ -3388,7 +3446,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get information about the current session.',
+        description:
+          'Get information about the current auth session. Requires auth.',
         output: {
           encoding: 'application/json',
           schema: {
@@ -3468,7 +3527,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Refresh an authentication session.',
+        description:
+          "Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt').",
         output: {
           encoding: 'application/json',
           schema: {
@@ -3574,7 +3634,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Reserve a repo signing key for account creation.',
+        description:
+          'Reserve a repo signing key, for use with account creation. Necessary so that a DID PLC update operation can be constructed during an account migraiton. Public and does not require auth; implemented by PDS. NOTE: this endpoint may change when full account migration is implemented.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -3582,7 +3643,8 @@ export const schemaDict = {
             properties: {
               did: {
                 type: 'string',
-                description: 'The did to reserve a new did:key for',
+                format: 'did',
+                description: 'The DID to reserve a key for.',
               },
             },
           },
@@ -3595,7 +3657,8 @@ export const schemaDict = {
             properties: {
               signingKey: {
                 type: 'string',
-                description: 'Public signing key in the form of a did:key.',
+                description:
+                  'The public key for the reserved signing key, in did:key serialization.',
               },
             },
           },
@@ -3702,7 +3765,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a blob associated with a given repo.',
+        description:
+          'Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS.',
         parameters: {
           type: 'params',
           required: ['did', 'cid'],
@@ -3710,7 +3774,7 @@ export const schemaDict = {
             did: {
               type: 'string',
               format: 'did',
-              description: 'The DID of the repo.',
+              description: 'The DID of the account.',
             },
             cid: {
               type: 'string',
@@ -3731,7 +3795,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get blocks from a given repo.',
+        description:
+          'Get data blocks from a given repo, by CID. For example, intermediate MST nodes, or records. Does not require auth; implemented by PDS.',
         parameters: {
           type: 'params',
           required: ['did', 'cids'],
@@ -3826,7 +3891,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get the current commit CID & revision of the repo.',
+        description:
+          'Get the current commit CID & revision of the specified repo. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['did'],
@@ -3869,7 +3935,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          'Get blocks needed for existence or non-existence of record.',
+          'Get data blocks needed to prove the existence or non-existence of record in the current version of repo. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['did', 'collection', 'rkey'],
@@ -3885,6 +3951,7 @@ export const schemaDict = {
             },
             rkey: {
               type: 'string',
+              description: 'Record Key',
             },
             commit: {
               type: 'string',
@@ -3906,7 +3973,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          "Gets the DID's repo, optionally catching up from a specific revision.",
+          "Download a repository export as CAR file. Optionally only a 'diff' since a previous revision. Does not require auth; implemented by PDS.",
         parameters: {
           type: 'params',
           required: ['did'],
@@ -3918,7 +3985,8 @@ export const schemaDict = {
             },
             since: {
               type: 'string',
-              description: 'The revision of the repo to catch up from.',
+              description:
+                "The revision ('rev') of the repo to create a diff from.",
             },
           },
         },
@@ -3934,7 +4002,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'List blob CIDs since some revision.',
+        description:
+          'List blob CIDso for an account, since some repo revision. Does not require auth; implemented by PDS.',
         parameters: {
           type: 'params',
           required: ['did'],
@@ -3987,7 +4056,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'List DIDs and root CIDs of hosted repos.',
+        description:
+          'Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay.',
         parameters: {
           type: 'params',
           properties: {
@@ -4033,6 +4103,7 @@ export const schemaDict = {
           head: {
             type: 'string',
             format: 'cid',
+            description: 'Current repo commit CID',
           },
           rev: {
             type: 'string',
@@ -4048,7 +4119,7 @@ export const schemaDict = {
       main: {
         type: 'procedure',
         description:
-          'Notify a crawling service of a recent update; often when a long break between updates causes the connection with the crawling service to break.',
+          'Notify a crawling service of a recent update, and that crawling should resume. Intended use is after a gap between repo stream events caused the crawling service to disconnect. Does not require auth; implemented by Relay.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -4058,7 +4129,7 @@ export const schemaDict = {
               hostname: {
                 type: 'string',
                 description:
-                  'Hostname of the service that is notifying of update.',
+                  'Hostname of the current service (usually a PDS) that is notifying of update.',
               },
             },
           },
@@ -4072,7 +4143,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Request a service to persistently crawl hosted repos.',
+        description:
+          'Request a service to persistently crawl hosted repos. Expected use is new PDS instances declaring their existence to Relays. Does not require auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -4082,7 +4154,7 @@ export const schemaDict = {
               hostname: {
                 type: 'string',
                 description:
-                  'Hostname of the service that is requesting to be crawled.',
+                  'Hostname of the current service (eg, PDS) that is requesting to be crawled.',
               },
             },
           },
@@ -4096,13 +4168,14 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'subscription',
-        description: 'Subscribe to repo updates.',
+        description:
+          'Repository event stream, aka Firehose endpoint. Outputs repo commits with diff data, and identity update events, for all repositories on the current server. See the atproto specifications for details around stream sequencing, repo versioning, CAR diff format, and more. Public and does not require auth; implemented by PDS and Relay.',
         parameters: {
           type: 'params',
           properties: {
             cursor: {
               type: 'integer',
-              description: 'The last known event to backfill from.',
+              description: 'The last known event seq number to backfill from.',
             },
           },
         },
@@ -4124,11 +4197,15 @@ export const schemaDict = {
           },
           {
             name: 'ConsumerTooSlow',
+            description:
+              'If the consumer of the stream can not keep up with events, and a backlog gets too large, the server will drop the connection.',
           },
         ],
       },
       commit: {
         type: 'object',
+        description:
+          'Represents an update of repository state. Note that empty commits are allowed, which include no repo data changes, but an update to rev and signature.',
         required: [
           'seq',
           'rebase',
@@ -4146,34 +4223,45 @@ export const schemaDict = {
         properties: {
           seq: {
             type: 'integer',
+            description: 'The stream sequence number of this message.',
           },
           rebase: {
             type: 'boolean',
+            description: 'DEPRECATED -- unused',
           },
           tooBig: {
             type: 'boolean',
+            description:
+              'Indicates that this commit contained too many ops, or data size was too large. Consumers will need to make a separate request to get missing data.',
           },
           repo: {
             type: 'string',
             format: 'did',
+            description: 'The repo this event comes from.',
           },
           commit: {
             type: 'cid-link',
+            description: 'Repo commit object CID.',
           },
           prev: {
             type: 'cid-link',
+            description:
+              'DEPRECATED -- unused. WARNING -- nullable and optional; stick with optional to ensure golang interoperability.',
           },
           rev: {
             type: 'string',
-            description: 'The rev of the emitted commit.',
+            description:
+              'The rev of the emitted commit. Note that this information is also in the commit object included in blocks, unless this is a tooBig event.',
           },
           since: {
             type: 'string',
-            description: 'The rev of the last emitted commit from this repo.',
+            description:
+              'The rev of the last emitted commit from this repo (if any).',
           },
           blocks: {
             type: 'bytes',
-            description: 'CAR file containing relevant blocks.',
+            description:
+              'CAR file containing relevant blocks, as a diff since the previous repo state.',
             maxLength: 1000000,
           },
           ops: {
@@ -4181,6 +4269,8 @@ export const schemaDict = {
             items: {
               type: 'ref',
               ref: 'lex:com.atproto.sync.subscribeRepos#repoOp',
+              description:
+                'List of repo mutation operations in this commit (eg, records created, updated, or deleted).',
             },
             maxLength: 200,
           },
@@ -4188,16 +4278,22 @@ export const schemaDict = {
             type: 'array',
             items: {
               type: 'cid-link',
+              description:
+                'List of new blobs (by CID) referenced by records in this commit.',
             },
           },
           time: {
             type: 'string',
             format: 'datetime',
+            description:
+              'Timestamp of when this message was originally broadcast.',
           },
         },
       },
       handle: {
         type: 'object',
+        description:
+          "Represents an update of the account's handle, or transition to/from invalid state.",
         required: ['seq', 'did', 'handle', 'time'],
         properties: {
           seq: {
@@ -4219,6 +4315,8 @@ export const schemaDict = {
       },
       migrate: {
         type: 'object',
+        description:
+          'Represents an account moving from one PDS instance to another. NOTE: not implemented; full account migration may introduce a new message instead.',
         required: ['seq', 'did', 'migrateTo', 'time'],
         nullable: ['migrateTo'],
         properties: {
@@ -4240,6 +4338,7 @@ export const schemaDict = {
       },
       tombstone: {
         type: 'object',
+        description: 'Indicates that an account has been deleted.',
         required: ['seq', 'did', 'time'],
         properties: {
           seq: {
@@ -4270,8 +4369,7 @@ export const schemaDict = {
       },
       repoOp: {
         type: 'object',
-        description:
-          "A repo operation, ie a write of a single record. For creates and updates, CID is the record's CID as of this operation. For deletes, it's null.",
+        description: 'A repo operation, ie a mutation of a single record.',
         required: ['action', 'path', 'cid'],
         nullable: ['cid'],
         properties: {
@@ -4284,6 +4382,8 @@ export const schemaDict = {
           },
           cid: {
             type: 'cid-link',
+            description:
+              'For creates and updates, the new record CID. For deletions, null.',
           },
         },
       },
@@ -4324,7 +4424,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          'Fetch all labels from a labeler created after a certain date.',
+          'Fetch all labels from a labeler created after a certain date. DEPRECATED: use queryLabels or subscribeLabels instead',
         parameters: {
           type: 'params',
           properties: {
@@ -4440,7 +4540,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Transfer an account.',
+        description:
+          'Transfer an account. NOTE: temporary method, necessarily how account migration will be implemented.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -4513,7 +4614,6 @@ export const schemaDict = {
   AppBskyActorDefs: {
     lexicon: 1,
     id: 'app.bsky.actor.defs',
-    description: 'A reference to an actor in the network.',
     defs: {
       profileViewBasic: {
         type: 'object',
@@ -4646,6 +4746,8 @@ export const schemaDict = {
       },
       viewerState: {
         type: 'object',
+        description:
+          "Metadata about the requesting account's relationship with the subject account. Only has meaningful content for authed requests.",
         properties: {
           muted: {
             type: 'boolean',
@@ -4731,6 +4833,9 @@ export const schemaDict = {
               format: 'at-uri',
             },
           },
+          timelineIndex: {
+            type: 'integer',
+          },
         },
       },
       personalDetailsPref: {
@@ -4815,7 +4920,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get private preferences attached to the account.',
+        description:
+          'Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.',
         parameters: {
           type: 'params',
           properties: {},
@@ -4842,7 +4948,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get detailed profile view of an actor.',
+        description:
+          'Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -4850,6 +4957,7 @@ export const schemaDict = {
             actor: {
               type: 'string',
               format: 'at-identifier',
+              description: 'Handle or DID of account to fetch profile of.',
             },
           },
         },
@@ -4909,7 +5017,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of suggested actors, used for discovery.',
+        description:
+          'Get a list of suggested actors. Expected use is discovery of accounts to follow during new account onboarding.',
         parameters: {
           type: 'params',
           properties: {
@@ -4952,7 +5061,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of a profile.',
+        description: 'A declaration of a Bluesky account profile.',
         key: 'literal:self',
         record: {
           type: 'object',
@@ -4964,21 +5073,28 @@ export const schemaDict = {
             },
             description: {
               type: 'string',
+              description: 'Free-form profile description text.',
               maxGraphemes: 256,
               maxLength: 2560,
             },
             avatar: {
               type: 'blob',
+              description:
+                "Small image to be displayed next to posts from account. AKA, 'profile picture'",
               accept: ['image/png', 'image/jpeg'],
               maxSize: 1000000,
             },
             banner: {
               type: 'blob',
+              description:
+                'Larger horizontal image to display behind profile view.',
               accept: ['image/png', 'image/jpeg'],
               maxSize: 1000000,
             },
             labels: {
               type: 'union',
+              description:
+                'Self-label values, specific to the Bluesky application, on the overall account.',
               refs: ['lex:com.atproto.label.defs#selfLabels'],
             },
           },
@@ -5015,7 +5131,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Find actors (profiles) matching search criteria.',
+        description:
+          'Find actors (profiles) matching search criteria. Does not require auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -5067,7 +5184,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Find actor suggestions for a prefix search term.',
+        description:
+          'Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -5109,11 +5227,11 @@ export const schemaDict = {
   AppBskyEmbedExternal: {
     lexicon: 1,
     id: 'app.bsky.embed.external',
-    description:
-      'A representation of some externally linked content, embedded in another form of content.',
     defs: {
       main: {
         type: 'object',
+        description:
+          "A representation of some externally linked content (eg, a URL and 'card'), embedded in a Bluesky record (eg, a post).",
         required: ['external'],
         properties: {
           external: {
@@ -5177,7 +5295,7 @@ export const schemaDict = {
   AppBskyEmbedImages: {
     lexicon: 1,
     id: 'app.bsky.embed.images',
-    description: 'A set of images embedded in some other form of content.',
+    description: 'A set of images embedded in a Bluesky record (eg, a post).',
     defs: {
       main: {
         type: 'object',
@@ -5204,6 +5322,8 @@ export const schemaDict = {
           },
           alt: {
             type: 'string',
+            description:
+              'Alt text description of the image, for accessibility.',
           },
           aspectRatio: {
             type: 'ref',
@@ -5247,12 +5367,18 @@ export const schemaDict = {
         properties: {
           thumb: {
             type: 'string',
+            description:
+              'Fully-qualified URL where a thumbnail of the image can be fetched. For example, CDN location provided by the App View.',
           },
           fullsize: {
             type: 'string',
+            description:
+              'Fully-qualified URL where a large version of the image can be fetched. May or may not be the exact original blob. For example, CDN location provided by the App View.',
           },
           alt: {
             type: 'string',
+            description:
+              'Alt text description of the image, for accessibility.',
           },
           aspectRatio: {
             type: 'ref',
@@ -5266,7 +5392,7 @@ export const schemaDict = {
     lexicon: 1,
     id: 'app.bsky.embed.record',
     description:
-      'A representation of a record embedded in another form of content.',
+      'A representation of a record embedded in a Bluesky record (eg, a post). For example, a quote-post, or sharing a feed generator record.',
     defs: {
       main: {
         type: 'object',
@@ -5312,6 +5438,7 @@ export const schemaDict = {
           },
           value: {
             type: 'unknown',
+            description: 'The record data itself.',
           },
           labels: {
             type: 'array',
@@ -5376,7 +5503,7 @@ export const schemaDict = {
     lexicon: 1,
     id: 'app.bsky.embed.recordWithMedia',
     description:
-      'A representation of a record embedded in another form of content, alongside other compatible embeds.',
+      'A representation of a record embedded in a Bluesky record (eg, a post), alongside other compatible embeds. For example, a quote post and image, or a quote post and external URL card.',
     defs: {
       main: {
         type: 'object',
@@ -5475,6 +5602,8 @@ export const schemaDict = {
       },
       viewerState: {
         type: 'object',
+        description:
+          "Metadata about the requesting account's relationship with the subject content. Only has meaningful content for authed requests.",
         properties: {
           repost: {
             type: 'string',
@@ -5735,7 +5864,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          'Get information about a feed generator, including policies and offered feed URIs.',
+          'Get information about a feed generator, including policies and offered feed URIs. Does not require auth; implemented by Feed Generator services (not App View).',
         output: {
           encoding: 'application/json',
           schema: {
@@ -5790,7 +5919,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of the existence of a feed generator.',
+        description:
+          'Record declaring of the existence of a feed generator, and containing metadata about it. The record can exist in any repository.',
         key: 'any',
         record: {
           type: 'object',
@@ -5824,6 +5954,7 @@ export const schemaDict = {
             },
             labels: {
               type: 'union',
+              description: 'Self-label values',
               refs: ['lex:com.atproto.label.defs#selfLabels'],
             },
             createdAt: {
@@ -5841,7 +5972,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of feeds created by the actor.',
+        description:
+          "Get a list of feeds (feed generator records) created by the actor (in the actor's repo).",
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -5889,7 +6021,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of posts liked by an actor.',
+        description:
+          'Get a list of posts liked by an actor. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -5945,7 +6078,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: "Get a view of an actor's feed.",
+        description:
+          "Get a view of an actor's 'author feed' (post and reposts by the author). Does not require auth.",
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -5965,6 +6099,8 @@ export const schemaDict = {
             },
             filter: {
               type: 'string',
+              description:
+                'Combinations of post/repost types to include in response.',
               knownValues: [
                 'posts_with_replies',
                 'posts_no_replies',
@@ -6012,7 +6148,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          "Get a hydrated feed from an actor's selected feed generator.",
+          "Get a hydrated feed from an actor's selected feed generator. Implemented by App View.",
         parameters: {
           type: 'params',
           required: ['feed'],
@@ -6065,7 +6201,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get information about a feed generator.',
+        description:
+          'Get information about a feed generator. Implemented by AppView.',
         parameters: {
           type: 'params',
           required: ['feed'],
@@ -6073,6 +6210,7 @@ export const schemaDict = {
             feed: {
               type: 'string',
               format: 'at-uri',
+              description: 'AT-URI of the feed generator record.',
             },
           },
         },
@@ -6088,9 +6226,13 @@ export const schemaDict = {
               },
               isOnline: {
                 type: 'boolean',
+                description:
+                  'Indicates whether the feed generator service has been online recently, or else seems to be inactive.',
               },
               isValid: {
                 type: 'boolean',
+                description:
+                  'Indicates whether the feed generator service is compatible with the record declaration.',
               },
             },
           },
@@ -6143,7 +6285,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a skeleton of a feed provided by a feed generator.',
+        description:
+          'Get a skeleton of a feed provided by a feed generator. Auth is optional, depending on provider requirements, and provides the DID of the requester. Implemented by Feed Generator Service.',
         parameters: {
           type: 'params',
           required: ['feed'],
@@ -6151,6 +6294,8 @@ export const schemaDict = {
             feed: {
               type: 'string',
               format: 'at-uri',
+              description:
+                'Reference to feed generator record describing the specific feed being requested.',
             },
             limit: {
               type: 'integer',
@@ -6196,7 +6341,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get the list of likes.',
+        description:
+          'Get like records which reference a subject (by AT-URI and CID).',
         parameters: {
           type: 'params',
           required: ['uri'],
@@ -6204,10 +6350,13 @@ export const schemaDict = {
             uri: {
               type: 'string',
               format: 'at-uri',
+              description: 'AT-URI of the subject (eg, a post record).',
             },
             cid: {
               type: 'string',
               format: 'cid',
+              description:
+                'CID of the subject record (aka, specific version of record), to filter likes.',
             },
             limit: {
               type: 'integer',
@@ -6274,7 +6423,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a view of a recent posts from actors in a list.',
+        description:
+          'Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.',
         parameters: {
           type: 'params',
           required: ['list'],
@@ -6282,6 +6432,7 @@ export const schemaDict = {
             list: {
               type: 'string',
               format: 'at-uri',
+              description: 'Reference (AT-URI) to the list record.',
             },
             limit: {
               type: 'integer',
@@ -6327,7 +6478,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get posts in a thread.',
+        description:
+          'Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.',
         parameters: {
           type: 'params',
           required: ['uri'],
@@ -6335,15 +6487,20 @@ export const schemaDict = {
             uri: {
               type: 'string',
               format: 'at-uri',
+              description: 'Reference (AT-URI) to post record.',
             },
             depth: {
               type: 'integer',
+              description:
+                'How many levels of reply depth should be included in response.',
               default: 6,
               minimum: 0,
               maximum: 1000,
             },
             parentHeight: {
               type: 'integer',
+              description:
+                'How many levels of parent (and grandparent, etc) post to include.',
               default: 80,
               minimum: 0,
               maximum: 1000,
@@ -6381,13 +6538,15 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: "Get a view of an actor's feed.",
+        description:
+          "Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.",
         parameters: {
           type: 'params',
           required: ['uris'],
           properties: {
             uris: {
               type: 'array',
+              description: 'List of post AT-URIs to return hydrated views for.',
               items: {
                 type: 'string',
                 format: 'at-uri',
@@ -6421,7 +6580,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of reposts.',
+        description: 'Get a list of reposts for a given post.',
         parameters: {
           type: 'params',
           required: ['uri'],
@@ -6429,10 +6588,13 @@ export const schemaDict = {
             uri: {
               type: 'string',
               format: 'at-uri',
+              description: 'Reference (AT-URI) of post record',
             },
             cid: {
               type: 'string',
               format: 'cid',
+              description:
+                'If supplied, filters to reposts of specific version (by CID) of the post record.',
             },
             limit: {
               type: 'integer',
@@ -6481,7 +6643,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of suggested feeds for the viewer.',
+        description:
+          'Get a list of suggested feeds (feed generators) for the requesting account.',
         parameters: {
           type: 'params',
           properties: {
@@ -6524,12 +6687,15 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: "Get a view of the actor's home timeline.",
+        description:
+          "Get a view of the requesting account's home timeline. This is expected to be some form of reverse-chronological feed.",
         parameters: {
           type: 'params',
           properties: {
             algorithm: {
               type: 'string',
+              description:
+                "Variant 'algorithm' for timeline. Implementation-specific. NOTE: most feed flexibility has been moved to feed generator mechanism.",
             },
             limit: {
               type: 'integer',
@@ -6570,7 +6736,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of a like.',
+        description: "Record declaring a 'like' of a piece of subject content.",
         key: 'tid',
         record: {
           type: 'object',
@@ -6595,7 +6761,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of a post.',
+        description: 'Record containing a Bluesky post.',
         key: 'tid',
         record: {
           type: 'object',
@@ -6605,10 +6771,12 @@ export const schemaDict = {
               type: 'string',
               maxLength: 3000,
               maxGraphemes: 300,
+              description:
+                'The primary post content. May be an empty string, if there are embeds.',
             },
             entities: {
               type: 'array',
-              description: 'Deprecated: replaced by app.bsky.richtext.facet.',
+              description: 'DEPRECATED: replaced by app.bsky.richtext.facet.',
               items: {
                 type: 'ref',
                 ref: 'lex:app.bsky.feed.post#entity',
@@ -6616,6 +6784,8 @@ export const schemaDict = {
             },
             facets: {
               type: 'array',
+              description:
+                'Annotations of text (mentions, URLs, hashtags, etc)',
               items: {
                 type: 'ref',
                 ref: 'lex:app.bsky.richtext.facet',
@@ -6636,6 +6806,8 @@ export const schemaDict = {
             },
             langs: {
               type: 'array',
+              description:
+                'Indicates human language of post primary text content.',
               maxLength: 3,
               items: {
                 type: 'string',
@@ -6644,21 +6816,25 @@ export const schemaDict = {
             },
             labels: {
               type: 'union',
+              description:
+                'Self-label values for this post. Effectively content warnings.',
               refs: ['lex:com.atproto.label.defs#selfLabels'],
             },
             tags: {
               type: 'array',
+              description: 'Additional non-inline tags describing this post.',
               maxLength: 8,
               items: {
                 type: 'string',
                 maxLength: 640,
                 maxGraphemes: 64,
               },
-              description: 'Additional non-inline tags describing this post.',
             },
             createdAt: {
               type: 'string',
               format: 'datetime',
+              description:
+                'Client-declared timestamp when this post was originally created.',
             },
           },
         },
@@ -6718,7 +6894,8 @@ export const schemaDict = {
     id: 'app.bsky.feed.repost',
     defs: {
       main: {
-        description: 'A declaration of a repost.',
+        description:
+          "Record representing a 'repost' of an existing Bluesky post.",
         type: 'record',
         key: 'tid',
         record: {
@@ -6744,7 +6921,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Find posts matching search criteria.',
+        description:
+          'Find posts matching search criteria, returning views of those posts.',
         parameters: {
           type: 'params',
           required: ['q'],
@@ -6807,7 +6985,7 @@ export const schemaDict = {
         type: 'record',
         key: 'tid',
         description:
-          "Defines interaction gating rules for a thread. The rkey of the threadgate record should match the rkey of the thread's root post.",
+          "Record defining interaction gating rules for a thread (aka, reply controls). The record key (rkey) of the threadgate record must match the record key of the thread's root post, and that record must be in the same repository..",
         record: {
           type: 'object',
           required: ['post', 'createdAt'],
@@ -6815,6 +6993,7 @@ export const schemaDict = {
             post: {
               type: 'string',
               format: 'at-uri',
+              description: 'Reference (AT-URI) to the post record.',
             },
             allow: {
               type: 'array',
@@ -6864,7 +7043,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of a block.',
+        description:
+          "Record declaring a 'block' relationship against another account. NOTE: blocks are public in Bluesky; see blog posts for details.",
         key: 'tid',
         record: {
           type: 'object',
@@ -6873,6 +7053,7 @@ export const schemaDict = {
             subject: {
               type: 'string',
               format: 'did',
+              description: 'DID of the account to be blocked.',
             },
             createdAt: {
               type: 'string',
@@ -7061,7 +7242,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of a social follow.',
+        description:
+          "Record declaring a social 'follow' relationship of another account. Duplicate follows will be ignored by the AppView.",
         key: 'tid',
         record: {
           type: 'object',
@@ -7086,7 +7268,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of who the actor is blocking.',
+        description:
+          'Enumerates which accounts the requesting account is currently blocking. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -7129,7 +7312,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: "Get a list of an actor's followers.",
+        description:
+          'Enumerates accounts which follow a specified account (actor).',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -7181,7 +7365,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of who the actor follows.',
+        description:
+          'Enumerates accounts which a specified account (actor) follows.',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -7233,7 +7418,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of actors.',
+        description:
+          "Gets a 'view' (with additional context) of a specified list.",
         parameters: {
           type: 'params',
           required: ['list'],
@@ -7241,6 +7427,7 @@ export const schemaDict = {
             list: {
               type: 'string',
               format: 'at-uri',
+              description: 'Reference (AT-URI) of the list record to hydrate.',
             },
             limit: {
               type: 'integer',
@@ -7285,7 +7472,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get lists that the actor is blocking.',
+        description:
+          'Get mod lists that the requesting account (actor) is blocking. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -7328,7 +7516,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get lists that the actor is muting.',
+        description:
+          'Enumerates mod lists that the requesting account (actor) currently has muted. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -7371,7 +7560,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of lists that belong to an actor.',
+        description:
+          'Enumerates the lists created by a specified account (actor).',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -7379,6 +7569,7 @@ export const schemaDict = {
             actor: {
               type: 'string',
               format: 'at-identifier',
+              description: 'The account (actor) to enumerate lists from.',
             },
             limit: {
               type: 'integer',
@@ -7419,7 +7610,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of who the actor mutes.',
+        description:
+          'Enumerates accounts that the requesting account (actor) currently has muted. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -7463,7 +7655,7 @@ export const schemaDict = {
       main: {
         type: 'query',
         description:
-          'Enumerates public relationships between one account, and a list of other accounts',
+          'Enumerates public relationships between one account, and a list of other accounts. Does not require auth.',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -7471,9 +7663,12 @@ export const schemaDict = {
             actor: {
               type: 'string',
               format: 'at-identifier',
+              description: 'Primary account requesting relationships for.',
             },
             others: {
               type: 'array',
+              description:
+                "List of 'other' accounts to be related back to the primary.",
               maxLength: 30,
               items: {
                 type: 'string',
@@ -7521,7 +7716,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get suggested follows related to a given actor.',
+        description:
+          'Enumerates follows similar to a given account (actor). Expected use is to recommend additional accounts immediately after following one account.',
         parameters: {
           type: 'params',
           required: ['actor'],
@@ -7557,7 +7753,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A declaration of a list of actors.',
+        description:
+          'Record representing a list of accounts (actors). Scope includes both moderation-oriented lists and curration-oriented lists.',
         key: 'tid',
         record: {
           type: 'object',
@@ -7565,12 +7762,15 @@ export const schemaDict = {
           properties: {
             purpose: {
               type: 'ref',
+              description:
+                'Defines the purpose of the list (aka, moderation-oriented or curration-oriented)',
               ref: 'lex:app.bsky.graph.defs#listPurpose',
             },
             name: {
               type: 'string',
               maxLength: 64,
               minLength: 1,
+              description: 'Display name for list; can not be empty.',
             },
             description: {
               type: 'string',
@@ -7608,7 +7808,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'A block of an entire list of actors.',
+        description:
+          'Record representing a block relationship against an entire an entire list of accounts (actors).',
         key: 'tid',
         record: {
           type: 'object',
@@ -7617,6 +7818,7 @@ export const schemaDict = {
             subject: {
               type: 'string',
               format: 'at-uri',
+              description: 'Reference (AT-URI) to the mod list record.',
             },
             createdAt: {
               type: 'string',
@@ -7633,7 +7835,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'record',
-        description: 'An item under a declared list of actors.',
+        description:
+          "Record representing an account's inclusion on a specific list. The AppView will ignore duplicate listitem records.",
         key: 'tid',
         record: {
           type: 'object',
@@ -7642,10 +7845,13 @@ export const schemaDict = {
             subject: {
               type: 'string',
               format: 'did',
+              description: 'The account which is included on the list.',
             },
             list: {
               type: 'string',
               format: 'at-uri',
+              description:
+                'Reference (AT-URI) to the list record (app.bsky.graph.list).',
             },
             createdAt: {
               type: 'string',
@@ -7662,7 +7868,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Mute an actor by DID or handle.',
+        description:
+          'Creates a mute relationship for the specified account. Mutes are private in Bluesky. Requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -7685,7 +7892,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Mute a list of actors.',
+        description:
+          'Creates a mute relationship for the specified list of accounts. Mutes are private in Bluesky. Requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -7708,7 +7916,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Unmute an actor by DID or handle.',
+        description: 'Unmutes the specified account. Requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -7731,7 +7939,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Unmute a list of actors.',
+        description: 'Unmutes the specified list of accounts. Requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -7754,7 +7962,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get the count of unread notifications.',
+        description:
+          'Count the number of unread notifications for the requesting account. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -7785,7 +7994,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'query',
-        description: 'Get a list of notifications.',
+        description:
+          'Enumerate notifications for the requesting account. Requires auth.',
         parameters: {
           type: 'params',
           properties: {
@@ -7896,7 +8106,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Register for push notifications with a service.',
+        description:
+          'Register to receive push notifications, via a specified service, for the requesting account. Requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -7929,7 +8140,8 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'procedure',
-        description: 'Notify server that the user has seen notifications.',
+        description:
+          'Notify server that the requesting account has seen notifications. Requires auth.',
         input: {
           encoding: 'application/json',
           schema: {
@@ -7952,6 +8164,7 @@ export const schemaDict = {
     defs: {
       main: {
         type: 'object',
+        description: 'Annotation of a sub-string within rich text.',
         required: ['index', 'features'],
         properties: {
           index: {
@@ -7973,7 +8186,8 @@ export const schemaDict = {
       },
       mention: {
         type: 'object',
-        description: 'A facet feature for actor mentions.',
+        description:
+          "Facet feature for mention of another account. The text is usually a handle, including a '@' prefix, but the facet reference is a DID.",
         required: ['did'],
         properties: {
           did: {
@@ -7984,7 +8198,8 @@ export const schemaDict = {
       },
       link: {
         type: 'object',
-        description: 'A facet feature for links.',
+        description:
+          'Facet feature for a URL. The text URL may have been simplified or truncated, but the facet reference should be a complete URL.',
         required: ['uri'],
         properties: {
           uri: {
@@ -7995,7 +8210,8 @@ export const schemaDict = {
       },
       tag: {
         type: 'object',
-        description: 'A hashtag.',
+        description:
+          "Facet feature for a hashtag. The text usually includes a '#' prefix, but the facet reference should not (except in the case of 'double hash tags').",
         required: ['tag'],
         properties: {
           tag: {
@@ -8008,7 +8224,7 @@ export const schemaDict = {
       byteSlice: {
         type: 'object',
         description:
-          'A text segment. Start is inclusive, end is exclusive. Indices are for utf8-encoded strings.',
+          'Specifies the sub-string range a facet feature applies to. Start index is inclusive, end index is exclusive. Indices are zero-indexed, counting bytes of the UTF-8 encoded text. NOTE: some languages, like Javascript, use UTF-16 or Unicode codepoints for string slice indexing; in these languages, convert to byte arrays before working with facets.',
         required: ['byteStart', 'byteEnd'],
         properties: {
           byteStart: {