conjira-cli 0.2.2__tar.gz → 0.2.3__tar.gz

{conjira_cli-0.2.2/src/conjira_cli.egg-info → conjira_cli-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conjira-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Unofficial agent-friendly CLI for self-hosted Confluence and Jira
 Author: quanttraderkim
 License-Expression: MIT
@@ -140,6 +140,50 @@ conjira export-page-md --page-id 123456 --output-dir "/path/to/notes"
 
 If you run the CLI from a different folder, pass the config file explicitly with `--env-file /path/to/local/agent.env`.
 
+## Prompt templates by document type
+
+When you ask an agent to upload or update a document, results are better if you tell it what kind of document it is, whether Markdown should remain the source of truth, and whether the Confluence page should stay plain or become more presentation-friendly.
+
+For skill specs or evaluation docs, a good request is:
+
+```text
+Use conjira to upload this Markdown file as a Confluence page. Treat it as a skill spec, keep the Markdown structure as the source of truth, preserve headings and tables, and only use Confluence-native rendering where it helps readability without changing the document's meaning.
+```
+
+For service planning docs or PRDs, a good request is:
+
+```text
+Use conjira to turn this Markdown file into a Confluence PRD. Keep the content faithful to the source, but make it easier to read in Confluence. Add status, callouts, and expand blocks where they improve readability, and organize the page around summary, background, problem, scope, flow, risks, and open questions.
+```
+
+For strategy reports or review decks, a good request is:
+
+```text
+Use conjira to publish this Markdown file as a report-style Confluence page. Keep the source content intact, but optimize the page for presentation. Put the executive summary first, surface key decisions and risks early, and use status, info blocks, expand sections, and Mermaid where appropriate.
+```
+
+If you want to stay closer to raw Markdown, say `keep this Markdown-first and avoid extra presentation macros`. If you want a more polished Confluence page, say `optimize this for Confluence readability while keeping the source content intact`.
+
+## Document writing style guide
+
+For Confluence uploads, structure matters as much as accuracy. Strategy memos, PRDs, planning docs, and report-style pages read much better when the writer uses a compact working-document style instead of long essay-like prose.
+
+Prefer report-style memo wording over verbose formal phrasing. In Korean this usually means reducing repetitive `~입니다` and `~합니다`, and favoring shorter noun-phrase or judgment-oriented endings such as `~필요`, `~전제`, `~검토`, `~제안`, or `~우선`. Do not force every sentence into rigid `~함` wording; the target is a concise internal memo tone, not mechanical shorthand. Keep paragraphs short, lead with the conclusion, and make `###` headings carry the message or judgment instead of acting as generic labels.
+
+Use bullet points only for true parallel items. Do not split a single thought into fake bullets just to reduce line length. Use tables for comparisons, summaries, options, risks, target groups, ownership, or decision support. Do not force short explanatory text into a table when a compact paragraph is clearer.
+
+A good default order is `purpose -> summary -> key judgments / evidence -> risks / assumptions -> implications / next actions`. Strategy memos usually need `why this matters`, `key judgment`, `evidence`, and `implications`. PRDs usually need `problem`, `goal`, `scope`, `flow`, `policy`, and `open issues`. Skill specs are better when they stay literal and dry, with sections like `one-line definition`, `when to use`, `inputs`, `outputs`, `exceptions`, and `evaluation criteria`.
+
+For longer strategy or report documents, explicit numbering helps. Top-level sections such as `A.`, `B.`, `C.` and second-level sections such as `A-1.`, `A-2.` usually make the table of contents and the body much easier to scan. As a default, stay within two levels unless the user explicitly wants a deeper document tree.
+
+Cut abstract filler. Avoid phrases like “strategically meaningful”, “fundamentally important value”, or “meaningful impact across multiple dimensions” unless they add something precise. Prefer concrete statements such as “follow-up gaps turn into revenue loss”, “A is the right first rollout option”, or “free-user monetization is necessary but total revenue impact is limited”.
+
+If you want an agent to follow this style explicitly, a good request is:
+
+```text
+Use conjira to publish this document to Confluence. Keep the source content intact, but rewrite it in a concise internal memo style. Reduce formal `~입니다/~합니다` phrasing, prefer short noun-phrase or judgment-oriented wording, put the key summary first, use stronger h3/h4 headings and tables where they help scanability, add `A.` / `A-1.` numbering when the document is long enough to benefit from it, keep bullets for true parallel items only, and remove abstract filler.
+```
+
 Short sample output blocks, using synthetic values:
 
 ```json
@@ -315,6 +359,14 @@ conjira --env-file ./local/agent.env jira-search --jql 'project = DEMO ORDER BY
 conjira --env-file ./local/agent.env jira-get-issue --issue-key DEMO-123
 ```
 
+Inspect updated timestamps or recent comments when needed:
+
+```bash
+conjira jira-get-issue --issue-key DEMO-123 --include-comments --comments-limit 2
+conjira jira-get-issue --issue-key DEMO-123 --raw --fields summary,updated,comment
+conjira jira-search --jql 'project = DEMO ORDER BY updated DESC' --raw --fields summary,updated
+```
+
 Create a Jira issue or add a comment:
 
 ```bash

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/README.md

@@ -111,6 +111,50 @@ conjira export-page-md --page-id 123456 --output-dir "/path/to/notes"
 
 If you run the CLI from a different folder, pass the config file explicitly with `--env-file /path/to/local/agent.env`.
 
+## Prompt templates by document type
+
+When you ask an agent to upload or update a document, results are better if you tell it what kind of document it is, whether Markdown should remain the source of truth, and whether the Confluence page should stay plain or become more presentation-friendly.
+
+For skill specs or evaluation docs, a good request is:
+
+```text
+Use conjira to upload this Markdown file as a Confluence page. Treat it as a skill spec, keep the Markdown structure as the source of truth, preserve headings and tables, and only use Confluence-native rendering where it helps readability without changing the document's meaning.
+```
+
+For service planning docs or PRDs, a good request is:
+
+```text
+Use conjira to turn this Markdown file into a Confluence PRD. Keep the content faithful to the source, but make it easier to read in Confluence. Add status, callouts, and expand blocks where they improve readability, and organize the page around summary, background, problem, scope, flow, risks, and open questions.
+```
+
+For strategy reports or review decks, a good request is:
+
+```text
+Use conjira to publish this Markdown file as a report-style Confluence page. Keep the source content intact, but optimize the page for presentation. Put the executive summary first, surface key decisions and risks early, and use status, info blocks, expand sections, and Mermaid where appropriate.
+```
+
+If you want to stay closer to raw Markdown, say `keep this Markdown-first and avoid extra presentation macros`. If you want a more polished Confluence page, say `optimize this for Confluence readability while keeping the source content intact`.
+
+## Document writing style guide
+
+For Confluence uploads, structure matters as much as accuracy. Strategy memos, PRDs, planning docs, and report-style pages read much better when the writer uses a compact working-document style instead of long essay-like prose.
+
+Prefer report-style memo wording over verbose formal phrasing. In Korean this usually means reducing repetitive `~입니다` and `~합니다`, and favoring shorter noun-phrase or judgment-oriented endings such as `~필요`, `~전제`, `~검토`, `~제안`, or `~우선`. Do not force every sentence into rigid `~함` wording; the target is a concise internal memo tone, not mechanical shorthand. Keep paragraphs short, lead with the conclusion, and make `###` headings carry the message or judgment instead of acting as generic labels.
+
+Use bullet points only for true parallel items. Do not split a single thought into fake bullets just to reduce line length. Use tables for comparisons, summaries, options, risks, target groups, ownership, or decision support. Do not force short explanatory text into a table when a compact paragraph is clearer.
+
+A good default order is `purpose -> summary -> key judgments / evidence -> risks / assumptions -> implications / next actions`. Strategy memos usually need `why this matters`, `key judgment`, `evidence`, and `implications`. PRDs usually need `problem`, `goal`, `scope`, `flow`, `policy`, and `open issues`. Skill specs are better when they stay literal and dry, with sections like `one-line definition`, `when to use`, `inputs`, `outputs`, `exceptions`, and `evaluation criteria`.
+
+For longer strategy or report documents, explicit numbering helps. Top-level sections such as `A.`, `B.`, `C.` and second-level sections such as `A-1.`, `A-2.` usually make the table of contents and the body much easier to scan. As a default, stay within two levels unless the user explicitly wants a deeper document tree.
+
+Cut abstract filler. Avoid phrases like “strategically meaningful”, “fundamentally important value”, or “meaningful impact across multiple dimensions” unless they add something precise. Prefer concrete statements such as “follow-up gaps turn into revenue loss”, “A is the right first rollout option”, or “free-user monetization is necessary but total revenue impact is limited”.
+
+If you want an agent to follow this style explicitly, a good request is:
+
+```text
+Use conjira to publish this document to Confluence. Keep the source content intact, but rewrite it in a concise internal memo style. Reduce formal `~입니다/~합니다` phrasing, prefer short noun-phrase or judgment-oriented wording, put the key summary first, use stronger h3/h4 headings and tables where they help scanability, add `A.` / `A-1.` numbering when the document is long enough to benefit from it, keep bullets for true parallel items only, and remove abstract filler.
+```
+
 Short sample output blocks, using synthetic values:
 
 ```json
@@ -286,6 +330,14 @@ conjira --env-file ./local/agent.env jira-search --jql 'project = DEMO ORDER BY
 conjira --env-file ./local/agent.env jira-get-issue --issue-key DEMO-123
 ```
 
+Inspect updated timestamps or recent comments when needed:
+
+```bash
+conjira jira-get-issue --issue-key DEMO-123 --include-comments --comments-limit 2
+conjira jira-get-issue --issue-key DEMO-123 --raw --fields summary,updated,comment
+conjira jira-search --jql 'project = DEMO ORDER BY updated DESC' --raw --fields summary,updated
+```
+
 Create a Jira issue or add a comment:
 
 ```bash

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "conjira-cli"
-version = "0.2.2"
+version = "0.2.3"
 description = "Unofficial agent-friendly CLI for self-hosted Confluence and Jira"
 readme = "README.md"
 requires-python = ">=3.9"

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/src/conjira_cli/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/src/conjira_cli/cli.py

@@ -26,6 +26,16 @@ from conjira_cli.markdown_import import markdown_to_storage_html
 from conjira_cli.section_edit import SectionEditError, replace_section_html
 from conjira_cli.tree_export import export_page_tree, sanitize_path_component
 
+_JIRA_SUMMARY_FIELDS = [
+    "summary",
+    "status",
+    "issuetype",
+    "project",
+    "assignee",
+    "reporter",
+    "updated",
+]
+
 
 def _read_text_arg(raw_text: Optional[str], file_path: Optional[str]) -> str:
     if raw_text is not None:
@@ -43,6 +53,21 @@ def _read_json_arg(raw_json: Optional[str], file_path: Optional[str]) -> Dict[st
     return {}
 
 
+def _merge_csv_fields(raw_fields: Optional[str], required_fields: list[str]) -> Optional[str]:
+    tokens: list[str] = []
+    seen: set[str] = set()
+    for value in [raw_fields, ",".join(required_fields)]:
+        if not value:
+            continue
+        for token in value.split(","):
+            item = token.strip()
+            if not item or item in seen:
+                continue
+            seen.add(item)
+            tokens.append(item)
+    return ",".join(tokens) if tokens else None
+
+
 def _read_confluence_body_arg(
     raw_html: Optional[str],
     html_file: Optional[str],
@@ -104,6 +129,62 @@ def _preview_html(value: Optional[str], limit: int = 240) -> Optional[str]:
     return _preview_text(preview, limit=limit)
 
 
+def _page_body_html(page: Dict[str, Any]) -> str:
+    return (((page.get("body") or {}).get("storage") or {}).get("value")) or ""
+
+
+def _is_effectively_empty_body(body_html: Optional[str]) -> bool:
+    if not body_html:
+        return True
+    normalized = body_html.replace("\xa0", " ").replace(" ", " ")
+    normalized = re.sub(r"<!--.*?-->", "", normalized, flags=re.DOTALL)
+    normalized = re.sub(r"<p>\s*(<br\s*/?>)?\s*</p>", "", normalized, flags=re.IGNORECASE)
+    normalized = re.sub(r"<br\s*/?>", "", normalized, flags=re.IGNORECASE)
+    normalized = re.sub(r"\s+", "", normalized)
+    return normalized == ""
+
+
+def _summarize_child_pages(child_pages: list[Dict[str, Any]]) -> list[Dict[str, Any]]:
+    return [ConfluenceClient.summarize_page(page) for page in child_pages]
+
+
+def _fallback_confluence_page_url(page: Dict[str, Any], page_id: Optional[str]) -> Optional[str]:
+    if not page_id:
+        return None
+    base_url = ((page.get("_links") or {}).get("base")) or ""
+    if not base_url:
+        return None
+    return "{0}/pages/viewpage.action?pageId={1}".format(base_url.rstrip("/"), page_id)
+
+
+def _page_navigation_payload(
+    *,
+    page: Dict[str, Any],
+    child_pages: list[Dict[str, Any]],
+) -> Dict[str, Any]:
+    body_html = _page_body_html(page)
+    body_is_effectively_empty = _is_effectively_empty_body(body_html)
+    child_summaries = _summarize_child_pages(child_pages)
+    for summary in child_summaries:
+        if not summary.get("webui_url"):
+            summary["webui_url"] = _fallback_confluence_page_url(page, summary.get("id"))
+    page_kind = "hub" if body_is_effectively_empty and child_summaries else "content"
+
+    payload: Dict[str, Any] = {
+        "page_kind": page_kind,
+        "body_is_effectively_empty": body_is_effectively_empty,
+        "child_count": len(child_summaries),
+    }
+    if child_summaries:
+        payload["children"] = child_summaries
+    if page_kind == "hub":
+        payload["read_hint"] = (
+            "This page behaves like a hub/index page. Read the listed child pages or use "
+            "`export-tree-md` for the full hierarchy."
+        )
+    return payload
+
+
 def _sanitize_markdown_filename(title: str) -> str:
     sanitized = "".join(
         "_" if char in '<>:"/\\|?*' else char
@@ -156,7 +237,7 @@ def _read_export_metadata(path: Path) -> Dict[str, Any]:
 
 def _page_export_payload(page: Dict[str, Any]) -> Dict[str, Any]:
     payload = ConfluenceClient.summarize_page(page)
-    payload["body_html"] = (((page.get("body") or {}).get("storage") or {}).get("value")) or ""
+    payload["body_html"] = _page_body_html(page)
     payload["ancestors"] = page.get("ancestors") or []
     return payload
 
@@ -353,6 +434,9 @@ def _build_parser() -> argparse.ArgumentParser:
     jira_get_issue.add_argument("--issue-key", required=True)
     jira_get_issue.add_argument("--fields")
     jira_get_issue.add_argument("--expand")
+    jira_get_issue.add_argument("--include-comments", action="store_true")
+    jira_get_issue.add_argument("--comments-limit", type=int, default=3)
+    jira_get_issue.add_argument("--raw", action="store_true")
 
     jira_search = subparsers.add_parser("jira-search", help="Search Jira with JQL")
     jira_search.add_argument("--jql", required=True)
@@ -360,6 +444,7 @@ def _build_parser() -> argparse.ArgumentParser:
     jira_search.add_argument("--start", type=int, default=0)
     jira_search.add_argument("--fields")
     jira_search.add_argument("--expand")
+    jira_search.add_argument("--raw", action="store_true")
 
     jira_get_createmeta = subparsers.add_parser(
         "jira-get-createmeta",
@@ -793,14 +878,19 @@ def _handle_confluence(args: argparse.Namespace) -> Dict[str, Any]:
     if args.command == "auth-check":
         return client.auth_check()
     if args.command == "get-page":
-        page = client.get_page(args.page_id, expand=args.expand)
+        expand = _merge_csv_fields(args.expand, ["body.storage", "version", "space"])
+        page = client.get_page(args.page_id, expand=expand)
+        child_pages = client.list_child_pages(args.page_id)
         payload = client.summarize_page(page)
+        payload.update(_page_navigation_payload(page=page, child_pages=child_pages))
         if args.expand and "body.storage" in args.expand:
-            payload["body_html"] = (((page.get("body") or {}).get("storage") or {}).get("value"))
+            payload["body_html"] = _page_body_html(page)
         return payload
     if args.command == "export-page-md":
         page = client.get_page(args.page_id, expand="body.storage,version,space")
+        child_pages = client.list_child_pages(args.page_id)
         payload = _page_export_payload(page)
+        payload.update(_page_navigation_payload(page=page, child_pages=child_pages))
         exporter = MarkdownExporter(
             base_url=settings.base_url,
             page_id=args.page_id,
@@ -823,6 +913,9 @@ def _handle_confluence(args: argparse.Namespace) -> Dict[str, Any]:
             "title": payload["title"],
             "output_file": str(output_path),
             "source_url": payload["webui_url"],
+            "page_kind": payload["page_kind"],
+            "child_count": payload["child_count"],
+            "hub_generated": payload["page_kind"] == "hub",
             "used_staging_local": str(output_path).startswith(
                 str((Path(settings.export_staging_dir) if settings.export_staging_dir else _default_export_staging_dir()))
             ),
@@ -1193,8 +1286,20 @@ def _handle_jira(args: argparse.Namespace) -> Dict[str, Any]:
     if args.command == "jira-auth-check":
         return client.auth_check()
     if args.command == "jira-get-issue":
-        issue = client.get_issue(args.issue_key, fields=args.fields, expand=args.expand)
-        return client.summarize_issue(issue)
+        fields = args.fields
+        if args.include_comments:
+            required_fields = ["comment", "updated"]
+            if args.fields is None:
+                required_fields = _JIRA_SUMMARY_FIELDS + ["comment"]
+            fields = _merge_csv_fields(args.fields, required_fields)
+        issue = client.get_issue(args.issue_key, fields=fields, expand=args.expand)
+        if args.raw:
+            return issue
+        return client.summarize_issue(
+            issue,
+            include_comments=args.include_comments,
+            comments_limit=args.comments_limit,
+        )
     if args.command == "jira-search":
         result = client.search(
             jql=args.jql,
@@ -1203,6 +1308,8 @@ def _handle_jira(args: argparse.Namespace) -> Dict[str, Any]:
             fields=args.fields,
             expand=args.expand,
         )
+        if args.raw:
+            return result
         return client.summarize_search_results(result.get("issues", []))
     if args.command == "jira-get-createmeta":
         result = client.get_createmeta(

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/src/conjira_cli/client.py

@@ -540,14 +540,32 @@ class JiraClient(BaseAtlassianClient):
             return None
         return "{0}/browse/{1}".format(base_url.rstrip("/"), issue_key)
 
-    def summarize_issue(self, issue: Dict[str, Any]) -> Dict[str, Any]:
+    @staticmethod
+    def _comment_body_preview(value: Any, limit: int = 280) -> Optional[str]:
+        if value is None:
+            return None
+        if isinstance(value, str):
+            collapsed = " ".join(value.split())
+        else:
+            collapsed = " ".join(json.dumps(value, ensure_ascii=False).split())
+        if len(collapsed) <= limit:
+            return collapsed
+        return collapsed[: limit - 1].rstrip() + "…"
+
+    def summarize_issue(
+        self,
+        issue: Dict[str, Any],
+        *,
+        include_comments: bool = False,
+        comments_limit: int = 3,
+    ) -> Dict[str, Any]:
         fields = issue.get("fields") or {}
         status = fields.get("status") or {}
         issue_type = fields.get("issuetype") or {}
         project = fields.get("project") or {}
         assignee = fields.get("assignee") or {}
         reporter = fields.get("reporter") or {}
-        return {
+        summary = {
             "id": issue.get("id"),
             "key": issue.get("key"),
             "summary": fields.get("summary"),
@@ -556,8 +574,25 @@ class JiraClient(BaseAtlassianClient):
             "project_key": project.get("key"),
             "assignee": assignee.get("displayName"),
             "reporter": reporter.get("displayName"),
+            "updated": fields.get("updated"),
             "browse_url": self.browse_url(self.base_url, issue.get("key")),
         }
+        if include_comments:
+            comment_block = fields.get("comment") or {}
+            comments = comment_block.get("comments") or []
+            limited = comments[-comments_limit:] if comments_limit > 0 else comments
+            summary["comment_count"] = comment_block.get("total", len(comments))
+            summary["recent_comments"] = [
+                {
+                    "id": comment.get("id"),
+                    "author": ((comment.get("author") or {}).get("displayName")),
+                    "created": comment.get("created"),
+                    "updated": comment.get("updated"),
+                    "body_preview": self._comment_body_preview(comment.get("body")),
+                }
+                for comment in limited
+            ]
+        return summary
 
     def summarize_search_results(self, items: Iterable[Dict[str, Any]]) -> Dict[str, Any]:
         results = [self.summarize_issue(item) for item in items]

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/src/conjira_cli/markdown_export.py

@@ -113,6 +113,10 @@ def _normalize_table_header(value: str) -> str:
     return value
 
 
+def _escape_table_cell(value: str) -> str:
+    return value.replace("|", "\\|").strip()
+
+
 @dataclass
 class MarkdownExporter:
     base_url: str
@@ -124,8 +128,14 @@ class MarkdownExporter:
         source_url = page.get("webui_url") or ""
         version = page.get("version")
         parent_page_id = page.get("parent_page_id")
+        page_kind = page.get("page_kind")
+        child_count = page.get("child_count")
         body_html = page.get("body_html") or ""
-        body_md = self.convert_fragment(body_html)
+        children = page.get("children") or []
+        if page_kind == "hub" and children:
+            body_md = self._render_hub_page(children)
+        else:
+            body_md = self.convert_fragment(body_html)
 
         parts = [
             "---",
@@ -135,6 +145,10 @@ class MarkdownExporter:
         ]
         if parent_page_id:
             parts.append(f"confluence_parent_page_id: {parent_page_id}")
+        if page_kind:
+            parts.append(f"confluence_page_kind: {page_kind}")
+        if child_count:
+            parts.append(f"confluence_child_count: {child_count}")
         parts.extend(
             [
             f"source_url: {source_url}",
@@ -151,6 +165,25 @@ class MarkdownExporter:
         )
         return "\n".join(parts)
 
+    def _render_hub_page(self, children: list[dict[str, Any]]) -> str:
+        lines = [
+            "> [!INFO] This is a Confluence hub/index page.",
+            "> The main content lives in the child pages listed below.",
+            "",
+            "## Child pages",
+            "",
+            "| Title | Page ID | Link |",
+            "| --- | --- | --- |",
+        ]
+        for child in children:
+            title = _escape_table_cell(child.get("title") or "Untitled")
+            page_id = _escape_table_cell(str(child.get("id") or ""))
+            url = child.get("webui_url") or ""
+            link = f"[Open]({url})" if url else ""
+            lines.append(f"| {title} | {page_id} | {link} |")
+        lines.append("")
+        return "\n".join(lines)
+
     def convert_fragment(self, body_html: str) -> str:
         wrapped = (
             '<root xmlns:ac="urn:ac" xmlns:ri="urn:ri">'

{conjira_cli-0.2.2 → conjira_cli-0.2.3/src/conjira_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conjira-cli
-Version: 0.2.2
+Version: 0.2.3
 Summary: Unofficial agent-friendly CLI for self-hosted Confluence and Jira
 Author: quanttraderkim
 License-Expression: MIT
@@ -140,6 +140,50 @@ conjira export-page-md --page-id 123456 --output-dir "/path/to/notes"
 
 If you run the CLI from a different folder, pass the config file explicitly with `--env-file /path/to/local/agent.env`.
 
+## Prompt templates by document type
+
+When you ask an agent to upload or update a document, results are better if you tell it what kind of document it is, whether Markdown should remain the source of truth, and whether the Confluence page should stay plain or become more presentation-friendly.
+
+For skill specs or evaluation docs, a good request is:
+
+```text
+Use conjira to upload this Markdown file as a Confluence page. Treat it as a skill spec, keep the Markdown structure as the source of truth, preserve headings and tables, and only use Confluence-native rendering where it helps readability without changing the document's meaning.
+```
+
+For service planning docs or PRDs, a good request is:
+
+```text
+Use conjira to turn this Markdown file into a Confluence PRD. Keep the content faithful to the source, but make it easier to read in Confluence. Add status, callouts, and expand blocks where they improve readability, and organize the page around summary, background, problem, scope, flow, risks, and open questions.
+```
+
+For strategy reports or review decks, a good request is:
+
+```text
+Use conjira to publish this Markdown file as a report-style Confluence page. Keep the source content intact, but optimize the page for presentation. Put the executive summary first, surface key decisions and risks early, and use status, info blocks, expand sections, and Mermaid where appropriate.
+```
+
+If you want to stay closer to raw Markdown, say `keep this Markdown-first and avoid extra presentation macros`. If you want a more polished Confluence page, say `optimize this for Confluence readability while keeping the source content intact`.
+
+## Document writing style guide
+
+For Confluence uploads, structure matters as much as accuracy. Strategy memos, PRDs, planning docs, and report-style pages read much better when the writer uses a compact working-document style instead of long essay-like prose.
+
+Prefer report-style memo wording over verbose formal phrasing. In Korean this usually means reducing repetitive `~입니다` and `~합니다`, and favoring shorter noun-phrase or judgment-oriented endings such as `~필요`, `~전제`, `~검토`, `~제안`, or `~우선`. Do not force every sentence into rigid `~함` wording; the target is a concise internal memo tone, not mechanical shorthand. Keep paragraphs short, lead with the conclusion, and make `###` headings carry the message or judgment instead of acting as generic labels.
+
+Use bullet points only for true parallel items. Do not split a single thought into fake bullets just to reduce line length. Use tables for comparisons, summaries, options, risks, target groups, ownership, or decision support. Do not force short explanatory text into a table when a compact paragraph is clearer.
+
+A good default order is `purpose -> summary -> key judgments / evidence -> risks / assumptions -> implications / next actions`. Strategy memos usually need `why this matters`, `key judgment`, `evidence`, and `implications`. PRDs usually need `problem`, `goal`, `scope`, `flow`, `policy`, and `open issues`. Skill specs are better when they stay literal and dry, with sections like `one-line definition`, `when to use`, `inputs`, `outputs`, `exceptions`, and `evaluation criteria`.
+
+For longer strategy or report documents, explicit numbering helps. Top-level sections such as `A.`, `B.`, `C.` and second-level sections such as `A-1.`, `A-2.` usually make the table of contents and the body much easier to scan. As a default, stay within two levels unless the user explicitly wants a deeper document tree.
+
+Cut abstract filler. Avoid phrases like “strategically meaningful”, “fundamentally important value”, or “meaningful impact across multiple dimensions” unless they add something precise. Prefer concrete statements such as “follow-up gaps turn into revenue loss”, “A is the right first rollout option”, or “free-user monetization is necessary but total revenue impact is limited”.
+
+If you want an agent to follow this style explicitly, a good request is:
+
+```text
+Use conjira to publish this document to Confluence. Keep the source content intact, but rewrite it in a concise internal memo style. Reduce formal `~입니다/~합니다` phrasing, prefer short noun-phrase or judgment-oriented wording, put the key summary first, use stronger h3/h4 headings and tables where they help scanability, add `A.` / `A-1.` numbering when the document is long enough to benefit from it, keep bullets for true parallel items only, and remove abstract filler.
+```
+
 Short sample output blocks, using synthetic values:
 
 ```json
@@ -315,6 +359,14 @@ conjira --env-file ./local/agent.env jira-search --jql 'project = DEMO ORDER BY
 conjira --env-file ./local/agent.env jira-get-issue --issue-key DEMO-123
 ```
 
+Inspect updated timestamps or recent comments when needed:
+
+```bash
+conjira jira-get-issue --issue-key DEMO-123 --include-comments --comments-limit 2
+conjira jira-get-issue --issue-key DEMO-123 --raw --fields summary,updated,comment
+conjira jira-search --jql 'project = DEMO ORDER BY updated DESC' --raw --fields summary,updated
+```
+
 Create a Jira issue or add a comment:
 
 ```bash

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/tests/test_cli.py

@@ -240,6 +240,142 @@ class CliTests(unittest.TestCase):
         mock_get_page.assert_called_once_with("12345", expand="body.storage,version,space,ancestors")
         mock_export_tree.assert_called_once()
 
+    def test_handle_confluence_get_page_marks_hub_and_lists_children(self) -> None:
+        args = SimpleNamespace(
+            command="get-page",
+            base_url=None,
+            token=None,
+            token_file=None,
+            token_keychain_service=None,
+            token_keychain_account=None,
+            timeout=None,
+            env_file=None,
+            page_id="12345",
+            expand="body.storage",
+        )
+        settings = ConfluenceSettings(
+            base_url="https://confluence.example.com",
+            token="token",
+            timeout_seconds=30,
+        )
+        page = {
+            "id": "12345",
+            "type": "page",
+            "status": "current",
+            "title": "AI 메시지 상세기획",
+            "space": {"key": "DOCS"},
+            "version": {"number": 7},
+            "body": {"storage": {"value": "<p><br/></p>"}},
+            "_links": {
+                "base": "https://confluence.example.com",
+                "webui": "/pages/viewpage.action?pageId=12345",
+            },
+        }
+        child_pages = [
+            {
+                "id": "20001",
+                "type": "page",
+                "status": "current",
+                "title": "메시지 AI 제안",
+            }
+        ]
+
+        with mock.patch("conjira_cli.cli.build_confluence_settings", return_value=settings), mock.patch(
+            "conjira_cli.cli.ConfluenceClient.get_page",
+            return_value=page,
+        ) as mock_get_page, mock.patch(
+            "conjira_cli.cli.ConfluenceClient.list_child_pages",
+            return_value=child_pages,
+        ) as mock_list_child_pages:
+            payload = _handle_confluence(args)
+
+        self.assertEqual(payload["page_kind"], "hub")
+        self.assertTrue(payload["body_is_effectively_empty"])
+        self.assertEqual(payload["child_count"], 1)
+        self.assertEqual(payload["children"][0]["id"], "20001")
+        self.assertEqual(
+            payload["children"][0]["webui_url"],
+            "https://confluence.example.com/pages/viewpage.action?pageId=20001",
+        )
+        self.assertIn("hub/index page", payload["read_hint"])
+        self.assertEqual(payload["body_html"], "<p><br/></p>")
+        mock_get_page.assert_called_once_with("12345", expand="body.storage,version,space")
+        mock_list_child_pages.assert_called_once_with("12345")
+
+    def test_handle_confluence_export_page_md_generates_hub_markdown(self) -> None:
+        args = SimpleNamespace(
+            command="export-page-md",
+            base_url=None,
+            token=None,
+            token_file=None,
+            token_keychain_service=None,
+            token_keychain_account=None,
+            timeout=None,
+            env_file=None,
+            page_id="12345",
+            output_file=None,
+            output_dir=None,
+            filename=None,
+            staging_local=True,
+        )
+        settings = ConfluenceSettings(
+            base_url="https://confluence.example.com",
+            token="token",
+            timeout_seconds=30,
+            export_staging_dir="/tmp/conjira-staging",
+        )
+        page = {
+            "id": "12345",
+            "type": "page",
+            "status": "current",
+            "title": "AI 메시지 상세기획",
+            "space": {"key": "DOCS"},
+            "version": {"number": 7},
+            "body": {"storage": {"value": ""}},
+            "_links": {
+                "base": "https://confluence.example.com",
+                "webui": "/pages/viewpage.action?pageId=12345",
+            },
+        }
+        child_pages = [
+            {
+                "id": "20001",
+                "type": "page",
+                "status": "current",
+                "title": "메시지 AI 제안",
+                "space": {"key": "DOCS"},
+                "version": {"number": 3},
+                "_links": {
+                    "base": "https://confluence.example.com",
+                    "webui": "/pages/viewpage.action?pageId=20001",
+                },
+            }
+        ]
+
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            settings.export_staging_dir = tmp_dir
+            with mock.patch("conjira_cli.cli.build_confluence_settings", return_value=settings), mock.patch(
+                "conjira_cli.cli.ConfluenceClient.get_page",
+                return_value=page,
+            ) as mock_get_page, mock.patch(
+                "conjira_cli.cli.ConfluenceClient.list_child_pages",
+                return_value=child_pages,
+            ) as mock_list_child_pages:
+                payload = _handle_confluence(args)
+
+            output_file = Path(payload["output_file"])
+            markdown = output_file.read_text(encoding="utf-8")
+
+        self.assertEqual(payload["page_kind"], "hub")
+        self.assertEqual(payload["child_count"], 1)
+        self.assertTrue(payload["hub_generated"])
+        self.assertIn("confluence_page_kind: hub", markdown)
+        self.assertIn("confluence_child_count: 1", markdown)
+        self.assertIn("> [!INFO] This is a Confluence hub/index page.", markdown)
+        self.assertIn("| 메시지 AI 제안 | 20001 |", markdown)
+        mock_get_page.assert_called_once_with("12345", expand="body.storage,version,space")
+        mock_list_child_pages.assert_called_once_with("12345")
+
     def test_handle_confluence_update_page_dry_run_uses_live_page_without_write(self) -> None:
         args = SimpleNamespace(
             command="update-page",
@@ -611,6 +747,153 @@ class CliTests(unittest.TestCase):
         mock_get_issue.assert_called_once_with("DEMO-123")
         mock_add_comment.assert_not_called()
 
+    def test_handle_jira_get_issue_can_include_comments(self) -> None:
+        args = SimpleNamespace(
+            command="jira-get-issue",
+            base_url=None,
+            token=None,
+            token_file=None,
+            token_keychain_service=None,
+            token_keychain_account=None,
+            timeout=None,
+            env_file=None,
+            issue_key="DEMO-123",
+            fields=None,
+            expand=None,
+            include_comments=True,
+            comments_limit=2,
+            raw=False,
+        )
+        settings = JiraSettings(
+            base_url="https://jira.example.com",
+            token="token",
+            timeout_seconds=30,
+        )
+        issue = {
+            "id": "9000",
+            "key": "DEMO-123",
+            "fields": {
+                "summary": "Demo issue",
+                "status": {"name": "In Progress"},
+                "issuetype": {"name": "Task"},
+                "project": {"key": "DEMO"},
+                "updated": "2026-04-09T18:20:00.000+0900",
+                "comment": {
+                    "total": 1,
+                    "comments": [
+                        {
+                            "id": "1001",
+                            "author": {"displayName": "Alex"},
+                            "created": "2026-04-09T09:00:00.000+0900",
+                            "updated": "2026-04-09T09:10:00.000+0900",
+                            "body": "Latest comment body",
+                        }
+                    ],
+                },
+            },
+        }
+
+        with mock.patch("conjira_cli.cli.build_jira_settings", return_value=settings), mock.patch(
+            "conjira_cli.cli.JiraClient.get_issue",
+            return_value=issue,
+        ) as mock_get_issue:
+            payload = _handle_jira(args)
+
+        self.assertEqual(payload["key"], "DEMO-123")
+        self.assertEqual(payload["updated"], "2026-04-09T18:20:00.000+0900")
+        self.assertEqual(payload["comment_count"], 1)
+        self.assertEqual(payload["recent_comments"][0]["body_preview"], "Latest comment body")
+        mock_get_issue.assert_called_once_with(
+            "DEMO-123",
+            fields="summary,status,issuetype,project,assignee,reporter,updated,comment",
+            expand=None,
+        )
+
+    def test_handle_jira_get_issue_raw_returns_full_payload(self) -> None:
+        args = SimpleNamespace(
+            command="jira-get-issue",
+            base_url=None,
+            token=None,
+            token_file=None,
+            token_keychain_service=None,
+            token_keychain_account=None,
+            timeout=None,
+            env_file=None,
+            issue_key="DEMO-123",
+            fields="summary,updated",
+            expand="changelog",
+            include_comments=False,
+            comments_limit=3,
+            raw=True,
+        )
+        settings = JiraSettings(
+            base_url="https://jira.example.com",
+            token="token",
+            timeout_seconds=30,
+        )
+        issue = {
+            "id": "9000",
+            "key": "DEMO-123",
+            "fields": {"summary": "Demo issue", "updated": "2026-04-09T18:20:00.000+0900"},
+        }
+
+        with mock.patch("conjira_cli.cli.build_jira_settings", return_value=settings), mock.patch(
+            "conjira_cli.cli.JiraClient.get_issue",
+            return_value=issue,
+        ) as mock_get_issue:
+            payload = _handle_jira(args)
+
+        self.assertEqual(payload, issue)
+        mock_get_issue.assert_called_once_with("DEMO-123", fields="summary,updated", expand="changelog")
+
+    def test_handle_jira_search_raw_returns_full_payload(self) -> None:
+        args = SimpleNamespace(
+            command="jira-search",
+            base_url=None,
+            token=None,
+            token_file=None,
+            token_keychain_service=None,
+            token_keychain_account=None,
+            timeout=None,
+            env_file=None,
+            jql="project = DEMO",
+            limit=5,
+            start=0,
+            fields="summary,updated",
+            expand=None,
+            raw=True,
+        )
+        settings = JiraSettings(
+            base_url="https://jira.example.com",
+            token="token",
+            timeout_seconds=30,
+        )
+        result = {
+            "issues": [
+                {
+                    "id": "9000",
+                    "key": "DEMO-123",
+                    "fields": {"summary": "Demo issue"},
+                }
+            ],
+            "total": 1,
+        }
+
+        with mock.patch("conjira_cli.cli.build_jira_settings", return_value=settings), mock.patch(
+            "conjira_cli.cli.JiraClient.search",
+            return_value=result,
+        ) as mock_search:
+            payload = _handle_jira(args)
+
+        self.assertEqual(payload, result)
+        mock_search.assert_called_once_with(
+            jql="project = DEMO",
+            limit=5,
+            start=0,
+            fields="summary,updated",
+            expand=None,
+        )
+
     def test_handle_confluence_upload_attachment_dry_run_detects_replace_mode(self) -> None:
         with tempfile.TemporaryDirectory() as tmp_dir:
             file_path = Path(tmp_dir) / "chart.png"

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/tests/test_client.py

@@ -109,6 +109,7 @@ class ClientTests(unittest.TestCase):
                 "project": {"key": "TEST"},
                 "assignee": {"displayName": "Assignee User"},
                 "reporter": {"displayName": "Reporter User"},
+                "updated": "2026-04-09T18:20:00.000+0900",
             },
         }
 
@@ -117,8 +118,49 @@ class ClientTests(unittest.TestCase):
         self.assertEqual(summary["key"], "TEST-9")
         self.assertEqual(summary["status"], "In Progress")
         self.assertEqual(summary["issue_type"], "Task")
+        self.assertEqual(summary["updated"], "2026-04-09T18:20:00.000+0900")
         self.assertEqual(summary["browse_url"], "https://jira.example.com/browse/TEST-9")
 
+    def test_summarize_issue_can_include_recent_comments(self) -> None:
+        client = JiraClient(base_url="https://jira.example.com", token="token")
+        issue = {
+            "id": "456",
+            "key": "TEST-9",
+            "fields": {
+                "summary": "Demo issue",
+                "status": {"name": "In Progress"},
+                "issuetype": {"name": "Task"},
+                "project": {"key": "TEST"},
+                "updated": "2026-04-09T18:20:00.000+0900",
+                "comment": {
+                    "total": 2,
+                    "comments": [
+                        {
+                            "id": "1001",
+                            "author": {"displayName": "Alex"},
+                            "created": "2026-04-08T10:00:00.000+0900",
+                            "updated": "2026-04-08T10:00:00.000+0900",
+                            "body": "First comment",
+                        },
+                        {
+                            "id": "1002",
+                            "author": {"displayName": "Taylor"},
+                            "created": "2026-04-09T09:00:00.000+0900",
+                            "updated": "2026-04-09T09:10:00.000+0900",
+                            "body": "Second comment with a longer body that should still remain readable.",
+                        },
+                    ],
+                },
+            },
+        }
+
+        summary = client.summarize_issue(issue, include_comments=True, comments_limit=1)
+
+        self.assertEqual(summary["comment_count"], 2)
+        self.assertEqual(len(summary["recent_comments"]), 1)
+        self.assertEqual(summary["recent_comments"][0]["id"], "1002")
+        self.assertEqual(summary["recent_comments"][0]["author"], "Taylor")
+
     def test_list_inline_comments_fetches_all_pages(self) -> None:
         client = ConfluenceClient(base_url="https://confluence.example.com", token="token")
 

{conjira_cli-0.2.2 → conjira_cli-0.2.3}/tests/test_markdown_export.py

@@ -38,6 +38,38 @@ class MarkdownExportTests(unittest.TestCase):
 
         self.assertIn("confluence_parent_page_id: 100", result)
 
+    def test_convert_page_renders_hub_children_as_index_content(self) -> None:
+        exporter = MarkdownExporter(base_url="https://confluence.example.com", page_id="123")
+
+        result = exporter.convert_page(
+            {
+                "title": "상세기획 루트",
+                "version": 7,
+                "webui_url": "https://confluence.example.com/pages/123",
+                "body_html": "",
+                "page_kind": "hub",
+                "child_count": 2,
+                "children": [
+                    {
+                        "id": "20001",
+                        "title": "메시지 AI 제안",
+                        "webui_url": "https://confluence.example.com/pages/20001",
+                    },
+                    {
+                        "id": "20002",
+                        "title": "메시지 요약",
+                        "webui_url": "https://confluence.example.com/pages/20002",
+                    },
+                ],
+            }
+        )
+
+        self.assertIn("confluence_page_kind: hub", result)
+        self.assertIn("confluence_child_count: 2", result)
+        self.assertIn("## Child pages", result)
+        self.assertIn("| 메시지 AI 제안 | 20001 | [Open](https://confluence.example.com/pages/20001) |", result)
+        self.assertIn("| 메시지 요약 | 20002 | [Open](https://confluence.example.com/pages/20002) |", result)
+
     def test_structured_table_renders_as_sections(self) -> None:
         exporter = MarkdownExporter(base_url="https://confluence.example.com", page_id="123")
         html = (