rollout-cli 0.2.1__py3-none-any.whl

rollout/__init__.py

@@ -0,0 +1,13 @@
+"""rollout-cli — agent-first CLI for an AgentCulture mesh agent."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("rollout-cli")
+except PackageNotFoundError:  # pragma: no cover - editable install without metadata
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

rollout/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for ``python -m rollout``."""
+
+from __future__ import annotations
+
+import sys
+
+from rollout.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rollout/cli/__init__.py

@@ -0,0 +1,136 @@
+"""Unified CLI entry point for rollout-cli.
+
+The agent-first global verbs (``whoami``, ``learn``, ``explain``, ``overview``,
+``doctor``) are registered here under :mod:`rollout.cli._commands`,
+alongside the ``cli`` noun group. Future noun groups register via their own
+``register()`` functions following the same pattern.
+
+Error propagation contract
+--------------------------
+Every handler raises :class:`rollout.cli._errors.CliError` on
+failure; ``main()`` catches it via :func:`_dispatch` and routes through
+:mod:`rollout.cli._output`. Unknown exceptions are wrapped into a
+``CliError`` so no Python traceback leaks to stderr.
+
+Argparse errors (unknown verb, missing arg) also route through the structured
+format — ``_CliArgumentParser`` overrides ``.error()`` and the subparsers are
+built with ``parser_class=_CliArgumentParser``. Whether errors render as text or
+JSON depends on whether ``--json`` appears in the raw argv (:func:`main` sets
+``_json_hint`` before ``parse_args``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from rollout import __version__
+from rollout.cli._errors import EXIT_USER_ERROR, CliError
+from rollout.cli._output import emit_error
+
+_ISSUES_URL = "https://github.com/agentculture/rollout-cli/issues"
+
+
+class _CliArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that routes errors through :func:`emit_error`.
+
+    Argparse's default error handler writes ``prog: error: <msg>`` to stderr
+    and exits 2, skipping the CliError plumbing (and the ``hint:`` line agents
+    look for). This subclass emits the structured format and exits with
+    :attr:`EXIT_USER_ERROR`.
+
+    JSON mode: parse-time errors happen before ``args.json`` exists, so we rely
+    on a class-level ``_json_hint`` that :func:`main` pre-populates by scanning
+    raw argv for ``--json``. Shared across all subparser instances.
+    """
+
+    _json_hint: bool = False
+
+    def error(self, message: str) -> None:  # type: ignore[override]
+        err = CliError(
+            code=EXIT_USER_ERROR,
+            message=message,
+            remediation=f"run '{self.prog} --help' to see valid arguments",
+        )
+        emit_error(err, json_mode=type(self)._json_hint)
+        raise SystemExit(err.code)
+
+
+def _argv_has_json(argv: list[str] | None) -> bool:
+    tokens = argv if argv is not None else sys.argv[1:]
+    return any(t == "--json" or t.startswith("--json=") for t in tokens)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    from rollout.cli._commands import cli as _cli_group
+    from rollout.cli._commands import doctor as _doctor_cmd
+    from rollout.cli._commands import explain as _explain_cmd
+    from rollout.cli._commands import learn as _learn_cmd
+    from rollout.cli._commands import overview as _overview_cmd
+    from rollout.cli._commands import whoami as _whoami_cmd
+
+    parser = _CliArgumentParser(
+        prog="rollout-cli",
+        description="rollout-cli — a clonable template for AgentCulture mesh agents.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    # parser_class propagates to every subparser so their .error() routes
+    # through _CliArgumentParser too.
+    sub = parser.add_subparsers(dest="command", parser_class=_CliArgumentParser)
+
+    _whoami_cmd.register(sub)
+    _learn_cmd.register(sub)
+    _explain_cmd.register(sub)
+    _overview_cmd.register(sub)
+    _doctor_cmd.register(sub)
+    _cli_group.register(sub)
+    # Register your own noun groups here:
+    #   from rollout.cli._commands import my_noun as _my_noun_group
+    #   _my_noun_group.register(sub)
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> int:
+    """Invoke the registered handler and translate exceptions to exit codes.
+
+    A handler may return ``None`` (success, exit 0) or an ``int`` exit code.
+    Failures MUST raise :class:`CliError`; any other exception is wrapped into
+    one so no Python traceback leaks.
+    """
+    json_mode = bool(getattr(args, "json", False))
+    try:
+        rc = args.func(args)
+    except CliError as err:
+        emit_error(err, json_mode=json_mode)
+        return err.code
+    except Exception as err:  # noqa: BLE001 - last-resort; wrap and route cleanly
+        wrapped = CliError(
+            code=EXIT_USER_ERROR,
+            message=f"unexpected: {err.__class__.__name__}: {err}",
+            remediation=f"file a bug at {_ISSUES_URL}",
+        )
+        emit_error(wrapped, json_mode=json_mode)
+        return wrapped.code
+    return rc if rc is not None else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Pre-parse peek so argparse-level errors honour --json.
+    _CliArgumentParser._json_hint = _argv_has_json(argv)
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    return _dispatch(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rollout/cli/_commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules. Each exposes a ``register(sub)`` function."""

rollout/cli/_commands/cli.py

@@ -0,0 +1,43 @@
+"""``rollout-cli cli`` — noun grouping CLI-surface introspection.
+
+Exists to satisfy the agent-first rubric's ``overview_cli_noun_exists`` check:
+any noun with action-verbs must also expose ``overview``. There are no
+action-verbs under ``cli`` today, but ``cli overview`` describes the CLI surface
+(distinct from the global ``overview``, which describes the agent).
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from rollout.cli._commands.overview import cli_sections, emit_overview
+
+
+def cmd_cli_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "rollout-cli cli",
+        cli_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    # `rollout-cli cli` with no sub-verb prints the noun's overview.
+    return cmd_cli_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "cli",
+        help="CLI-surface introspection (see 'rollout-cli cli overview').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=_no_verb, json=False)
+    # `p` is a _CliArgumentParser (the top-level subparsers were built with that
+    # parser_class); propagate it so `cli overview` parse errors route through
+    # the structured error contract instead of argparse's default stderr/exit 2.
+    noun_sub = p.add_subparsers(dest="cli_command", parser_class=type(p))
+    ov = noun_sub.add_parser("overview", help="Describe the rollout-cli CLI surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_cli_overview)

rollout/cli/_commands/doctor.py

@@ -0,0 +1,122 @@
+"""``rollout-cli doctor`` — check the agent-identity invariants.
+
+Mirrors the two invariants ``steward doctor`` verifies for a mesh agent:
+
+* **prompt-file-present** — the repo declares an agent in ``culture.yaml`` and
+  has the matching prompt file on disk;
+* **backend-consistency** — the declared ``backend`` matches the prompt file
+  (``claude`` → ``CLAUDE.md``, ``acp`` → ``AGENTS.md``, ``gemini`` → ``GEMINI.md``).
+
+Plus a **skills-present** check (the vendored ``.claude/skills/`` kit). Read-only.
+
+Reports the rubric-shaped contract
+``{healthy, checks: [{id, passed, severity, message, remediation}]}`` so the
+agent-first rubric's bundle 7 passes. When run from a wheel install (no
+``culture.yaml`` alongside the package), it reports a single info check and
+exits 0 — there is nothing to diagnose.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from rollout.cli._commands.whoami import find_culture_yaml, read_agent_fields
+from rollout.cli._output import emit_result
+
+# backend → required prompt file (the backend-consistency mapping).
+_PROMPT_FILE = {
+    "claude": "CLAUDE.md",
+    "acp": "AGENTS.md",
+    "gemini": "GEMINI.md",
+}
+
+
+def _diagnose() -> dict[str, object]:
+    cfg = find_culture_yaml()
+    if cfg is None:
+        check = {
+            "id": "source_checkout",
+            "passed": True,
+            "severity": "info",
+            "message": "no culture.yaml found alongside the package; identity checks skipped",
+            "remediation": "",
+        }
+        return {"healthy": True, "checks": [check]}
+
+    root = cfg.parent
+    fields = read_agent_fields()
+    backend = fields["backend"]
+    checks: list[dict[str, object]] = []
+
+    # 1. backend-consistency: the prompt file for the declared backend exists.
+    expected = _PROMPT_FILE.get(backend)
+    if expected is None:
+        checks.append(
+            {
+                "id": "backend_consistency",
+                "passed": False,
+                "severity": "error",
+                "message": f"unknown backend '{backend}' in culture.yaml",
+                "remediation": f"set backend to one of: {', '.join(sorted(_PROMPT_FILE))}",
+            }
+        )
+    else:
+        present = (root / expected).is_file()
+        checks.append(
+            {
+                "id": "prompt_file_present",
+                "passed": present,
+                "severity": "error",
+                "message": (
+                    f"backend '{backend}' requires {expected} — "
+                    + ("present" if present else "missing")
+                ),
+                "remediation": "" if present else f"create {expected} at the repo root",
+            }
+        )
+
+    # 2. skills-present: the vendored skill kit is on disk.
+    skills_dir = root / ".claude" / "skills"
+    has_skills = skills_dir.is_dir() and any(skills_dir.iterdir())
+    checks.append(
+        {
+            "id": "skills_present",
+            "passed": has_skills,
+            "severity": "warning",
+            "message": (
+                ".claude/skills/ vendored" if has_skills else ".claude/skills/ missing or empty"
+            ),
+            "remediation": (
+                "" if has_skills else "vendor the skill kit (see docs/skill-sources.md)"
+            ),
+        }
+    )
+
+    healthy = all(c["passed"] for c in checks)
+    return {"healthy": healthy, "checks": checks}
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    report = _diagnose()
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(report, json_mode=True)
+    else:
+        status = "healthy" if report["healthy"] else "unhealthy"
+        lines = [f"rollout-cli doctor: {status}", ""]
+        for check in report["checks"]:
+            mark = "ok" if check["passed"] else "FAIL"
+            lines.append(f"[{mark}] {check['id']}: {check['message']}")
+            if not check["passed"] and check["remediation"]:
+                lines.append(f"  hint: {check['remediation']}")
+        emit_result("\n".join(lines), json_mode=False)
+    return 0 if report["healthy"] else 1
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "doctor",
+        help="Check the agent-identity invariants (prompt-file-present, backend-consistency).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_doctor)

rollout/cli/_commands/explain.py

@@ -0,0 +1,38 @@
+"""``rollout-cli explain <path>...`` — global markdown catalog lookup (stable-contract).
+
+``explain`` is global (not nested under a noun). It takes zero or more path
+tokens and resolves them via the catalog in :mod:`rollout.explain`.
+Unknown paths raise :class:`CliError` with a remediation hint.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from rollout.cli._output import emit_result
+from rollout.explain import resolve
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    path = tuple(args.path) if args.path else ()
+    markdown = resolve(path)
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result({"path": list(path), "markdown": markdown}, json_mode=True)
+    else:
+        emit_result(markdown, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "explain",
+        help="Print markdown docs for a noun/verb path. Supports --json.",
+    )
+    p.add_argument(
+        "path",
+        nargs="*",
+        help="Command path tokens; empty = root (same as 'rollout-cli').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

rollout/cli/_commands/learn.py

@@ -0,0 +1,88 @@
+"""``rollout-cli learn`` — the learnability affordance.
+
+Prints a structured self-teaching prompt. Must satisfy the agent-first rubric:
+>=200 chars and mention purpose, command map, exit codes, --json, and explain.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from rollout import __version__
+from rollout.cli._output import emit_result
+
+_TEXT = """\
+rollout-cli — a clonable template for AgentCulture mesh agents.
+
+Purpose
+-------
+Scaffold for a new Culture mesh agent: an agent-first CLI (cited from the teken
+`python-cli` reference), an identity (culture.yaml + CLAUDE.md), the canonical
+guildmaster skill kit under .claude/skills/, and a deploy/CI baseline. Clone it,
+rename the package, and edit culture.yaml to mint a new agent.
+
+Commands
+--------
+  rollout-cli whoami             Identity from culture.yaml.
+  rollout-cli learn              This self-teaching prompt.
+  rollout-cli explain <path>...  Markdown docs for any noun/verb path.
+  rollout-cli overview           Descriptive snapshot of the agent.
+  rollout-cli doctor             Check the agent-identity invariants.
+  rollout-cli cli overview       Describe the CLI surface itself.
+
+Machine-readable output
+-----------------------
+Every command supports --json. Errors in JSON mode emit
+{"code", "message", "remediation"} to stderr. Stdout and stderr never mix.
+
+Exit-code policy
+----------------
+  0 success
+  1 user-input error (bad flag, bad path, missing arg)
+  2 environment / setup error
+  3+ reserved
+
+More detail
+-----------
+  rollout-cli explain rollout-cli
+"""
+
+
+def _as_json_payload() -> dict[str, object]:
+    return {
+        "tool": "rollout-cli",
+        "version": __version__,
+        "purpose": "Clonable scaffold for a new AgentCulture mesh agent.",
+        "commands": [
+            {"path": ["whoami"], "summary": "Identity probe from culture.yaml."},
+            {"path": ["learn"], "summary": "Self-teaching prompt."},
+            {"path": ["explain"], "summary": "Markdown docs by path."},
+            {"path": ["overview"], "summary": "Descriptive snapshot of the agent."},
+            {"path": ["doctor"], "summary": "Check the agent-identity invariants."},
+            {"path": ["cli", "overview"], "summary": "Describe the CLI surface."},
+        ],
+        "exit_codes": {
+            "0": "success",
+            "1": "user-input error",
+            "2": "environment/setup error",
+        },
+        "json_support": True,
+        "explain_pointer": "rollout-cli explain <path>",
+    }
+
+
+def cmd_learn(args: argparse.Namespace) -> int:
+    if getattr(args, "json", False):
+        emit_result(_as_json_payload(), json_mode=True)
+    else:
+        emit_result(_TEXT, json_mode=False)
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "learn",
+        help="Print a structured self-teaching prompt for agent consumers.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_learn)

rollout/cli/_commands/overview.py

@@ -0,0 +1,112 @@
+"""``rollout-cli overview`` — read-only descriptive snapshot of the agent.
+
+Describes the agent to an agent reader: identity (from culture.yaml), the verb
+surface, and the sibling-pattern artifacts this template carries. The shared
+section/render helpers here are reused by the ``cli`` noun's ``overview`` (see
+:mod:`rollout.cli._commands.cli`).
+
+Descriptive verbs never hard-fail on a missing target path — an optional
+positional ``target`` is accepted and ignored (overview describes this agent,
+not an external target), so ``overview <bogus-path>`` still exits 0.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from rollout.cli._commands.whoami import report
+from rollout.cli._output import emit_result
+
+_ARTIFACTS = [
+    "culture.yaml + CLAUDE.md — mesh identity (suffix + backend)",
+    ".claude/skills/ — the canonical guildmaster skill kit (cite-don't-import)",
+    "docs/skill-sources.md — skill provenance ledger",
+    "pyproject.toml + .github/workflows/ — buildable, deployable package baseline",
+]
+
+_VERBS = [
+    "whoami — identity probe (nick, version, backend, model)",
+    "learn — structured self-teaching prompt",
+    "explain <path> — markdown docs for a topic",
+    "overview — this descriptive snapshot",
+    "doctor — check the agent-identity invariants",
+]
+
+
+def agent_sections() -> list[dict[str, object]]:
+    """Sections describing the agent (used by the global verb)."""
+    ident = report()
+    return [
+        {
+            "title": "Identity",
+            "items": [
+                f"nick: {ident['nick']}",
+                f"version: {ident['version']}",
+                f"backend: {ident['backend']}",
+                f"model: {ident['model']}",
+            ],
+        },
+        {"title": "Verbs", "items": list(_VERBS)},
+        {"title": "Sibling-pattern artifacts", "items": list(_ARTIFACTS)},
+    ]
+
+
+def cli_sections() -> list[dict[str, object]]:
+    """Sections describing the CLI surface itself (used by `cli overview`)."""
+    return [
+        {
+            "title": "Verbs",
+            "items": list(_VERBS) + ["cli overview — describe the CLI surface (this command)"],
+        },
+        {
+            "title": "Conventions",
+            "items": [
+                "every command supports --json",
+                "results to stdout, errors/diagnostics to stderr (never mixed)",
+                "exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved",
+            ],
+        },
+    ]
+
+
+def render_text(subject: str, sections: list[dict[str, object]]) -> str:
+    lines = [f"# {subject}", ""]
+    for section in sections:
+        lines.append(f"## {section['title']}")
+        for item in section["items"]:
+            lines.append(f"- {item}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def emit_overview(subject: str, sections: list[dict[str, object]], *, json_mode: bool) -> None:
+    if json_mode:
+        emit_result({"subject": subject, "sections": sections}, json_mode=True)
+    else:
+        emit_result(render_text(subject, sections), json_mode=False)
+
+
+def cmd_overview(args: argparse.Namespace) -> int:
+    # `target` is accepted for rubric compatibility (descriptive verbs must not
+    # hard-fail on a missing path) but overview describes this agent itself.
+    emit_overview(
+        "rollout-cli",
+        agent_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "overview",
+        help="Read-only descriptive snapshot of the agent (identity, verbs, artifacts).",
+    )
+    p.add_argument(
+        "target",
+        nargs="?",
+        help="Ignored — overview always describes this agent itself. Accepted so a "
+        "stray path argument never hard-fails.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_overview)

rollout/cli/_commands/whoami.py

@@ -0,0 +1,106 @@
+"""``rollout-cli whoami`` — the smallest identity probe.
+
+Reports the agent's identity as declared in ``culture.yaml``: its nick
+(``suffix``), the backend it runs on, and the served model (if any) — plus the
+package version. Read-only; touches nothing but its own ``culture.yaml``.
+
+When you clone this template, rename the package and update ``culture.yaml`` —
+``whoami`` then reflects your new agent's identity with no code change.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from rollout import __version__
+from rollout.cli._output import emit_result
+
+_FALLBACK_NICK = "rollout-cli"
+
+
+def find_culture_yaml() -> Path | None:
+    """Locate this agent's own ``culture.yaml`` by walking up from this module.
+
+    The identity must be the agent's own, not whatever ``culture.yaml`` happens
+    to sit in the caller's current working directory. In an editable / source
+    install, walking up from ``__file__`` finds the repo root; in a wheel
+    install no ``culture.yaml`` ships alongside the package and the caller falls
+    back to the literal defaults.
+    """
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "culture.yaml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def read_agent_fields() -> dict[str, str]:
+    """Return ``suffix``/``backend``/``model`` from the first agent block.
+
+    Parsed without a YAML dependency to keep the runtime deps empty. Reads
+    top-level ``key: value`` lines within the first agent entry; anything
+    fancier than the documented shape falls back to the defaults below.
+    """
+    fields = {"nick": _FALLBACK_NICK, "backend": "unknown", "model": "unknown"}
+    cfg = find_culture_yaml()
+    if cfg is None:
+        return fields
+    try:
+        text = cfg.read_text(encoding="utf-8")
+    except OSError:
+        return fields
+    seen_agent = False
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(("- suffix:", "suffix:")):
+            if seen_agent:  # second agent block — stop at the first
+                break
+            seen_agent = True
+            fields["nick"] = _scalar(stripped, "suffix")
+        elif seen_agent and stripped.startswith("backend:"):
+            fields["backend"] = _scalar(stripped, "backend")
+        elif seen_agent and stripped.startswith("model:"):
+            fields["model"] = _scalar(stripped, "model")
+    return fields
+
+
+def _scalar(line: str, key: str) -> str:
+    """Extract the scalar after ``key:`` from a ``culture.yaml`` line."""
+    _, _, value = line.partition(f"{key}:")
+    return value.strip().strip("'\"") or "unknown"
+
+
+def report() -> dict[str, object]:
+    fields = read_agent_fields()
+    return {
+        "nick": fields["nick"],
+        "version": __version__,
+        "backend": fields["backend"],
+        "model": fields["model"],
+    }
+
+
+def cmd_whoami(args: argparse.Namespace) -> None:
+    identity = report()
+    json_mode = bool(getattr(args, "json", False))
+    if json_mode:
+        emit_result(identity, json_mode=True)
+        return
+    text = (
+        f"nick: {identity['nick']}\n"
+        f"version: {identity['version']}\n"
+        f"backend: {identity['backend']}\n"
+        f"model: {identity['model']}"
+    )
+    emit_result(text, json_mode=False)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "whoami",
+        help="Report this agent's nick, version, backend, and served model.",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_whoami)

rollout/cli/_errors.py

@@ -0,0 +1,42 @@
+"""CliError and exit-code policy (stable-contract).
+
+Every failure inside rollout-cli raises :class:`CliError`. The
+top-level ``main()`` catches it, formats via :mod:`rollout.cli._output`,
+and exits with :attr:`CliError.code`. This guarantees:
+
+* no Python traceback leaks to stderr (the agent-first error contract);
+* every error has a structured shape ``{code, message, remediation}``;
+* the exit-code policy is centralised in one place.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Exit-code policy. Documented in ``rollout-cli learn`` output.
+# 0      = success
+# 1      = user-input error (bad flag, missing required arg, unknown path)
+# 2      = environment / setup error (tool not installed, file unreadable)
+# 3+     = reserved for future categorisation
+EXIT_SUCCESS = 0
+EXIT_USER_ERROR = 1
+EXIT_ENV_ERROR = 2
+
+
+@dataclass
+class CliError(Exception):
+    """Structured error raised within the CLI; carries a remediation hint for agents."""
+
+    code: int
+    message: str
+    remediation: str = ""
+
+    def __post_init__(self) -> None:
+        super().__init__(self.message)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "remediation": self.remediation,
+        }

rollout/cli/_output.py

@@ -0,0 +1,53 @@
+"""stdout / stderr helpers with a strict split (stable-contract).
+
+Rule: **results go to stdout, diagnostics and errors go to stderr.** Agents
+parsing output can rely on this invariant. JSON mode routes structured
+payloads to the same streams — never mixes them.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+from rollout.cli._errors import CliError
+
+
+def emit_result(data: Any, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a command result to stdout (or ``stream``)."""
+    s = stream if stream is not None else sys.stdout
+    if json_mode:
+        json.dump(data, s, ensure_ascii=False)
+        s.write("\n")
+        return
+    text = data if isinstance(data, str) else str(data)
+    s.write(text)
+    if not text.endswith("\n"):
+        s.write("\n")
+
+
+def emit_error(err: CliError, *, json_mode: bool, stream: TextIO | None = None) -> None:
+    """Write a :class:`CliError` to stderr.
+
+    Text mode renders as two lines when a remediation is present::
+
+        error: <message>
+        hint: <remediation>
+
+    The ``hint:`` prefix is required by the agent-first error rubric.
+    """
+    s = stream if stream is not None else sys.stderr
+    if json_mode:
+        json.dump(err.to_dict(), s, ensure_ascii=False)
+        s.write("\n")
+        return
+    s.write(f"error: {err.message}\n")
+    if err.remediation:
+        s.write(f"hint: {err.remediation}\n")
+
+
+def emit_diagnostic(message: str, *, stream: TextIO | None = None) -> None:
+    """Write a human diagnostic (progress, summary) to stderr."""
+    s = stream if stream is not None else sys.stderr
+    s.write(message if message.endswith("\n") else message + "\n")

rollout/explain/__init__.py

@@ -0,0 +1,24 @@
+"""Explain catalog — markdown keyed by command-path tuples (stable-contract).
+
+Every noun/verb registered in the CLI should have a catalog entry.
+"""
+
+from __future__ import annotations
+
+from rollout.cli._errors import EXIT_USER_ERROR, CliError
+from rollout.explain.catalog import ENTRIES
+
+
+def resolve(path: tuple[str, ...]) -> str:
+    if path in ENTRIES:
+        return ENTRIES[path]
+    display = " ".join(path) if path else "<root>"
+    raise CliError(
+        code=EXIT_USER_ERROR,
+        message=f"no explain entry for: {display}",
+        remediation="list entries with: rollout-cli explain rollout-cli",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    return list(ENTRIES.keys())

rollout/explain/catalog.py

@@ -0,0 +1,130 @@
+"""Markdown catalog for ``rollout-cli explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
+and ``("rollout-cli",)`` both resolve to the root entry.
+
+Keep bodies self-contained: an agent reading one entry should get enough
+context without chaining reads.
+"""
+
+from __future__ import annotations
+
+_ROOT = """\
+# rollout-cli
+
+A clonable template for AgentCulture mesh agents. It carries an agent-first CLI
+(cited from the teken `python-cli` reference), a mesh identity (`culture.yaml` +
+`CLAUDE.md`), the canonical guildmaster skill kit under `.claude/skills/`, and a
+buildable/deployable package baseline. Clone it, rename the package, edit
+`culture.yaml`, and you have a new agent.
+
+## Verbs
+
+- `rollout-cli whoami` — identity probe from `culture.yaml`.
+- `rollout-cli learn` — structured self-teaching prompt.
+- `rollout-cli explain <path>` — markdown docs for any noun/verb.
+- `rollout-cli overview` — descriptive snapshot of the agent.
+- `rollout-cli doctor` — check the agent-identity invariants.
+- `rollout-cli cli overview` — describe the CLI surface.
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `rollout-cli explain whoami`
+- `rollout-cli explain doctor`
+"""
+
+_WHOAMI = """\
+# rollout-cli whoami
+
+Reports the agent's identity from `culture.yaml`: nick (`suffix`), backend,
+served model, and the package version. Read-only.
+
+## Usage
+
+    rollout-cli whoami
+    rollout-cli whoami --json
+"""
+
+_LEARN = """\
+# rollout-cli learn
+
+Prints a structured self-teaching prompt covering purpose, command map,
+exit-code policy, `--json` support, and the `explain` pointer.
+
+## Usage
+
+    rollout-cli learn
+    rollout-cli learn --json
+"""
+
+_EXPLAIN = """\
+# rollout-cli explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help` (terse,
+positional), `explain` is global and addressable by path.
+
+## Usage
+
+    rollout-cli explain rollout-cli
+    rollout-cli explain whoami
+    rollout-cli explain --json <path>
+"""
+
+_OVERVIEW = """\
+# rollout-cli overview
+
+Read-only descriptive snapshot of the agent: identity (from `culture.yaml`), the
+verb surface, and the sibling-pattern artifacts the template carries. Accepts an
+ignored `target` so a stray path never hard-fails.
+
+## Usage
+
+    rollout-cli overview
+    rollout-cli overview --json
+"""
+
+_DOCTOR = """\
+# rollout-cli doctor
+
+Checks the agent-identity invariants `steward doctor` verifies:
+prompt-file-present and backend-consistency (`claude` → `CLAUDE.md`), plus a
+skills-present check. Exits 1 when unhealthy.
+
+## Usage
+
+    rollout-cli doctor
+    rollout-cli doctor --json
+"""
+
+_CLI = """\
+# rollout-cli cli
+
+Noun group for CLI-surface introspection. `cli overview` describes the CLI
+itself (distinct from the global `overview`, which describes the agent).
+
+## Usage
+
+    rollout-cli cli overview
+    rollout-cli cli overview --json
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("rollout-cli",): _ROOT,
+    ("rollout",): _ROOT,
+    ("whoami",): _WHOAMI,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+    ("overview",): _OVERVIEW,
+    ("doctor",): _DOCTOR,
+    ("cli",): _CLI,
+    ("cli", "overview"): _CLI,
+}

rollout_cli-0.2.1.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: rollout-cli
+Version: 0.2.1
+Summary: Cross-repo propagation workflow built on refactor-cli — apply a transformation across many repos at once.
+Project-URL: Homepage, https://github.com/agentculture/rollout-cli
+Project-URL: Issues, https://github.com/agentculture/rollout-cli/issues
+Author: Ori Nachum
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# rollout-cli
+
+Cross-repo propagation workflow built on refactor-cli — apply a transformation across many repos at once.
+
+## What you get
+
+- **An agent-first CLI** cited from [teken](https://github.com/agentculture/teken)
+  (`afi-cli`) — the runtime package has no third-party dependencies.
+- **A mesh identity** — `culture.yaml` (`suffix` + `backend`) and the matching
+  prompt file (`CLAUDE.md` for `backend: claude`).
+- **The canonical guildmaster skill kit** (11 skills) under `.claude/skills/`,
+  vendored cite-don't-import. See [`docs/skill-sources.md`](docs/skill-sources.md).
+- **A build + deploy baseline** — pytest, lint, the agent-first rubric gate, and
+  PyPI Trusted Publishing wired into GitHub Actions.
+
+## Quickstart
+
+```bash
+uv sync
+uv run pytest -n auto                 # run the test suite
+uv run rollout-cli whoami  # identity from culture.yaml
+uv run rollout-cli learn   # self-teaching prompt (add --json)
+uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
+```
+
+## CLI
+
+| Verb | What it does |
+|------|--------------|
+| `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
+| `learn` | Print a structured self-teaching prompt. |
+| `explain <path>` | Markdown docs for any noun/verb path. |
+| `overview` | Read-only descriptive snapshot of the agent. |
+| `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
+| `cli overview` | Describe the CLI surface itself. |
+
+Every command supports `--json`. Results go to stdout, errors/diagnostics to
+stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
+error, `3+` reserved.
+
+## Make it your own
+
+1. Rename the package `rollout/` and the `rollout-cli`
+   CLI/dist name throughout `pyproject.toml`, the package, `tests/`,
+   `sonar-project.properties`, and this `README.md`. The name is hard-coded in
+   ~100 places, so list every occurrence first — see the `git grep` discovery
+   command in [`CLAUDE.md`](CLAUDE.md), the authoritative rename procedure.
+2. Edit `culture.yaml` with your `suffix` and `backend`.
+3. Rewrite `CLAUDE.md` for your agent and run `/init`.
+4. Re-vendor only the skills you need from guildmaster (see
+   [`docs/skill-sources.md`](docs/skill-sources.md)).
+
+See [`CLAUDE.md`](CLAUDE.md) for the full conventions (version-bump-every-PR,
+the `cicd` PR lane, deploy setup).
+
+## License
+
+Apache 2.0 — see [`LICENSE`](LICENSE).

rollout_cli-0.2.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+rollout/__init__.py,sha256=xgecakTKsponNsY3Ev9rQsqTO_vC4hpVsmEKzLtxid8,404
+rollout/__main__.py,sha256=ga2-VOptxJwLATptP6xp4B-xu3XjxBBJzYnWrZifrKM,172
+rollout/cli/__init__.py,sha256=A8d0iLBQ2QGlTvYZufZDrDC8QkYWi1u8xqS8AAU9qLY,4947
+rollout/cli/_errors.py,sha256=nfK0tFzJH_TsQacUIpw2EwV5l8LvT_yyNcya_xzfYqM,1300
+rollout/cli/_output.py,sha256=PwyEiTqw7ztILjf765xPKY9kjS3LX_s0LLEHXZQbkUo,1706
+rollout/cli/_commands/__init__.py,sha256=DqpfVkhBo7cj6eWOpSlwx1ag0nTbrYJkV8pnPgl2gyU,70
+rollout/cli/_commands/cli.py,sha256=mEnyTvNXTWgbyacBQdBItcj-t3Z4edMwWsk4SXlVIFs,1679
+rollout/cli/_commands/doctor.py,sha256=K92sKPeaTYIEWRXhLG6aacwqiQNclausnHL4hluY-c4,4391
+rollout/cli/_commands/explain.py,sha256=DvzVJqM4VCP5dOI6uwWyTC5EXMopQMJxjeZWQTuP8S8,1220
+rollout/cli/_commands/learn.py,sha256=x8o6iFvMM4AnVL-i6CMp7jIvwgnLong6XCJFDhSMqRA,3005
+rollout/cli/_commands/overview.py,sha256=TFl2FOq25JYHKr76yaLPt93jIHjz2PokRXa5_VbSkAs,3944
+rollout/cli/_commands/whoami.py,sha256=O2obpskMqzf-UT-9dsNMfIHZ71geOC3AiR59hJieVIs,3646
+rollout/explain/__init__.py,sha256=kNBYT1v5baaJ2oOYUAXbR65kLpMEY30-FzAIJsOqU_0,700
+rollout/explain/catalog.py,sha256=o2LeEc_CSNFIBW6AlGfMUGOWmLb6ZX6WBGBl2iV_S5U,3253
+rollout_cli-0.2.1.dist-info/METADATA,sha256=vWx_i9lcyswrkhIhEDTGcMQT6iTt8B8JA7UqNI04wOw,3136
+rollout_cli-0.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+rollout_cli-0.2.1.dist-info/entry_points.txt,sha256=cpZMUZM5oPj_P_iC2sjgIE7-m3-wuwHmWAc6vGv2Pi0,45
+rollout_cli-0.2.1.dist-info/licenses/LICENSE,sha256=UTsio4-AMxNDoMcES3iMDOVbdrnTy1rQD7Be7zWjqcA,11340
+rollout_cli-0.2.1.dist-info/RECORD,,

rollout_cli-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

rollout_cli-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rollout = rollout.cli:main

rollout_cli-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Ori Nachum
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.