convertible-cli 0.1.2__py3-none-any.whl

convertible/__init__.py

@@ -0,0 +1,13 @@
+"""convertible — 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("convertible-cli")
+except PackageNotFoundError:  # pragma: no cover - editable install without metadata
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

convertible/__main__.py

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

convertible/cli/__init__.py

@@ -0,0 +1,136 @@
+"""Unified CLI entry point for convertible.
+
+The agent-first global verbs (``whoami``, ``learn``, ``explain``, ``overview``,
+``doctor``) are registered here under :mod:`convertible.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:`convertible.cli._errors.CliError` on
+failure; ``main()`` catches it via :func:`_dispatch` and routes through
+:mod:`convertible.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 convertible import __version__
+from convertible.cli._errors import EXIT_USER_ERROR, CliError
+from convertible.cli._output import emit_error
+
+_ISSUES_URL = "https://github.com/agentculture/convertible/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 convertible.cli._commands import cli as _cli_group
+    from convertible.cli._commands import doctor as _doctor_cmd
+    from convertible.cli._commands import explain as _explain_cmd
+    from convertible.cli._commands import learn as _learn_cmd
+    from convertible.cli._commands import overview as _overview_cmd
+    from convertible.cli._commands import whoami as _whoami_cmd
+
+    parser = _CliArgumentParser(
+        prog="convertible",
+        description="convertible — 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 convertible.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())

convertible/cli/_commands/__init__.py

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

convertible/cli/_commands/cli.py

@@ -0,0 +1,43 @@
+"""``convertible 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 convertible.cli._commands.overview import cli_sections, emit_overview
+
+
+def cmd_cli_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "convertible cli",
+        cli_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    # `convertible 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 'convertible 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 convertible CLI surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_cli_overview)

convertible/cli/_commands/doctor.py

@@ -0,0 +1,122 @@
+"""``convertible 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 convertible.cli._commands.whoami import find_culture_yaml, read_agent_fields
+from convertible.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"convertible 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)

convertible/cli/_commands/explain.py

@@ -0,0 +1,38 @@
+"""``convertible 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:`convertible.explain`.
+Unknown paths raise :class:`CliError` with a remediation hint.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from convertible.cli._output import emit_result
+from convertible.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 'convertible').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_explain)

convertible/cli/_commands/learn.py

@@ -0,0 +1,88 @@
+"""``convertible 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 convertible import __version__
+from convertible.cli._output import emit_result
+
+_TEXT = """\
+convertible — 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
+--------
+  convertible whoami             Identity from culture.yaml.
+  convertible learn              This self-teaching prompt.
+  convertible explain <path>...  Markdown docs for any noun/verb path.
+  convertible overview           Descriptive snapshot of the agent.
+  convertible doctor             Check the agent-identity invariants.
+  convertible 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
+-----------
+  convertible explain convertible
+"""
+
+
+def _as_json_payload() -> dict[str, object]:
+    return {
+        "tool": "convertible",
+        "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": "convertible 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)

convertible/cli/_commands/overview.py

@@ -0,0 +1,112 @@
+"""``convertible 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:`convertible.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 convertible.cli._commands.whoami import report
+from convertible.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(
+        "convertible",
+        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)

convertible/cli/_commands/whoami.py

@@ -0,0 +1,106 @@
+"""``convertible 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 convertible import __version__
+from convertible.cli._output import emit_result
+
+_FALLBACK_NICK = "convertible"
+
+
+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)

convertible/cli/_errors.py

@@ -0,0 +1,42 @@
+"""CliError and exit-code policy (stable-contract).
+
+Every failure inside convertible raises :class:`CliError`. The
+top-level ``main()`` catches it, formats via :mod:`convertible.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 ``convertible 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,
+        }

convertible/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 convertible.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")

convertible/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 convertible.cli._errors import EXIT_USER_ERROR, CliError
+from convertible.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: convertible explain convertible",
+    )
+
+
+def known_paths() -> list[tuple[str, ...]]:
+    return list(ENTRIES.keys())

convertible/explain/catalog.py

@@ -0,0 +1,129 @@
+"""Markdown catalog for ``convertible explain <path>``.
+
+Each entry is verbatim markdown. Keys are command-path tuples. The empty tuple
+and ``("convertible",)`` 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 = """\
+# convertible
+
+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
+
+- `convertible whoami` — identity probe from `culture.yaml`.
+- `convertible learn` — structured self-teaching prompt.
+- `convertible explain <path>` — markdown docs for any noun/verb.
+- `convertible overview` — descriptive snapshot of the agent.
+- `convertible doctor` — check the agent-identity invariants.
+- `convertible cli overview` — describe the CLI surface.
+
+## Exit-code policy
+
+- `0` success
+- `1` user-input error
+- `2` environment / setup error
+- `3+` reserved
+
+## See also
+
+- `convertible explain whoami`
+- `convertible explain doctor`
+"""
+
+_WHOAMI = """\
+# convertible whoami
+
+Reports the agent's identity from `culture.yaml`: nick (`suffix`), backend,
+served model, and the package version. Read-only.
+
+## Usage
+
+    convertible whoami
+    convertible whoami --json
+"""
+
+_LEARN = """\
+# convertible learn
+
+Prints a structured self-teaching prompt covering purpose, command map,
+exit-code policy, `--json` support, and the `explain` pointer.
+
+## Usage
+
+    convertible learn
+    convertible learn --json
+"""
+
+_EXPLAIN = """\
+# convertible explain <path>
+
+Prints markdown documentation for any noun/verb path. Unlike `--help` (terse,
+positional), `explain` is global and addressable by path.
+
+## Usage
+
+    convertible explain convertible
+    convertible explain whoami
+    convertible explain --json <path>
+"""
+
+_OVERVIEW = """\
+# convertible 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
+
+    convertible overview
+    convertible overview --json
+"""
+
+_DOCTOR = """\
+# convertible 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
+
+    convertible doctor
+    convertible doctor --json
+"""
+
+_CLI = """\
+# convertible cli
+
+Noun group for CLI-surface introspection. `cli overview` describes the CLI
+itself (distinct from the global `overview`, which describes the agent).
+
+## Usage
+
+    convertible cli overview
+    convertible cli overview --json
+"""
+
+
+ENTRIES: dict[tuple[str, ...], str] = {
+    (): _ROOT,
+    ("convertible",): _ROOT,
+    ("whoami",): _WHOAMI,
+    ("learn",): _LEARN,
+    ("explain",): _EXPLAIN,
+    ("overview",): _OVERVIEW,
+    ("doctor",): _DOCTOR,
+    ("cli",): _CLI,
+    ("cli", "overview"): _CLI,
+}

convertible_cli-0.1.2.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: convertible-cli
+Version: 0.1.2
+Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
+Project-URL: Homepage, https://github.com/agentculture/convertible
+Project-URL: Issues, https://github.com/agentculture/convertible/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# convertible
+
+Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
+
+## 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 convertible whoami  # identity from culture.yaml
+uv run convertible 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 `convertible/` and the `convertible`
+   CLI/dist name throughout `pyproject.toml`, the package, `tests/`, and
+   `sonar-project.properties`.
+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
+
+MIT — see [`LICENSE`](LICENSE).

convertible_cli-0.1.2.dist-info/RECORD

@@ -0,0 +1,19 @@
+convertible/__init__.py,sha256=JYtnSOfHnF_Mi1-X2zf4UrFykjHuvZFT-0zkt6NEB4A,408
+convertible/__main__.py,sha256=WHuLyDe2jxViy3egr8ULsKn1mbEEah8vhjyy4OiHcxQ,180
+convertible/cli/__init__.py,sha256=WAqekKV1Ynt-Qaw0RcDDNnjh0CiKZtwTPvwzEKeGN6A,4999
+convertible/cli/_errors.py,sha256=U-yoWAPzhcC189gA2d88-4Lit7b_hHeoPYQwc_NpNgE,1304
+convertible/cli/_output.py,sha256=p-SAa8yucaWtid13Yb6QUDrQeTn3ZboFyeOY-cpX5LU,1710
+convertible/cli/_commands/__init__.py,sha256=DqpfVkhBo7cj6eWOpSlwx1ag0nTbrYJkV8pnPgl2gyU,70
+convertible/cli/_commands/cli.py,sha256=9N7uRfJkA9UMiPtsg4MRbsEE-SdnaTIItjT9hV_mk8s,1683
+convertible/cli/_commands/doctor.py,sha256=ZT-Gml3X0en3pQjpW36KM1cprCcpG2GsL4BM7oloE3I,4399
+convertible/cli/_commands/explain.py,sha256=IlXlP94TT92Ne8nPqll2WIaPcKFTsikAslfNF8jYH4M,1232
+convertible/cli/_commands/learn.py,sha256=tcAh2oUYTr2m2a4L8oALgLgFCC-joNHX56ocHGf1Qyg,3013
+convertible/cli/_commands/overview.py,sha256=6oN1PLHsGkdaRAaoNg69gl8AJ1Wq7WLIAZzopVoMRVA,3956
+convertible/cli/_commands/whoami.py,sha256=je7WAjb4SzBH6DdGMP5DzUvANFsr-0WhiK4ARUaFdsk,3654
+convertible/explain/__init__.py,sha256=YPZcsSN_YPXzAUbPajnqVawEU2sdt5Q0oyfi0ZHj7H4,708
+convertible/explain/catalog.py,sha256=evKCfcLxbUVACBKpwitNlqLXHArbZFX1OutPwU8Thio,3228
+convertible_cli-0.1.2.dist-info/METADATA,sha256=syXr0mAFesi8UpBO5ytXNpPxS4HREv2BhuVLuCFcYwU,2964
+convertible_cli-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+convertible_cli-0.1.2.dist-info/entry_points.txt,sha256=ZZ5pg_AcVNlbDlKrT5oe9J8UqSn_YLaj7sXSKb1wlts,53
+convertible_cli-0.1.2.dist-info/licenses/LICENSE,sha256=wCcdPywGtFXx1P8N0j0eEDINSWfSjrIsU7ds1YZl-MA,1069
+convertible_cli-0.1.2.dist-info/RECORD,,

convertible_cli-0.1.2.dist-info/WHEEL

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

convertible_cli-0.1.2.dist-info/entry_points.txt

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

convertible_cli-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentCulture
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.