openral-cli 0.1.0__py3-none-any.whl

openral_cli/__init__.py

@@ -0,0 +1,6 @@
+"""openral CLI — the `ros` command entry point."""
+
+__version__ = "0.1.0"
+__all__ = ["app"]
+
+from openral_cli.main import app

openral_cli/_hf_publish.py

@@ -0,0 +1,125 @@
+"""Shared HF Hub publishing helpers — token resolution, scope check, ignore patterns.
+
+Lifted from :mod:`tools.rskill_publisher` so that both ``openral dataset push``
+and the existing skill publisher share one canonical path
+for token discovery, scope verification, and ignore-pattern filtering. Per
+CLAUDE.md §1.13, this de-duplication preempts the next "add another HF
+uploader" PR from copying the rSkill version verbatim.
+
+The helpers are conservative by design:
+
+* :func:`resolve_token` accepts an explicit token argument, then falls back
+  to ``HF_TOKEN`` / ``HUGGINGFACE_HUB_TOKEN`` environment variables. It
+  raises :class:`openral_core.exceptions.ROSConfigError` (with an actionable
+  hint) when nothing is found, rather than handing the API a ``None`` and
+  watching it produce a generic 401.
+* :func:`ensure_private` re-fetches repo metadata after creation and aborts
+  if the API reports the repo as public. This catches the edge case where
+  ``create_repo(private=True)`` silently fails to apply on a pre-existing
+  public repo.
+* :data:`IGNORE_PATTERNS` excludes the same secrets / build-artifact glob
+  as ``rskill_publisher`` so dataset uploads can't accidentally publish
+  ``.env`` files or ``__pycache__/`` directories.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, Final
+
+from openral_core.exceptions import ROSConfigError
+
+if TYPE_CHECKING:
+    from huggingface_hub import HfApi
+
+__all__ = [
+    "IGNORE_PATTERNS",
+    "ensure_private",
+    "resolve_token",
+]
+
+# Files / directories excluded from every HF Hub upload. Same set the
+# rSkill publisher uses — keeps secrets out of public-by-accident repos.
+IGNORE_PATTERNS: Final[list[str]] = [
+    "*.pyc",
+    "__pycache__",
+    ".env",
+    ".env.*",
+    "*.key",
+    "*.pem",
+    ".DS_Store",
+    "Thumbs.db",
+]
+
+
+def resolve_token(token_arg: str | None = None) -> str:
+    """Return the HF token from the argument or the environment.
+
+    Args:
+        token_arg: Value passed via a ``--token`` CLI flag (may be None).
+            When provided, takes precedence over the environment.
+
+    Returns:
+        The resolved token string.
+
+    Raises:
+        ROSConfigError: When no token is available (with a hint listing
+            the env vars and the CLI flag).
+
+    Example:
+        >>> import os
+        >>> os.environ["HF_TOKEN"] = "hf_test_token"
+        >>> resolve_token()
+        'hf_test_token'
+        >>> resolve_token("hf_override")
+        'hf_override'
+        >>> del os.environ["HF_TOKEN"]
+    """
+    token = token_arg or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+    if not token:
+        raise ROSConfigError(
+            "no HF token found; set HF_TOKEN (or HUGGINGFACE_HUB_TOKEN) env var, "
+            "or pass --token <hf_xxx>. Token must have 'repo.write' scope. "
+            "Generate at https://huggingface.co/settings/tokens."
+        )
+    return token
+
+
+def ensure_private(api: HfApi, repo_id: str, *, repo_type: str = "model") -> None:
+    """Re-fetch repo metadata and raise if it is not private.
+
+    Critical safety gate: even when ``create_repo`` was called with
+    ``private=True``, an existing public repo at the same id will NOT
+    be auto-flipped to private. This function verifies the live state
+    on the Hub.
+
+    Args:
+        api: Authenticated :class:`huggingface_hub.HfApi` client.
+        repo_id: The repository to verify (e.g. ``"openral/dataset-foo"``).
+        repo_type: ``"model"`` (default — used by rSkills), ``"dataset"``
+            (used by dataset uploads), or ``"space"``.
+
+    Raises:
+        ROSConfigError: When the repo is not private or metadata cannot
+            be fetched. The caller must abort the upload and let the user
+            either delete the existing public repo or rename.
+    """
+    # HF Hub returns different concrete info types per repo_type, but all
+    # carry the .private attribute. Use Any to side-step the union plumbing.
+    info: Any
+    try:
+        if repo_type == "dataset":
+            info = api.dataset_info(repo_id)
+        elif repo_type == "space":
+            info = api.space_info(repo_id)
+        else:
+            info = api.model_info(repo_id)
+    except Exception as exc:  # HF SDK raises many specific types
+        raise ROSConfigError(f"privacy check failed for {repo_type} '{repo_id}': {exc!s}") from exc
+
+    if not info.private:
+        raise ROSConfigError(
+            f"ABORT: {repo_type} '{repo_id}' is public on the HF Hub. "
+            "OpenRAL never publishes a public repo automatically. "
+            "Delete the existing public repo manually before retrying."
+        )

openral_cli/_rskill_doc_validator.py

@@ -0,0 +1,562 @@
+"""rSkill README + manifest documentation validator.
+
+Enforces that an rSkill directory ships with a *useful* README and a
+filled-in manifest before it can be published to the HF Hub. The
+schema-level Pydantic validators on
+:class:`openral_core.schemas.RSkillManifest` answer "is this YAML
+well-formed"; this validator answers "is this rSkill ready for someone
+who isn't the author to install and run".
+
+CLAUDE.md §6.4 lists ``README.md with a runnable example`` as required
+packaging for every rSkill, alongside ``rskill.yaml``, weights, and
+``eval/``. Until this module existed the README requirement was only a
+prose obligation — ``tools/rskill_publisher.py`` happily uploaded a
+manifest with the template's ``"Scaffold template generated by …"``
+description and no README at all. The publisher now imports
+:func:`validate_rskill_docs` as a hard gate (the dry-run path emits the
+same report so authors see the issues before they ever pass
+``--publish``).
+
+What the validator enforces
+---------------------------
+
+README presence and shape:
+
+* ``README.md`` exists at the top of the rSkill directory.
+* Body is non-trivial (``>= _MIN_README_BODY_LENGTH`` bytes).
+* Headings cover the canonical sections that answer the three questions
+  every consumer asks: **what** the skill does, **how** it works, and
+  **how it was trained**. See :data:`README_REQUIRED_SECTIONS`.
+* No unresolved template sentinels (``TEMPLATE_ORG`` / ``TEMPLATE_ID``)
+  or generic placeholder strings (``TODO:``, ``FIXME``, ``<fill-in>``).
+* A preview image or video is present (a ``![](…)`` markdown image, an
+  ``<img>``, or a ``<video>``) — emitted as a **warning**, not an error,
+  so the pre-existing in-tree skills that lack a preview keep passing
+  while new skills get prompted via the template's ``## Preview`` section.
+
+Manifest content (beyond what the Pydantic schema already catches):
+
+* ``description`` is not the template scaffold placeholder and is at
+  least :data:`_MIN_DESCRIPTION_LENGTH` characters.
+* At least one of ``paper_url`` / ``source_repo`` is set — both are
+  schema-optional but publish requires one or the other so consumers
+  always have a citation or upstream-model link to follow.
+* ``weights_uri`` / ``source_repo`` do not contain ``TEMPLATE`` (the
+  scaffolder leaves those URIs alone in some paths and a published skill
+  pointing at a sentinel URL is broken on the consumer end).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Final, Literal
+
+from openral_core.schemas import RSKILL_TEMPLATE_SENTINELS, RSkillManifest
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "DELEGATION_MARKER_NAME",
+    "PLACEHOLDER_MANIFEST_DESCRIPTION_MARKERS",
+    "PLACEHOLDER_SENTINELS",
+    "README_REQUIRED_SECTIONS",
+    "DocValidationIssue",
+    "DocValidationReport",
+    "format_report",
+    "validate_rskill_docs",
+]
+
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+_README_FILENAME: Final[str] = "README.md"
+_MIN_README_BODY_LENGTH: Final[int] = 200
+_MIN_DESCRIPTION_LENGTH: Final[int] = 30
+
+_MEDIA_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"!\[[^\]]*\]\([^)]+\)|<img\b|<video\b", re.IGNORECASE
+)
+"""Matches a markdown image ``![alt](src)``, an ``<img>``, or a ``<video>`` tag.
+
+A published rSkill README should show *what the skill does* — a preview image or
+a demo clip. Enforced as a **warning** (not a publish-blocking error) so the 39
+in-tree skills that predate this requirement keep passing; new skills scaffolded
+from ``rskills/template/README.md`` get the ``## Preview`` section for free.
+"""
+
+README_REQUIRED_SECTIONS: Final[tuple[tuple[str, tuple[str, ...]], ...]] = (
+    # (display_label, lowercase substrings that satisfy this section)
+    (
+        "Upstream model / training",
+        ("upstream", "model", "training", "provenance", "architecture"),
+    ),
+    (
+        "Supported robots / embodiments",
+        ("robot", "embodiment", "supported"),
+    ),
+    (
+        "Sensors / observation contract",
+        ("sensor", "observation", "input"),
+    ),
+    (
+        "Manifest summary",
+        ("manifest",),
+    ),
+    (
+        "License",
+        ("license",),
+    ),
+)
+"""Canonical README section coverage (display label → acceptable substrings).
+
+For each tuple, the README is acceptable if **any** of the substrings
+appears (case-insensitive) in **any** heading line. The set is
+deliberately permissive — ``## Model``, ``## Upstream model``,
+``## Architecture``, and ``## Provenance`` all satisfy the first slot —
+so the diverse in-tree READMEs (smolvla-libero, pi05-libero-int8,
+diffusion-pusht, …) pass without rewrites.
+"""
+
+PLACEHOLDER_SENTINELS: Final[tuple[str, ...]] = (
+    # Canonical unresolved-scaffold sentinels (shared with the reasoner palette
+    # gate via RSkillManifest.is_scaffold_placeholder), plus README-only markers.
+    *RSKILL_TEMPLATE_SENTINELS,
+    "TODO:",
+    "<TODO>",
+    "FIXME:",
+    "<FIXME>",
+    "<fill-in>",
+    "<your-org>",
+    "<your-skill>",
+    "TBD:",
+    "XXX:",
+)
+"""Strings that must NOT survive into a published README or manifest."""
+
+PLACEHOLDER_MANIFEST_DESCRIPTION_MARKERS: Final[tuple[str, ...]] = (
+    "Scaffold template generated by",
+    "Edit this description",
+)
+"""Substrings that flag a manifest ``description`` left at the template default."""
+
+DELEGATION_MARKER_NAME: Final[str] = "openral:rskill-readme-delegates-to"
+"""HTML-comment marker name that lets a stub README delegate to a sibling.
+
+A README containing
+``<!-- openral:rskill-readme-delegates-to: <relative-path> -->``
+is treated as a stub: the section checks are run against the resolved
+sibling instead of the stub itself. Placeholder and length checks still
+apply to the stub. Delegation is single-hop — a delegated-to README
+cannot itself delegate further.
+
+This handles families like the RLDX-1 ports (``rldx1-ft-rc365-nf4``
+delegates shared architecture / license docs to
+``rldx1-ft-libero-nf4``) without forcing every sibling skill to
+duplicate the same content.
+"""
+
+_DELEGATION_MARKER_PATTERN: Final[re.Pattern[str]] = re.compile(
+    r"<!--\s*" + re.escape(DELEGATION_MARKER_NAME) + r"\s*:\s*(?P<path>[^\s>]+)\s*-->",
+    re.IGNORECASE,
+)
+
+
+# ── Report types ─────────────────────────────────────────────────────────────
+
+
+class DocValidationIssue(BaseModel):
+    """One problem surfaced by :func:`validate_rskill_docs`.
+
+    Attributes:
+        severity: ``"error"`` blocks publishing; ``"warning"`` is
+            advisory (shown but does not exit 1).
+        field: Dot-path of the field that failed
+            (``"readme.body"`` / ``"readme.section.License"`` /
+            ``"manifest.description"`` / …).
+        message: Human-readable explanation including remediation hint.
+    """
+
+    severity: Literal["error", "warning"]
+    field: str
+    message: str
+
+
+class DocValidationReport(BaseModel):
+    """Result of validating one rSkill's README + manifest.
+
+    Attributes:
+        skill_dir: Absolute path to the validated rSkill directory.
+        manifest_name: ``RSkillManifest.name`` of the validated manifest.
+        issues: All issues found, in the order they were detected.
+
+    Example:
+        >>> # report = validate_rskill_docs(Path("rskills/smolvla-libero"), manifest)
+        >>> # if not report.is_valid:
+        >>> #     for issue in report.errors:
+        >>> #         print(f"{issue.field}: {issue.message}")
+    """
+
+    skill_dir: str
+    manifest_name: str
+    issues: list[DocValidationIssue] = Field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        """True iff no ``error``-severity issues were found."""
+        return not any(i.severity == "error" for i in self.issues)
+
+    @property
+    def errors(self) -> list[DocValidationIssue]:
+        """The subset of :attr:`issues` with ``severity == "error"``."""
+        return [i for i in self.issues if i.severity == "error"]
+
+    @property
+    def warnings(self) -> list[DocValidationIssue]:
+        """The subset of :attr:`issues` with ``severity == "warning"``."""
+        return [i for i in self.issues if i.severity == "warning"]
+
+
+# ── Validator entry point ────────────────────────────────────────────────────
+
+
+def validate_rskill_docs(skill_dir: Path, manifest: RSkillManifest) -> DocValidationReport:
+    """Validate an rSkill directory's README and manifest documentation.
+
+    Composes :func:`_validate_readme` and :func:`_validate_manifest_content`
+    into one report so the publisher can render a single block of issues
+    rather than failing piecemeal.
+
+    Args:
+        skill_dir: Path to the rSkill directory (the parent of
+            ``rskill.yaml`` and ``README.md``).
+        manifest: Already-loaded, schema-valid manifest. Callers obtain
+            this via :meth:`RSkillManifest.from_yaml` before calling here.
+
+    Returns:
+        :class:`DocValidationReport` with one issue per problem found.
+        Iterate :attr:`DocValidationReport.errors` to decide whether to
+        block publishing.
+
+    Example:
+        >>> # from pathlib import Path
+        >>> # from openral_core.schemas import RSkillManifest
+        >>> # m = RSkillManifest.from_yaml("rskills/smolvla-libero/rskill.yaml")
+        >>> # rep = validate_rskill_docs(Path("rskills/smolvla-libero"), m)
+        >>> # rep.is_valid
+        True
+    """
+    issues: list[DocValidationIssue] = []
+    issues.extend(_validate_readme(skill_dir))
+    issues.extend(_validate_manifest_content(manifest))
+    return DocValidationReport(
+        skill_dir=str(skill_dir.resolve()),
+        manifest_name=manifest.name,
+        issues=issues,
+    )
+
+
+# ── README checks ────────────────────────────────────────────────────────────
+
+
+def _validate_readme(skill_dir: Path) -> list[DocValidationIssue]:
+    """Check README presence, length, required sections, and sentinels.
+
+    Honors single-hop delegation via the
+    ``<!-- openral:rskill-readme-delegates-to: <path> -->`` marker (see
+    :data:`DELEGATION_MARKER_NAME`): when present, the section checks run
+    against the resolved sibling README instead of this one. Placeholder
+    and length checks still apply to the stub itself.
+    """
+    readme_path = skill_dir / _README_FILENAME
+    if not readme_path.is_file():
+        return [
+            DocValidationIssue(
+                severity="error",
+                field="readme",
+                message=(
+                    f"README.md is required at {readme_path}. Every rSkill "
+                    "package must ship a README explaining what the skill "
+                    "does, how it works, and how it was trained "
+                    "(CLAUDE.md §6.4). Start from rskills/template/README.md."
+                ),
+            )
+        ]
+
+    body = readme_path.read_text(encoding="utf-8")
+    issues: list[DocValidationIssue] = []
+
+    if len(body.strip()) < _MIN_README_BODY_LENGTH:
+        issues.append(
+            DocValidationIssue(
+                severity="error",
+                field="readme.body",
+                message=(
+                    f"README.md is shorter than {_MIN_README_BODY_LENGTH} characters "
+                    f"({len(body.strip())} found); too short to document what "
+                    "the skill does, the upstream model, the embodiment, and the "
+                    "license. Flesh it out using rskills/template/README.md."
+                ),
+            )
+        )
+
+    # Single-hop delegation: a stub README points the section checks at a
+    # sibling. Used by the RLDX-1 family where one canonical README owns
+    # the shared architecture / license / sidecar docs.
+    delegated_headings, delegation_issues = _resolve_delegation(skill_dir, body)
+    issues.extend(delegation_issues)
+    headings_for_sections = (
+        delegated_headings if delegated_headings is not None else _extract_headings(body)
+    )
+
+    for label, substrings in README_REQUIRED_SECTIONS:
+        if not _any_heading_matches(headings_for_sections, substrings):
+            field = f"readme.section.{label}"
+            message = (
+                f"README.md is missing a heading for '{label}'. "
+                f"Add a section whose heading contains one of: "
+                f"{', '.join(repr(s) for s in substrings)}. "
+                "See rskills/template/README.md for the canonical layout."
+            )
+            if delegated_headings is not None:
+                message = (
+                    f"Delegated README is missing a heading for '{label}'. "
+                    f"Add a section whose heading contains one of: "
+                    f"{', '.join(repr(s) for s in substrings)} to the "
+                    "sibling README this stub delegates to."
+                )
+            issues.append(DocValidationIssue(severity="error", field=field, message=message))
+
+    for sentinel in PLACEHOLDER_SENTINELS:
+        if sentinel in body:
+            issues.append(
+                DocValidationIssue(
+                    severity="error",
+                    field="readme.placeholder",
+                    message=(
+                        f"README.md still contains the placeholder {sentinel!r}. "
+                        "Replace every template sentinel and TODO marker with "
+                        "real content before publishing."
+                    ),
+                )
+            )
+
+    if not _MEDIA_PATTERN.search(body):
+        issues.append(
+            DocValidationIssue(
+                severity="warning",
+                field="readme.media",
+                message=(
+                    "README.md has no preview image or video. Add a '## Preview' "
+                    "section with at least one image (markdown ![alt](media/...) "
+                    "or an <img> tag) or a <video> — a still, a progress overlay, "
+                    "or a demo clip showing what the skill does. HF model cards "
+                    "render images but not <video>, so for a video, also commit "
+                    "the .mp4 and show start/middle/end stills. See "
+                    "rskills/template/README.md."
+                ),
+            )
+        )
+
+    return issues
+
+
+def _resolve_delegation(
+    skill_dir: Path, body: str
+) -> tuple[list[str] | None, list[DocValidationIssue]]:
+    """Resolve a ``rskill-readme-delegates-to`` marker.
+
+    Args:
+        skill_dir: Directory of the README being validated.
+        body: Text of the current README.
+
+    Returns:
+        Tuple ``(delegated_headings, issues)``:
+
+        * ``delegated_headings is None`` if there is no delegation marker
+          (caller falls back to the current README's own headings).
+        * ``delegated_headings is []`` if the marker exists but cannot
+          be resolved (an issue is emitted into ``issues``); the caller
+          treats this as "no headings found" so every section reports as
+          missing on top of the delegation error.
+        * Otherwise the parsed heading lines of the sibling README.
+
+        ``issues`` is empty when delegation resolves cleanly.
+    """
+    match = _DELEGATION_MARKER_PATTERN.search(body)
+    if match is None:
+        return None, []
+
+    target_rel = match.group("path")
+    target_dir = (skill_dir / target_rel).resolve()
+    target_path = target_dir / _README_FILENAME if target_dir.is_dir() else target_dir
+    if not target_path.is_file():
+        return [], [
+            DocValidationIssue(
+                severity="error",
+                field="readme.delegation",
+                message=(
+                    f"README.md delegates to {target_rel!r} via the "
+                    f"{DELEGATION_MARKER_NAME} marker, but no README was found "
+                    f"at {target_path}. Fix the relative path or remove the marker."
+                ),
+            )
+        ]
+
+    target_body = target_path.read_text(encoding="utf-8")
+    # Refuse double-hop delegation: a delegated-to README cannot itself
+    # delegate further. Single-hop keeps the check fast and the contract
+    # easy to reason about.
+    if _DELEGATION_MARKER_PATTERN.search(target_body):
+        return [], [
+            DocValidationIssue(
+                severity="error",
+                field="readme.delegation",
+                message=(
+                    f"README.md delegates to {target_rel!r}, but that sibling "
+                    f"also contains the {DELEGATION_MARKER_NAME} marker. "
+                    "Delegation is single-hop only; resolve to the canonical "
+                    "README directly."
+                ),
+            )
+        ]
+
+    return _extract_headings(target_body), []
+
+
+def _extract_headings(body: str) -> list[str]:
+    """Return every ATX heading line (``#``/``##``/``###`` …) found in ``body``."""
+    return re.findall(r"^#{1,6}\s+.*$", body, flags=re.MULTILINE)
+
+
+def _any_heading_matches(headings: list[str], substrings: tuple[str, ...]) -> bool:
+    """Return True if any heading contains any of ``substrings`` (case-insensitive)."""
+    lowered = [h.lower() for h in headings]
+    return any(s in h for h in lowered for s in substrings)
+
+
+# ── Manifest checks ──────────────────────────────────────────────────────────
+
+
+def _validate_manifest_content(manifest: RSkillManifest) -> list[DocValidationIssue]:
+    """Check the manifest fields that the Pydantic schema can't fail on."""
+    issues: list[DocValidationIssue] = []
+
+    description = manifest.description.strip()
+    for marker in PLACEHOLDER_MANIFEST_DESCRIPTION_MARKERS:
+        if marker in description:
+            issues.append(
+                DocValidationIssue(
+                    severity="error",
+                    field="manifest.description",
+                    message=(
+                        "manifest.description still contains the template "
+                        f"placeholder {marker!r}. Replace it with a real "
+                        "summary of what the skill does (the LLM tool palette "
+                        "uses this text — keep it specific to the task, "
+                        "objects, and scene)."
+                    ),
+                )
+            )
+            break  # one placeholder hit is enough; don't double-report
+
+    if len(description) < _MIN_DESCRIPTION_LENGTH:
+        issues.append(
+            DocValidationIssue(
+                severity="error",
+                field="manifest.description",
+                message=(
+                    f"manifest.description is {len(description)} chars; "
+                    f"publish requires >= {_MIN_DESCRIPTION_LENGTH}. The reasoner "
+                    "LLM scores skills primarily on this text — make it specific."
+                ),
+            )
+        )
+
+    if manifest.paper_url is None and manifest.source_repo is None:
+        issues.append(
+            DocValidationIssue(
+                severity="error",
+                field="manifest.provenance",
+                message=(
+                    "Publish requires at least one of manifest.paper_url or "
+                    "manifest.source_repo to be set, so consumers have a "
+                    "citation / upstream-model link to follow. The HF Hub model "
+                    "card URL is acceptable for paper_url when no formal paper "
+                    "exists."
+                ),
+            )
+        )
+
+    _candidates = (
+        ("weights_uri", manifest.weights_uri),
+        ("source_repo", manifest.source_repo),
+    )
+    for field_name, value in _candidates:
+        if value and "TEMPLATE" in value:
+            issues.append(
+                DocValidationIssue(
+                    severity="error",
+                    field=f"manifest.{field_name}",
+                    message=(
+                        f"manifest.{field_name} still contains the template "
+                        f"sentinel substring 'TEMPLATE' ({value!r}). Point it at "
+                        "the real HF Hub repo before publishing."
+                    ),
+                )
+            )
+
+    for sentinel in RSKILL_TEMPLATE_SENTINELS:
+        if sentinel in manifest.name:
+            issues.append(
+                DocValidationIssue(
+                    severity="error",
+                    field="manifest.name",
+                    message=(
+                        f"manifest.name still contains the template sentinel "
+                        f"{sentinel!r} ({manifest.name!r}). Rename via `openral rskill new` "
+                        "or rewrite the field directly."
+                    ),
+                )
+            )
+
+    return issues
+
+
+# ── Pretty-printer ───────────────────────────────────────────────────────────
+
+
+def format_report(report: DocValidationReport) -> str:
+    """Render a human-readable summary of a :class:`DocValidationReport`.
+
+    Used by ``tools/rskill_publisher.py`` and ``openral rskill new`` for the
+    publish-readiness banner. Errors are prefixed with ``error:`` and
+    warnings with ``warning:`` so the output greps cleanly.
+
+    Args:
+        report: The report to render.
+
+    Returns:
+        Multi-line string with one issue per line plus a summary footer.
+
+    Example:
+        >>> # print(format_report(report))
+    """
+    lines: list[str] = []
+    lines.append(f"rSkill docs report — {report.manifest_name}")
+    lines.append(f"  dir: {report.skill_dir}")
+    if not report.issues:
+        lines.append("  ✓ README + manifest documentation are publish-ready.")
+        return "\n".join(lines)
+
+    for issue in report.issues:
+        lines.append(f"  {issue.severity}: [{issue.field}] {issue.message}")
+
+    n_err = len(report.errors)
+    n_warn = len(report.warnings)
+    lines.append(f"  → {n_err} error(s), {n_warn} warning(s).")
+    if n_err:
+        lines.append(
+            "  Publishing is BLOCKED until every error is resolved "
+            "(see rskills/template/README.md for the canonical layout)."
+        )
+    return "\n".join(lines)