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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 0.6.0
+Version: 0.7.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.6.0 → confpub_cli-0.7.0}/confpub/__init__.py

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

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

@@ -222,22 +222,31 @@ def page_inspect(
 def page_publish(
     file: str = typer.Argument(..., help="Markdown file to publish"),
     space: str = typer.Option(..., "--space", help="Confluence space key"),
-    parent: str = typer.Option(..., "--parent", help="Parent page title"),
+    parent: Optional[str] = typer.Option(None, "--parent", help="Parent page title"),
     title: Optional[str] = typer.Option(None, "--title", help="Page title (defaults to filename stem, hyphen/underscore→spaces, title-cased)"),
+    page_id: Optional[str] = typer.Option(None, "--page-id", help="Confluence page ID (skip lookup, update directly)"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without writing"),
     backup: bool = typer.Option(False, "--backup", help="Backup existing page before overwriting"),
 ) -> None:
     """Publish a single Markdown file to Confluence."""
     from confpub.publish import derive_title
     resolved_title = derive_title(file, title)
+    if not page_id and not parent:
+        raise ConfpubError(
+            "ERR_VALIDATION_REQUIRED",
+            "Either --page-id or --parent is required",
+        )
     target = {"space": space, "title": resolved_title, "file": file}
+    if page_id:
+        target["page_id"] = page_id
     with command_context("page.publish", target=target) as ctx:
         from confpub.publish import publish_page
         result = publish_page(
             file=file,
             space=space,
-            parent=parent,
+            parent=parent or "",
             title=title,
+            page_id=page_id,
             dry_run=dry_run,
             backup=backup,
             progress_callback=ctx,
@@ -284,15 +293,26 @@ def page_pull(
 
 @page_app.command("delete")
 def page_delete(
-    space: str = typer.Option(..., "--space", help="Confluence space key"),
-    title: str = typer.Option(..., "--title", help="Page title"),
+    space: Optional[str] = typer.Option(None, "--space", help="Confluence space key"),
+    title: Optional[str] = typer.Option(None, "--title", help="Page title"),
+    page_id: Optional[str] = typer.Option(None, "--page-id", help="Confluence page ID"),
     cascade: bool = typer.Option(False, "--cascade", help="Also delete child pages"),
 ) -> None:
     """Delete a Confluence page."""
-    with command_context("page.delete", target={"space": space, "title": title}) as ctx:
+    with command_context("page.delete", target={"space": space, "title": title, "page_id": page_id}) as ctx:
+        if not page_id and not (space and title):
+            raise ConfpubError(
+                "ERR_VALIDATION_REQUIRED",
+                "Either --page-id or both --space and --title are required",
+            )
         from confpub.confluence import build_client
         client = build_client()
-        result = client.delete_page_by_title(space, title, cascade=cascade)
+        if page_id:
+            if cascade:
+                client._delete_descendants(page_id)
+            result = client.delete_page(page_id)
+        else:
+            result = client.delete_page_by_title(space, title, cascade=cascade)
         ctx.result = result
 
 
@@ -435,6 +455,7 @@ def config_inspect() -> None:
 def search(
     cql: Optional[str] = typer.Option(None, "--cql", help="Raw CQL query"),
     space: Optional[str] = typer.Option(None, "--space", help="Filter by space key"),
+    title: Optional[str] = typer.Option(None, "--title", help="Search by page title (fuzzy match)"),
     content_type: Optional[str] = typer.Option(None, "--type", help="Filter by content type (page, blogpost, etc.)"),
     limit: int = typer.Option(25, "--limit", help="Maximum results to return"),
     start: int = typer.Option(0, "--start", help="Starting offset for pagination"),
@@ -442,12 +463,14 @@ def search(
     excerpt_length: int = typer.Option(200, "--excerpt-length", help="Max excerpt chars (0 = unlimited)"),
 ) -> None:
     """Search Confluence content using CQL."""
-    target = {"cql": cql, "space": space, "type": content_type}
+    target = {"cql": cql, "space": space, "title": title, "type": content_type}
     with command_context("search", target=target) as ctx:
         # Build effective CQL from flags
         fragments: list[str] = []
         if space:
             fragments.append(f'space = "{space}"')
+        if title:
+            fragments.append(f'title ~ "{title}"')
         if content_type:
             fragments.append(f'type = "{content_type}"')
         if cql:
@@ -456,7 +479,7 @@ def search(
         if not fragments:
             raise ConfpubError(
                 "ERR_VALIDATION_REQUIRED",
-                "At least one of --cql, --space, or --type is required",
+                "At least one of --cql, --space, --title, or --type is required",
             )
 
         effective_cql = " AND ".join(fragments)

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

@@ -93,7 +93,7 @@ class ConfluenceClient:
         """Get a page by space key and title."""
         self._call_count += 1
         try:
-            result = self._api.get_page_by_title(space, title, expand="version,body.storage,space")
+            result = self._api.get_page_by_title(space, title, expand="version,body.storage,space,ancestors")
             return result if result else None
         except Exception as exc:
             self._handle_error(exc, "get_page")
@@ -103,7 +103,7 @@ class ConfluenceClient:
         """Get a page by its Confluence ID."""
         self._call_count += 1
         try:
-            return self._api.get_page_by_id(page_id, expand="version,body.storage,space")
+            return self._api.get_page_by_id(page_id, expand="version,body.storage,space,ancestors")
         except Exception as exc:
             self._handle_error(exc, "get_page_by_id")
             return {}
@@ -230,6 +230,16 @@ class ConfluenceClient:
             start += limit
         return all_children
 
+    def get_page_ancestors(self, page_id: str) -> list[dict[str, Any]]:
+        """Get the ancestor chain of a page (root first, immediate parent last)."""
+        self._call_count += 1
+        try:
+            page = self._api.get_page_by_id(page_id, expand="ancestors")
+            return page.get("ancestors", [])
+        except Exception as exc:
+            self._handle_error(exc, "get_page_ancestors")
+            return []
+
     # ------------------------------------------------------------------
     # Space operations
     # ------------------------------------------------------------------
@@ -419,9 +429,14 @@ def _slim_page(page: dict[str, Any], *, base_url: str = "") -> dict[str, Any]:
     body = page.get("body", {}).get("storage", {}).get("value")
     if body is not None:
         result["body_storage"] = body
+    ancestors = page.get("ancestors")
+    if isinstance(ancestors, list) and ancestors:
+        parent = ancestors[-1]
+        result["parent_id"] = parent.get("id")
+        result["parent_title"] = parent.get("title")
     links = page.get("_links", {})
     if "webui" in links:
-        base = links.get("base", "") or base_url
+        base = base_url or links.get("base", "")
         result["webui"] = base + links["webui"]
     return result
 

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

@@ -65,7 +65,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "read",
                 "mutates": False,
                 "description": "Search Confluence content using CQL",
-                "flags": ["--cql", "--space", "--type", "--limit", "--start", "--include-archived", "--excerpt-length"],
+                "flags": ["--cql", "--space", "--title", "--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",
@@ -79,6 +79,7 @@ def build_guide() -> dict[str, Any]:
                     'confpub search --cql \'label = "api-docs"\'',
                     "confpub search --space DEV --type page --limit 10",
                     'confpub search --space DEV --cql \'title ~ "deploy"\'',
+                    'confpub search --title "deploy guide" --space DEV',
                 ],
             },
             "page.list": {
@@ -97,7 +98,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "write",
                 "mutates": True,
                 "description": "Publish a single Markdown file to Confluence",
-                "flags": ["--space", "--parent", "--title", "--dry-run", "--backup"],
+                "flags": ["--space", "--parent", "--title", "--page-id", "--dry-run", "--backup"],
             },
             "page.pull": {
                 "group": "read",
@@ -116,7 +117,7 @@ def build_guide() -> dict[str, Any]:
                 "group": "write",
                 "mutates": True,
                 "description": "Delete a Confluence page",
-                "flags": ["--space", "--title", "--cascade"],
+                "flags": ["--space", "--title", "--page-id", "--cascade"],
                 "safety_flags": {
                     "--cascade": "Also deletes child pages",
                 },
@@ -248,6 +249,28 @@ def build_guide() -> dict[str, Any]:
                 "Does not prevent concurrent operations — purely local state tracking",
             ],
         },
+        "assertions": {
+            "description": "Post-condition assertions verified by plan.verify.",
+            "file_format": "JSON array of assertion objects, or embedded in confpub.yaml under the 'assertions' key.",
+            "auto_generation": "When --plan is passed without --assertions, plan.verify auto-generates page.exists assertions for every create/update page in the plan.",
+            "types": {
+                "page.exists": {
+                    "description": "Verify that a page exists in the given space.",
+                    "required_fields": ["type", "space", "title"],
+                    "example": {"type": "page.exists", "space": "DEV", "title": "My Page"},
+                },
+                "page.parent": {
+                    "description": "Verify that a page has the expected parent.",
+                    "required_fields": ["type", "space", "title", "expected_parent"],
+                    "example": {"type": "page.parent", "space": "DEV", "title": "My Page", "expected_parent": "Parent Page"},
+                },
+                "attachment.exists": {
+                    "description": "Verify that an attachment exists on a page.",
+                    "required_fields": ["type", "space", "page", "filename"],
+                    "example": {"type": "attachment.exists", "space": "DEV", "page": "My Page", "filename": "diagram.png"},
+                },
+            },
+        },
         "auth": {
             "precedence": [
                 "--token + --user",

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

@@ -35,6 +35,7 @@ def publish_page(
     space: str,
     parent: str,
     title: str | None = None,
+    page_id: str | None = None,
     dry_run: bool = False,
     backup: bool = False,
     progress_callback: Any = None,
@@ -73,7 +74,14 @@ def publish_page(
     existing_page_id = None
     current_version = None
 
-    if page_title in lockfile.pages:
+    if page_id:
+        # Direct page ID provided — skip lockfile/title lookup
+        existing_page_id = page_id
+        page_data = client.get_page_by_id(existing_page_id)
+        if page_data:
+            version = page_data.get("version", {})
+            current_version = version.get("number") if isinstance(version, dict) else version
+    elif page_title in lockfile.pages:
         existing_page_id = lockfile.pages[page_title].page_id
         page_data = client.get_page_by_id(existing_page_id)
         if page_data:
@@ -99,6 +107,12 @@ def publish_page(
     # Determine operation
     operation = "update" if existing_page_id else "create"
 
+    # Detect noop — skip update when content is unchanged
+    if operation == "update":
+        remote_fingerprint = client.fingerprint_page(existing_page_id)
+        if remote_fingerprint and remote_fingerprint == local_fingerprint:
+            operation = "noop"
+
     if dry_run:
         change: dict[str, Any] = {
             "type": f"page.{operation}",
@@ -124,6 +138,18 @@ def publish_page(
         return result_dict
 
     # Real publish
+    if operation == "noop":
+        return {
+            "dry_run": False,
+            "changes": [{
+                "type": "page.noop",
+                "title": page_title,
+                "confluence_page_id": existing_page_id,
+                "before": {"version": current_version} if current_version else None,
+            }],
+            "summary": {"noop": 1},
+        }
+
     backup_file_path: str | None = None
     if operation == "create":
         # Find parent page

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

@@ -312,8 +312,11 @@ def pull_pages(
     manifest_file: str | None = None
     if generate_manifest:
         root_title = root_page.get("title", "")
+        # Determine the actual parent of the root page
+        ancestors = client.get_page_ancestors(root_id)
+        manifest_parent = ancestors[-1].get("title", root_title) if ancestors else root_title
         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_yaml = generate_manifest_yaml(root_space, manifest_parent, page_tree)
         manifest_path = os.path.join(output_dir, "confpub.yaml")
         Path(manifest_path).write_text(manifest_yaml, encoding="utf-8")
         manifest_file = manifest_path

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

@@ -35,7 +35,6 @@ def _load_assertions(assertions_path: str | None, plan_path: str | None) -> list
             raise ConfpubError(ERR_VALIDATION_MANIFEST, f"Invalid assertions JSON: {exc}") from exc
 
     if plan_path:
-        # Try to load assertions from the plan's source manifest
         p = Path(plan_path)
         if not p.exists():
             raise ConfpubError(
@@ -44,9 +43,33 @@ def _load_assertions(assertions_path: str | None, plan_path: str | None) -> list
                 retryable=False,
                 suggested_action="fix_input",
             )
+
+        # Check for confpub.yaml alongside the plan file
+        manifest_path = p.parent / "confpub.yaml"
+        if manifest_path.exists():
+            try:
+                import yaml
+                manifest_data = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))
+                if isinstance(manifest_data, dict) and manifest_data.get("assertions"):
+                    raw = manifest_data["assertions"]
+                    if isinstance(raw, list):
+                        return raw
+            except Exception:
+                pass
+
+        # Auto-generate page.exists assertions from the plan
         plan_data = json.loads(p.read_text(encoding="utf-8"))
-        # Plan doesn't contain assertions directly — return empty
-        return []
+        auto: list[dict[str, Any]] = []
+        space = plan_data.get("space", "")
+        for page in plan_data.get("pages", []):
+            op = page.get("operation", "")
+            if op in ("create", "update"):
+                auto.append({
+                    "type": "page.exists",
+                    "space": space,
+                    "title": page.get("title", ""),
+                })
+        return auto
 
     return []
 
@@ -88,14 +111,22 @@ def verify_assertions(
                 all_passed = False
 
         elif a_type == "page.parent":
+            space = assertion.get("space", "")
             title = assertion.get("title", "")
             expected_parent = assertion.get("expected_parent", "")
             result["title"] = title
-            # Get page and check its parent
-            # This is a simplified check — in a full implementation
-            # we'd look up the page's ancestor chain
-            result["passed"] = True  # Simplified for now
             result["expected_parent"] = expected_parent
+            page = client.get_page(space, title) if space else None
+            if page:
+                ancestors = client.get_page_ancestors(str(page["id"]))
+                actual_parent = ancestors[-1].get("title", "") if ancestors else ""
+                result["actual_parent"] = actual_parent
+                result["passed"] = actual_parent == expected_parent
+            else:
+                result["passed"] = False
+                result["error"] = f"Page '{title}' not found"
+            if not result["passed"]:
+                all_passed = False
 
         elif a_type == "attachment.exists":
             page_title = assertion.get("page", "")

{confpub_cli-0.6.0 → confpub_cli-0.7.0}/tests/test_confluence.py

@@ -52,7 +52,7 @@ class TestGetPage:
         result = client.get_page("DEV", "Test")
         assert result["id"] == "123"
         client._mock_api.get_page_by_title.assert_called_once_with(
-            "DEV", "Test", expand="version,body.storage,space"
+            "DEV", "Test", expand="version,body.storage,space,ancestors"
         )
 
     def test_returns_none_when_not_found(self, client):

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

@@ -58,11 +58,15 @@ def _mock_client(pages: dict[str, dict], children: dict[str, list] | None = None
     def download_attachment(pid, filename, path):
         return False
 
+    def get_page_ancestors(pid):
+        return []
+
     client.get_page_by_id = get_page_by_id
     client.get_page = get_page
     client.get_page_children_deep = get_page_children_deep
     client.get_attachments = get_attachments
     client.download_attachment = download_attachment
+    client.get_page_ancestors = get_page_ancestors
     return client
 
 

{confpub_cli-0.6.0 → confpub_cli-0.7.0}/tests/test_verifier.py

@@ -12,7 +12,7 @@ from confpub.verifier import verify_assertions
 
 SAMPLE_ASSERTIONS = [
     {"type": "page.exists", "space": "DEV", "title": "Overview"},
-    {"type": "page.parent", "title": "Child", "expected_parent": "Overview"},
+    {"type": "page.parent", "space": "DEV", "title": "Child", "expected_parent": "Overview"},
     {"type": "attachment.exists", "space": "DEV", "page": "Overview", "filename": "arch.png"},
 ]
 
@@ -31,6 +31,7 @@ class TestVerifyAssertions:
         mock_client = MagicMock()
         mock_client.get_page.return_value = {"id": "123", "title": "Overview"}
         mock_client.get_attachments.return_value = [{"title": "arch.png"}]
+        mock_client.get_page_ancestors.return_value = [{"id": "100", "title": "Overview"}]
         MockClient.return_value = mock_client
         mock_config.return_value = MagicMock()
 

confpub_cli-0.6.0/FEEDBACK.md

@@ -1,197 +0,0 @@
-# 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.