fix few doc

Author: iam404

README.md

@@ -175,6 +175,9 @@ For full details — environment variables, redaction guarantees, and how to add
   - [Manage workspace variables](./docs/scenarios/manage-workspace-variables.md)
   - [Team access onboarding](./docs/scenarios/team-access-onboarding.md)
   - [State management](./docs/scenarios/state-management.md)
+  - [Errored state recovery](./docs/scenarios/errored-state-recovery.md)
+  - [Agent pool setup](./docs/scenarios/agent-pool-setup.md)
+  - [Notification configurations](./docs/scenarios/notification-configurations.md)
   - [Policy enforcement](./docs/scenarios/policy-enforcement.md)
   - [Run task integration](./docs/scenarios/run-task-integration.md)
 - Operations guides:

docs/TESTS.md

@@ -136,8 +136,8 @@ def test_create_workspace(self, client):
     client._transport.request = MagicMock(return_value=mock_response)
 
     # Execute the operation
-    options = WorkspaceCreateOptions(name="new-workspace", organization="test-org")
-    workspace = client.workspaces.create(options)
+    options = WorkspaceCreateOptions(name="new-workspace")
+    workspace = client.workspaces.create("test-org", options)
 
     # Assertions
     assert workspace.id == "ws-new"
@@ -156,15 +156,20 @@ Always test validation and error handling:
 
 ```python
 def test_create_workspace_invalid_org(self, client):
-    """Test creating workspace with invalid organization."""
+    """Test creating workspace with an empty organization name."""
+    options = WorkspaceCreateOptions(name="test")
     with pytest.raises(InvalidOrgError):
-        options = WorkspaceCreateOptions(name="test", organization="")
-        client.workspaces.create(options)
+        client.workspaces.create("", options)
 
 def test_read_workspace_invalid_id(self, client):
-    """Test reading workspace with invalid ID."""
+    """Test read_by_id with an empty workspace ID."""
     with pytest.raises(InvalidWorkspaceIDError):
-        client.workspaces.read(workspace_id="")
+        client.workspaces.read_by_id("")
+
+def test_read_workspace_invalid_name(self, client):
+    """Test read with an empty workspace name."""
+    with pytest.raises(InvalidWorkspaceValueError):
+        client.workspaces.read("", organization="valid-org")
 ```
 
 ### 4. Test Pagination

docs/api/workspaces.md

@@ -13,15 +13,17 @@ Example: [workspace.py](../../examples/workspace.py)
 | Method | Purpose |
 |---|---|
 | `client.workspaces.list(organization, options=None)` | Iterate workspaces in an organization. |
-| `client.workspaces.read(organization, name)` | Read by organization/name. |
+| `client.workspaces.read(name, *, organization)` | Read by name. `organization` is keyword-only. |
 | `client.workspaces.read_by_id(workspace_id)` | Read by workspace ID. |
 | `client.workspaces.create(organization, options)` | Create a workspace. |
-| `client.workspaces.update(organization, name, options)` | Update by organization/name. |
+| `client.workspaces.update(name, options, *, organization)` | Update by name. `organization` is keyword-only. |
 | `client.workspaces.update_by_id(workspace_id, options)` | Update by workspace ID. |
-| `client.workspaces.delete(...)` / `delete_by_id(...)` | Delete a workspace. |
-| `client.workspaces.safe_delete(...)` / `safe_delete_by_id(...)` | Delete with the API safe-delete path. |
+| `client.workspaces.delete(name, *, organization)` / `delete_by_id(workspace_id)` | Delete a workspace. |
+| `client.workspaces.safe_delete(name, *, organization)` / `safe_delete_by_id(workspace_id)` | Delete with the API safe-delete path. |
 | `client.workspaces.lock(...)`, `unlock(...)`, `force_unlock(...)` | Manage workspace locks. |
 | `client.workspaces.assign_ssh_key(...)`, `unassign_ssh_key(...)` | Manage workspace SSH key assignment. |
+| `client.workspaces.current_assessment_result(workspace_id)` | Read the latest health assessment, or `None` if assessments are disabled. |
+| `client.workspaces.list_applicable_varsets(workspace_id)` | Iterate variable sets that apply to a workspace (direct, inherited, and global). |
 | `client.workspaces.list_remote_state_consumers(...)` and related methods | Manage remote state consumers. |
 | `client.workspaces.list_tags(...)`, `add_tags(...)`, `remove_tags(...)` | Manage workspace tags. |
 | `client.workspaces.list_tag_bindings(...)` and related methods | Manage tag bindings. |
@@ -62,10 +64,26 @@ print(workspace.id)
 ## Read by name or ID
 
 ```python
-workspace = client.workspaces.read("my-organization", "example-workspace")
+workspace = client.workspaces.read("example-workspace", organization="my-organization")
 same_workspace = client.workspaces.read_by_id(workspace.id)
 ```
 
+`organization` is a keyword-only argument on `read`, `update`, `delete`, and
+`safe_delete`. The workspace name is positional; the organization name must be
+passed by keyword. The same applies when updating or deleting by name:
+
+```python
+from pytfe.models import WorkspaceUpdateOptions
+
+client.workspaces.update(
+    "example-workspace",
+    WorkspaceUpdateOptions(description="Updated by pyTFE"),
+    organization="my-organization",
+)
+
+client.workspaces.delete("example-workspace", organization="my-organization")
+```
+
 Prefer ID-based methods in automation when you already have the workspace ID.
 They avoid ambiguity when names change.
 

docs/scenarios/agent-pool-setup.md

@@ -0,0 +1,170 @@
+# Scenario: Agent pool setup
+
+HCP Terraform agents let Terraform runs reach private networks that the hosted
+runners cannot. A working agent setup needs four pieces:
+
+1. An agent pool in the organization.
+2. An agent authentication token for each running agent process.
+3. Workspaces (or projects) configured to use the pool.
+4. One or more agent processes started with the token, pointing at the API
+   address.
+
+This scenario covers the SDK side: creating the pool, generating a token, and
+attaching workspaces. Starting the agent process itself is done outside Python
+with the `tfc-agent` binary.
+
+Upstream docs:
+
+- Agents: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/agents
+- Agent tokens: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/agent-tokens
+- Agent pool concepts: https://developer.hashicorp.com/terraform/cloud-docs/agents
+
+## Prerequisites
+
+```bash
+export TFE_TOKEN="your-api-token"
+export TFE_ADDRESS="https://app.terraform.io"
+```
+
+The token needs `manage-agent-pools` permission on the organization, and
+workspace write access on any workspaces you intend to attach.
+
+## Step 1: Create the agent pool
+
+```python
+from pytfe import TFEClient
+from pytfe.models import AgentPoolCreateOptions
+
+
+client = TFEClient()
+organization = "my-organization"
+
+pool = client.agent_pools.create(
+    organization,
+    AgentPoolCreateOptions(
+        name="private-network-pool",
+        organization_scoped=False,
+        allowed_workspace_ids=["ws-abc123"],
+    ),
+)
+
+print(pool.id, pool.name)
+```
+
+Set `organization_scoped=True` to allow every workspace in the organization to
+use the pool. Set it to `False` and pass `allowed_workspace_ids` (and/or
+`allowed_project_ids`) to scope the pool explicitly. Scoped pools are safer for
+shared organizations because they prevent unrelated workspaces from picking up
+the agent.
+
+## Step 2: Create an agent token
+
+Each running agent process needs its own token:
+
+```python
+from pytfe.models import AgentTokenCreateOptions
+
+token = client.agent_tokens.create(
+    pool.id,
+    AgentTokenCreateOptions(description="agent-host-1"),
+)
+
+print(token.id)
+print(token.token)
+```
+
+The token value is returned only at creation time. Store it in a secret manager
+immediately and reference it from the agent host's environment.
+
+For multiple agents, create one token per host so revocation is granular:
+
+```python
+for host in ["agent-host-1", "agent-host-2", "agent-host-3"]:
+    t = client.agent_tokens.create(
+        pool.id,
+        AgentTokenCreateOptions(description=host),
+    )
+    save_to_secret_manager(host, t.token)
+```
+
+## Step 3: Attach workspaces to the pool
+
+A workspace uses an agent pool when its `execution_mode` is `agent` and its
+`agent_pool_id` references the pool:
+
+```python
+from pytfe.models import ExecutionMode, WorkspaceUpdateOptions
+
+client.workspaces.update_by_id(
+    "ws-abc123",
+    WorkspaceUpdateOptions(
+        execution_mode=ExecutionMode.AGENT,
+        agent_pool_id=pool.id,
+    ),
+)
+```
+
+For a scoped pool, you can also widen or narrow the allowed list later:
+
+```python
+from pytfe.models import AgentPoolAssignToWorkspacesOptions
+
+client.agent_pools.assign_to_workspaces(
+    pool.id,
+    AgentPoolAssignToWorkspacesOptions(
+        workspace_ids=["ws-abc123", "ws-def456"],
+    ),
+)
+```
+
+`assign_to_workspaces` replaces the allowed-workspaces list in full; it does
+not append. Always pass the complete intended list.
+
+## Step 4: Start the agent process
+
+Outside Python, on the host that has the network path to your private
+infrastructure:
+
+```bash
+export TFC_AGENT_TOKEN="<token value from Step 2>"
+export TFC_AGENT_NAME="agent-host-1"
+export TFC_ADDRESS="https://app.terraform.io"
+
+tfc-agent
+```
+
+Confirm the agent registered:
+
+```python
+for agent in client.agents.list(pool.id):
+    print(agent.id, agent.name, agent.status)
+```
+
+A healthy agent reports `status="idle"` or `status="busy"`.
+
+## Cleanup
+
+Revoke tokens when a host is decommissioned. Delete the pool only after no
+workspaces or projects reference it.
+
+```python
+client.agent_tokens.delete(token.id)
+
+# Detach the workspace before deleting the pool.
+client.workspaces.update_by_id(
+    "ws-abc123",
+    WorkspaceUpdateOptions(execution_mode=ExecutionMode.REMOTE),
+)
+client.agent_pools.delete(pool.id)
+```
+
+## Operational notes
+
+- Treat agent tokens like SSH keys: one per host, rotated, stored in a secret
+  manager.
+- Prefer scoped pools over organization-scoped pools when only some workspaces
+  need private-network access.
+- Agent processes hold long-lived connections. Restart them after rotating
+  tokens or upgrading the agent binary.
+- An agent pool with no running agents will leave runs queued indefinitely.
+  Monitor `client.agents.list(pool.id)` from your observability stack.

docs/scenarios/api-driven-run.md

@@ -58,7 +58,7 @@ terraform_dir = Path("./terraform")
 
 def read_or_create_workspace() -> Workspace:
     try:
-        return client.workspaces.read(organization, workspace_name)
+        return client.workspaces.read(workspace_name, organization=organization)
     except TFEError:
         return client.workspaces.create(
             organization,