litestar-pagination 0.2.0__tar.gz

litestar_pagination-0.2.0/.agents/skills/async-python-patterns/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: async-python-patterns
+description: Async patterns for litestar-pagination: AsyncSession execution, async cursor pagination, Litestar request-scoped sessions, cancellation, sync/async parity, and pytest-asyncio tests. Use when implementing or reviewing async code in this project.
+---
+
+# Async Python Patterns — litestar-pagination
+
+Combine this skill with `python-pro` for async implementation or review.
+
+## Evidence first
+
+- Read `AGENTS.md`, `PRD.md`, and `TECHSTACK.md`.
+- Use Context7 for current `AsyncSession`, Litestar DI, Advanced Alchemy session, sqlakeyset async, and pytest-asyncio behavior.
+- Trace the sync path before duplicating it asynchronously; shared pure query construction belongs in one helper.
+
+## Rules
+
+- `apaginate()` accepts an existing request-scoped `AsyncSession`; it never creates, commits, closes, or owns that session.
+- Await count and page queries explicitly and preserve their SQLAlchemy exceptions.
+- Do not call sync session methods, blocking I/O, `time.sleep()`, or synchronous database drivers in async code.
+- Keep cursor decoding and query construction synchronous when they are CPU-only and trivial.
+- Re-raise `asyncio.CancelledError` after cleanup; do not convert cancellation into pagination errors.
+- Do not add concurrent count/page execution without evidence: they share a session/transaction and many drivers prohibit simultaneous operations.
+- Keep `paginate()` and `apaginate()` behavior symmetric. Differences require tests and documentation.
+
+## Litestar and Advanced Alchemy
+
+- Advanced Alchemy owns engine/session lifecycle; consume its injected session unchanged.
+- Use Litestar dependency injection for `CursorParams`; no pagination plugin or route patching.
+- Request state must not be stored in module globals or mutable singletons.
+
+## Tests
+
+- pytest-asyncio runs in auto mode; do not add `@pytest.mark.asyncio` by habit.
+- Test against real async SQLite and PostgreSQL drivers, not `AsyncMock` session behavior.
+- Pair important sync and async cases: first/last page, forward/backward traversal, malformed cursor, count override, and no-total mode.
+- Assert observable page contents and bookmarks, not internal await counts.
+
+See `resources/implementation-playbook.md` for the canonical shape.

litestar_pagination-0.2.0/.agents/skills/async-python-patterns/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Async Python Patterns"
+  short_description: "Async SQLAlchemy cursor-pagination patterns."
+  default_prompt: "Use $async-python-patterns to review or implement async cursor pagination with correct AsyncSession ownership, cancellation, parity, and tests."
+
+policy:
+  allow_implicit_invocation: true

litestar_pagination-0.2.0/.agents/skills/async-python-patterns/resources/implementation-playbook.md

@@ -0,0 +1,40 @@
+# Async Pagination — Implementation Playbook
+
+## Request-scoped session
+
+```python
+@get("/users")
+async def list_users(
+    db_session: AsyncSession,
+    pagination: CursorParams,
+) -> CursorPage[User]:
+    statement = select(User).order_by(User.created_at, User.id)
+    return await apaginate(db_session, statement, pagination)
+```
+
+The session is injected and owned by Litestar/Advanced Alchemy. `apaginate()` only executes statements.
+
+## Shared query construction
+
+Keep statement validation, count-statement construction, cursor decoding, and result normalization in synchronous pure helpers. Sync and async entrypoints should differ only at execution boundaries.
+
+## Do not parallelize one session
+
+Do not run count and page statements concurrently on the same `AsyncSession`. Execute them in the documented order so transaction and driver behavior remains predictable.
+
+## Async tests
+
+```python
+import pytest
+
+
+pytestmark = pytest.mark.integration
+
+
+async def test_next_page(async_session: AsyncSession) -> None:
+    first = await apaginate(async_session, statement, CursorParams(size=2))
+    second = await apaginate(async_session, statement, CursorParams(cursor=first.next_page, size=2))
+    assert [item.id for item in second.items] == [3, 4]
+```
+
+Use real async database drivers and pytest-asyncio auto mode.

litestar_pagination-0.2.0/.agents/skills/github-actions-pin-refresh/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: github-actions-pin-refresh
+description: "Audit `.github` workflows for remote `uses:` entries pinned to full commit SHAs, resolve the newest intended upstream refs, refresh the pinned SHAs, and update trailing version comments when they change. Use when reviewing stale GitHub Actions pins or normalizing `uses: owner/repo@SHA # vX.Y.Z` lines."
+---
+
+# GitHub Actions Pin Refresh
+
+Use this skill when changing `.github/workflows/*.yml` or reusable workflows that pin remote actions by full SHA.
+
+Use AgentMemory for prior CI/release decisions before changing workflow behavior. CodeGraph is usually unnecessary for pin-only edits; use it only if workflow changes require code impact analysis.
+
+## Goal
+
+Keep remote `uses:` lines on full 40-character commit SHAs while moving them to the newest intended upstream version and keeping the trailing `# ...` comment honest.
+
+## Inventory First
+
+Run the bundled check before editing:
+
+```bash
+python3 .agents/skills/github-actions-pin-refresh/scripts/list_pinned_actions.py --check
+python3 .agents/skills/github-actions-pin-refresh/scripts/list_pinned_actions.py --format json
+```
+
+`--check` exits nonzero for a mutable remote GitHub-hosted ref. The inventory command lists existing full-SHA pins like:
+
+```yaml
+uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+```
+
+It intentionally ignores local actions (`./...`) and docker actions.
+
+## Update Workflow
+
+For each unique `owner/repo[/path]` found under `.github/`:
+
+1. Read the current trailing comment, if any.
+2. Resolve the target upstream ref:
+   - Default: the newest stable release or tag.
+   - Ignore prereleases unless the current pin already tracks one or the user explicitly asks for prereleases.
+   - If the existing comment is a channel such as `v4`, `v4.1`, `main`, or `master`, preserve that channel unless the user explicitly asks for a cross-channel or cross-major jump.
+3. Resolve the exact commit SHA for that ref.
+4. Rewrite the YAML to keep full-SHA pinning:
+   - `uses: owner/repo[/path]@<40-char-commit-sha> # <comment>`
+5. Update the trailing comment when needed:
+   - exact-version comments such as `# v6.0.2` should become the new exact tag;
+   - channel comments such as `# v6`, `# v6.1`, or `# main` stay channel comments;
+   - if comments are used consistently in the file and one pinned action is missing its comment, add the resolved ref comment.
+6. If the update crosses a major version, skim upstream release notes or changelog before finalizing and adjust the workflow if required (inputs, permissions, Node/runtime expectations, removed flags).
+
+## Resolve Refs Without Guessing
+
+Prefer GitHub CLI when it is available.
+
+### Latest Stable Release
+
+```bash
+gh api repos/{owner}/{repo}/releases/latest
+```
+
+Use this when the action publishes stable GitHub releases.
+
+### Exact Tag or Branch Ref
+
+```bash
+gh api repos/{owner}/{repo}/git/ref/tags/{tag}
+gh api repos/{owner}/{repo}/git/ref/heads/{branch}
+```
+
+Annotated tags point to tag objects, not directly to commits. Dereference them:
+
+```bash
+gh api repos/{owner}/{repo}/git/tags/{tag_object_sha}
+```
+
+Use the nested `object.sha` commit as the final pin when the tag is annotated.
+
+### When `releases/latest` Is Unavailable
+
+```bash
+gh api repos/{owner}/{repo}/tags?per_page=100
+```
+
+Pick the newest stable semver tag that matches the intended track. Do not upgrade a stable track to a prerelease.
+
+If GitHub CLI is unavailable, fall back to GitHub's web/API surface or `git ls-remote` for exact refs. Still resolve to a commit SHA and keep the workflow pinned to that full SHA.
+
+## Editing Rules
+
+- Never replace a full-SHA pin with a mutable tag or branch.
+- Preserve `owner/repo/path` subpaths for nested actions and reusable workflows.
+- Keep one upstream ref per action family consistent across the repo unless a workflow intentionally needs a different version.
+- Do not invent comments that you cannot justify from the resolved upstream ref.
+- If an upstream release changes required permissions or inputs, update the workflow in the same change.
+- Keep YAML formatting and indentation stable so the diff is easy to review.
+
+## Verification
+
+- Re-run the bundled `--check` to confirm every remote GitHub-hosted `uses:` line is pinned to a 40-character SHA.
+- Review `rg "uses:" .github -n` and the `.github` diff.
+- For workflow-only pin refreshes, run the workflow-specific checks from `AGENTS.md`:
+  ```bash
+  python3 .agents/skills/github-actions-pin-refresh/scripts/list_pinned_actions.py --check
+  python3 .agents/skills/github-actions-pin-refresh/scripts/list_pinned_actions.py --format text
+  rg "uses:" .github -n
+  git diff -- .github
+  ```
+- If the workflow change modifies job commands, permissions, matrices, release behavior, or anything that changes how the library is built, tested, published, or deployed, also run the relevant targeted project checks. Use the full Python verification block only when the workflow change needs local evidence that the library test/build path still works.

litestar_pagination-0.2.0/.agents/skills/github-actions-pin-refresh/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "GitHub Actions Pin Refresh"
+  short_description: "Refresh pinned GitHub Action SHAs and version comments."
+  default_prompt: "Use $github-actions-pin-refresh to audit .github workflows, update pinned action SHAs to the intended latest upstream refs, and fix trailing version comments."
+
+policy:
+  allow_implicit_invocation: true

litestar_pagination-0.2.0/.agents/skills/github-actions-pin-refresh/scripts/list_pinned_actions.py

@@ -0,0 +1,259 @@
+"""Inventory and validate GitHub-hosted ``uses:`` entries under ``.github``."""  # noqa: INP001
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+FULL_SHA_PATTERN = re.compile(r"[0-9a-fA-F]{40}\Z")
+USES_PATTERN = re.compile(
+    r"^\s*(?:-\s*)?uses:\s*"
+    r"(?P<slug>[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:/[^\s@#]+)?)"
+    r"@(?P<ref>[^\s#]+)"
+    r"(?:\s*#\s*(?P<comment>.*?))?\s*$",
+)
+YAML_SUFFIXES = frozenset({".yml", ".yaml"})
+DEFAULT_REPO_ROOT = Path(__file__).resolve().parents[4]
+DEFAULT_GITHUB_DIR = DEFAULT_REPO_ROOT / ".github"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowUse:
+    """A GitHub-hosted ``uses:`` entry from a workflow-related YAML file."""
+
+    file: str
+    line: int
+    slug: str
+    ref: str
+    comment: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PinnedAction:
+    """A remote GitHub Action or reusable workflow pinned to a commit SHA."""
+
+    file: str
+    line: int
+    repository: str
+    subpath: str | None
+    uses_target: str
+    sha: str
+    comment: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class UnpinnedAction:
+    """A remote GitHub Action or reusable workflow not pinned to a full SHA."""
+
+    file: str
+    line: int
+    uses_target: str
+    ref: str
+    comment: str | None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser.
+
+    Returns:
+        The configured parser.
+    """
+    parser = argparse.ArgumentParser(
+        description="List or validate remote GitHub-hosted uses: entries under .github.",
+    )
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=DEFAULT_REPO_ROOT,
+        help="Repository root used to relativize file paths.",
+    )
+    parser.add_argument(
+        "--github-dir",
+        type=Path,
+        default=DEFAULT_GITHUB_DIR,
+        help="Directory to scan for workflow YAML files.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="Output format.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Exit nonzero when a remote GitHub-hosted uses: entry is not pinned to a full SHA.",
+    )
+    return parser
+
+
+def iter_yaml_files(github_dir: Path) -> list[Path]:
+    """Return YAML files under a validated GitHub directory.
+
+    Returns:
+        Workflow-related YAML files in deterministic order.
+    """
+    return sorted(path for path in github_dir.rglob("*") if path.is_file() and path.suffix in YAML_SUFFIXES)
+
+
+def display_path(path: Path, *, repo_root: Path) -> str:
+    """Return a repo-relative display path when possible.
+
+    Returns:
+        A display path.
+    """
+    try:
+        return path.relative_to(repo_root).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def parse_workflow_use(line: str, *, file: Path, line_number: int, repo_root: Path) -> WorkflowUse | None:
+    """Parse one remote GitHub-hosted ``uses:`` line.
+
+    Returns:
+        The parsed entry, or ``None`` for local, Docker, and unrelated lines.
+    """
+    match = USES_PATTERN.match(line)
+    if match is None:
+        return None
+
+    comment = match.group("comment")
+    return WorkflowUse(
+        file=display_path(file, repo_root=repo_root),
+        line=line_number,
+        slug=match.group("slug"),
+        ref=match.group("ref"),
+        comment=(comment.strip() or None) if comment is not None else None,
+    )
+
+
+def parse_pinned_action(line: str, *, file: Path, line_number: int, repo_root: Path) -> PinnedAction | None:
+    """Parse one fully pinned remote GitHub-hosted ``uses:`` line.
+
+    Returns:
+        The parsed pinned entry, or ``None`` when the line is not a full-SHA pin.
+    """
+    workflow_use = parse_workflow_use(line, file=file, line_number=line_number, repo_root=repo_root)
+    if workflow_use is None or FULL_SHA_PATTERN.fullmatch(workflow_use.ref) is None:
+        return None
+
+    owner, repository_name, *subpath_parts = workflow_use.slug.split("/")
+    return PinnedAction(
+        file=workflow_use.file,
+        line=workflow_use.line,
+        repository=f"{owner}/{repository_name}",
+        subpath="/".join(subpath_parts) or None,
+        uses_target=workflow_use.slug,
+        sha=workflow_use.ref.lower(),
+        comment=workflow_use.comment,
+    )
+
+
+def collect_pinned_actions(*, repo_root: Path, github_dir: Path) -> list[PinnedAction]:
+    """Collect full-SHA pins from workflow-related YAML files.
+
+    Returns:
+        Parsed full-SHA pins.
+    """
+    pinned_actions: list[PinnedAction] = []
+    for workflow_file in iter_yaml_files(github_dir):
+        for line_number, line in enumerate(workflow_file.read_text(encoding="utf-8").splitlines(), start=1):
+            if pinned_action := parse_pinned_action(
+                line,
+                file=workflow_file,
+                line_number=line_number,
+                repo_root=repo_root,
+            ):
+                pinned_actions.append(pinned_action)
+    return pinned_actions
+
+
+def collect_unpinned_actions(*, repo_root: Path, github_dir: Path) -> list[UnpinnedAction]:
+    """Collect remote GitHub-hosted entries that are not full-SHA pins.
+
+    Returns:
+        Parsed mutable references.
+    """
+    unpinned_actions: list[UnpinnedAction] = []
+    for workflow_file in iter_yaml_files(github_dir):
+        for line_number, line in enumerate(workflow_file.read_text(encoding="utf-8").splitlines(), start=1):
+            workflow_use = parse_workflow_use(line, file=workflow_file, line_number=line_number, repo_root=repo_root)
+            if workflow_use is not None and FULL_SHA_PATTERN.fullmatch(workflow_use.ref) is None:
+                unpinned_actions.append(
+                    UnpinnedAction(
+                        file=workflow_use.file,
+                        line=workflow_use.line,
+                        uses_target=workflow_use.slug,
+                        ref=workflow_use.ref,
+                        comment=workflow_use.comment,
+                    ),
+                )
+    return unpinned_actions
+
+
+def render_text(items: list[PinnedAction] | list[UnpinnedAction]) -> str:
+    """Render action items in a concise, human-readable form.
+
+    Returns:
+        Rendered lines, or an empty string for an empty list.
+    """
+    if not items:
+        return ""
+
+    if isinstance(items[0], PinnedAction):
+        lines = ["file:line | target | sha | comment"]
+        lines.extend(
+            f"{item.file}:{item.line} | {item.uses_target} | {item.sha} | {item.comment or '-'}" for item in items
+        )
+    else:
+        lines = ["file:line | target | mutable ref | comment"]
+        lines.extend(
+            f"{item.file}:{item.line} | {item.uses_target} | {item.ref} | {item.comment or '-'}" for item in items
+        )
+    return "\n".join(lines)
+
+
+def write_items(items: list[PinnedAction] | list[UnpinnedAction], *, output_format: str) -> None:
+    """Write action items in the selected format."""
+    if output_format == "json":
+        json.dump([asdict(item) for item in items], sys.stdout, indent=2, ensure_ascii=False)
+        sys.stdout.write("\n")
+        return
+
+    text_output = render_text(items)
+    if text_output:
+        sys.stdout.write(text_output)
+        sys.stdout.write("\n")
+
+
+def main() -> int:
+    """Run the inventory or validation command.
+
+    Returns:
+        A process exit code.
+    """
+    parser = build_parser()
+    args = parser.parse_args()
+    repo_root = args.repo_root.resolve()
+    github_dir = args.github_dir.resolve()
+    if not github_dir.is_dir():
+        sys.stderr.write(f"[ERROR] GitHub directory does not exist or is not a directory: {github_dir}\n")
+        return 2
+
+    if args.check:
+        unpinned_actions = collect_unpinned_actions(repo_root=repo_root, github_dir=github_dir)
+        write_items(unpinned_actions, output_format=args.format)
+        return int(bool(unpinned_actions))
+
+    pinned_actions = collect_pinned_actions(repo_root=repo_root, github_dir=github_dir)
+    write_items(pinned_actions, output_format=args.format)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

litestar_pagination-0.2.0/.agents/skills/python-packaging/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: python-packaging
+description: Packaging guide for litestar-pagination: hatchling, uv, commitizen, optional SQLAlchemy/Advanced Alchemy extras, dependency groups, builds, and releases. Use for pyproject, dependencies, lockfiles, CI packaging, or publishing work.
+---
+
+# Python Packaging — litestar-pagination
+
+## Evidence first
+
+- Read `AGENTS.md`, `PRD.md`, `TECHSTACK.md`, and `pyproject.toml`.
+- Use Context7 or official project docs when tool/dependency behavior matters.
+- Treat `pyproject.toml` and `uv.lock` as authoritative.
+
+## Project shape
+
+- Distribution: `litestar-pagination`; flat import package: `litestar_pagination`.
+- Build backend: hatchling.
+- Supported Python: `>=3.12.0,<3.15.0`.
+- Base dependency: Litestar.
+- Public extras: `sqlalchemy`, `advanced-alchemy`, and `all`.
+- Dev/docs tools belong in PEP 735 dependency groups, not public extras.
+- `[tool.uv] default-groups = []` keeps installs minimal.
+
+## Dependency rules
+
+- Use uv, not ad-hoc pip or manually managed virtualenvs.
+- Use compatible ranges `>=X,<NEXT_MAJOR`; exact resolutions belong in `uv.lock`.
+- SQLAlchemy and sqlakeyset remain optional and must not leak into root imports.
+- The Advanced Alchemy extra includes the SQLAlchemy integration.
+- Update extras, lockfile, docs, deptry configuration, and CI together when dependencies change.
+
+```bash
+uv sync
+uv sync --frozen --all-extras --group dev
+uv lock
+```
+
+## Version and release
+
+- Commitizen uses conventional commits and PEP 621 versioning.
+- Version is mirrored in `pyproject.toml` and `litestar_pagination/__init__.py`.
+- Tags are bare semantic versions without a `v` prefix.
+- Build with `uv build`; publish only when explicitly authorized.
+- Verify wheel contents include `py.typed` and optional imports remain absent from base installation.
+
+## Verification
+
+Run the full block in `AGENTS.md`, plus `uv build` for build/release changes. `uv run pip-audit` is best effort when network is available.
+
+See `resources/implementation-playbook.md` for common commands.

litestar_pagination-0.2.0/.agents/skills/python-packaging/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Python Packaging"
+  short_description: "Packaging, uv, dependencies, build, release."
+  default_prompt: "Use $python-packaging to modify or review pyproject.toml, uv dependencies, optional extras, build settings, or release tooling."
+
+policy:
+  allow_implicit_invocation: true

litestar_pagination-0.2.0/.agents/skills/python-packaging/resources/implementation-playbook.md

@@ -0,0 +1,34 @@
+# Packaging — Implementation Playbook
+
+## Authoritative files
+
+- `pyproject.toml`: metadata, dependencies, tools, build, and versioning.
+- `uv.lock`: exact resolution used by CI.
+- `litestar_pagination/__init__.py`: mirrored package version.
+- `AGENTS.md`: verification commands.
+
+## Common commands
+
+```bash
+uv lock
+just setup
+uv run ruff check --fix .
+uv run ruff format .
+uv run ty check
+uv run deptry .
+just test
+uv build
+```
+
+## Extras
+
+- Base: Litestar dataclass/DI/OpenAPI surface.
+- `sqlalchemy`: SQLAlchemy and sqlakeyset adapter.
+- `advanced-alchemy`: Advanced Alchemy compatibility plus SQLAlchemy adapter.
+- `all`: every public integration.
+
+Keep optional imports lazy and test a base-only installation before release.
+
+## Release
+
+Commitizen updates `pyproject.toml` and `litestar_pagination/__init__.py`, refreshes `uv.lock`, and creates a bare semantic-version tag. GitHub Actions builds reproducible artifacts and publishes through trusted PyPI OIDC only after the tag test workflow succeeds.

litestar_pagination-0.2.0/.agents/skills/python-pro/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: python-pro
+description: Python 3.12+ coding standards for litestar-pagination: modern typing, dataclass contracts, optional integration boundaries, Ruff ALL rules, cursor validation, and public API conventions. Use proactively when writing or reviewing Python code in this project.
+---
+
+# Python Pro — litestar-pagination
+
+Use this skill for all Python implementation and review work in this repository.
+
+## Evidence first
+
+- Read `AGENTS.md`, `PRD.md`, `TECHSTACK.md`, and relevant code before editing.
+- Use CodeGraph for flows and impact when `.codegraph/` exists.
+- Use Context7 for current Litestar, Advanced Alchemy, SQLAlchemy, sqlakeyset, or pytest APIs.
+- Do not infer behavior from `fastapi-pagination`; inspect it only as prior art and preserve this project's PRD.
+
+## Python and typing
+
+- Support Python 3.12–3.14 and use built-in generics, `X | None`, PEP 695 type aliases/generics, `Self`, and `override` where useful.
+- Fully annotate every public function and method. Keep sync `paginate()` and async `apaginate()` return types precise.
+- Use `collections.abc` for `Sequence`, `Callable`, and iterator interfaces.
+- Prefer narrow helpers and explicit type guards over repeated `cast()`.
+- Put import-only dependencies behind `TYPE_CHECKING` when that preserves optional-import boundaries.
+
+## Public contracts
+
+- Use standard-library dataclasses for `CursorParams` and `CursorPage`; do not add Pydantic.
+- Keep root imports lightweight and stable. SQLAlchemy APIs live in `litestar_pagination.ext.sqlalchemy`.
+- Do not import optional SQLAlchemy or Advanced Alchemy dependencies from the package root.
+- Public query names, response fields, defaults, and cursor semantics come from `PRD.md`.
+
+## Error handling and trust boundaries
+
+- Catch the narrowest exception and chain translated errors with `raise ... from error`.
+- Preserve SQLAlchemy execution errors; do not relabel database failures as client input failures.
+- Invalid external cursors map to Litestar HTTP 400. Missing ordering and unsupported statement shapes are developer errors.
+- Never place decoded bookmark values or sensitive query data in logs or error responses.
+- Base64 is encoding, not encryption or signing; do not imply otherwise.
+
+## Ruff and style
+
+- Ruff uses `ALL`, preview mode, Google docstrings, 120-character lines, and Python 3.12 syntax.
+- Use `msg = "..."; raise Error(msg)` when required by Ruff's exception-message rules.
+- Use stdlib → third-party → local import order.
+- Every `# pragma: no cover` must include a reason.
+- Prefer deletion and direct code over factories, registries, protocols, and abstractions without two real consumers.
+
+## Verification
+
+Before completion claims, use `verification-before-completion`. For Python changes run the full verification block in `AGENTS.md`.

litestar_pagination-0.2.0/.agents/skills/python-pro/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Python Pro"
+  short_description: "Python 3.12+ standards for litestar-pagination."
+  default_prompt: "Use $python-pro to write or review Python code in this project with modern typing, Ruff ALL compliance, and project conventions."
+
+policy:
+  allow_implicit_invocation: true

litestar_pagination-0.2.0/.agents/skills/python-testing-patterns/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: python-testing-patterns
+description: Test-writing guide for litestar-pagination. Use for pytest tests covering cursor codecs, keyset traversal, SQLAlchemy sync/async behavior, Litestar DI/OpenAPI/DTO integration, Advanced Alchemy sessions, and supported databases.
+---
+
+# Python Testing Patterns — litestar-pagination
+
+Combine this skill with `python-pro`; also use `async-python-patterns` for async tests.
+
+## Evidence first
+
+- Read `AGENTS.md`, `PRD.md`, `TECHSTACK.md`, and the public API under test.
+- Use Context7 when assertions depend on current Litestar, SQLAlchemy, sqlakeyset, Advanced Alchemy, or pytest behavior.
+- Use CodeGraph for test-impact discovery when available.
+
+## Test shape
+
+- Use markers: `unit`, `integration`, and `e2e`.
+- pytest-asyncio uses auto mode and a session-scoped loop.
+- Prefer behavior assertions through public imports and functions.
+- Keep fixtures narrow and data deterministic. Avoid helper layers that hide ordering or bookmark inputs.
+- Do not mock SQLAlchemy/sqlakeyset semantics. Use real SQLite/PostgreSQL engines and sessions.
+
+## Required behavior coverage
+
+- Codec round trips and malformed cursor HTTP 400 behavior.
+- Size defaults and boundaries through Litestar DI.
+- Forward and backward traversal without duplicates or omissions on a stable dataset.
+- Ascending, descending, and compound ordering with duplicate leading values and a unique tie-breaker.
+- Missing ordering and unsupported select shapes as developer errors.
+- Entity result unwrapping and uniquification.
+- Default, custom, and disabled total counting.
+- Sync/async parity on SQLite and PostgreSQL.
+- OpenAPI, dataclass serialization, and `SQLAlchemyDTO` transformation inside `items`.
+- Sessions injected by Advanced Alchemy without an additional plugin.
+
+## Quality
+
+- Tests should fail for one clear reason and assert external behavior before implementation details.
+- Use parametrization for small matrices; keep dialect-specific expectations explicit.
+- Do not add tautological tests or branches solely to satisfy coverage.
+- Run the verification block from `AGENTS.md` for library/test changes.

litestar_pagination-0.2.0/.agents/skills/python-testing-patterns/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Python Testing Patterns"
+  short_description: "Pytest patterns for cursor pagination."
+  default_prompt: "Use $python-testing-patterns to add or review behavior-focused cursor, SQLAlchemy, Litestar, and Advanced Alchemy tests."
+
+policy:
+  allow_implicit_invocation: true