confpub-cli 1.5.0__tar.gz → 1.7.0__tar.gz

{confpub_cli-1.5.0 → confpub_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 1.5.0
+Version: 1.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
@@ -118,7 +118,7 @@ confpub plan apply --plan confpub-plan.json --dry-run
 
 - **Structured JSON output** — every command returns the same envelope shape on stdout
 - **Transactional workflow** — plan → validate → apply → verify with fingerprint-based conflict detection
-- **Markdown → Confluence** — code blocks become code macros, `> [!NOTE]` becomes Info panels, tables stay tables, task lists, math, definition lists, footnotes, panels, expand/collapse, and page layouts
+- **Markdown → Confluence** — code blocks become code macros, `> [!NOTE]` becomes Info panels, tables stay tables, task lists, math, definition lists, footnotes, panels, expand/collapse, page layouts, and `{macro}` syntax for Status, TOC, Jira, Anchor, Children, and more
 - **Asset handling** — images are uploaded as attachments and URLs are rewritten automatically
 - **Idempotent** — a lockfile tracks page IDs so re-publishing updates in place
 - **Agent-ready** — `confpub guide` returns the full CLI schema; `LLM=true` suppresses interactive behavior
@@ -353,6 +353,15 @@ confpub converts Markdown to Confluence Storage Format (and back via `page pull`
 | `::: expand Title` | Confluence Expand macro |
 | `:::: layout two-equal` | Confluence page layout |
 | `---yaml---` front matter | Silently stripped |
+| `{status:Done\|colour=Green}` | Confluence Status lozenge |
+| `{toc}` | Table of Contents macro |
+| `{anchor:name}` | Anchor macro |
+| `{children}` | Children Display macro |
+| `{jira:PROJECT-123}` | Jira issue link/table |
+| `{recently-updated}` | Recently Updated macro |
+| `{excerpt-include:Page}` | Excerpt Include macro |
+| `{include:Page}` | Include Page macro |
+| `::: excerpt` | Excerpt macro (body) |
 
 ---
 

{confpub_cli-1.5.0 → confpub_cli-1.7.0}/README.md

@@ -77,7 +77,7 @@ confpub plan apply --plan confpub-plan.json --dry-run
 
 - **Structured JSON output** — every command returns the same envelope shape on stdout
 - **Transactional workflow** — plan → validate → apply → verify with fingerprint-based conflict detection
-- **Markdown → Confluence** — code blocks become code macros, `> [!NOTE]` becomes Info panels, tables stay tables, task lists, math, definition lists, footnotes, panels, expand/collapse, and page layouts
+- **Markdown → Confluence** — code blocks become code macros, `> [!NOTE]` becomes Info panels, tables stay tables, task lists, math, definition lists, footnotes, panels, expand/collapse, page layouts, and `{macro}` syntax for Status, TOC, Jira, Anchor, Children, and more
 - **Asset handling** — images are uploaded as attachments and URLs are rewritten automatically
 - **Idempotent** — a lockfile tracks page IDs so re-publishing updates in place
 - **Agent-ready** — `confpub guide` returns the full CLI schema; `LLM=true` suppresses interactive behavior
@@ -312,6 +312,15 @@ confpub converts Markdown to Confluence Storage Format (and back via `page pull`
 | `::: expand Title` | Confluence Expand macro |
 | `:::: layout two-equal` | Confluence page layout |
 | `---yaml---` front matter | Silently stripped |
+| `{status:Done\|colour=Green}` | Confluence Status lozenge |
+| `{toc}` | Table of Contents macro |
+| `{anchor:name}` | Anchor macro |
+| `{children}` | Children Display macro |
+| `{jira:PROJECT-123}` | Jira issue link/table |
+| `{recently-updated}` | Recently Updated macro |
+| `{excerpt-include:Page}` | Excerpt Include macro |
+| `{include:Page}` | Include Page macro |
+| `::: excerpt` | Excerpt macro (body) |
 
 ---
 

{confpub_cli-1.5.0 → confpub_cli-1.7.0}/confpub/__init__.py

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

{confpub_cli-1.5.0 → confpub_cli-1.7.0}/confpub/cli.py

@@ -21,19 +21,19 @@ from confpub.errors import ConfpubError, exit_code_for, ERR_INTERNAL_SDK
 from confpub.output import emit_stderr, emit_stdout, is_compact, is_verbose, set_compact, set_quiet, set_verbose
 
 
-def _resolve_space(cli_space: str | None, required: bool = False) -> str | None:
-    """Resolve space from CLI flag or CONFPUB_SPACE env var, with validation."""
+def _resolve_space(cli_space: str | None, required: bool = False, fm_space: str | None = None) -> str | None:
+    """Resolve space from CLI flag, front-matter, or CONFPUB_SPACE env var, with validation."""
     from confpub.config import ENV_SPACE
     from confpub.errors import validate_space_key
 
-    space = cli_space or os.environ.get(ENV_SPACE)
+    space = cli_space or fm_space or os.environ.get(ENV_SPACE)
     if space is not None:
         validate_space_key(space)
         return space
     if required:
         raise ConfpubError(
             "ERR_VALIDATION_REQUIRED",
-            "Space key is required. Use --space or set CONFPUB_SPACE.",
+            "Space key is required. Use --space, front-matter, or set CONFPUB_SPACE.",
         )
     return None
 
@@ -290,30 +290,59 @@ def page_publish(
     label: Optional[list[str]] = typer.Option(None, "--label", help="Label to apply (repeatable)"),
 ) -> None:
     """Publish a single Markdown file to Confluence."""
+    from pathlib import Path as _Path
+    from confpub.front_matter import parse_front_matter
     from confpub.publish import derive_title
-    resolved_title = derive_title(file, title, title_from_h1=title_from_h1)
+
+    # Parse front-matter from the file (before command_context so title is resolved for target)
+    fm = None
+    source = _Path(file)
+    if source.exists():
+        md_text = source.read_text(encoding="utf-8")
+        fm = parse_front_matter(md_text)
+
+    fm_title = fm.title if fm else None
+    fm_space = fm.space if fm else None
+    fm_parent = fm.parent if fm else None
+    fm_page_id = fm.page_id if fm else None
+    fm_labels = fm.labels if fm else []
+
+    resolved_title = derive_title(file, title, title_from_h1=title_from_h1, front_matter_title=fm_title)
+
+    # Resolve page_id: CLI flag > front-matter
+    effective_page_id = page_id or fm_page_id
+
     target = {"space": space, "title": resolved_title, "file": file}
-    if page_id:
-        target["page_id"] = page_id
+    if effective_page_id:
+        target["page_id"] = effective_page_id
     with command_context("page.publish", target=target) as ctx:
-        space = _resolve_space(space, required=True)
+        space = _resolve_space(space, required=True, fm_space=fm_space)
         ctx.target["space"] = space
-        if not page_id and not parent:
+
+        # Resolve parent: CLI flag > front-matter
+        effective_parent = parent or fm_parent
+
+        if not effective_page_id and not effective_parent:
             raise ConfpubError(
                 "ERR_VALIDATION_REQUIRED",
-                "Either --page-id or --parent is required",
+                "Either --page-id or --parent is required (via flag or front-matter)",
             )
+
+        # Merge labels: CLI + front-matter (deduplicated, order-preserving)
+        cli_labels = label or []
+        merged_labels = list(dict.fromkeys(cli_labels + fm_labels))
+
         from confpub.publish import publish_page
         result = publish_page(
             file=file,
             space=space,
-            parent=parent or "",
-            title=title,
-            page_id=page_id,
+            parent=effective_parent or "",
+            title=resolved_title,
+            page_id=effective_page_id,
             dry_run=dry_run,
             backup=backup,
             progress_callback=ctx,
-            labels=label or [],
+            labels=merged_labels,
         )
         ctx.result = result
 

{confpub_cli-1.5.0 → confpub_cli-1.7.0}/confpub/converter.py

@@ -13,6 +13,8 @@ import re
 from html import escape
 from typing import Any
 
+import yaml
+
 from markdown_it import MarkdownIt
 from markdown_it.token import Token
 from mdit_py_plugins.tasklists import tasklists_plugin
@@ -22,6 +24,8 @@ from mdit_py_plugins.footnote import footnote_plugin
 from mdit_py_plugins.front_matter import front_matter_plugin
 from mdit_py_plugins.container import container_plugin
 
+from confpub.macro_plugin import confluence_macro_plugin
+
 # Admonition types mapping: GitHub [!TYPE] → Confluence macro name
 ADMONITION_MAP: dict[str, str] = {
     "NOTE": "info",
@@ -558,6 +562,136 @@ class ConfluenceRenderer:
         self._output.append("</ac:layout-cell>")
         return idx + 1
 
+    # ------------------------------------------------------------------
+    # Container: excerpt
+    # ------------------------------------------------------------------
+
+    def _render_container_excerpt_open(self, tokens: list[Token], idx: int, _o: Any, _e: Any) -> int:
+        info = tokens[idx].info.strip() if tokens[idx].info else ""
+        # info is e.g. "excerpt hidden" — strip the container name prefix
+        rest = info[len("excerpt"):].strip() if info.startswith("excerpt") else info
+        self._output.append('<ac:structured-macro ac:name="excerpt">')
+        if "hidden" in rest.lower():
+            self._output.append('<ac:parameter ac:name="hidden">true</ac:parameter>')
+        self._output.append("<ac:rich-text-body>")
+        return idx + 1
+
+    def _render_container_excerpt_close(self, tokens: list[Token], idx: int, _o: Any, _e: Any) -> int:
+        self._output.append("</ac:rich-text-body></ac:structured-macro>")
+        return idx + 1
+
+    # ------------------------------------------------------------------
+    # Confluence macros (body-less, from macro_plugin.py)
+    # ------------------------------------------------------------------
+
+    def _render_confluence_macro(self, tokens: list[Token], idx: int, _o: Any, _e: Any) -> int:
+        """Block-level macro token."""
+        token = tokens[idx]
+        name = token.info
+        meta = token.meta or {}
+        self._output.append(self._emit_macro(name, meta.get("positional", ""), meta.get("params", {})))
+        return idx + 1
+
+    def _inline_confluence_macro(self, token: Token) -> None:
+        """Inline macro token."""
+        name = token.info
+        meta = token.meta or {}
+        self._output.append(self._emit_macro(name, meta.get("positional", ""), meta.get("params", {})))
+
+    def _emit_macro(self, name: str, positional: str, params: dict[str, str]) -> str:
+        """Dispatch to per-macro handler or fall back to generic."""
+        method_name = f"_macro_{name.replace('-', '_')}"
+        handler = getattr(self, method_name, None)
+        if handler:
+            return handler(positional, params)
+        return self._emit_generic_macro(name, positional, params)
+
+    def _emit_generic_macro(self, name: str, positional: str, params: dict[str, str]) -> str:
+        parts = [f'<ac:structured-macro ac:name="{escape(name)}">']
+        if positional:
+            parts.append(f'<ac:parameter ac:name="">{escape(positional)}</ac:parameter>')
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_status(self, positional: str, params: dict[str, str]) -> str:
+        parts = ['<ac:structured-macro ac:name="status">']
+        if positional:
+            parts.append(f'<ac:parameter ac:name="title">{escape(positional)}</ac:parameter>')
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_toc(self, positional: str, params: dict[str, str]) -> str:
+        parts = ['<ac:structured-macro ac:name="toc">']
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_anchor(self, positional: str, params: dict[str, str]) -> str:
+        parts = ['<ac:structured-macro ac:name="anchor">']
+        if positional:
+            parts.append(f'<ac:parameter ac:name="">{escape(positional)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_children(self, positional: str, params: dict[str, str]) -> str:
+        parts = ['<ac:structured-macro ac:name="children">']
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_jira(self, positional: str, params: dict[str, str]) -> str:
+        parts = ['<ac:structured-macro ac:name="jira">']
+        if "jql" in params or "jqlQuery" in params:
+            jql_value = params.pop("jql", "") or params.pop("jqlQuery", "")
+            parts.append(f'<ac:parameter ac:name="jqlQuery">{escape(jql_value)}</ac:parameter>')
+        elif positional:
+            parts.append(f'<ac:parameter ac:name="key">{escape(positional)}</ac:parameter>')
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_recently_updated(self, positional: str, params: dict[str, str]) -> str:
+        parts = ['<ac:structured-macro ac:name="recently-updated">']
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_excerpt_include(self, positional: str, params: dict[str, str]) -> str:
+        space = params.pop("space", "")
+        parts = ['<ac:structured-macro ac:name="excerpt-include">']
+        parts.append('<ac:parameter ac:name="">')
+        ri_attrs = f'ri:content-title="{escape(positional)}"'
+        if space:
+            ri_attrs += f' ri:space-key="{escape(space)}"'
+        parts.append(f"<ac:link><ri:page {ri_attrs} /></ac:link>")
+        parts.append("</ac:parameter>")
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
+    def _macro_include(self, positional: str, params: dict[str, str]) -> str:
+        space = params.pop("space", "")
+        parts = ['<ac:structured-macro ac:name="include">']
+        parts.append('<ac:parameter ac:name="">')
+        ri_attrs = f'ri:content-title="{escape(positional)}"'
+        if space:
+            ri_attrs += f' ri:space-key="{escape(space)}"'
+        parts.append(f"<ac:link><ri:page {ri_attrs} /></ac:link>")
+        parts.append("</ac:parameter>")
+        for k, v in params.items():
+            parts.append(f'<ac:parameter ac:name="{escape(k)}">{escape(v)}</ac:parameter>')
+        parts.append("</ac:structured-macro>")
+        return "".join(parts)
+
 
 def _create_parser() -> MarkdownIt:
     """Create a configured markdown-it-py parser."""
@@ -574,6 +708,8 @@ def _create_parser() -> MarkdownIt:
     container_plugin(md, name="expand")
     container_plugin(md, name="layout")
     container_plugin(md, name="cell")
+    container_plugin(md, name="excerpt")
+    confluence_macro_plugin(md)
     return md
 
 
@@ -613,6 +749,27 @@ def extract_h1_title(md_text: str) -> str | None:
     return None
 
 
+def extract_front_matter(md_text: str) -> dict[str, Any] | None:
+    """Extract YAML front-matter as a raw dict, or None.
+
+    Uses the markdown-it-py front_matter plugin to locate the block,
+    then parses with yaml.safe_load.  Returns None if no front-matter
+    is present, if the YAML is invalid, or if the result is not a mapping.
+    """
+    parser = _create_parser()
+    tokens = parser.parse(md_text)
+    for token in tokens:
+        if token.type == "front_matter":
+            try:
+                data = yaml.safe_load(token.content)
+            except yaml.YAMLError:
+                return None
+            if isinstance(data, dict):
+                return data
+            return None
+    return None
+
+
 def fingerprint_content(content: str) -> str:
     """Return SHA-256 hex digest of content."""
     return hashlib.sha256(content.encode("utf-8")).hexdigest()

confpub_cli-1.7.0/confpub/front_matter.py

@@ -0,0 +1,99 @@
+"""Front-matter extraction and validation for single-file publish.
+
+Parses YAML front-matter from Markdown files into a typed dataclass.
+Used only by `page publish`; manifest flows ignore front-matter entirely.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any
+
+from confpub.converter import extract_front_matter
+from confpub.errors import ERR_VALIDATION_MARKDOWN, ConfpubError
+
+
+@dataclass
+class FrontMatterData:
+    """Validated front-matter fields."""
+
+    title: str | None = None
+    space: str | None = None
+    parent: str | None = None
+    labels: list[str] = field(default_factory=list)
+    page_id: str | None = None
+
+
+def _validate_string(raw: dict[str, Any], key: str) -> str | None:
+    """Extract and validate a string field, or None if absent."""
+    val = raw.get(key)
+    if val is None:
+        return None
+    if not isinstance(val, str):
+        raise ConfpubError(
+            ERR_VALIDATION_MARKDOWN,
+            f"Front-matter field '{key}' must be a string, got {type(val).__name__}",
+            details={"field": key, "value_type": type(val).__name__},
+        )
+    return val
+
+
+def parse_front_matter(md_text: str) -> FrontMatterData | None:
+    """Extract and validate front-matter from Markdown text.
+
+    Returns a FrontMatterData with validated fields, or None if no
+    front-matter is present.  Unknown keys are silently ignored.
+
+    Raises ConfpubError (ERR_VALIDATION_MARKDOWN) on type errors.
+    """
+    raw = extract_front_matter(md_text)
+    if raw is None:
+        return None
+
+    title = _validate_string(raw, "title")
+    space = _validate_string(raw, "space")
+    parent = _validate_string(raw, "parent")
+
+    # labels: list[str] or single string → list[str]
+    labels_raw = raw.get("labels")
+    labels: list[str] = []
+    if labels_raw is not None:
+        if isinstance(labels_raw, str):
+            labels = [labels_raw]
+        elif isinstance(labels_raw, list):
+            for item in labels_raw:
+                if not isinstance(item, str):
+                    raise ConfpubError(
+                        ERR_VALIDATION_MARKDOWN,
+                        f"Front-matter 'labels' items must be strings, got {type(item).__name__}",
+                        details={"field": "labels", "value_type": type(item).__name__},
+                    )
+            labels = labels_raw
+        else:
+            raise ConfpubError(
+                ERR_VALIDATION_MARKDOWN,
+                f"Front-matter 'labels' must be a list or string, got {type(labels_raw).__name__}",
+                details={"field": "labels", "value_type": type(labels_raw).__name__},
+            )
+
+    # page_id: string or int → string
+    page_id_raw = raw.get("page_id")
+    page_id: str | None = None
+    if page_id_raw is not None:
+        if isinstance(page_id_raw, (str, int)):
+            page_id = str(page_id_raw)
+        else:
+            raise ConfpubError(
+                ERR_VALIDATION_MARKDOWN,
+                f"Front-matter 'page_id' must be a string or integer, got {type(page_id_raw).__name__}",
+                details={"field": "page_id", "value_type": type(page_id_raw).__name__},
+            )
+
+    return FrontMatterData(
+        title=title,
+        space=space,
+        parent=parent,
+        labels=labels,
+        page_id=page_id,
+    )

{confpub_cli-1.5.0 → confpub_cli-1.7.0}/confpub/guide.py

@@ -138,12 +138,12 @@ def build_guide() -> dict[str, Any]:
                 "description": "Publish a single Markdown file to Confluence",
                 "flags": ["--space", "--parent", "--title", "--title-from-h1", "--page-id", "--dry-run", "--backup", "--label"],
                 "agent_hint": (
-                    "Title precedence: explicit --title > --title-from-h1 (first H1 heading) > filename inference. "
-                    "When --title is omitted, the title is inferred from the filename: "
-                    "the stem is extracted, hyphens and underscores are replaced with spaces, "
-                    "and the result is title-cased. E.g. 'my-cool-page.md' → 'My Cool Page'. "
-                    "Use --title-from-h1 to extract the title from the first # heading in the file. "
-                    "Use --label to apply labels (repeatable): --label api --label docs. "
+                    "Title precedence: explicit --title > --title-from-h1 > front-matter title > filename inference. "
+                    "Space precedence: --space > front-matter space > CONFPUB_SPACE env var. "
+                    "Parent precedence: --parent > front-matter parent. "
+                    "Labels: CLI --label merged with front-matter labels (union, deduplicated). "
+                    "When writing Markdown files for publication, include YAML front-matter to embed metadata: "
+                    "---\\ntitle: Page Title\\nspace: SPACEKEY\\nparent: Parent Title\\nlabels:\\n  - tag1\\n---\\n "
                     "For personal spaces, quote the tilde: --space '~username' "
                     "(PowerShell expands unquoted ~). Or set CONFPUB_SPACE env var."
                 ),
@@ -402,16 +402,72 @@ def build_guide() -> dict[str, Any]:
                 "math_block":     "$$...$$ → ac:structured-macro mathblock",
                 "definition_lists": "Term\\n: Definition → <dl><dt><dd>",
                 "footnotes":      "[^1] + [^1]: text → superscript links with numbered list",
-                "front_matter":   "---\\nyaml\\n--- → silently stripped",
+                "front_matter": (
+                    "---\\nyaml\\n--- → extracted for page metadata "
+                    "(title, space, parent, labels, page_id); "
+                    "used by page.publish; ignored when a manifest is used"
+                ),
                 "panels":         "::: panel Title\\ncontent\\n::: → ac:structured-macro panel",
                 "expand":         "::: expand Title\\ncontent\\n::: → ac:structured-macro expand",
                 "layouts":        ":::: layout two-equal\\n::: cell\\n...\\n::::\\n → ac:layout with ac:layout-section",
+                "status":           "{status:Title|colour=Color} → ac:structured-macro status",
+                "toc":              "{toc} / {toc:maxLevel=N} → ac:structured-macro toc",
+                "anchor":           "{anchor:name} → ac:structured-macro anchor",
+                "children":         "{children} / {children:depth=N} → ac:structured-macro children",
+                "jira":             "{jira:KEY-123} / {jira:jql=...} → ac:structured-macro jira",
+                "recently_updated": "{recently-updated} → ac:structured-macro recently-updated",
+                "excerpt_include":  "{excerpt-include:Page Title} → ac:structured-macro excerpt-include",
+                "include_page":     "{include:Page Title} → ac:structured-macro include",
+                "excerpt":          "::: excerpt hidden\\ncontent\\n::: → ac:structured-macro excerpt",
             },
             "layout_types": ["single", "two-equal", "two-left-sidebar", "two-right-sidebar", "three-equal", "three-with-sidebars"],
             "agent_hint": (
                 "All features are always-on — the parser simply ignores syntax that isn't used. "
                 "Math macros require the Confluence LaTeX Math plugin to be installed on the server. "
-                "Layouts use :::: (4 colons) for the outer layout block and ::: (3 colons) for inner cells."
+                "Layouts use :::: (4 colons) for the outer layout block and ::: (3 colons) for inner cells. "
+                "Use {macro-name:params} for body-less Confluence macros. "
+                "Macros on their own line become block-level (no <p> wrapping)."
+            ),
+        },
+        "front_matter": {
+            "description": (
+                "YAML front-matter in Markdown files provides default page metadata for page.publish. "
+                "When a manifest (confpub.yaml) is used, front-matter is ignored entirely."
+            ),
+            "fields": {
+                "title": "Page title (string)",
+                "space": "Confluence space key (string)",
+                "parent": "Parent page title (string)",
+                "labels": "Labels to apply (list of strings, or single string)",
+                "page_id": "Confluence page ID for direct update (string or integer)",
+            },
+            "precedence": {
+                "title": "--title > --title-from-h1 > front-matter > filename",
+                "space": "--space > front-matter > CONFPUB_SPACE",
+                "parent": "--parent > front-matter",
+                "page_id": "--page-id > front-matter",
+                "labels": "CLI --label + front-matter labels merged (deduplicated)",
+            },
+            "example": (
+                "---\n"
+                "title: API Reference\n"
+                "space: DEV\n"
+                "parent: Documentation\n"
+                "labels:\n"
+                "  - api\n"
+                "  - public\n"
+                "---\n"
+                "\n"
+                "# API Reference\n"
+                "\n"
+                "Content here..."
+            ),
+            "agent_hint": (
+                "When creating Markdown files for Confluence publication, always include "
+                "front-matter with at least title, space, and parent so the file can be "
+                "published with just `confpub page publish <file>` — no extra flags needed. "
+                "Unknown front-matter keys (e.g. draft, author) are silently ignored, "
+                "so front-matter is compatible with other tools like Jekyll or Hugo."
             ),
         },
         "assertions": {