Document AttributeType naming conventions comprehensively

- Reorganize "Special DataJoint-only datatypes" as "AttributeTypes"
- Add naming convention explanation (dj prefix, x prefix, @store suffix)
- List all built-in AttributeTypes with categories:
  - Serialization types: <djblob>, <xblob>
  - File storage types: <object>, <content>
  - File attachment types: <attach>, <xattach>
  - File reference types: <filepath>
- Fix inconsistent angle bracket notation throughout docs
- Update example to use int32 core type and include <djblob>
- Expand naming conventions in Key Design Decisions section

Co-authored-by: dimitri-yatsenko <dimitri@datajoint.com>

Author: claude

docs/src/design/tables/attributes.md

@@ -76,27 +76,55 @@ for portable pipelines. Using native types will generate a warning.
 
 See the [storage types spec](storage-types-spec.md) for complete mappings.
 
-## Special DataJoint-only datatypes
+## AttributeTypes (special datatypes)
 
-These types abstract certain kinds of non-database data to facilitate use
-together with DataJoint.
+AttributeTypes provide `encode()`/`decode()` semantics for complex data that doesn't
+fit native database types. They are denoted with angle brackets: `<type_name>`.
+
+### Naming conventions
+
+- **`dj` prefix**: DataJoint-specific internal serialization (`<djblob>`)
+- **`x` prefix**: External/content-addressed variant (`<xblob>`, `<xattach>`)
+- **`@store` suffix**: Specifies which configured store to use
+
+### Built-in AttributeTypes
+
+**Serialization types** - for Python objects:
 
 - `<djblob>`: DataJoint's native serialization format for Python objects. Supports
-NumPy arrays, dicts, lists, datetime objects, and nested structures. Compatible with
-MATLAB. See [custom types](customtype.md) for details.
+  NumPy arrays, dicts, lists, datetime objects, and nested structures. Stores in
+  database. Compatible with MATLAB. See [custom types](customtype.md) for details.
+
+- `<xblob>` / `<xblob@store>`: Like `<djblob>` but stores externally with content-
+  addressed deduplication. Use for large arrays that may be duplicated across rows.
+
+**File storage types** - for managed files:
+
+- `<object>` / `<object@store>`: Managed file and folder storage with path derived
+  from primary key. Supports Zarr, HDF5, and direct writes via fsspec. Returns
+  `ObjectRef` for lazy access. See [object storage](object.md).
+
+- `<content>` / `<content@store>`: Content-addressed storage for raw bytes with
+  SHA256 deduplication. Use via `<xblob>` or `<xattach>` rather than directly.
+
+**File attachment types** - for file transfer:
+
+- `<attach>`: File attachment stored in database with filename preserved. Similar
+  to email attachments. Good for small files (<16MB). See [attachments](attach.md).
+
+- `<xattach>` / `<xattach@store>`: Like `<attach>` but stores externally with
+  deduplication. Use for large files.
 
-- `object`: managed [file and folder storage](object.md) with support for direct writes
-(Zarr, HDF5) and fsspec integration. Recommended for new pipelines.
+**File reference types** - for external files:
 
-- `attach`: a [file attachment](attach.md) similar to email attachments facillitating
-sending/receiving an opaque data file to/from a DataJoint pipeline.
+- `<filepath@store>`: Reference to existing file in a configured store. No file
+  copying occurs. Returns `ObjectRef` for lazy access. See [filepath](filepath.md).
 
-- `filepath@store`: a [filepath](filepath.md) used to link non-DataJoint managed files
-into a DataJoint pipeline.
+### User-defined AttributeTypes
 
-- `<custom_type>`: a [custom attribute type](customtype.md) that defines bidirectional
-conversion between Python objects and database storage formats. Use this to store
-complex data types like graphs, domain-specific objects, or custom data structures.
+- `<custom_type>`: Define your own [custom attribute type](customtype.md) with
+  bidirectional conversion between Python objects and database storage. Use for
+  graphs, domain-specific objects, or custom data structures.
 
 ## Core type aliases
 
@@ -125,14 +153,15 @@ Example usage:
 @schema
 class Measurement(dj.Manual):
     definition = """
-    measurement_id : int
+    measurement_id : int32
     ---
     temperature : float32       # single-precision temperature reading
     precise_value : float64     # double-precision measurement
     sample_count : uint32       # unsigned 32-bit counter
     sensor_flags : uint8        # 8-bit status flags
     is_valid : bool             # boolean flag
     raw_data : bytes            # raw binary data
+    processed : <djblob>        # serialized Python object
     """
 ```
 

docs/src/design/tables/storage-types-spec.md

@@ -652,11 +652,11 @@ def garbage_collect(project):
 8. **No `uri` type**: For arbitrary URLs, use `varchar`—simpler and more transparent
 9. **Content type**: Single-blob, content-addressed, deduplicated storage
 10. **Parameterized types**: `<type@param>` passes store parameter
-11. **Naming convention**:
-    - `<djblob>` = internal serialized (database)
-    - `<xblob>` = external serialized (content-addressed)
-    - `<attach>` = internal file (single file)
-    - `<xattach>` = external file (single file)
+11. **Naming conventions**:
+    - `dj` prefix = DataJoint-specific internal serialization (`<djblob>`)
+    - `x` prefix = external/content-addressed variant (`<xblob>`, `<xattach>`)
+    - `@store` suffix = specifies which configured store to use
+    - Types without prefix: core storage mechanisms (`<object>`, `<content>`, `<attach>`, `<filepath>`)
 12. **Transparent access**: AttributeTypes return Python objects or file paths
 13. **Lazy access**: `<object>`, `<object@store>`, and `<filepath@store>` return ObjectRef
 
@@ -668,7 +668,7 @@ def garbage_collect(project):
 | `blob@store` | `<xblob@store>` |
 | `attach` | `<attach>` |
 | `attach@store` | `<xattach@store>` |
-| `filepath@store` (copy-based) | `filepath@store` (ObjectRef-based, upgraded) |
+| `filepath@store` (copy-based) | `<filepath@store>` (ObjectRef-based, upgraded) |
 
 ### Migration from Legacy `~external_*` Stores