parse-sdk 0.1.0__py3-none-any.whl

parse_sdk/docgen.py

@@ -0,0 +1,587 @@
+"""Offline docs renderer for `parse sync`.
+
+Single-purpose companion to ``codegen_v2`` (which owns the typed ``.py``
+module + its docstrings). ``docgen`` renders the human/agent-facing prose
+artifacts from the SAME stored schema (the ``/sdk/schemas`` ``SDKSchema``
+shape), deterministically and offline — no LLM, no network:
+
+  * ``render_readme(schema, *, has_example)`` → per-API ``README.md``
+    (endpoint index table; the ``example.py`` pointer is emitted only when
+    ``has_example``).
+  * ``render_example(schema, *, slug)`` → the shippable per-API ``example.py``
+    (the stored ``sdk_usage_example`` with its self-import rebound to the
+    assigned ``slug``), or ``None`` when there is no shippable example (absent,
+    unparseable, or a collision-broken self-import).
+  * ``render_agents_index(schemas)``/``render_claude_index(schemas)`` → the
+    two identical root index files (``AGENTS.md`` / ``CLAUDE.md``).
+  * ``coverage_warnings(schema)``   → the missing-narrative gaps the CLI
+    surfaces (degraded path).
+
+Every file carries :data:`BANNER_TEXT` so a human/agent never edits a
+generated file expecting it to survive the next sync.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+BANNER_TEXT = "Generated by `parse sync` — edits will be overwritten. Edit the API in Parse."
+
+# Markdown comment so the banner renders invisibly in a rendered README but is
+# present in the raw file an agent reads.
+_MD_BANNER = f"<!-- {BANNER_TEXT} -->"
+# Python comment for example.py.
+_PY_BANNER = f"# {BANNER_TEXT}"
+
+# How many APIs the cross-API index lists inline before collapsing to the
+# "…and M more" pointer. Module-level so tests assert against the source of
+# truth (keeps the index O(1) in API count — see `_render_index`).
+_INDEX_PREVIEW_COUNT = 6
+
+
+def _rewrite_import_modules(code: str, nodes: "List[ast.ImportFrom]", new_module: str) -> str:
+    """Rewrite ONLY the module token of each ``from <module> import …`` statement
+    that begins on ``node.lineno``, to ``new_module`` — preserving the imported
+    names list (and any aliases / trailing comment / parenthesised continuation)
+    byte-for-byte. The module token is the single contiguous dotted identifier
+    right after ``from`` on the statement's first physical line, so a regex bound
+    to that one line swaps it without touching anything else.
+    """
+    lines = code.splitlines(keepends=True)
+    for n in nodes:
+        i = n.lineno - 1
+        lines[i] = re.sub(
+            r"(^\s*from\s+)[\w.]+",
+            lambda m: m.group(1) + new_module,
+            lines[i],
+            count=1,
+        )
+    return "".join(lines)
+
+
+def _is_parse_pkg_module(module: "Optional[str]") -> bool:
+    """True iff ``module`` is the generated-package namespace — ``parse_apis`` /
+    ``parse_sdk`` or a submodule of either. The agent's self-import always lives
+    here (its guess is the *submodule*, never the top-level package or a foreign
+    one), so both the rebind anchor and the collision-broken check restrict to it
+    — a genuine third-party import that happens to share the root class name is
+    left alone, not clobbered."""
+    return bool(module) and (
+        module == "parse_apis" or module.startswith("parse_apis.")
+        or module == "parse_sdk" or module.startswith("parse_sdk."))
+
+
+def _imports_from_parse_pkg(tree: ast.AST, name: str) -> bool:
+    """True iff ``name`` is imported via ``from parse_apis[.…] / parse_sdk[.…]
+    import …name…`` (used to recognise a collision-broken self-import)."""
+    return any(
+        isinstance(n, ast.ImportFrom) and not n.level and _is_parse_pkg_module(n.module)
+        and any(a.name == name for a in n.names)
+        for n in ast.walk(tree))
+
+
+def _root_import_nodes(tree: ast.AST, root: str) -> "List[ast.ImportFrom]":
+    """The ``from parse_apis[.…] / parse_sdk[.…] import …`` statements whose names
+    include ``root`` — this API's self-import, anchored on the one symbol codegen
+    emits AND restricted to the generated-package namespace (matching
+    :func:`_imports_from_parse_pkg`) so a foreign ``from <lib> import <Root>`` that
+    merely shares the root class name is never rebound to a wrong module."""
+    return [n for n in ast.walk(tree)
+            if isinstance(n, ast.ImportFrom) and not n.level and _is_parse_pkg_module(n.module)
+            and any(a.name == root for a in n.names)]
+
+
+def _root_name(schema: Dict[str, Any]) -> str:
+    """The root client class name codegen emits — delegated to codegen's single
+    allocator so a published import line can never diverge from the emitted class
+    (a ``root_name`` colliding with a resource name is suffixed there, and the
+    slug→CamelCase fallback uses codegen's ``_camel``, not a partial ``split('_')``)."""
+    from parse_sdk.codegen_v2 import resolve_root_name
+    return resolve_root_name(schema)
+
+
+def _import_line(schema: Dict[str, Any]) -> str:
+    """The blessed Phase-1 import line for this API."""
+    return f"from parse_apis.{schema.get('slug')} import {_root_name(schema)}"
+
+
+def _operations(schema: Dict[str, Any]):
+    """Yield ``(ref, op_dict)`` for every resource + sub-resource operation,
+    in a stable (resource, op) order. ``ref`` is ``<Resource>.<op>`` (or
+    ``<Resource>.<sub>.<op>``), matching the coverage unit + the gate's walk.
+    """
+    resources = schema.get("resources")
+    if not isinstance(resources, dict):
+        return
+    for rname, rspec in resources.items():
+        if not isinstance(rspec, dict):
+            continue
+        for opname, op in (rspec.get("operations") or {}).items():
+            if isinstance(op, dict):
+                yield f"{rname}.{opname}", op
+        for sname, sspec in (rspec.get("sub_resources") or {}).items():
+            if isinstance(sspec, dict):
+                for subop, op in (sspec.get("operations") or {}).items():
+                    if isinstance(op, dict):
+                        yield f"{rname}.{sname}.{subop}", op
+
+
+def _md_cell(text: Optional[str]) -> str:
+    """Escape a value for a single markdown table cell (pipes + newlines)."""
+    if not isinstance(text, str):
+        return ""
+    return text.replace("\n", " ").replace("|", "\\|").strip()
+
+
+def _returns_label(op: Dict[str, Any]) -> str:
+    """The README ``Returns`` cell. A paginated op (one declaring a ``pagination``
+    block) is emitted by codegen as ``Paginator[Element]`` — so surface that, not
+    the raw ``List[Element]`` spec label, which would teach a return type the SDK
+    never produces. Single-sources the element extraction from codegen."""
+    label = op.get("returns")
+    if not isinstance(label, str) or not label.strip():
+        return "—"
+    if isinstance(op.get("pagination"), dict):
+        from parse_sdk.codegen_v2 import _collection_element
+        return f"Paginator[{_collection_element(label)}]"
+    return _md_cell(label) or "—"
+
+
+def _reachability_warnings(schema: Dict[str, Any]) -> List[str]:
+    """Deterministic dead-code check: a resource with NO root accessor ships as
+    unreachable code.
+
+    This is easy to miss in review (a github-shaped SDK
+    whose ``User`` was unreachable as ``high``), so this is the structural
+    backstop. A resource is REACHABLE iff ANY of (collection / safe factory /
+    referenced-as-a-type).
+
+    **This DERIVES from the shared, named predicate**
+    ``parse_sdk.resource_surface.resource_surface_facts`` — the SAME function
+    codegen's ``client.<plural>`` emission gate and downstream tooling
+    consume — so the three notions of reachability cannot desync. A resource is
+    warned iff ``not is_class_reachable`` (no root collection, no safe factory,
+    not returned by any operation). Type-name matching, the ``_camel``-canonical
+    resource universe, and the normalized-schema handling all live in the shared
+    predicate now; this function only renders the warning text.
+    """
+    from parse_sdk.codegen_v2 import _camel
+    from parse_sdk.resource_surface import resource_surface_facts
+
+    facts = resource_surface_facts(schema)
+    warns: List[str] = []
+    for rk, rfacts in facts.items():
+        if rfacts.is_class_reachable:
+            continue
+        name = _camel(rk)
+        warns.append(
+            f"{schema.get('slug')}: Resource {name!r} is unreachable: no root "
+            f"collection, no safe factory, and not returned by any operation — "
+            f"it ships as dead code."
+        )
+    return warns
+
+
+def _suppressed_factory_warnings(schema: Dict[str, Any]) -> List[str]:
+    """Slug-attributed warnings for constructible factories codegen suppresses.
+
+    Consumes the SAME ``factory_descriptors`` read the emitter's factory pass
+    is built on (one home for the suppression gates), so the CLI can print the
+    suppression through its change-gated, slugged warning channel. The
+    codegen-side ``logger.warning`` stays for library consumers with real
+    logging configs; it is not CLI output.
+    """
+    from parse_sdk.codegen_v2 import _camel, _safe_ident, factory_descriptors
+
+    warns: List[str] = []
+    for res_name, unsafe, keyed_by in factory_descriptors(schema)["suppressed"]:
+        name = _camel(res_name)
+        warns.append(
+            f"{schema.get('slug')}: constructible factory for {name!r} suppressed — "
+            f"a reachable op pins non-key field {unsafe!r} (keyed_by={keyed_by!r}); "
+            f"no `client.{_safe_ident(name.lower())}(<{keyed_by}>)` factory; reach "
+            f"{name} via operation results."
+        )
+    return warns
+
+
+def coverage_warnings(schema: Dict[str, Any]) -> List[Tuple[str, str]]:
+    """Per-API ``(severity, text)`` warnings. Empty when the spec is fully
+    enriched and structurally sound.
+
+    Two tiers, consumed by the CLI's echo logic: ``"structural"`` — something
+    is wrong or dead in the emitted surface (unreachable resource, suppressed
+    factory, prose contradicting the emitted signature) and always prints
+    per-line; ``"enrichment"`` — missing narrative (an endpoint with no
+    ``description``) that degrades the README but breaks nothing, aggregated to
+    one line per API so dozens of identical advisories cannot drown the real
+    problems.
+
+    Also surfaces a DETERMINISTIC dead-code warning for any resource with no
+    root accessor (no collection, no safe factory, never returned) — the LLM
+    reviewer does not reliably catch this.
+    """
+    warns: List[Tuple[str, str]] = []
+    from parse_sdk.codegen_v2 import endpoint_description_map
+    ep_descriptions = endpoint_description_map(schema)
+    missing_desc = [ref for ref, op in _operations(schema)
+                    if not (isinstance(op.get("endpoint"), str)
+                            and ep_descriptions.get(op["endpoint"]))]
+    if missing_desc:
+        warns.append((
+            "enrichment",
+            f"{schema.get('slug')}: {len(missing_desc)} operation(s) whose endpoint has no "
+            f"`description` ({', '.join(missing_desc)}) — their README rows will have no description."
+        ))
+    # Endpoint prose still teaching a paginator-swallowed param: the
+    # emitted signature has no such kwarg, so the description contradicts the
+    # generated method (e.g. "per_page x page controls the window" with no
+    # `page` param). Surfaced for an upstream re-edit; server prose is never
+    # auto-rewritten.
+    drifted: List[str] = []
+    for ref, op in _operations(schema):
+        pg = op.get("pagination")
+        rp = pg.get("request_param") if isinstance(pg, dict) else None
+        ep = op.get("endpoint")
+        ep_desc = ep_descriptions.get(ep) if isinstance(ep, str) else None
+        if (isinstance(rp, str) and rp and isinstance(ep_desc, str)
+                and re.search(rf"\b{re.escape(rp)}\b", ep_desc)):
+            drifted.append(f"{ref} (`{rp}`)")
+    if drifted:
+        warns.append((
+            "structural",
+            f"{schema.get('slug')}: endpoint description(s) mention a pagination "
+            f"param the SDK handles automatically — {', '.join(drifted)}; edit "
+            f"the description(s) in the Parse dashboard."
+        ))
+    # Deterministic dead-code (unreachable-resource) backstop — a different
+    # concern than the narrative gaps above, surfaced through the same channel.
+    warns.extend(("structural", w) for w in _reachability_warnings(schema))
+    # Factory suppression, slug-attributed (codegen's logger.warning is a
+    # library channel, not CLI output — see _suppressed_factory_warnings).
+    warns.extend(("structural", w) for w in _suppressed_factory_warnings(schema))
+    return warns
+
+
+def render_readme(schema: Dict[str, Any], *, has_example: bool = True) -> str:
+    """Render the per-API ``README.md``.
+
+    Renders the structural reference only (title + optional API description +
+    import line + endpoint index table) — there is no separate prose narrative
+    section. Per-operation prose comes from each endpoint's ``description``,
+    surfaced in the index table's Description column.
+
+    ``has_example`` says whether ``example.py`` was actually written for this
+    API (an unshippable example is dropped — see :func:`render_example`). When
+    it is false, every reference to ``example.py`` is omitted so the README does
+    not link a file that is not on disk.
+    """
+    name = schema.get("name") or schema.get("slug") or "API"
+    lines: List[str] = [_MD_BANNER, "", f"# {name}", ""]
+
+    desc = schema.get("description")
+    if isinstance(desc, str) and desc.strip():
+        lines += [desc.strip(), ""]
+
+    lines += ["## Install / import", "", "```python", _import_line(schema), "```", ""]
+
+    # Endpoint / operation index table — always rendered (structural). The
+    # "Call" cell shows the REAL callable expression (sourced from codegen's
+    # single allocator), not the bare ``<Resource>.<op>`` ref, which is never a
+    # callable symbol. The row source is the NORMALIZED schema — the table
+    # documents the EMITTED surface, so a ``fetched_by``-synthesized ``get``
+    # gets a row (it exists in code; the raw spec never declared it).
+    # ``coverage_warnings``' own walk stays on the raw schema — its counts are
+    # a different consumer and must not change here.
+    # Normalize ONCE and share it with the two codegen reads — each would
+    # otherwise re-normalize the same schema (3× per README at corpus scale).
+    from parse_sdk.codegen_v2 import _normalize_schema, factory_descriptors
+    norm = _normalize_schema(schema)
+    ops = list(_operations(norm))
+    factories = factory_descriptors(schema, _norm=norm)["rows"]
+    if ops or factories:
+        from parse_sdk.codegen_v2 import endpoint_description_map, op_call_descriptors
+        descriptors = op_call_descriptors(schema, _norm=norm)
+        # An op's Description is the `description` of the endpoint it calls —
+        # resolved by `op["endpoint"]` (the same inline join codegen uses for the
+        # method docstring summary). Per-op `when` is retired and not read.
+        ep_descriptions = endpoint_description_map(schema)
+        intro = (
+            "Call these on the client's collection accessors "
+            "(e.g. `client.<collection>.<op>(…)`) or via active-record navigation "
+            "on returned objects"
+        )
+        intro += (
+            " — see [`example.py`](./example.py) for the exact call spelling."
+            if has_example else "."
+        )
+        intro += " List operations return a lazy `Paginator`."
+        lines += [
+            "## Operations", "",
+            intro, "",
+            "| Call | Returns | Description |",
+            "|---|---|---|",
+        ]
+        for ref, op in ops:
+            returns = _returns_label(op)
+            ep = op.get("endpoint")
+            desc = _md_cell(ep_descriptions.get(ep) if isinstance(ep, str) else None) or "—"
+            pg = op.get("pagination")
+            if isinstance(pg, dict):
+                # Deterministic, ADDITIVE clarification — the endpoint's prose
+                # may still describe the raw API's page/cursor param, which the
+                # paginator swallowed from the emitted signature. Server
+                # prose is never rewritten; the drift itself is surfaced via
+                # coverage_warnings for an upstream re-edit. The note tells the
+                # truth per scheme: a single_page op never advances, so
+                # promising "pagination is handled" teaches depth that doesn't
+                # exist (most corpus ops are single_page).
+                note = (
+                    "Single-fetch result set; the iterator yields one page."
+                    if pg.get("scheme") == "single_page" else
+                    "Pagination is handled by the returned iterator; "
+                    "page/cursor parameters are not exposed."
+                )
+                desc = note if desc == "—" else f"{desc} {note}"
+            call = descriptors.get(ref, ref)
+            # Signatures carry raw pipes (`Sort | Literal['a'] | str`); an
+            # unescaped `|` splits a GFM cell even inside a code span.
+            lines.append(f"| `{_md_cell(call)}` | `{_md_cell(returns)}` | {desc} |")
+        # Constructible root factories — emitted callables that are not spec
+        # operations (the factory pass synthesizes them), so the raw/normalized
+        # op walk can never produce their rows.
+        for attr, res_cls, key_ident, key_anno in factories:
+            call = f"client.{attr}({key_ident}: {key_anno})"
+            desc = (f"Constructs a local `{res_cls}` handle from a known "
+                    f"`{key_ident}` — no request is made.")
+            lines.append(f"| `{_md_cell(call)}` | `{_md_cell(res_cls)}` | {desc} |")
+        lines.append("")
+
+    # Typed-error reference — API-level by design: errors are declared per-API
+    # (`schema['errors']` → one `_ERROR_CLASSES` registry); no per-operation
+    # `raises` exists in the schema, so rows name what each error means, not
+    # which op raises it. Class names come from the module allocator so the
+    # table names the importable spelling even under a collision suffix.
+    errors = schema.get("errors")
+    if isinstance(errors, dict) and errors:
+        from parse_sdk.codegen_v2 import error_class_names
+        alloc = error_class_names(schema)
+        lines += [
+            "## Errors", "",
+            "| Error | Raised when | Carries |",
+            "|---|---|---|",
+        ]
+        for err_name, err_spec in errors.items():
+            if not isinstance(err_spec, dict):
+                continue
+            cls = alloc.get(err_name, err_name)
+            when = _md_cell(err_spec.get("when")) or "—"
+            carries = err_spec.get("carries")
+            carries_cell = (
+                ", ".join(f"`{_md_cell(str(c))}`" for c in carries)
+                if isinstance(carries, list) and carries else "—"
+            )
+            lines.append(f"| `{_md_cell(cls)}` | {when} | {carries_cell} |")
+        lines += [
+            "",
+            "Runtime errors (`RateLimitError`, `UpstreamError`, "
+            "`PaginationLimitError`, …) are importable from `parse_apis` and can "
+            "occur on any call.",
+            "",
+        ]
+
+    # F10 (generic) — when this API declares any enum, warn that a param may
+    # accept an enum whose corresponding OUTPUT field is raw `str`/`list`, so
+    # comparing it against an enum member never matches. Generic (no strict
+    # same-name join — for some APIs the param is singular and the output
+    # field is a plural list, which an exact-name detector would miss). Per-API
+    # (README), NOT the shared Conventions block, so AGENTS==CLAUDE identity holds.
+    enums = schema.get("enums")
+    if isinstance(enums, dict) and enums:
+        lines += [
+            "> **Note.** Some params accept an enum whose corresponding output "
+            "field is raw `str`/`list` (the wire value isn't bound to the enum). "
+            "Enum members never compare equal to raw strings — compare such "
+            "output values against `member.value`, or use plain string literals.",
+            "",
+        ]
+
+    if has_example:
+        lines += [
+            "## Example", "",
+            "See [`example.py`](./example.py) for a runnable usage example.", "",
+        ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_example(schema: Dict[str, Any], *, slug: str) -> Optional[str]:
+    """Render the shippable per-API ``example.py`` from the stored example, or
+    ``None`` when there is no shippable example.
+
+    The single render-time chokepoint for "is this example's self-import
+    correct". The agent authored the example before the slug existed, so its
+    self-import names the right client class but (often) the wrong module. We
+    bind the import path correct-by-construction:
+
+      * ``schema`` is the schema codegen RENDERED (so ``resolve_root_name`` is
+        the exact root class the module emits), and ``slug`` is the ASSIGNED slug
+        (the on-disk directory + import path) — passed explicitly, never the raw
+        ``schema['slug']``.
+      * The self-import is the ``from parse_apis[.…] / parse_sdk[.…] import …``
+        statement that imports the emitted root; its module token is rebound to
+        ``parse_apis.<slug>`` and the imported-names list is preserved verbatim.
+        This subsumes the legacy ``parse_sdk.`` prefix and mis-dotted cases — all
+        just "root imported from the wrong module". The parse-namespace
+        restriction (matching the collision check) means a foreign
+        ``from <lib> import <Root>`` sharing the root class name is left alone.
+
+    Returns ``None`` (the example is dropped) when it is unshippable:
+
+      * the stored code is unparseable (fail-closed — never abort the sync);
+      * it carries a CONFIRMED collision-broken self-import — it imports the
+        DECLARED root (``root_name``) that codegen suffixed away
+        (``declared != emitted``) from the generated-package namespace, which the
+        module-rebind cannot make correct (it would import the resource class).
+
+    An example with no self-import of THIS API (a minimal snippet, or one that
+    imports only OTHER APIs) carries nothing broken and ships as-is.
+
+    Scope: only the import naming the emitted root is rebound. A self-import that
+    names ONLY a resource class (e.g. ``from parse_apis.<wrong> import Listing``)
+    on its own line — not the root — is not corrected. A real usage example
+    imports the root client (handled here, mis-dotted module and all); a
+    resource-only self-import is not observed in agent output, and re-deriving the
+    module from a slug-string match is exactly the brittle predicate this rebind
+    replaced.
+    """
+    code = schema.get("sdk_usage_example")
+    if not (isinstance(code, str) and code.strip()):
+        return None
+    try:
+        tree = ast.parse(code)
+    except (SyntaxError, ValueError):
+        return None  # unparseable → unshippable (fail-closed)
+
+    emitted_root = _root_name(schema)
+    targets = _root_import_nodes(tree, emitted_root)
+    if targets:
+        code = _rewrite_import_modules(code, targets, f"parse_apis.{slug}")
+        return f"{_PY_BANNER}\n{code.rstrip()}\n"
+
+    declared_root = schema.get("root_name")
+    if (declared_root and declared_root != emitted_root
+            and _imports_from_parse_pkg(tree, declared_root)):
+        return None  # collision-broken self-import → drop
+
+    return f"{_PY_BANNER}\n{code.rstrip()}\n"
+
+
+def _api_one_liner(schema: Dict[str, Any]) -> str:
+    """A one-line summary for the cross-API index — the description's first
+    line, else the slug."""
+    desc = schema.get("description")
+    if isinstance(desc, str) and desc.strip():
+        return desc.strip().splitlines()[0]
+    return str(schema.get("slug") or "")
+
+
+def _render_index(schemas: List[Dict[str, Any]], *, base_url: str) -> str:
+    """The shared body for ``AGENTS.md`` / ``CLAUDE.md`` — a cross-API TOC
+    plus global SDK conventions. Both files get byte-identical content (two
+    real files, not a symlink — symlinks are flaky on Windows/git).
+
+    This file loads on demand (when an agent works in the generated tree), not
+    every session. The ``## APIs`` table is a bounded PREVIEW — the first 6
+    APIs (slug-sorted), each as import line + one-line summary + example
+    availability — so the index stays ~O(1) regardless of how many APIs are
+    connected; the rest are enumerated on demand from the generated tree or
+    ``parse list --json``. Each API's detail surface is its ``<slug>/README.md``.
+    """
+    lines: List[str] = [
+        _MD_BANNER, "",
+        "# Parse typed APIs", "",
+        "Typed Python clients generated by `parse sync` from your Parse APIs. "
+        "They are installed as the editable `parse_apis` package, so "
+        "`from parse_apis.<slug> import <Root>` resolves from any directory. "
+        "Each API's reference is `<slug>/README.md`; APIs marked ✓ below also "
+        "ship a runnable `<slug>/example.py`.", "",
+        "## APIs", "",
+        "| Import (client) | Summary | Example |",
+        "|---|---|---|",
+    ]
+    _ordered = sorted(schemas, key=lambda x: str(x.get("slug") or ""))
+    for s in _ordered[:_INDEX_PREVIEW_COUNT]:
+        # An unshippable example is dropped (see render_example) — the row
+        # says so instead of silently omitting it, so its absence is a fact
+        # with a remedy, not a mystery.
+        example_cell = ("✓" if s.get("_has_example")
+                        else "unavailable — fix in Parse")
+        lines.append(
+            f"| `{_md_cell(_import_line(s))}` | {_md_cell(_api_one_liner(s))} "
+            f"| {example_cell} |")
+    lines.append("")
+    if len(_ordered) > _INDEX_PREVIEW_COUNT:
+        # Don't blur local-importable (the generated tree) vs live (the server)
+        # inventory: imports come from the tree; `parse list` is server-side.
+        lines += [
+            f"_…and {len(_ordered) - _INDEX_PREVIEW_COUNT} more. For local "
+            "importable clients, "
+            "list the slug directories under `src/parse_apis/` and read each "
+            "`<slug>/README.md`; for live APIs your key can call, run "
+            "`uv run parse list --json`._",
+            "",
+        ]
+
+    lines += [
+        "## Conventions", "",
+        "- **Import model.** `from parse_apis.<slug> import <Root>`. `parse_apis` is "
+        "an installed editable package, so this import resolves from any directory — "
+        "no need to run from a particular folder.",
+        "- **Auth.** Construct a client with `api_key=...`, or rely on the configured "
+        "Parse credentials (`parse login`).",
+        "- **Pagination.** List operations return a lazy paginator — iterate it; it "
+        "fetches pages on demand and stops at the declared boundary. If the upstream "
+        "refuses deeper pages (a result-window cap), iteration raises "
+        "`PaginationLimitError` — items already yielded are valid; bound the scan "
+        "with `limit=`, or catch it (`.list()` attaches the collected items as "
+        "`err.partial_items`).",
+        "- **Field typing is best-effort.** Field types are coerced best-effort at "
+        "construction; construction never raises. An un-parseable-but-present value "
+        "is kept RAW — a `float`-typed field may hold a `str` (e.g. `'negotiable'`), "
+        "and a `bool`-typed field parses common string values like `'false'` / `'0'` "
+        "without falling back to Python truthiness. A typed field may also be "
+        "`None` if the scraper did not capture it on this object — e.g. a "
+        "detail-only field read off a summary is absent there. Validate values you "
+        "branch on; don't assume the annotation was enforced.",
+        "- **Errors.** The runtime error classes (`ParseError`, `AuthError`, "
+        "`NotFoundError`, `RateLimitError`, `UpstreamError`, "
+        "`PaginationLimitError`, …) are importable from `parse_apis`. On a caught "
+        "error read `str(e)` (the actionable message), `e.code` (the stable wire "
+        "kind), `e.status_code` (the Parse GATEWAY's HTTP status), and "
+        "`e.upstream_status_code` / `e.snippet` / `e.url` (the TARGET SITE's "
+        "status, body excerpt, and URL when the gateway relayed one). APIs also "
+        "declare typed per-API errors — subclasses listed in each README — you "
+        "can catch by name. Retries: the SDK auto-retries ONLY gateway 429 on "
+        "GET/HEAD (honoring `Retry-After`); everything else surfaces immediately.",
+        "- **Self-pacing (optional).** Each response's cost/limit headers are "
+        "parsed onto `client.last_meta` (after a successful call) and `err.meta` "
+        "(on a raised error): `credits_remaining`, `rate_limit_remaining` / "
+        "`rate_limit_reset`, `retry_after`. Read them only if you want to throttle "
+        "proactively — the SDK already handles 429 backpressure for you.",
+        f"- **Source.** Generated from {base_url}. Re-run `parse sync` to refresh; do "
+        "not hand-edit generated files.",
+        "",
+    ]
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_agents_index(schemas: List[Dict[str, Any]], *, base_url: str) -> str:
+    """Root ``AGENTS.md`` content (cross-API index + conventions)."""
+    return _render_index(schemas, base_url=base_url)
+
+
+def render_claude_index(schemas: List[Dict[str, Any]], *, base_url: str) -> str:
+    """Root ``CLAUDE.md`` content — byte-identical to ``AGENTS.md``."""
+    return _render_index(schemas, base_url=base_url)