docs: add examples for centralized SDK docs

[quettabit]

No description provided.

[greptile-apps]

Greptile Summary

This PR adds five runnable documentation example scripts under examples/docs/ covering SDK overview, configuration, account/basin management, streams, and metrics. It also renames the poethepoet tasks to a consistent kebab-case convention and updates the CI workflow step accordingly.

All changes are non-breaking and the example scripts are well-structured with ANCHOR/ANCHOR_END markers for the docs build system.

Confidence Score: 5/5

Safe to merge — all findings are P2 style suggestions with no correctness or runtime impact.

No P0 or P1 issues found. The two P2 findings (unclosed clients in a docs-only script and an accidentally removed module docstring) are minor quality notes that do not affect correctness, security, or the existing SDK behaviour.

examples/docs/configuration.py — S2 clients created outside async context managers may emit ResourceWarning at runtime.

Vulnerabilities

No security concerns identified. Access tokens are read from environment variables, not hardcoded, in all runnable scripts. The only hardcoded token value ("local-token") is scoped to a localhost endpoint example in the configuration docs.

Important Files Changed

Filename	Overview
.github/workflows/ci.yml	Renames the CI step label and poe task reference from ci_checker to cq-check, matching the updated pyproject.toml task names.
examples/docs/account_and_basins.py	New documentation example file covering basin CRUD, stream CRUD, access-token management, and pagination — well-structured with ANCHOR markers for the docs build system.
examples/docs/configuration.py	New documentation example for SDK configuration; creates three S2 client instances at module level without async context managers, so __aenter__/__aexit__ is never called and the underlying HTTP transport is not cleanly shut down when the script exits.
examples/docs/metrics.py	New documentation example for account/basin/stream metrics queries — clean and complete.
examples/docs/overview.py	New documentation example showing minimal client creation; runs at module level without I/O, so no cleanup is needed.
examples/docs/streams.py	New documentation example for stream append, read, append-session, producer, and check-tail; read_session_* helpers are intentionally excluded from main() since they loop indefinitely on a live stream.
pyproject.toml	Renames poe tasks to a consistent kebab-case scheme (cq-check, cq-fix, etc.) and aligns with the CI workflow change.
src/s2_sdk/_compression.py	Removes the module-level docstring; no functional change to the compression logic itself.

Sequence Diagram

sequenceDiagram
    participant Script
    participant S2 Client
    participant Account API
    participant Basin API
    participant Stream API

    Script->>S2 Client: S2(access_token)
    S2 Client-->>Script: client

    Script->>Account API: list_basins()
    Script->>Account API: create_basin("my-events")
    Script->>Account API: get_basin_config("my-events")
    Script->>Account API: delete_basin("my-events")

    Script->>Basin API: list_streams(prefix="user-")
    Script->>Basin API: create_stream("user-actions")
    Script->>Basin API: get_stream_config("user-actions")
    Script->>Basin API: delete_stream("user-actions")

    Script->>Account API: list_access_tokens()
    Script->>Account API: issue_access_token(...)
    Script->>Account API: revoke_access_token(...)

    Script->>Stream API: append(records)
    Stream API-->>Script: AppendAck (start/end seq_num)
    Script->>Stream API: read(start, limit)
    Stream API-->>Script: batch of records
    Script->>Stream API: check_tail()
    Stream API-->>Script: tail seq_num

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: examples/docs/configuration.py
Line: 15-21

Comment:
**`S2` clients not closed — possible ResourceWarning**

All three `S2` instances are created at module level without an `async with` block, so `__aenter__`/`__aexit__` is never called and the underlying HTTP transport pool is never shut down. On CPython this typically produces `ResourceWarning: Unclosed client session` at script exit. Since this file is intended to be runnable as a script, consider wrapping each snippet in a small `async def` and calling `await client.aclose()` (or using `async with`) to avoid noisy warnings that might confuse readers who run the examples.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/s2_sdk/_compression.py
Line: 1

Comment:
**Module docstring removed**

The previous docstring `"""S2S message-level compression (zstd and gzip)."""` was removed in this PR. The intent isn't clear — if it's part of a broader cleanup that's fine, but if it was unintentional it's worth restoring for IDE discoverability and `help()` output.

```suggestion
"""S2 message-level compression (zstd and gzip)."""

```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "initial commit" | Re-trigger Greptile}