ghost-reader 0.0.1__py3-none-any.whl

ghost_reader/cli.py

@@ -0,0 +1,1124 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import signal
+import sys
+if sys.platform != "win32":
+    import fcntl
+import time
+import traceback
+import uuid
+from pathlib import Path
+from pprint import pformat
+
+from ghost_reader import __version__
+from ghost_reader.constants import (
+    AVAILABLE_PERSONAS,
+    DEFAULT_PERSONAS,
+    SCHEMA_VERSIONS,
+    TEMPLATE_VERSION,
+)
+from ghost_reader.dialogue import (
+    dialogue_append,
+    dialogue_context,
+)
+from ghost_reader.errors import GhostReaderError
+from ghost_reader.io import (
+    emit_yaml,
+    load_yaml_file,
+    load_yaml_text,
+    read_input,
+    write_yaml,
+)
+from ghost_reader.paths import (
+    artifact_paths,
+    find_project_root,
+    ghost_reader_home,
+    project_dir,
+    session_dir,
+)
+from ghost_reader.project import (
+    ensure_home,
+    ensure_project,
+    ensure_session_structure,
+    load_manifest,
+    parse_personas,
+    persona_brief,
+    read_persona,
+    save_manifest,
+)
+from ghost_reader.report import render_report
+from ghost_reader.reviews import compact_review_item, feedback_summary, load_reviews
+from ghost_reader.revision import generate_revision_prompt
+from ghost_reader.round import refine_snapshot, round_init, round_status
+from ghost_reader.server import serve_report
+from ghost_reader.sync import create_sync_bundle
+from ghost_reader.telemetry import append_event, telemetry_status
+from ghost_reader.time import new_session_id, now_iso
+from ghost_reader.feedback_store import record_feedback
+from ghost_reader.release import (
+    GITHUB_INSTALL_GIT,
+    GITHUB_REPO_URL,
+    UNAVAILABLE_STATUS,
+    embedded_release_version,
+    fetch_latest_release,
+)
+from ghost_reader.validators import validate_review
+from ghost_reader.verify import verify_session
+
+OUTPUT_FORMATS = ("yaml", "json", "pretty")
+
+
+def add_output_format_option(
+    parser: argparse.ArgumentParser,
+    *,
+    default: str | object = argparse.SUPPRESS,
+) -> None:
+    parser.add_argument(
+        "--format",
+        "-f",
+        dest="output_format",
+        choices=OUTPUT_FORMATS,
+        default=default,
+        help="Output format for summary/status commands (default: yaml).",
+    )
+
+
+def emit_output(args: argparse.Namespace, data: object) -> None:
+    output_format = getattr(args, "output_format", "yaml")
+    if output_format == "json":
+        sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+    elif output_format == "pretty":
+        sys.stdout.write(pformat(data, sort_dicts=False) + "\n")
+    else:
+        emit_yaml(data)
+
+
+def _help_personas(home: Path) -> list[dict[str, str]]:
+    entries: list[dict[str, str]] = []
+    for persona_id in AVAILABLE_PERSONAS:
+        persona = read_persona(home, persona_id)
+        entries.append(
+            {
+                "id": persona_id,
+                "name": persona["name"],
+                "focus": persona_brief(persona),
+            }
+        )
+    return entries
+
+
+def command_help(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    ensure_home(home)
+    emit_output(
+        args,
+        {
+            "name": "ghost-reader",
+            "version": __version__,
+            "description": "Local-first persona-driven fiction review simulator",
+            "repository": GITHUB_REPO_URL,
+            "install": f"uv tool install '{GITHUB_INSTALL_GIT}'",
+            "personas": _help_personas(home),
+            "commands": {
+                "init": "Initialize story project and persona home",
+                "help": "Show this manifest",
+                "update check": "Compare CLI version with latest GitHub release",
+                "session create": "Create a review session with selected personas",
+                "session summary": "List review items and artifact paths",
+                "artifact write": "Write context, source map, source text, or review YAML",
+                "feedback add": "Record user feedback on review items",
+                "feedback summary": "Summarize selected feedback items",
+                "prompt revision": "Generate unified revision prompt from feedback",
+                "dialogue append": "Append a turn to a persona dialogue thread",
+                "dialogue context": "Show dialogue context for a review item",
+                "history summary": "Show recent session usage",
+                "round init": "Start a new review round",
+                "round status": "Show current round state",
+                "refine snapshot": "Archive reviews and feedback before refinement",
+                "render": "Build report HTML from payload (use --format list for templates)",
+                "verify": "Validate session artifacts and return workflow status",
+                "telemetry append": "Append a content-safe telemetry event",
+                "telemetry status": "Show telemetry outbox and last sync time",
+                "sync": "Export a local telemetry bundle",
+                "serve": "Serve report and accept feedback via HTTP",
+            },
+            "phase": 2,
+            "planned_commands": ["recommend"],
+        }
+    )
+    return 0
+
+
+def command_init(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = Path.cwd()
+    project = ensure_project(project_root, home)
+    status = telemetry_status(home)
+    emit_output(
+        args,
+        {
+            "project_initialized": True,
+            "project_root": str(project_root),
+            "config_found": (home / "config.yaml").exists(),
+            "available_personas": project.get("available_personas", AVAILABLE_PERSONAS),
+            "default_personas": project.get("default_personas", DEFAULT_PERSONAS),
+            "schema_versions": dict(SCHEMA_VERSIONS),
+            "template_version": TEMPLATE_VERSION,
+            "updates": {
+                "cli": "current",
+                "personas": "current",
+                "templates": "current",
+            },
+            "pending_telemetry_events": status["pending_events"],
+            "last_sync_at": status["last_sync_at"],
+            "warnings": [],
+        }
+    )
+    return 0
+
+
+def command_update_check(args: argparse.Namespace) -> int:
+    embedded_version = embedded_release_version()
+    payload: dict[str, object] = {
+        "cli_version": __version__,
+        "repository": GITHUB_REPO_URL,
+        "repository_visibility": "private_or_public",
+        "personas": "current",
+        "persona_schema_version": SCHEMA_VERSIONS["persona"],
+        "templates": "current",
+        "template_version": TEMPLATE_VERSION,
+    }
+    if embedded_version:
+        payload["embedded_release_version"] = embedded_version
+        if embedded_version != __version__:
+            payload["update_status"] = "upgrade_available"
+            payload["install_hint"] = (
+                f"uv tool install '{GITHUB_INSTALL_GIT}' "
+                f"# latest packaged release record is {embedded_version}"
+            )
+            # Fall through to GitHub API for full release metadata
+            # (the embedded record is a floor, not a ceiling)
+
+    latest = fetch_latest_release()
+    if latest and latest.get("version"):
+        latest_version = str(latest["version"])
+        payload["latest_release"] = latest
+        if latest_version == __version__:
+            payload["update_status"] = "current"
+        else:
+            payload["update_status"] = "upgrade_available"
+            tag = latest.get("tag")
+            ref = tag if tag else "main"
+            install_ref = GITHUB_INSTALL_GIT if ref == "main" else f"{GITHUB_INSTALL_GIT}@{ref}"
+            payload["install_hint"] = (
+                f"uv tool install '{install_ref}' "
+                f"# private repo: requires GitHub SSH access, GH_TOKEN, or authenticated git HTTPS"
+            )
+    else:
+        if embedded_version:
+            if embedded_version == __version__:
+                payload["update_status"] = "current"
+            # else: update_status already set to "upgrade_available" above
+            payload["latest_release"] = {
+                "version": embedded_version,
+                "source": "embedded_release_record",
+            }
+            payload["warning"] = "GitHub release API unavailable; using local release record."
+        else:
+            payload["update_status"] = UNAVAILABLE_STATUS
+            payload["latest_release"] = None
+    emit_output(args, payload)
+    return 0
+
+
+def command_persona_list(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    ensure_home(home)
+    output: list[dict[str, object]] = []
+    for persona_id in AVAILABLE_PERSONAS:
+        try:
+            persona = read_persona(home, persona_id)
+        except GhostReaderError:
+            continue
+        brief = persona_brief(persona)
+        output.append({
+            "id": persona_id,
+            "name": persona.get("name", persona_id.title()),
+            "reader_type": persona.get("reader_type", ""),
+            "summary": persona.get("profile", {}).get("summary", ""),
+            "review_focus": brief,
+        })
+    emit_output(args, output)
+    return 0
+
+
+def command_persona_show(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    ensure_home(home)
+    persona_id = args.persona_id
+    try:
+        persona = read_persona(home, persona_id)
+    except GhostReaderError as exc:
+        sys.stderr.write(f"ghost-reader: error: {exc}\n")
+        return 2
+    emit_output(args, persona)
+    return 0
+
+
+def command_session_create(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    ensure_project(project_root, home)
+    personas = parse_personas(args.personas)
+    session_id = args.id or new_session_id(args.story_unit)
+    path = session_dir(project_root, session_id)
+    existed = (path / "manifest.yaml").exists()
+    if existed and not args.resume:
+        raise GhostReaderError(
+            f"Session `{session_id}` already exists. Use --resume to reuse it."
+        )
+
+    ensure_session_structure(path)
+    if existed:
+        manifest = load_yaml_file(path / "manifest.yaml")
+    else:
+        manifest = {
+            "schema_version": SCHEMA_VERSIONS["session_manifest"],
+            "session_id": session_id,
+            "current_round": 1,
+            "story_unit": args.story_unit,
+            "personas": personas,
+            "story_audience_contract": load_yaml_file(Path(args.contract))
+            if args.contract
+            else {},
+            "rounds": [
+                {
+                    "id": 1,
+                    "status": "reviews_pending",
+                    "created_at": now_iso(),
+                    "refinement_count": 0,
+                }
+            ],
+            "created_at": now_iso(),
+            "updated_at": now_iso(),
+        }
+        write_yaml(path / "manifest.yaml", manifest)
+        append_event(
+            home,
+            project_root,
+            "session_created",
+            session_id,
+            meta={"selected_personas": personas},
+            correlation_id=getattr(args, '_correlation_id', None),
+        )
+
+    emit_output(
+        args,
+        {
+            "session_id": session_id,
+            "session_path": str(path),
+            "personas": manifest.get("personas", personas),
+            "created": not existed,
+        }
+    )
+    return 0
+
+
+def command_session_summary(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    manifest = load_manifest(project_root, args.session)
+    review_items = {}
+    for review in load_reviews(project_root, home, args.session):
+        items = {}
+        for item in review.get("strengths", []):
+            items[item["id"]] = compact_review_item(item)
+        for item in review.get("concerns", []):
+            items[item["id"]] = compact_review_item(item)
+        review_items[review["persona_id"]] = items
+
+    base = session_dir(project_root, args.session)
+    available_artifacts = [
+        str(path.relative_to(base))
+        for path in sorted(base.rglob("*"))
+        if path.is_file() and path.name != "events.ndjson"
+    ]
+    emit_output(
+        args,
+        {
+            "session_id": args.session,
+            "story_unit": manifest.get("story_unit"),
+            "personas": manifest.get("personas", []),
+            "review_items": review_items,
+            "user_notes": feedback_summary(project_root, args.session)["user_notes"],
+            "available_artifacts": available_artifacts,
+        },
+    )
+    return 0
+
+
+def command_artifact_write(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    ensure_project(project_root, home)
+    manifest = load_manifest(project_root, args.session)
+    path = session_dir(project_root, args.session)
+    ensure_session_structure(path)
+    content = read_input(args)
+    validated_yaml = None
+    if args.validate:
+        if args.type not in {"review", "source-map"}:
+            raise GhostReaderError("--validate is only available for YAML artifacts.")
+        validated_yaml = load_yaml_text(content, source=f"{args.type} input")
+
+    if args.type == "review":
+        target = write_review_artifact(
+            home,
+            project_root,
+            args.session,
+            args.persona,
+            content,
+            manifest,
+            parsed_review=validated_yaml,
+            correlation_id=getattr(args, '_correlation_id', None),
+        )
+    elif args.type == "context-note":
+        target = artifact_paths(project_root, args.session)["context"] / "context-notes.md"
+        if args.append and target.exists():
+            target.write_text(
+                f"{target.read_text(encoding='utf-8').rstrip()}\n\n{content.strip()}\n",
+                encoding="utf-8",
+            )
+        else:
+            target.write_text(content, encoding="utf-8")
+        append_event(home, project_root, "context_note_written", args.session, correlation_id=getattr(args, '_correlation_id', None))
+    elif args.type == "source-map":
+        target = artifact_paths(project_root, args.session)["context"] / "source-map.yaml"
+        write_yaml(
+            target,
+            validated_yaml
+            if validated_yaml is not None
+            else load_yaml_text(content, source="source-map input"),
+        )
+        append_event(
+            home,
+            project_root,
+            "context_note_written",
+            args.session,
+            meta={"artifact": "source-map"},
+            correlation_id=getattr(args, '_correlation_id', None),
+        )
+    elif args.type == "source-text":
+        target = artifact_paths(project_root, args.session)["context"] / "source-text.md"
+        target.write_text(content, encoding="utf-8")
+        append_event(
+            home,
+            project_root,
+            "context_note_written",
+            args.session,
+            meta={"artifact": "source-text"},
+            correlation_id=getattr(args, '_correlation_id', None),
+        )
+    else:
+        raise GhostReaderError(f"Unsupported artifact type `{args.type}`.")
+
+    emit_output(args, {"written": True, "path": str(target)})
+    return 0
+
+
+def write_review_artifact(
+    home: Path,
+    project_root: Path,
+    session_id: str,
+    persona_id: str | None,
+    content: str,
+    manifest: dict,
+    parsed_review: dict | None = None,
+    correlation_id: str | None = None,
+) -> Path:
+    if not persona_id:
+        raise GhostReaderError("--persona is required when --type review.")
+    review = parsed_review if parsed_review is not None else load_yaml_text(
+        content, source="review input"
+    )
+    validate_review(review, session_id, persona_id)
+    read_persona(home, persona_id)
+    target = (
+        artifact_paths(project_root, session_id)["reviews"] / f"{persona_id}.review.yaml"
+    )
+    write_yaml(target, review)
+    if persona_id not in manifest.get("personas", []):
+        manifest.setdefault("personas", []).append(persona_id)
+    save_manifest(project_root, session_id, manifest)
+    append_event(
+        home,
+        project_root,
+        "review_completed",
+        session_id,
+        meta={"persona_id": persona_id},
+        correlation_id=correlation_id,
+    )
+    return target
+
+
+def command_feedback_add(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    feedback = load_yaml_text(read_input(args))
+    target = record_feedback(
+        project_root, home, args.session, feedback, surface="cli"
+    )
+    emit_output(args, {"feedback_recorded": True, "path": str(target)})
+    return 0
+
+
+def command_feedback_summary(args: argparse.Namespace) -> int:
+    emit_output(args, feedback_summary(find_project_root(), args.session))
+    return 0
+
+
+def command_prompt_revision(args: argparse.Namespace) -> int:
+    paths = generate_revision_prompt(
+        find_project_root(),
+        ghost_reader_home(),
+        args.session,
+        args.goal,
+        args.preserve,
+    )
+    emit_output(args, {"revision_prompt_generated": True, **paths})
+    return 0
+
+
+def command_render(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    if args.format == "list":
+        templates = sorted(
+            p.name for p in (home / "templates").glob("*.html")
+        )
+        emit_output(args, {"templates": templates, "default": "report"})
+        return 0
+    paths = render_report(
+        find_project_root(),
+        home,
+        args.session,
+        args.command_prefix,
+        args.format,
+        args.export_config,
+    )
+    emit_output(
+        args,
+        {
+            "rendered": True,
+            **paths,
+            "next_step": f"serve --session {args.session}",
+        },
+    )
+    return 0
+
+
+def command_verify(args: argparse.Namespace) -> int:
+    result = verify_session(find_project_root(), ghost_reader_home(), args.session)
+    if result.get("status") == "review_ready_feedback_pending":
+        result["next_step"] = f"serve --session {args.session}"
+    emit_output(args, result)
+    return 0
+
+
+def command_telemetry_append(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = None
+    try:
+        project_root = find_project_root()
+        if args.session:
+            load_manifest(project_root, args.session)
+    except GhostReaderError:
+        if args.session:
+            raise
+    event = append_event(
+        home,
+        project_root,
+        args.event,
+        args.session,
+        args.surface,
+        parse_meta(args.meta),
+    )
+    emit_output(args, {"telemetry_appended": True, "event_id": event["event_id"]})
+    return 0
+
+
+def parse_meta(values: list[str] | None) -> dict[str, str]:
+    meta = {}
+    for value in values or []:
+        if "=" not in value:
+            raise GhostReaderError(
+                f"Telemetry meta `{value}` must use key=value format."
+            )
+        key, item = value.split("=", 1)
+        meta[key] = item
+    return meta
+
+
+def command_telemetry_status(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    ensure_home(home)
+    emit_output(args, telemetry_status(home))
+    return 0
+
+
+def command_dialogue_append(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    has_question_answer = args.question is not None or args.answer is not None
+    has_blob_input = args.content is not None or args.from_file is not None
+    if has_question_answer and has_blob_input:
+        raise GhostReaderError(
+            "--question/--answer cannot be combined with --content or --from."
+        )
+    if (args.question is None) != (args.answer is None):
+        raise GhostReaderError("--question and --answer must be used together.")
+    turn_text = (
+        f"**User:** {args.question}\n**Persona:** {args.answer}"
+        if has_question_answer
+        else read_input(args)
+    )
+    result = dialogue_append(
+        project_root,
+        home,
+        args.session,
+        args.persona,
+        args.item,
+        turn_text,
+    )
+    emit_output(args, result)
+    return 0
+
+
+def command_dialogue_context(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    emit_output(
+        args,
+        dialogue_context(project_root, home, args.session, args.persona, args.item),
+    )
+    return 0
+
+
+def command_history_summary(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = None
+    try:
+        project_root = find_project_root()
+    except GhostReaderError:
+        pass
+    emit_output(args, history_summary(home, project_root))
+    return 0
+
+
+def history_summary(home: Path, project_root: Path | None) -> dict:
+    all_manifests: list[dict] = []
+
+    if project_root:
+        sessions_dir = project_root / ".ghostreader" / "sessions"
+        if sessions_dir.exists():
+            for manifest_path in sorted(sessions_dir.glob("*/manifest.yaml")):
+                try:
+                    manifest = load_yaml_file(manifest_path)
+                    if "session_id" in manifest:
+                        all_manifests.append(manifest)
+                except Exception:
+                    pass
+
+    session_count = len(all_manifests)
+    persona_counts: dict[str, int] = {}
+    for manifest in all_manifests:
+        for persona_id in manifest.get("personas", []):
+            persona_counts[persona_id] = persona_counts.get(persona_id, 0) + 1
+    most_selected = sorted(
+        persona_counts.items(), key=lambda item: item[1], reverse=True
+    )[:5]
+
+    return {
+        "recent_usage": {
+            "sessions": session_count,
+            "most_selected_personas": [
+                {"persona_id": pid, "session_count": count}
+                for pid, count in most_selected
+            ],
+            "frequently_included_concern_types": [],
+            "common_story_contracts": [],
+        }
+    }
+
+
+def command_round_init(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    emit_output(
+        args,
+        round_init(
+            project_root,
+            home,
+            args.session,
+            story_unit=getattr(args, "story_unit", None),
+            source_file=getattr(args, "source", None),
+        )
+    )
+    return 0
+
+
+def command_round_status(args: argparse.Namespace) -> int:
+    project_root = find_project_root()
+    emit_output(args, round_status(project_root, args.session))
+    return 0
+
+
+def command_refine_snapshot(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    emit_output(args, refine_snapshot(project_root, home, args.session))
+    return 0
+
+
+def command_serve(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    project_root = find_project_root()
+    if not getattr(args, "session", None):
+        raise GhostReaderError("--session is required.")
+    load_manifest(project_root, args.session)
+    render_flag = None if getattr(args, "render", None) is None else args.render
+    if args.detach:
+        return _serve_detached(args, project_root, home, render_flag)
+    serve_report(
+        project_root,
+        home,
+        args.session,
+        port=args.port,
+        timeout=args.timeout,
+        render=render_flag,
+        command_prefix=getattr(args, "command_prefix", "ghost-reader"),
+        template_name=getattr(args, "format", "report"),
+    )
+    return 0
+
+
+def _serve_detached(
+    args: argparse.Namespace,
+    project_root: Path,
+    home: Path,
+    render_flag: bool | None,
+) -> int:
+    if sys.platform == "win32":
+        raise GhostReaderError(
+            "ghost-reader serve --detach is not supported on Windows. "
+            "Use `ghost-reader serve --session <id>` and run it in a separate terminal."
+        )
+
+    state_dir = project_dir(project_root)
+    state_dir.mkdir(parents=True, exist_ok=True)
+    pid_path = state_dir / "server.pid"
+    log_path = state_dir / "server.log"
+
+    pidfile_fd = os.open(str(pid_path), os.O_CREAT | os.O_RDWR, 0o644)
+    try:
+        fcntl.flock(pidfile_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except BlockingIOError:
+        os.close(pidfile_fd)
+        raise GhostReaderError(
+            "Detached server already running. "
+            "Run `ghost-reader serve stop` first."
+        )
+
+    r_fd, w_fd = os.pipe()
+    try:
+        pid = os.fork()
+    except OSError:
+        os.close(r_fd)
+        os.close(w_fd)
+        os.close(pidfile_fd)
+        raise
+    if pid == 0:
+        os.close(r_fd)
+        try:
+            os.setsid()
+            _redirect_daemon_io(log_path)
+            serve_report(
+                project_root,
+                home,
+                args.session,
+                port=args.port,
+                timeout=args.timeout,
+                render=render_flag,
+                command_prefix=getattr(args, "command_prefix", "ghost-reader"),
+                template_name=getattr(args, "format", "report"),
+                pipe_wfd=w_fd,
+            )
+        except BaseException:
+            traceback.print_exc()
+            os.write(w_fd, b"error\n")
+            os.close(w_fd)
+            os._exit(1)
+        os.close(w_fd)
+        os._exit(0)
+    else:
+        try:
+            os.close(w_fd)
+            data = os.read(r_fd, 1024).decode().strip()
+            os.close(r_fd)
+            if not data.startswith("ok:"):
+                raise GhostReaderError(
+                    "Detached server failed to start. Check the server log for details."
+                )
+            actual_port = data[3:]
+            pid_path.write_text(f"{pid}\n", encoding="utf-8")
+            emit_output(
+                args,
+                {
+                    "detached": True,
+                    "pid": pid,
+                    "pid_file": str(pid_path),
+                    "log_file": str(log_path),
+                    "url": f"http://localhost:{actual_port}",
+                }
+            )
+            sys.stdout.flush()
+            return 0
+        finally:
+            os.close(pidfile_fd)
+
+
+def command_serve_stop(args: argparse.Namespace) -> int:
+    if getattr(args, "session", None):
+        raise GhostReaderError(
+            "`serve stop` is project-wide, not session-scoped. "
+            "Use `ghost-reader serve stop` without --session."
+        )
+    project_root = find_project_root()
+    pid_path = project_dir(project_root) / "server.pid"
+    pid = _read_pid(pid_path)
+    if not pid:
+        raise GhostReaderError("No detached Ghost Reader server PID file found.")
+    if not _process_running(pid):
+        pid_path.unlink(missing_ok=True)
+        emit_output(
+            args,
+            {"stopped": False, "pid": pid, "stale_pid_file_removed": True},
+        )
+        return 0
+
+    os.kill(pid, signal.SIGTERM)
+    stopped = False
+    for _ in range(30):
+        if not _process_running(pid):
+            stopped = True
+            break
+        time.sleep(0.1)
+    if not stopped:
+        raise GhostReaderError(f"Server process {pid} did not stop after SIGTERM.")
+
+    pid_path.unlink(missing_ok=True)
+    emit_output(args, {"stopped": True, "pid": pid})
+    return 0
+
+
+def _read_pid(path: Path) -> int | None:
+    try:
+        return int(path.read_text(encoding="utf-8").strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def _process_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _redirect_daemon_io(log_path: Path) -> None:
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    log = log_path.open("w", encoding="utf-8")
+    devnull = open(os.devnull, "r", encoding="utf-8")
+    os.dup2(devnull.fileno(), sys.stdin.fileno())
+    os.dup2(log.fileno(), sys.stdout.fileno())
+    os.dup2(log.fileno(), sys.stderr.fileno())
+    devnull.close()
+    log.close()
+
+
+def command_sync(args: argparse.Namespace) -> int:
+    home = ghost_reader_home()
+    ensure_home(home)
+    project_root = None
+    try:
+        project_root = find_project_root()
+    except GhostReaderError:
+        pass
+    append_event(
+        home,
+        project_root,
+        "sync_attempted",
+        args.session,
+        meta={"mode": "local_bundle"},
+        correlation_id=getattr(args, '_correlation_id', None),
+    )
+    emit_output(args, create_sync_bundle(home))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ghost-reader")
+    add_output_format_option(parser, default="yaml")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("init").set_defaults(func=command_init)
+
+    help_parser = subparsers.add_parser("help")
+    help_parser.set_defaults(func=command_help)
+
+    update_parser = subparsers.add_parser("update")
+    update_subparsers = update_parser.add_subparsers(
+        dest="update_command", required=True
+    )
+    update_check = update_subparsers.add_parser("check")
+    add_output_format_option(update_check)
+    update_check.set_defaults(func=command_update_check)
+
+    session_parser = subparsers.add_parser("session")
+    session_subparsers = session_parser.add_subparsers(
+        dest="session_command", required=True
+    )
+    session_create = session_subparsers.add_parser("create")
+    session_create.add_argument("--id")
+    session_create.add_argument("--story-unit")
+    session_create.add_argument(
+        "--personas", help="Comma or space separated persona IDs."
+    )
+    session_create.add_argument(
+        "--contract", help="Optional story/audience contract YAML."
+    )
+    session_create.add_argument("--resume", action="store_true")
+    session_create.set_defaults(func=command_session_create)
+    session_summary = session_subparsers.add_parser("summary")
+    session_summary.add_argument("--session", required=True)
+    add_output_format_option(session_summary)
+    session_summary.set_defaults(func=command_session_summary)
+
+    artifact_parser = subparsers.add_parser("artifact")
+    artifact_subparsers = artifact_parser.add_subparsers(
+        dest="artifact_command", required=True
+    )
+    artifact_write = artifact_subparsers.add_parser("write")
+    artifact_write.add_argument("--session", required=True)
+    artifact_write.add_argument(
+        "--type",
+        required=True,
+        choices=["review", "context-note", "source-map", "source-text"],
+    )
+    artifact_write.add_argument("--persona")
+    artifact_write.add_argument("--from", dest="from_file")
+    artifact_write.add_argument("--content")
+    artifact_write.add_argument("--append", action="store_true")
+    artifact_write.add_argument(
+        "--validate",
+        action="store_true",
+        help="Validate YAML syntax before writing review or source-map artifacts.",
+    )
+    artifact_write.set_defaults(func=command_artifact_write)
+
+    feedback_parser = subparsers.add_parser("feedback")
+    feedback_subparsers = feedback_parser.add_subparsers(
+        dest="feedback_command", required=True
+    )
+    feedback_add = feedback_subparsers.add_parser("add")
+    feedback_add.add_argument("--session", required=True)
+    feedback_add.add_argument("--from", dest="from_file", required=True)
+    feedback_add.set_defaults(func=command_feedback_add)
+    feedback_summary_parser = feedback_subparsers.add_parser("summary")
+    feedback_summary_parser.add_argument("--session", required=True)
+    add_output_format_option(feedback_summary_parser)
+    feedback_summary_parser.set_defaults(func=command_feedback_summary)
+
+    prompt_parser = subparsers.add_parser("prompt")
+    prompt_subparsers = prompt_parser.add_subparsers(
+        dest="prompt_command", required=True
+    )
+    prompt_revision = prompt_subparsers.add_parser("revision")
+    prompt_revision.add_argument("--session", required=True)
+    prompt_revision.add_argument("--goal")
+    prompt_revision.add_argument("--preserve", action="append")
+    prompt_revision.set_defaults(func=command_prompt_revision)
+
+    dialogue_parser = subparsers.add_parser("dialogue")
+    dialogue_subparsers = dialogue_parser.add_subparsers(
+        dest="dialogue_command", required=True
+    )
+    dialogue_append_parser = dialogue_subparsers.add_parser("append")
+    dialogue_append_parser.add_argument("--session", required=True)
+    dialogue_append_parser.add_argument("--persona", required=True)
+    dialogue_append_parser.add_argument(
+        "--item",
+        required=True,
+        help="Review concern ID (e.g. c1, c3) or strength ID (e.g. s1, s2) from the persona review.",
+    )
+    dialogue_append_parser.add_argument("--from", dest="from_file")
+    dialogue_append_parser.add_argument("--content")
+    dialogue_append_parser.add_argument("--question")
+    dialogue_append_parser.add_argument("--answer")
+    dialogue_append_parser.set_defaults(func=command_dialogue_append)
+    dialogue_context_parser = dialogue_subparsers.add_parser("context")
+    dialogue_context_parser.add_argument("--session", required=True)
+    dialogue_context_parser.add_argument("--persona", required=True)
+    dialogue_context_parser.add_argument(
+        "--item",
+        required=True,
+        help="Review concern ID (e.g. c1, c3) or strength ID (e.g. s1, s2) from the persona review.",
+    )
+    dialogue_context_parser.set_defaults(func=command_dialogue_context)
+
+    history_parser = subparsers.add_parser("history")
+    history_subparsers = history_parser.add_subparsers(
+        dest="history_command", required=True
+    )
+    history_summary_parser = history_subparsers.add_parser("summary")
+    add_output_format_option(history_summary_parser)
+    history_summary_parser.set_defaults(func=command_history_summary)
+
+    round_parser = subparsers.add_parser("round")
+    round_subparsers = round_parser.add_subparsers(
+        dest="round_command", required=True
+    )
+    round_init_parser = round_subparsers.add_parser("init")
+    round_init_parser.add_argument("--session", required=True)
+    round_init_parser.add_argument("--story-unit")
+    round_init_parser.add_argument("--source")
+    round_init_parser.set_defaults(func=command_round_init)
+    round_status_parser = round_subparsers.add_parser("status")
+    round_status_parser.add_argument("--session", required=True)
+    round_status_parser.set_defaults(func=command_round_status)
+
+    refine_parser = subparsers.add_parser("refine")
+    refine_subparsers = refine_parser.add_subparsers(
+        dest="refine_command", required=True
+    )
+    refine_snapshot_parser = refine_subparsers.add_parser("snapshot")
+    refine_snapshot_parser.add_argument("--session", required=True)
+    refine_snapshot_parser.set_defaults(func=command_refine_snapshot)
+
+    render_parser = subparsers.add_parser("render")
+    render_parser.add_argument("--session", required=True)
+    render_parser.add_argument(
+        "--command-prefix",
+        default="ghost-reader",
+        help="Command prefix embedded in the local report's continuation block.",
+    )
+    render_parser.add_argument(
+        "--format",
+        default="report",
+        help="Template name to render (default: report). Use 'list' to see available templates.",
+    )
+    render_parser.add_argument(
+        "--export-config",
+        action="store_true",
+        default=False,
+        help="Also write report/config.yaml alongside payload.json.",
+    )
+    render_parser.set_defaults(func=command_render)
+
+    verify_parser = subparsers.add_parser("verify")
+    verify_parser.add_argument("--session", required=True)
+    verify_parser.set_defaults(func=command_verify)
+
+    telemetry_parser = subparsers.add_parser("telemetry")
+    telemetry_subparsers = telemetry_parser.add_subparsers(
+        dest="telemetry_command", required=True
+    )
+    telemetry_append = telemetry_subparsers.add_parser("append")
+    telemetry_append.add_argument("--event", required=True)
+    telemetry_append.add_argument("--session")
+    telemetry_append.add_argument("--surface", default="cli")
+    telemetry_append.add_argument("--meta", action="append")
+    telemetry_append.set_defaults(func=command_telemetry_append)
+    telemetry_status_parser = telemetry_subparsers.add_parser("status")
+    add_output_format_option(telemetry_status_parser)
+    telemetry_status_parser.set_defaults(func=command_telemetry_status)
+
+    sync_parser = subparsers.add_parser("sync")
+    sync_parser.add_argument("--session")
+    sync_parser.set_defaults(func=command_sync)
+
+    persona_parser = subparsers.add_parser("persona")
+    persona_subparsers = persona_parser.add_subparsers(dest="persona_command", required=True)
+    persona_list = persona_subparsers.add_parser("list")
+    persona_list.set_defaults(func=command_persona_list)
+    persona_show = persona_subparsers.add_parser("show")
+    persona_show.add_argument("persona_id", help="Persona ID (e.g., mara, dex, pip)")
+    persona_show.set_defaults(func=command_persona_show)
+
+    serve_parser = subparsers.add_parser("serve")
+    serve_subparsers = serve_parser.add_subparsers(dest="serve_command")
+    serve_stop = serve_subparsers.add_parser("stop")
+    serve_stop.set_defaults(func=command_serve_stop)
+    serve_parser.add_argument("--session")
+    serve_parser.add_argument("--port", type=int, default=8765)
+    serve_parser.add_argument("--timeout", type=int, default=0)
+    serve_parser.add_argument("--detach", action="store_true")
+    serve_parser.add_argument("--render", dest="render", action="store_true", default=None)
+    serve_parser.add_argument("--no-render", dest="render", action="store_false", default=None)
+    serve_parser.add_argument(
+        "--command-prefix",
+        default="ghost-reader",
+        help="Command prefix for the rendered report's continuation block.",
+    )
+    serve_parser.add_argument(
+        "--format",
+        default="report",
+        help="Template name to render (default: report).",
+    )
+    serve_parser.set_defaults(func=command_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    correlation_id = str(uuid.uuid4())
+    args._correlation_id = correlation_id
+    try:
+        return args.func(args)
+    except GhostReaderError as exc:
+        try:
+            home = ghost_reader_home()
+        except Exception:
+            home = Path.home() / ".ghostreader"
+        try:
+            project_root = find_project_root()
+            ensure_home(home)
+            append_event(
+                home,
+                project_root,
+                "error_occurred",
+                meta={
+                    "error_type": type(exc).__name__,
+                    "error_message": str(exc),
+                },
+                correlation_id=correlation_id,
+            )
+        except Exception:
+            pass
+        sys.stderr.write(f"ghost-reader: error: {exc}\n")
+        return 2
+
+
+def entrypoint() -> None:
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    entrypoint()