features/project_commands_coverage.feature

@@ -96,9 +96,10 @@ Feature: Project Commands Coverage
     And the command should abort
 
   @phase1
-  Scenario: Test project list command with no database
+  Scenario: Test project list command with no projects
+    Given I have a temporary working directory
     When I run project list command
-    Then the command should abort
+    Then the project list output should contain "No projects found"
 
   @phase1
   Scenario: Test project clean command not implemented

features/steps/project_commands_coverage_steps.py

@@ -274,7 +274,33 @@ def step_execute_project_status_error(context):
 
 @when("I run project list command")
 def step_run_project_list(context):
-    """Run project list command."""
+    """Run project list command.
+
+    Ensures the default database path is writable by creating the
+    ``.cleveragents`` directory and bootstrapping the schema so the
+    ``list`` sub-command can query the ``ns_projects`` table even
+    when no projects exist.
+    """
+    import os
+
+    from sqlalchemy import create_engine
+
+    from cleveragents.infrastructure.database.models import Base
+
+    # Ensure the fallback database directory exists inside the temp CWD
+    db_dir = Path.cwd() / ".cleveragents"
+    db_dir.mkdir(parents=True, exist_ok=True)
+    db_path = db_dir / "db.sqlite"
+
+    # Point the container at this database so it doesn't fail on open
+    db_url = f"sqlite:///{db_path.absolute()}"
+    os.environ["CLEVERAGENTS_DATABASE_URL"] = db_url
+
+    # Bootstrap the schema so the table exists for the query
+    engine = create_engine(db_url, echo=False)
+    Base.metadata.create_all(engine)
+    engine.dispose()
+
     runner = CliRunner()
     result = runner.invoke(project.app, ["list"])
     context.result = result
@@ -676,3 +702,14 @@ def step_project_command_exit_code(context, code):
     assert context.result.exit_code == code, (
         f"Expected exit code {code}, got {context.result.exit_code}. Output: {context.result.output}"
     )
+
+
+@then('the project list output should contain "{text}"')
+def step_project_list_output_contains(context, text):
+    """Assert the project list output contains expected text."""
+    assert context.result.exit_code == 0, (
+        f"Expected exit code 0, got {context.result.exit_code}. Output: {context.result.output}"
+    )
+    assert text in context.result.output, (
+        f"Expected '{text}' in output: {context.result.output}"
+    )

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

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

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

@@ -23,13 +23,13 @@ devops/docker-build
 
 ## Source Types
 
-| Source        | Description                                    | Required Fields             |
-|---------------|------------------------------------------------|-----------------------------|
-| ``mcp``       | Delegates to an MCP server                     | ``mcp_server``, ``mcp_tool_name`` |
-| ``agent_skill``| Agent Skills Standard folder                  | ``agent_skill_path``        |
-| ``builtin``   | Provided by the runtime                        | (none)                      |
-| ``custom``    | Inline Python code                             | ``code``                    |
-| ``wrapped``   | Validation-only; wraps an existing tool        | (set via Validation)        |
+| Source      | Description                      | Required Fields          |
+|-------------|----------------------------------|--------------------------|
+| ``mcp``     | Delegates to an MCP server       | ``mcp_server/tool_name`` |
+| ``agent_skill`` | Agent Skills Standard folder | ``agent_skill_path``     |
+| ``builtin`` | Provided by the runtime          | (none)                   |
+| ``custom``  | Inline Python code               | ``code``                 |
+| ``wrapped`` | Validation-only; wraps a tool    | (set via Validation)     |
 
 ## Validation Modes
 

src/cleveragents/infrastructure/database/models.py

@@ -5,20 +5,20 @@ Alembic migrations.
 
 ## Tables
 
-| Table                     | Model                         | Description                     |
-|---------------------------|-------------------------------|---------------------------------|
-| ``actions``               | ``ActionModel``               | Action templates                |
-| ``action_invariants``     | ``ActionInvariantModel``      | Action invariant rules          |
-| ``action_arguments``      | ``ActionArgumentModel``       | Action typed arguments          |
-| ``v3_plans``              | ``V3PlanModel``               | Plan lifecycle instances        |
-| ``plan_projects``         | ``PlanProjectModel``          | Plan-project links              |
-| ``plan_arguments``        | ``PlanArgumentModel``         | Plan argument values            |
-| ``plan_invariants``       | ``PlanInvariantModel``        | Plan invariant rules            |
-| ``resource_types``        | ``ResourceTypeModel``         | Resource type definitions       |
-| ``resources``             | ``ResourceModel``             | Resource instances              |
-| ``resource_edges``        | ``ResourceEdgeModel``         | Resource DAG edges              |
-| ``ns_projects``           | ``NamespacedProjectModel``    | Namespaced projects             |
-| ``project_resource_links``| ``ProjectResourceLinkModel``  | Project-resource bindings       |
+| Table                  | Model                      | Description            |
+|------------------------|----------------------------|------------------------|
+| ``actions``            | ``ActionModel``            | Action templates       |
+| ``action_invariants``  | ``ActionInvariantModel``   | Invariant rules        |
+| ``action_arguments``   | ``ActionArgumentModel``    | Typed arguments        |
+| ``v3_plans``           | ``V3PlanModel``            | Plan lifecycle         |
+| ``plan_projects``      | ``PlanProjectModel``       | Plan-project links     |
+| ``plan_arguments``     | ``PlanArgumentModel``      | Plan argument values   |
+| ``plan_invariants``    | ``PlanInvariantModel``     | Plan invariant rules   |
+| ``resource_types``     | ``ResourceTypeModel``      | Resource type defs     |
+| ``resources``          | ``ResourceModel``          | Resource instances     |
+| ``resource_edges``     | ``ResourceEdgeModel``      | Resource DAG edges     |
+| ``ns_projects``        | ``NamespacedProjectModel`` | Namespaced projects    |
+| ``project_resource_links`` | ``ProjectResourceLinkModel`` | Project-resource |
 
 Based on ADR-007 (Repository Pattern) and Phase 0 discovery.
 Includes spec-aligned lifecycle models per Stage A5

src/cleveragents/tool/lifecycle.py

@@ -27,10 +27,10 @@ ToolRuntime
 
 ## Capability Enforcement
 
-| Constraint           | Condition                        | Error                             |
-|----------------------|----------------------------------|-----------------------------------|
-| Read-only plan       | Tool has ``writes=True``         | ``ToolAccessDeniedError``         |
-| Checkpoint required  | Tool has ``checkpointable=False``| ``ToolCheckpointRequiredError``   |
+| Constraint         | Condition                  | Error                       |
+|--------------------|----------------------------|-----------------------------|
+| Read-only plan     | ``writes=True``            | ``ToolAccessDeniedError``   |
+| Checkpoint needed  | ``checkpointable=False``   | ``ToolCheckpointRequired``  |
 
 ## Error Hierarchy