confpub-cli 0.5.0__tar.gz → 0.6.0__tar.gz

confpub_cli-0.6.0/FEEDBACK.md

@@ -0,0 +1,197 @@
+# confpub-cli v0.5.0 — Blind Test Feedback
+
+Tested by: Claude Code (Opus 4.6) on 2026-03-01, Windows 11, via `uvx confpub-cli`.
+
+---
+
+## Summary
+
+confpub v0.5.0 is a well-designed, agent-friendly CLI. The structured JSON envelope, clear error taxonomy, and comprehensive `guide` command make it straightforward for an LLM agent to drive programmatically. The full publish/pull/delete lifecycle works correctly, and round-trip Markdown fidelity is excellent. This review covers what works well, what could be improved, and specific bugs encountered.
+
+---
+
+## What Works Well
+
+### Structured JSON Envelope
+Every command returns the same `{ ok, command, target, result, warnings, errors, metrics }` shape. This is the single most important design decision for agent consumption — no output parsing required.
+
+### Error Taxonomy
+Typed error codes (`ERR_VALIDATION_*`, `ERR_AUTH_*`, `ERR_IO_*`, `ERR_CONFLICT_*`) with `retryable` and `suggested_action` fields make programmatic error handling trivial. Exit codes are consistent with the documented schema.
+
+### `guide` Command
+The machine-readable schema is comprehensive: command metadata, flags, safety annotations, concurrency rules, error codes, and auth precedence. The `--section` flag works for top-level keys (`commands`, `auth`, `error_codes`, `concurrency`).
+
+### Markdown Round-Trip Fidelity
+Published a file with headings, bullet lists, tables, blockquotes, and fenced code blocks. Pulled it back — the Markdown was virtually identical (only trivial whitespace differences in table alignment `| --- |` vs `|---------|`). This is a strong result.
+
+### Publish Lifecycle
+- `page.publish` with `--dry-run` correctly reports what would happen before writing.
+- Re-publishing an existing page updates it in-place with version increment.
+- `--backup` flag saves the previous HTML to `.confpub-backup-{id}.html`.
+- `--title` override works as expected.
+- `page.delete` cleanly removes the page.
+
+### Recursive Pull + Manifest Generation
+`page pull --recursive --manifest` correctly traverses child pages and generates a well-structured `confpub.yaml` manifest. The flat layout manifest correctly represents the page hierarchy with `children:` nesting.
+
+### Plan Workflow
+The `plan create` / `plan validate` / `plan apply --dry-run` workflow functions correctly. Plans include fingerprints for stale-state detection, which is a nice safety feature.
+
+### Lock File
+`confpub.lock` tracks page IDs and versions, providing local state awareness across commands.
+
+### Auth & Config
+`auth inspect` and `config inspect` return clear, useful information. Token masking in `config inspect` is a good security practice.
+
+---
+
+## Bugs
+
+### 1. Stderr Message Leaks on Expected "Not Found" Lookups
+**Severity: Medium**
+
+When publishing a new page (or doing a dry-run), the CLI prints `Can't find '<title>' page on ...` to stderr before the JSON output. This happens because the tool checks whether the page exists first. For a *new* page, not finding it is the expected path — not an error. The message is confusing, especially during `--dry-run` where the user explicitly wants to preview a creation.
+
+`--quiet` suppresses it, but agents shouldn't need `--quiet` for expected behavior.
+
+**Suggestion:** Only emit this message at `--verbose` level, or suppress it when the subsequent operation succeeds.
+
+### 2. Relative Paths Fail for `plan validate` and `plan apply`
+**Severity: Medium**
+
+```
+uvx confpub-cli plan validate --plan plan-test/test-plan.json
+# ERR_IO_FILE_NOT_FOUND: Plan file not found: plan-test/test-plan.json
+
+uvx confpub-cli plan validate --plan "C:/Users/.../test-plan.json"
+# Works fine
+```
+
+Relative paths resolve correctly for `page publish` (the FILE argument) but not for `--plan` in plan commands. This is likely a `Path.resolve()` vs `Path()` issue.
+
+### 3. `page inspect` `webui` Field Inconsistent Format
+**Severity: Low**
+
+- With `--space SD --title "..."`: returns relative URL `/spaces/SD/pages/327981/Test+Page`
+- With `--page-id 327981`: returns absolute URL `https://...atlassian.net/wiki/spaces/SD/pages/327981/Test+Page`
+
+Should be consistent — preferably always absolute, since the agent may not know the base URL.
+
+### 4. `ERR_AUTH_FORBIDDEN` for Nonexistent Space
+**Severity: Low**
+
+```
+uvx confpub-cli page inspect --space FAKESPACE --title "Test"
+# ERR_AUTH_FORBIDDEN: "Permission denied (get_page)"
+# suggested_action: "escalate"
+```
+
+A nonexistent space key returns a permission error rather than a "space not found" validation error. The `suggested_action` is `"escalate"` but the guide says ERR_AUTH_FORBIDDEN should suggest `"reauth"`. An agent following the guide would incorrectly attempt to re-authenticate.
+
+### 5. `guide --section` Does Not List Valid Sections on Error
+**Severity: Low**
+
+```
+uvx confpub-cli guide --section search
+# ERR_VALIDATION_REQUIRED: "Unknown guide section: search"
+```
+
+The error doesn't tell you what the valid sections are. Adding `"valid_sections": ["commands", "auth", "error_codes", "concurrency", "compatibility"]` to the error details would save a round-trip.
+
+### 6. Nested Layout Manifest Uses Ambiguous `file: index.md` for All Pages
+**Severity: Medium**
+
+When using `--layout nested`, every page gets `file: index.md` in the manifest without a directory prefix:
+
+```yaml
+pages:
+- title: confpub v0.3.0 Blind Test Report
+  file: index.md
+  children:
+  - title: What Works Well
+    file: index.md
+  - title: Bugs and Issues
+    file: index.md
+```
+
+These are all `index.md` — a plan created from this manifest would have no way to distinguish them. The file paths should include the relative directory (e.g., `confpub-v030-blind-test-report/index.md`).
+
+### 7. Nested Layout Doesn't Actually Nest Directories
+**Severity: Low**
+
+The `--layout nested` option creates a flat set of directories rather than truly nesting children inside parents:
+
+```
+pulled-nested/
+  confpub-v030-blind-test-report/index.md   # parent
+  what-works-well/index.md                   # child (not nested inside parent dir)
+  bugs-and-issues/index.md                   # child
+  full-test-matrix/index.md                  # child
+```
+
+Expected behavior for "nested" layout would place children inside the parent directory.
+
+### 8. `--layout nested` Generates Manifest Without `--manifest` Flag
+**Severity: Low**
+
+Using `page pull --layout nested` generates a `confpub.yaml` even without the `--manifest` flag. The flat layout correctly requires `--manifest` to generate one.
+
+---
+
+## Suggestions (Not Bugs)
+
+### Add `page.inspect --format markdown`
+Currently `page inspect` returns raw Confluence storage XML. An option to return the reverse-converted Markdown would be useful for quick content review without pulling to a file.
+
+### Add `search --type page` Default for Agent Usage
+Agents almost always want pages, not attachments or space entities. Consider a default or a `--pages-only` shorthand.
+
+### Document `confpub.lock` in `guide`
+The lock file is created implicitly but isn't documented in the guide schema. Agents should know it exists and what it tracks.
+
+### `ERR_IO_FILE_NOT_FOUND` Suggestion for Missing Source
+When the source file doesn't exist, `retryable: true` with `suggested_action: "retry"` is misleading — a file that doesn't exist won't appear on retry. Consider `retryable: false` with `suggested_action: "fix_input"` for local file-not-found errors (vs. transient network errors).
+
+---
+
+## Test Matrix
+
+| Command | Flags Tested | Result | Notes |
+|---|---|---|---|
+| `guide` | (none), `--section commands`, `--section auth`, `--section error_codes` | Pass | `--section` works for top-level keys |
+| `guide --section` | invalid section name | Pass (with note) | Error lacks valid section list |
+| `auth inspect` | (none) | Pass | |
+| `config inspect` | (none) | Pass | Token correctly masked |
+| `space list` | (none) | Pass | |
+| `page list` | `--space` | Pass | |
+| `page inspect` | `--space --title`, `--page-id` | Pass | webui format inconsistency |
+| `page publish` | `--dry-run`, `--backup`, `--title` | Pass | stderr leak on new page |
+| `page publish` (update) | `--backup` | Pass | Version incremented correctly |
+| `page pull` | `--output`, `--force`, `--manifest` | Pass | |
+| `page pull` | `--recursive`, `--layout flat` | Pass | |
+| `page pull` | `--recursive`, `--layout nested` | Pass (with notes) | Manifest ambiguity, not truly nested |
+| `page delete` | `--space --title` | Pass | |
+| `search` | `--space`, `--limit`, `--cql` | Pass | |
+| `plan create` | `--manifest`, `--output` | Pass | |
+| `plan validate` | `--plan` (absolute path) | Pass | Relative path fails |
+| `plan apply` | `--plan --dry-run` | Pass | |
+| `attachment list` | `--page-id` | Pass | |
+| `--quiet` | global flag | Pass | Suppresses stderr messages |
+| `--verbose` | global flag | Pass | Adds diagnostics to metrics |
+| Error: missing file | `page publish nonexistent.md` | Pass | Clear error |
+| Error: missing page | `page inspect --title "..."` | Pass | |
+| Error: missing args | `page publish` (no file) | Pass | |
+| Error: missing space | `--space FAKESPACE` | Fail | Misleading ERR_AUTH_FORBIDDEN |
+
+---
+
+## Overall Assessment
+
+**confpub v0.5.0 is production-ready for the core publish/pull/delete workflow.** The agent-first JSON design, error taxonomy, and guide command set a high bar for CLI ergonomics. The main areas for improvement are:
+
+1. Fix relative path resolution for plan commands (blocks scripted workflows)
+2. Fix the nested layout manifest ambiguity (blocks round-trip with nested trees)
+3. Suppress the "Can't find" stderr noise on expected new-page creation
+4. Normalize the `webui` field format
+
+None of these are blockers for single-page publishing, which is the most common use case.

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: Agent-first CLI to publish Markdown to Confluence
 Project-URL: Homepage, https://github.com/ThomasRohde/confpub-cli
 Project-URL: Repository, https://github.com/ThomasRohde/confpub-cli.git

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/__init__.py

@@ -1,3 +1,3 @@
 """confpub — Agent-first CLI to publish Markdown to Confluence."""
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/applier.py

@@ -62,6 +62,8 @@ def apply_plan(
             raise ConfpubError(
                 ERR_IO_FILE_NOT_FOUND,
                 f"Source file missing: {page.source_file}",
+                retryable=False,
+                suggested_action="fix_input",
             )
 
         # Fingerprint check (unless skipped)

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/cli.py

@@ -177,7 +177,7 @@ def page_list(
         from confpub.confluence import build_client, _slim_page
         client = build_client()
         pages = client.list_pages(space)
-        ctx.result = {"pages": [_slim_page(p) for p in pages]}
+        ctx.result = {"pages": [_slim_page(p, base_url=client._config.base_url.rstrip("/")) for p in pages]}
 
 
 @page_app.command("inspect")
@@ -186,6 +186,7 @@ def page_inspect(
     title: str = typer.Option(None, "--title", help="Page title"),
     page_id: str = typer.Option(None, "--page-id", help="Confluence page ID"),
     raw: bool = typer.Option(False, "--raw", help="Return full raw API response"),
+    format: str = typer.Option("storage", "--format", help="Output format: storage (raw HTML) or markdown"),
 ) -> None:
     """Inspect a Confluence page."""
     with command_context("page.inspect", target={"space": space, "title": title, "page_id": page_id}) as ctx:
@@ -201,7 +202,20 @@ def page_inspect(
         if not page:
             from confpub.errors import ERR_VALIDATION_NOT_FOUND
             raise ConfpubError(ERR_VALIDATION_NOT_FOUND, f"Page not found")
-        ctx.result = page if raw else _slim_page(page)
+        if raw:
+            ctx.result = page
+        else:
+            result = _slim_page(page, base_url=client._config.base_url.rstrip("/"))
+            if format == "markdown" and "body_storage" in result:
+                from confpub.reverse_converter import convert_storage_to_markdown
+                conversion = convert_storage_to_markdown(result["body_storage"])
+                result["body_markdown"] = conversion.markdown
+                del result["body_storage"]
+                if conversion.warnings:
+                    result["conversion_warnings"] = conversion.warnings
+                if conversion.unknown_macros:
+                    result["unknown_macros"] = conversion.unknown_macros
+            ctx.result = result
 
 
 @page_app.command("publish")
@@ -484,6 +498,7 @@ def guide(
                     raise validation_error(
                         ERR_VALIDATION_REQUIRED,
                         f"Unknown guide section: {section}",
+                        valid_sections=list(full_guide.keys()),
                     )
             ctx.result = result
         else:

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/confluence.py

@@ -32,10 +32,10 @@ class ConfluenceClient:
         self._call_count = 0
 
         # Suppress noisy atlassian-python-api logging (e.g. "Can't find 'X' page")
-        from confpub.output import is_quiet
+        from confpub.output import is_verbose
 
         atlassian_logger = logging.getLogger("atlassian")
-        atlassian_logger.setLevel(logging.CRITICAL if is_quiet() else logging.WARNING)
+        atlassian_logger.setLevel(logging.WARNING if is_verbose() else logging.CRITICAL)
 
     @staticmethod
     def _build_api(config: ResolvedConfig) -> Any:
@@ -74,7 +74,7 @@ class ConfluenceClient:
             raise ConfpubError(
                 ERR_AUTH_FORBIDDEN,
                 f"Permission denied ({context}): {msg}",
-                suggested_action="escalate",
+                details={"note": "This may indicate a nonexistent resource; Confluence returns 403 for both."},
             ) from exc
         # Not found (404 or explicit "not found")
         if "404" in msg or "not found" in msg.lower():
@@ -403,7 +403,7 @@ class ConfluenceClient:
             return None
 
 
-def _slim_page(page: dict[str, Any]) -> dict[str, Any]:
+def _slim_page(page: dict[str, Any], *, base_url: str = "") -> dict[str, Any]:
     """Extract agent-relevant fields from a raw Confluence page object."""
     result: dict[str, Any] = {
         "id": page.get("id"),
@@ -421,7 +421,7 @@ def _slim_page(page: dict[str, Any]) -> dict[str, Any]:
         result["body_storage"] = body
     links = page.get("_links", {})
     if "webui" in links:
-        base = links.get("base", "")
+        base = links.get("base", "") or base_url
         result["webui"] = base + links["webui"]
     return result
 

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/guide.py

@@ -66,6 +66,7 @@ def build_guide() -> dict[str, Any]:
                 "mutates": False,
                 "description": "Search Confluence content using CQL",
                 "flags": ["--cql", "--space", "--type", "--limit", "--start", "--include-archived", "--excerpt-length"],
+                "agent_hint": "Most agent workflows should include --type page to exclude attachments and space entities from results.",
                 "result_schema": {
                     "cql_query": "string — effective CQL sent to the API",
                     "results": "list of {id, type, title, excerpt, url, space_key, entity_type, status, last_modified, container_title}",
@@ -90,7 +91,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "read",
                 "mutates": False,
                 "description": "Inspect a Confluence page",
-                "flags": ["--space", "--title", "--page-id"],
+                "flags": ["--space", "--title", "--page-id", "--format"],
             },
             "page.publish": {
                 "group": "write",
@@ -232,6 +233,21 @@ def build_guide() -> dict[str, Any]:
                 "to the same workspace return ERR_CONFLICT_LOCK"
             ),
         },
+        "lockfile": {
+            "description": "Local state file tracking page IDs and versions from publish/pull operations.",
+            "file": "confpub.lock",
+            "schema": {
+                "schema_version": "Lockfile format version (currently '1.0')",
+                "last_updated": "ISO 8601 timestamp of last write",
+                "pages": "Map of page title to { page_id, version }",
+            },
+            "behavior": [
+                "Created/updated automatically by page.publish, page.pull, and plan.apply",
+                "Written atomically (temp file + rename) for crash safety",
+                "Used by plan.create to detect existing pages and versions",
+                "Does not prevent concurrent operations — purely local state tracking",
+            ],
+        },
         "auth": {
             "precedence": [
                 "--token + --user",

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/manifest.py

@@ -139,7 +139,12 @@ def load_manifest(path: str) -> Manifest:
     p = Path(path)
     if not p.exists():
         from confpub.errors import ERR_IO_FILE_NOT_FOUND
-        raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Manifest not found: {path}")
+        raise ConfpubError(
+            ERR_IO_FILE_NOT_FOUND,
+            f"Manifest not found: {path}",
+            retryable=False,
+            suggested_action="fix_input",
+        )
     try:
         data = yaml.safe_load(p.read_text(encoding="utf-8"))
         if not isinstance(data, dict):

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/planner.py

@@ -70,6 +70,8 @@ def create_plan(
                 ERR_IO_FILE_NOT_FOUND,
                 f"Source file not found: {fp.file}",
                 details={"file": fp.file},
+                retryable=False,
+                suggested_action="fix_input",
             )
 
         # Read and convert markdown

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/publish.py

@@ -49,6 +49,8 @@ def publish_page(
             ERR_IO_FILE_NOT_FOUND,
             f"Source file not found: {file}",
             details={"file": file},
+            retryable=False,
+            suggested_action="fix_input",
         )
 
     # Derive title from filename if not provided

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/puller.py

@@ -107,8 +107,9 @@ def _compute_file_paths(
             while current and current != root_page_id:
                 chain.append(id_to_slug.get(current, current))
                 current = id_to_parent.get(current)  # type: ignore[assignment]
-            if pid == root_page_id:
-                chain.append(slug)
+            # Always include root as the outermost directory
+            if root_slug:
+                chain.append(root_slug)
             chain.reverse()
             rel_path = os.path.join(*chain, "index.md") if len(chain) > 0 else f"{slug}/index.md"
             paths[pid] = os.path.join(output_dir, rel_path)
@@ -185,6 +186,7 @@ def _build_page_tree(
     pages: list[dict[str, Any]],
     file_paths: dict[str, str],
     root_page_id: str,
+    output_dir: str = ".",
 ) -> list[dict[str, Any]]:
     """Build a hierarchical page tree for manifest generation."""
     id_to_entry: dict[str, dict[str, Any]] = {}
@@ -198,7 +200,7 @@ def _build_page_tree(
 
         id_to_entry[pid] = {
             "title": page.get("title", ""),
-            "file": os.path.basename(file_path) if file_path else "",
+            "file": os.path.relpath(file_path, output_dir) if file_path else "",
             "children": [],
         }
         children_map.setdefault(parent_id, []).append(pid)
@@ -308,9 +310,9 @@ def pull_pages(
 
     # Generate manifest if requested or recursive with multiple pages
     manifest_file: str | None = None
-    if generate_manifest or (recursive and len(all_pages) > 1):
+    if generate_manifest:
         root_title = root_page.get("title", "")
-        page_tree = _build_page_tree(all_pages, file_paths, root_id)
+        page_tree = _build_page_tree(all_pages, file_paths, root_id, output_dir)
         manifest_yaml = generate_manifest_yaml(root_space, root_title, page_tree)
         manifest_path = os.path.join(output_dir, "confpub.yaml")
         Path(manifest_path).write_text(manifest_yaml, encoding="utf-8")

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/validator.py

@@ -19,9 +19,14 @@ from confpub.manifest import PlanArtifact, PlanPage
 
 def _load_plan(plan_path: str) -> PlanArtifact:
     """Load and parse a plan artifact JSON file."""
-    p = Path(plan_path)
+    p = Path(plan_path).resolve()
     if not p.exists():
-        raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Plan file not found: {plan_path}")
+        raise ConfpubError(
+            ERR_IO_FILE_NOT_FOUND,
+            f"Plan file not found: {plan_path}",
+            retryable=False,
+            suggested_action="fix_input",
+        )
     try:
         data = json.loads(p.read_text(encoding="utf-8"))
         return PlanArtifact(**data)

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/confpub/verifier.py

@@ -20,7 +20,12 @@ def _load_assertions(assertions_path: str | None, plan_path: str | None) -> list
     if assertions_path:
         p = Path(assertions_path)
         if not p.exists():
-            raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Assertions file not found: {assertions_path}")
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"Assertions file not found: {assertions_path}",
+                retryable=False,
+                suggested_action="fix_input",
+            )
         try:
             data = json.loads(p.read_text(encoding="utf-8"))
             if isinstance(data, list):
@@ -33,7 +38,12 @@ def _load_assertions(assertions_path: str | None, plan_path: str | None) -> list
         # Try to load assertions from the plan's source manifest
         p = Path(plan_path)
         if not p.exists():
-            raise ConfpubError(ERR_IO_FILE_NOT_FOUND, f"Plan file not found: {plan_path}")
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"Plan file not found: {plan_path}",
+                retryable=False,
+                suggested_action="fix_input",
+            )
         plan_data = json.loads(p.read_text(encoding="utf-8"))
         # Plan doesn't contain assertions directly — return empty
         return []

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/tests/test_guide.py

@@ -6,7 +6,7 @@ from confpub.guide import build_guide
 class TestBuildGuide:
     def test_has_required_top_level_keys(self):
         guide = build_guide()
-        for key in ("schema_version", "commands", "error_codes", "auth", "concurrency"):
+        for key in ("schema_version", "commands", "error_codes", "auth", "concurrency", "lockfile"):
             assert key in guide, f"Missing top-level key: {key}"
 
     def test_all_commands_present(self):

{confpub_cli-0.5.0 → confpub_cli-0.6.0}/tests/test_puller.py

@@ -176,6 +176,7 @@ class TestRecursivePull:
                 page_id="1",
                 output_dir=str(tmp_path),
                 recursive=True,
+                generate_manifest=True,
             )
 
         assert result["summary"]["manifest_generated"] is True
@@ -265,7 +266,7 @@ class TestLayoutModes:
 
         assert result["layout"] == "nested"
         assert (tmp_path / "root" / "index.md").exists()
-        assert (tmp_path / "child" / "index.md").exists()
+        assert (tmp_path / "root" / "child" / "index.md").exists()
 
 
 # ---------------------------------------------------------------------------
@@ -405,6 +406,7 @@ class TestDataCenterCompat:
             result = pull_pages(
                 space="PROJ", title="Root",
                 output_dir=str(tmp_path), recursive=True,
+                generate_manifest=True,
             )
 
         assert result["summary"]["pages_pulled"] == 2

confpub_cli-0.5.0/FEEDBACK.md

@@ -1,226 +0,0 @@
-# confpub-cli v0.2.3 — Blind Test Feedback
-
-**Tester**: Claude Opus 4.6 (LLM agent)
-**Date**: 2026-03-01
-**Environment**: Windows 11, bash shell, `uvx confpub-cli`
-**Confluence**: Cloud instance (thomasklokrohde.atlassian.net)
-
----
-
-## Overall Impression
-
-confpub-cli is a remarkably well-designed agent-first CLI. As an LLM agent driving it
-zero-shot, I was productive within seconds. The `guide` command gave me everything I
-needed to understand the full command surface, error taxonomy, and concurrency rules.
-The consistent JSON envelope made it trivial to parse every response. This is one of
-the best-designed CLIs I've encountered for agent consumption.
-
-**Rating: 4/5** — Excellent foundation with a handful of rough edges to polish.
-
----
-
-## What Works Well
-
-### Structured JSON Envelope
-Every command returns the same `{ ok, command, target, result, warnings, errors, metrics }`
-shape. Parsing is zero-effort. The `request_id` and `metrics.duration_ms` fields are a
-nice touch for tracing and diagnostics.
-
-### `guide` Command
-Brilliant bootstrapping mechanism. One call gives an agent: every command with its flags,
-mutability annotations, error codes with exit codes and retry hints, auth precedence,
-and concurrency rules. The `--section` flag is useful for targeted queries. This alone
-puts confpub ahead of most CLI tools for agent integration.
-
-### Transactional Plan Workflow
-The plan → validate → apply → verify pipeline is well thought out:
-- `plan create` generates a readable artifact with clear operation types
-- `plan validate` checks for drift before apply
-- `plan apply` supports `--dry-run` for preview
-- The lockfile (`confpub.lock`) enables idempotent re-publishing
-
-I tested the full cycle and it worked flawlessly: manifest → plan → validate → dry-run → apply → verify.
-
-### Markdown Conversion
-Tested headings, bold/italic, inline code, fenced code blocks (with language), tables,
-admonitions (`[!NOTE]`, `[!WARNING]`, `[!TIP]`), strikethrough, and horizontal rules.
-All converted correctly to Confluence Storage Format. Particularly impressed that
-admonitions map to the proper Confluence Info/Warning/Tip macros.
-
-### Error Taxonomy
-Stable error codes (`ERR_*`) with structured details, exit codes, and `suggested_action`
-hints (`fix_input`, `retry`, `reauth`, `escalate`). An agent can branch on these without
-parsing human-readable messages. The `retryable` flag and `retry_after_ms` for I/O errors
-are agent-friendly.
-
-### Safety Design
-- Write commands are clearly annotated as `mutates: true` in the guide
-- `--dry-run` is available on both `page publish` and `plan apply`
-- `--cascade` is a separate opt-in for cascading deletes
-- `safety_flags` section in the guide calls out dangerous flags
-
-### Auth Resolution
-Clean precedence chain (flags → env vars → config file → keychain) with auto-detection
-of Cloud vs Server from the URL. `auth inspect` gives a quick status check.
-
----
-
-## Bugs Found
-
-### BUG-1: `--space` flag ignored during page update (Severity: High)
-
-When I published a page to space `SD`, then re-published with `--space NONEXIST`, the
-command succeeded (exit 0) and updated the existing page in the `SD` space. The `--space`
-flag was silently ignored on the update path.
-
-**Repro:**
-```bash
-confpub page publish test.md --space SD --parent "Software Development"
-# Creates page in SD, version 1
-
-confpub page publish test.md --space NONEXIST --parent "Software Development"
-# Expected: error (space not found or page not found in that space)
-# Actual: ok=true, updated page in SD to version 3
-```
-
-**Impact**: An agent could accidentally update a page in the wrong space without any
-warning. The title-based lookup appears to match globally (or against the lockfile)
-rather than scoping to the specified space.
-
-### BUG-2: Nonexistent page returns `ok: true` with `result: null` (Severity: Medium)
-
-```bash
-confpub page inspect --space SD --title "nonexistent-page"
-# Returns: ok=true, result=null, errors=[]
-```
-
-This should return `ok: false` with an appropriate error (e.g., a new `ERR_NOT_FOUND`
-code). An agent checking `ok` to determine success would incorrectly think the call
-succeeded. Currently the only way to detect "not found" is to check if `result` is null,
-which is an undocumented convention.
-
-A `"Can't find ... page"` message also leaks to stderr, suggesting the underlying library
-knows it's not found — the CLI just doesn't surface it as a structured error.
-
-### BUG-3: Missing required options return exit code 2, not JSON envelope (Severity: Medium)
-
-```bash
-confpub page list
-# Returns Typer's error format: "Missing option '--space'." with exit code 2
-```
-
-This breaks the documented invariant: "stdout is exclusively JSON — one object, no
-preamble, no epilogue." An agent expecting to always parse JSON on stdout will crash.
-Exit code 2 is also undocumented (the error code table only covers 0/10/20/40/50/90).
-
-**Suggestion**: Catch Typer's `MissingParameter` and convert it to an
-`ERR_VALIDATION_REQUIRED` envelope with exit code 10.
-
-### BUG-4: `--backup` flag produces no observable output (Severity: Low)
-
-```bash
-confpub page publish test.md --space SD --parent "Software Development" --backup
-```
-
-The command succeeded but the result JSON contains no mention of a backup being created —
-no backup file path, no `backup: true` field, nothing. Either the backup didn't happen,
-or it happened silently. An agent has no way to confirm.
-
-### BUG-5: Nonexistent parent accepted in dry-run (Severity: Low)
-
-```bash
-confpub page publish test.md --space SD --parent "Nonexistent Parent" --dry-run
-# Returns: ok=true, type=page.update
-```
-
-Dry-run should ideally validate that the parent page exists, or at least emit a warning.
-Currently it plans an update to a nonexistent parent, which would fail on real apply.
-
----
-
-## Improvement Suggestions
-
-### 1. Normalize attachment command output
-
-`attachment.list` and `attachment.upload` return raw Confluence API responses with
-internal fields (`_expandable`, ARIs, `base64EncodedAri`, full user profiles). Every
-other command returns a curated result. These should be normalized to the same level
-of curation.
-
-**Suggested `attachment.list` shape:**
-```json
-{
-  "attachments": [
-    {
-      "id": "att262400",
-      "title": "test-attachment.txt",
-      "media_type": "application/binary",
-      "file_size": 27,
-      "download_url": "/download/attachments/360459/test-attachment.txt?..."
-    }
-  ]
-}
-```
-
-### 2. Add `--format` flag or page count to `page.list`
-
-For spaces with many pages, `page.list` returns everything. Consider:
-- A `--limit` / `--offset` for pagination
-- A `--format compact` option (just titles + IDs)
-- Include total count in the result
-
-### 3. Suppress `"Can't find ... page"` stderr noise
-
-Multiple commands emit `"Can't find 'X' page on ..."` to stderr. This comes from the
-underlying `atlassian-python-api` library but leaks through even with `--quiet`. Since
-not finding a page is a normal flow (e.g., first publish), this shouldn't appear by
-default — maybe only with `--verbose`.
-
-### 4. Add stdin support
-
-`echo "# Hello" | confpub page publish - --space SD --parent "Docs" --title "Hello"`
-would be useful for piped workflows and agent-generated content. Currently `-` is treated
-as a literal filename.
-
-### 5. `plan verify` with no assertions is a no-op
-
-```bash
-confpub plan verify --plan confpub-plan.json
-# Returns: all_passed=true, results=[]
-```
-
-Without `--assertions`, this always passes vacuously. Consider:
-- Auto-generating basic assertions from the plan (pages exist, correct parent, version incremented)
-- Emitting a warning when no assertions are provided
-
-### 6. Consider `--json` flag for Typer-level errors
-
-As a bridge until BUG-3 is fully fixed, a `--json` flag could force JSON output even
-for framework-level errors (missing options, unknown commands).
-
-### 7. Lockfile includes pages from `page publish` and `plan apply`
-
-The lockfile accumulated entries from both `page publish` (single-file mode) and
-`plan apply`. This might be intentional for idempotency, but it could surprise users
-who expected the lockfile to only track manifest-managed pages. Consider documenting
-this behavior or separating the two.
-
----
-
-## Summary
-
-| Area | Score |
-|------|-------|
-| Agent discoverability (`guide`) | 5/5 |
-| JSON envelope consistency | 4/5 (BUG-3 breaks it for Typer errors) |
-| Error handling | 4/5 (BUG-2 masks not-found) |
-| Markdown conversion | 5/5 |
-| Plan workflow | 5/5 |
-| Write correctness | 3/5 (BUG-1 is a real data integrity risk) |
-| Output curation | 3/5 (attachments leak raw API) |
-| Documentation (README) | 5/5 |
-
-confpub is production-ready for the core read + plan + publish workflows. The main
-blocker is BUG-1 (space flag ignored on updates), which could cause silent cross-space
-writes. Fixing that plus normalizing the attachment output would bring this to a
-strong 5/5.