simklcli 0.1.0__tar.gz

simklcli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.14"
+      - run: python -m pip install uv==0.12.3
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check src tests scripts
+      - run: uv run mypy src tests scripts
+
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install uv==0.12.3
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - run: uv run --python ${{ matrix.python }} pytest
+
+  artifacts:
+    name: Build and smoke-test artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.14"
+      - run: python -m pip install uv==0.12.3
+      - run: uv lock --check
+      - run: uv build --no-sources
+      - name: Smoke-test wheel
+        shell: bash
+        run: |
+          uv venv .smoke-wheel
+          uv pip install --python .smoke-wheel/bin/python dist/*.whl
+          .smoke-wheel/bin/simkl --help
+      - name: Smoke-test source distribution
+        shell: bash
+        run: |
+          uv venv .smoke-sdist
+          uv pip install --python .smoke-sdist/bin/python dist/*.tar.gz
+          .smoke-sdist/bin/simkl --help
+
+  aggregate:
+    name: CI
+    if: always()
+    needs: [quality, tests, artifacts]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every merge gate
+        env:
+          QUALITY: ${{ needs.quality.result }}
+          TESTS: ${{ needs.tests.result }}
+          ARTIFACTS: ${{ needs.artifacts.result }}
+        run: |
+          test "$QUALITY" = success
+          test "$TESTS" = success
+          test "$ARTIFACTS" = success

simklcli-0.1.0/.github/workflows/pre-release.yml

@@ -0,0 +1,39 @@
+name: Live pre-release smoke
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: simkl-live-smoke
+  cancel-in-progress: false
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: simkl-smoke
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.14"
+      - run: python -m pip install uv==0.12.3
+      - run: uv sync --locked
+      - name: Exercise core loop and restore reserved Movie
+        env:
+          SIMKL_ACCESS_TOKEN: ${{ secrets.SIMKL_SMOKE_ACCESS_TOKEN }}
+          SIMKL_CLIENT_ID: ${{ vars.SIMKL_CLIENT_ID }}
+          SIMKL_SMOKE_ACCOUNT_ID: ${{ vars.SIMKL_SMOKE_ACCOUNT_ID }}
+          SIMKL_SMOKE_MEDIA_REFERENCE: ${{ vars.SIMKL_SMOKE_MEDIA_REFERENCE }}
+        run: uv run python scripts/live_smoke.py
+      - name: Retain restoration backup and success receipt
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: smoke-evidence
+          path: smoke-*.json
+          if-no-files-found: ignore
+          retention-days: 30

simklcli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,94 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.14"
+      - run: python -m pip install uv==0.12.3
+      - name: Require CI and a successful live smoke for this exact commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          test "$(gh run list --workflow ci.yml --commit "$GITHUB_SHA" --status success --limit 100 --json databaseId --jq length)" -gt 0
+          test "$(gh run list --workflow pre-release.yml --commit "$GITHUB_SHA" --status success --limit 100 --json databaseId --jq length)" -gt 0
+      - name: Require a SemVer tag matching both package versions
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import ast
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          tree = ast.parse(Path("src/simklcli/__init__.py").read_text())
+          package_version = next(ast.literal_eval(node.value) for node in tree.body if isinstance(node, ast.Assign) and any(isinstance(t, ast.Name) and t.id == "__version__" for t in node.targets))
+          tag = os.environ["RELEASE_TAG"]
+          assert re.fullmatch(r"v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)", tag), "Expected vX.Y.Z"
+          assert tag == f"v{version}" and version == package_version, "Tag/package version mismatch"
+          PY
+      - run: uv lock --check
+      - run: uv build --no-sources
+      - name: Install and smoke-test both distribution artifacts
+        run: |
+          uv venv .release-wheel
+          uv pip install --python .release-wheel/bin/python dist/*.whl
+          .release-wheel/bin/simkl --help
+          uv venv .release-sdist
+          uv pip install --python .release-sdist/bin/python dist/*.tar.gz
+          .release-sdist/bin/simkl --help
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: release-artifacts
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/simklcli
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: release-artifacts
+          path: dist
+      - name: Publish with PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  notes:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish GitHub Release notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release create "$RELEASE_TAG" --verify-tag --generate-notes

simklcli-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Local credentials and overrides
+.env
+.env.*
+!.env.example
+!.env*.example
+
+# In-repository worktrees
+.worktrees/
+
+# Python development artifacts
+.venv/
+__pycache__/
+*.py[cod]
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+.release-wheel/
+.release-sdist/
+smoke-*.json

simklcli-0.1.0/AGENTS.md

@@ -0,0 +1,21 @@
+# simklcli
+
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked as GitHub issues in this repo, using the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+### Build specification
+
+The consolidated v1 product and engineering contract is `docs/spec.md`. Treat
+it as authoritative together with `CONTEXT.md` and the ADRs; GitHub issue
+comments provide provenance rather than a second specification surface.

simklcli-0.1.0/CONTEXT.md

@@ -0,0 +1,183 @@
+# Simkl Tracking
+
+The language used by `simkl` to describe catalog media and a user's relationship with it. These terms deliberately separate stable domain concepts from Simkl API transport vocabulary.
+
+## Authentication
+
+**PIN Authorization**:
+The interactive AUTH V2 authorization process in which the CLI displays a short code and approval link, the user approves it on Simkl's website, and the CLI receives an Access Token and Refresh Token.
+_Avoid_: Device Flow, OAuth Device Flow
+
+**Access Token**:
+The short-lived bearer credential authorizing the CLI to act for one Simkl account and registered app. AUTH V2 Access Tokens expire after seven days.
+_Avoid_: Session Token, API Key
+
+**Refresh Token**:
+The secret paired with an Access Token that renews authorization for the same account and app. Refresh replaces the Access Token and extends the Refresh Token's 180-day expiry; the Refresh Token itself does not rotate.
+_Avoid_: Permanent Token, API Key
+
+**Authenticated Account**:
+A Simkl account for which the CLI currently has an Access Token, identified by its stable Simkl account ID and display name.
+_Avoid_: Profile, Session, User
+
+## Media
+
+**Media Item**:
+The abstract umbrella for a Movie, Show, Anime, or Episode.
+_Avoid_: Content, title (when referring to every kind of item)
+
+**Catalog Metadata**:
+The non-user-specific description of a Media Item in Simkl's catalog, such as its titles, year, kind, episode structure, and Community Rating; it excludes Library state, Watched State, User Rating, and the narrow Library Display Identity retained with a Library Snapshot.
+_Avoid_: Metadata (unqualified), Item Details
+
+**Movie**:
+A standalone filmed work that can be tracked as a whole.
+_Avoid_: Film
+
+**Show**:
+A non-anime episodic television program whose episodes may be tracked individually.
+_Avoid_: TV, series
+
+**Anime**:
+An anime work, episodic or standalone, kept distinct from Show because its kinds and episode numbering follow anime-native conventions.
+_Avoid_: Animated show, Japanese show
+
+**Anime Kind**:
+A secondary classification of an Anime as TV Anime, Special, OVA, Movie, Music Video, or ONA; an Anime whose kind is Movie remains an Anime.
+_Avoid_: Media type, format
+
+**Season**:
+A numbered grouping of Episodes belonging to a Show; it is not part of the canonical structure of an Anime.
+_Avoid_: Anime season
+
+**Episode**:
+An individually trackable installment of a Show or Anime, canonically located by Episode Number and, for a Show, Season.
+_Avoid_: Chapter
+
+**Episode Number**:
+The stable number locating an Episode within a Show Season or within an Anime's anime-native episode sequence.
+_Avoid_: Episode ID
+
+**TVDB Episode Coordinates**:
+An alternate season-and-episode location assigned by TVDB to an Anime Episode, not the Anime's canonical structure.
+_Avoid_: Anime Season
+
+## User Library
+
+**Library**:
+The complete collection of Media Items tracked on a user's Simkl account, across every List Status.
+_Avoid_: Watchlist (when referring to the complete collection)
+
+**Library Snapshot**:
+The CLI's last reconciled representation of an Authenticated Account's Library state, including List Status, Watched State, User Ratings, Library Display Identity, and the activity positions needed to reconcile later changes; it excludes all other Catalog Metadata.
+_Avoid_: Library cache, local Library
+
+**Library Display Identity**:
+The minimal identifying fields retained with a Library Snapshot so its entries remain understandable: Simkl ID, title, year, and media kind.
+_Avoid_: Cached Catalog Metadata, item details
+
+**List Status**:
+The kind-constrained bucket that describes the user's current intent or relationship with a Library item; invalid combinations are not silently normalized.
+_Avoid_: Watch state, list
+
+Allowed combinations are explicit:
+
+| Media kind | Allowed List Statuses |
+| --- | --- |
+| Movie | Plan to Watch, Dropped, Completed |
+| Show | Watching, Plan to Watch, On Hold, Dropped, Completed |
+| Anime | Watching, Plan to Watch, On Hold, Dropped, Completed |
+
+**Plan to Watch**:
+The List Status for a Media Item the user intends to watch later.
+_Avoid_: Watchlist, backlog
+
+**Watching**:
+The List Status for a Show or Anime the user is actively following.
+_Avoid_: In progress
+
+**On Hold**:
+The List Status for a Show or Anime the user has paused but may resume.
+_Avoid_: Hold, paused
+
+**Dropped**:
+The List Status for a Media Item the user has stopped intending to finish.
+_Avoid_: Abandoned
+
+**Completed**:
+The List Status for a Media Item the user regards as finished; it is not, by itself, evidence of a Viewing.
+_Avoid_: Watched
+
+**Viewing**:
+A recorded occurrence of the user watching a Movie, Episode, or standalone Anime.
+_Avoid_: History entry, play
+
+**Watched State**:
+Whether a Media Item or Episode has at least one recorded Viewing.
+_Avoid_: History
+
+**Last Watched At**:
+The timestamp of the latest known Viewing, without implying that every earlier Viewing is available.
+_Avoid_: History timestamp
+
+**Bulk Watched Update**:
+A change to the Watched State of multiple applicable Episodes, optionally accompanied by a parent List Status change; it is not one Viewing of the parent.
+_Avoid_: Show viewing, mark-all viewing
+
+**Unmark Watched**:
+Clearing Watched State from a standalone Media Item, selected Episodes, or a Season while preserving the parent or standalone Media Item's Library membership, List Status, and User Rating.
+_Avoid_: Remove from history
+
+**Remove from Library**:
+Deleting a Media Item from the Library together with its associated Watched State and User Rating.
+_Avoid_: Unwatch, remove from history
+
+**Rewatch**:
+A Viewing after the first recorded Viewing of the same Movie, Episode, or standalone Anime.
+_Avoid_: Replay
+
+## Identity and Ratings
+
+**Simkl ID**:
+The permanent, globally unique identifier that canonically identifies a Media Item in Simkl.
+_Avoid_: Internal ID, canonical ID
+
+**External ID**:
+An identifier assigned by another provider, always qualified by provider and by media kind when the provider's namespace requires it.
+_Avoid_: Alternate ID, ID (when the provider is ambiguous)
+
+**Media Reference**:
+User-supplied information that resolves to a Media Item: a Simkl ID, a qualified External ID, or a title and year fallback.
+_Avoid_: Media ID, query
+
+**Episode Reference**:
+A parent Media Reference plus canonical episode coordinates—Season and Episode Number for a Show, or Episode Number for an Anime—or a qualified TVDB or AniDB episode-level External ID.
+_Avoid_: Episode ID (when no provider is named)
+
+**Slug**:
+A response-provided URL hint that is not unique and never establishes a Media Item's identity.
+_Avoid_: Slug ID
+
+**User Rating**:
+The authenticated user's personal score for a Movie, Show, or Anime on Simkl's 1–10 scale; Episodes are not rateable in the initial domain model.
+_Avoid_: Rating (when ownership is ambiguous)
+
+**Community Rating**:
+An aggregate catalog score from Simkl or another named provider.
+_Avoid_: Public rating, rating (when its source is ambiguous)
+
+## Simkl API Mapping
+
+| Domain concept | Simkl representation |
+| --- | --- |
+| Movie | `movies[]` and `/movies/{simkl_id}` |
+| Show | `shows[]`, Simkl type `tv`, and `/tv/{simkl_id}` |
+| Anime | `anime[]` and `/anime/{simkl_id}`; some synchronization responses fold Anime into `shows[]` |
+| Episode | Nested `seasons[].episodes[]` or anime-native `episodes[]` |
+| Library / List Status | `/sync/all-items` and `watching`, `plantowatch`, `hold`, `dropped`, or `completed` status tokens |
+| Viewing / Watched State | `/sync/history` and `/sync/watched`; `last_watched_at` maps to Last Watched At |
+| Unmark Watched / Remove from Library | Different granularities of `/sync/history/remove` |
+| User Rating | `/sync/ratings` |
+| Community Rating | Catalog-detail rating fields |
+| Simkl ID | `ids.simkl` or the response alias `ids.simkl_id` |
+| External ID | Any other provider-qualified field under `ids` |

simklcli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Ochoa
+
+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.

simklcli-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: simklcli
+Version: 0.1.0
+Summary: Track movies, shows, and anime on Simkl from the command line.
+Author: Javier Ochoa
+License: MIT License
+        
+        Copyright (c) 2026 Javier Ochoa
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: filelock<4,>=3.18
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: keyring<26,>=25
+Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: rich<15,>=14
+Requires-Dist: typer<1,>=0.27
+Description-Content-Type: text/markdown
+
+# simklcli
+
+`simklcli` is a public command-line client for the core Simkl tracking loop:
+authentication, catalog search and lookup, Library management, Watched State,
+and User Ratings. The PyPI distribution exposes the shorter `simkl` command.
+
+The CLI supports Simkl PIN Authorization, catalog search and lookup, Library
+management, Watched State, and User Ratings. It reconciles account state online
+and retains a dated Library Snapshot for explicit offline reads.
+
+## Install
+
+Python 3.11 or newer is required. Once the first release is published, install
+the supported package with:
+
+```sh
+uv tool install simklcli
+# or: pipx install simklcli
+```
+
+## Authentication
+
+The CLI ships with simklcli's public AUTH V2 app ID, so no developer
+registration is needed:
+
+```sh
+simkl auth login
+simkl auth status --check
+simkl search "Cowboy Bebop" --kind anime
+simkl library list
+simkl library list --offline
+```
+
+From a checkout, run the same commands through `uv sync --locked` and
+`uv run simkl …`.
+
+Login uses the V2 device-based PIN Authorization flow. Open the printed link
+and approve the application on Simkl; no client secret, redirect URL, or PKCE
+parameters are used by this flow. The client ID is public by design: on its
+own it reaches only public catalog data, and every user-scoped request also
+needs that user's Access Token.
+
+To use your own app instead, register an **AUTH V2** application as
+**TV, devices & command line** at
+[Simkl Developer Settings](https://simkl.com/settings/developer/) and set
+`SIMKL_CLIENT_ID` to its public ID before logging in. The issuing app ID is
+stored with each credential, so later invocations keep using it without the
+environment variable. An override must match the app that issued the stored
+tokens.
+
+```sh
+simkl auth login
+simkl auth status
+simkl auth status --check
+simkl auth logout
+```
+
+Login stores the Access Token and Refresh Token together in the OS keyring.
+If the platform has no usable keyring, plaintext storage must be
+selected explicitly with `simkl auth login --storage file`. Set
+`SIMKL_ACCESS_TOKEN` for a non-persisted automation override; it takes
+precedence over local credentials and must come from the built-in app or from
+the app named by `SIMKL_CLIENT_ID`.
+Environment overrides are not refreshed or persisted; supply a fresh Access
+Token when it expires. The old embedded V1 client ID has been removed.
+
+Access Tokens last seven days; the CLI refreshes shortly before expiry or once
+after an explicit token rejection. Refresh Tokens last 180 days with sliding
+expiry. Refresh and storage changes share an account lock across processes.
+Search and External ID resolution require sign-in. An anonymous known-ID lookup
+is available with `simkl lookup simkl:<id> --kind movie|show|anime`.
+
+An existing V1 account reconnects through `simkl auth login` without first
+logging out: approval must match the recorded account, and its Library Snapshot
+is retained. A failed or cancelled login preserves the existing credentials.
+Expired or revoked grants require explicit login and keep offline snapshots.
+See the [migration guide](docs/auth-v2-migration.md) for local verification.
+
+Logout removes local credentials and the Library Snapshot and makes a
+best-effort request to revoke the stored V2 grant. `--local-only` skips that
+request. Simkl acknowledges revocation without revealing whether a token was
+valid; the CLI reports acknowledgement rather than proof of revocation.
+
+Use `simkl auth status --json` for a single machine-readable stdout payload.
+The default status check is local-only; `--check` explicitly validates the
+Access Token with Simkl and refreshes the display name.
+
+## Development
+
+```sh
+uv sync --locked
+uv run ruff check .
+uv run mypy src tests scripts
+uv run pytest
+uv build --no-sources
+```
+
+## Tracking
+
+```sh
+simkl search "Cowboy Bebop" --kind anime
+simkl lookup imdb:tt0133093
+simkl lookup tmdb:603 --kind movie
+simkl library list --kind anime --status watching
+simkl library set-status simkl:3708 plan-to-watch
+simkl watched mark simkl:3708 --episode 1 --at 2026-08-08T20:00:00Z
+simkl watched mark simkl:3708 --all --yes
+simkl watched unmark simkl:3708 --episode 1
+simkl rating set simkl:3708 9
+simkl rating remove simkl:3708
+simkl library remove simkl:3708 --yes
+simkl library list --offline --json
+simkl library repair
+```
+
+Media References accept `simkl:<id>`, supported provider-qualified External
+IDs, or title text with optional `--kind` and `--year`. TMDB IDs require
+`--kind movie` or `--kind show`. An ambiguous title returns candidates and fails
+in scripts; interactive terminals can select a candidate. Search accepts
+`--page` (1–20) and `--limit` (1–50 results per media kind).
+
+Movies and standalone Anime take no Episode selectors. Shows require
+`--season N --episode N`; episodic Anime uses `--episode N` without a Season.
+Both accept `--all`; Shows also accept `--season N --all`. Bulk marks select
+aired Episodes. `--episode-id tvdb:<id>` or `--episode-id anidb:<id>` accepts an
+episode-level External ID with a parent Media Reference. When a response to
+such a write is lost, parent state alone cannot prove which Episode changed,
+so the CLI reports an unknown outcome instead of encouraging a blind retry.
+
+`watched mark --rewatch` explicitly records another Viewing and requires
+Simkl PRO or VIP. Use `--rewatch-id` to resume a specific known session.
+Unmark Watched preserves Library membership, List Status, and User Rating;
+`library remove` deletes all three along with Watched State.
+Simkl makes Completed Movies watched automatically, so `watched unmark` rejects
+that case before changing anything. Use an explicit `library set-status` move
+to `plan-to-watch` or `dropped` to clear a Movie's Watched State while keeping
+its User Rating.
+
+Every command accepts `--json`: stdout contains one JSON result, diagnostics
+go to stderr, and prompts are disabled. Whole-item removal, bulk updates, and
+logout require `--yes` in JSON or noninteractive use. User Ratings range from
+1 to 10 and apply to Movies, Shows, and Anime.
+
+Environment-token accounts can read their snapshots offline after one online
+Library read validates their identity. Only a token fingerprint and account ID
+are retained for that association; the Access Token is never persisted.
+
+Online Library reads check activities, merge changed List Status and rating
+state, and compare IDs when removals occur. Offline reads require a complete
+snapshot and report its age. Focused writes work before that first complete
+read. A successful remote write followed by failed reconciliation reports
+success and dirty local state; the next online read reconciles it. No writes
+are queued or automatically replayed.
+
+## Releases
+
+The [release guide](docs/releasing.md) describes the mandatory live smoke,
+restoration backup, GitHub environments, PyPI Trusted Publishing, and version
+tag checks. Merge-gating tests use authored HTTPX responses and never contact
+Simkl; the manually triggered smoke is the only live test workflow.
+
+## Project map
+
+- [`docs/spec.md`](docs/spec.md) — build-ready v1 product and engineering specification
+- [`CONTEXT.md`](CONTEXT.md) — canonical domain vocabulary
+- [`docs/adr/`](docs/adr/) — architectural decisions
+- [`docs/research/`](docs/research/) — cited API and prior-art research
+- [`src/simklcli/`](src/simklcli/) — installable tracking CLI
+- [`tests/`](tests/) — offline unit, HTTPX transport, and Typer CLI tests
+- [`prototypes/command-surface/`](prototypes/command-surface/) — runnable Typer command-surface prototype
+
+Run the prototype from the repository root:
+
+```sh
+./prototypes/command-surface/run surface
+./prototypes/command-surface/run --help
+```
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).