Docs: Resolved docs warnings

docs/gen_ref_pages.py

@@ -76,6 +76,10 @@ for path in sorted(SRC_DIR.rglob("*.py")):
     # Tell mkdocs-gen-files where the edit link should point
     mkdocs_gen_files.set_edit_path(full_doc_path, path.as_posix())
 
+# Include manually-authored reference pages that live alongside the
+# auto-generated API docs.
+nav[("actors_schema",)] = "actors_schema.md"
+
 # Write the literate-nav summary file for the Reference section
 with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
     nav_file.writelines(nav.build_literate_nav())

src/cleveragents/domain/models/core/resource.py

@@ -10,10 +10,8 @@ This module implements:
   physical / virtual classification enum
 - [`SandboxStrategy`][cleveragents.domain.models.core.resource.SandboxStrategy] --
   sandbox isolation strategy enum
-- [`ResourceCapabilities`][caps] --
+- [`ResourceCapabilities`][cleveragents.domain.models.core.resource.ResourceCapabilities] --
   capability flags (readable, writable, sandboxable, checkpointable)
-
-[caps]: cleveragents.domain.models.core.resource.ResourceCapabilities
 - [`Resource`][cleveragents.domain.models.core.resource.Resource] --
   the core Resource domain model (``ResourceRecord``)
 
@@ -27,10 +25,8 @@ Based on:
 - ADR-004: Pydantic v2 Validation
 
 See Also:
-    - [ResourceTypeSpec][rts] --
+    - [ResourceTypeSpec][cleveragents.domain.models.core.resource_type.ResourceTypeSpec] --
       Resource type schema definitions
-
-    .. [rts]: cleveragents.domain.models.core.resource_type.ResourceTypeSpec
 """
 
 from __future__ import annotations
@@ -128,9 +124,7 @@ class Resource(BaseModel):
     - ``is_read_only`` -- True when the resource cannot be written
 
     See Also:
-        - [ResourceTypeSpec][rts2]
-
-    .. [rts2]: cleveragents.domain.models.core.resource_type.ResourceTypeSpec
+        - [ResourceTypeSpec][cleveragents.domain.models.core.resource_type.ResourceTypeSpec]
     """
 
     # Identity -- resource_id is the primary key (ULID)