From 39216b724bd1491bc00cb380b249cbb43595ad12 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Tue, 30 Jun 2026 18:35:24 -0700
Subject: [PATCH] docs: document base cli context fields

---
 docs/base-cli.md            |  2 ++
 tests/test_base_cli_docs.py | 24 ++++++++++++++++++++++++
 2 files changed, 26 insertions(+)
 create mode 100644 tests/test_base_cli_docs.py

diff --git a/docs/base-cli.md b/docs/base-cli.md
index fc7a61d..e0b7972 100644
--- a/docs/base-cli.md
+++ b/docs/base-cli.md
@@ -127,6 +127,7 @@ ctx.run_id         # str
 ctx.base_home      # Path | None
 ctx.project_root   # Path | None
 ctx.manifest_path  # Path | None
+ctx.workspace_root # configured workspace root, or None
 ctx.state_dir      # Base cache root / cli / <cli-name>
 ctx.log_dir        # state_dir/logs
 ctx.cache_dir      # state_dir/cache
@@ -138,6 +139,7 @@ ctx.environment    # str
 ctx.debug          # bool
 ctx.dry_run        # bool
 ctx.keep_temp      # bool
+ctx.quiet          # bool
 ctx.log            # logging.Logger
 ```
 
diff --git a/tests/test_base_cli_docs.py b/tests/test_base_cli_docs.py
new file mode 100644
index 0000000..4b4f5ff
--- /dev/null
+++ b/tests/test_base_cli_docs.py
@@ -0,0 +1,24 @@
+import re
+from dataclasses import fields
+from pathlib import Path
+
+from base_cli.context import Context
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+BASE_CLI_DOC = REPO_ROOT / "docs" / "base-cli.md"
+INTERNAL_CONTEXT_FIELDS = {"cleanup_hooks"}
+
+
+def context_section() -> str:
+    text = BASE_CLI_DOC.read_text(encoding="utf-8")
+    start = text.index("## Context")
+    end = text.index("## State Directories")
+    return text[start:end]
+
+
+def test_base_cli_context_docs_list_public_context_fields() -> None:
+    documented_fields = set(re.findall(r"ctx\.([a-z_]+)", context_section()))
+    public_context_fields = {field.name for field in fields(Context)} - INTERNAL_CONTEXT_FIELDS
+
+    assert public_context_fields <= documented_fields