kryten-webqueue 0.36.7__tar.gz → 0.37.0__tar.gz

kryten_webqueue-0.37.0/AGENTS.md

@@ -0,0 +1,71 @@
+# Kryten-WebQueue — Project Guidelines
+
+Kryten-WebQueue is the **web/HTTP layer** of the Kryten ecosystem: a Netflix/Tubi-style
+catalog browser and pay-to-play queue manager for a CyTube channel. It is a FastAPI +
+uvicorn app that serves the public site, enriches a local catalog mirrored from **MediaCMS**,
+and drives playback by issuing commands through **kryten-api-gate**. Unlike the NATS-only
+microservices, this is a user-facing HTTP application with its own SQLite database.
+
+## Architecture
+- **FastAPI app** (`kryten_webqueue/app.py`) — routers under `routes/`, Jinja2 `templates/`,
+  `static/` assets, WebSockets under `ws/` (queue + race views). Auth is a JWT **session
+  cookie** (`auth/session.py`); admin routes require rank ≥ 3 (`require_admin`).
+- **Local catalog in SQLite** via `aiosqlite` (`catalog/db/`). Schema + **forward-only
+  migrations** live in `catalog/db/_connection.py` (bump the version and add a migration;
+  never rewrite an applied one). DB path comes from config (`db_path`).
+- **Catalog sync** (`catalog/sync.py`) mirrors items + facets from MediaCMS. It bulk-pulls
+  tags/categories via `GET /api/v1/media_facets` (falls back to per-item detail on stock
+  CMS). `set_catalog_tags` is a **REPLACE** — **CMS is the source of truth for tags**.
+- **Enrichment pipeline** (`catalog/enrichment/`): `sync → classify → title → meta → art →
+  tags → categories`. TMDB/OMDB lookups in `providers.py`; all title normalization in
+  `normalise.py` (`normalize_movie_title`). Classification is **cached** in enrichment state;
+  classify-logic changes only reach existing items on a `force` re-run.
+- **Jobs** (`jobs/`): `JobManager` runs single-flight background jobs with **schema-validated
+  params** (`catalog_enrich`, `catalog_sync`, …) and APScheduler cron (`job_scheduler.py`).
+  The `steps` param is a **validated enum** — only fixed combos are accepted (e.g.
+  `all`, `classify,meta,art,tags`, `classify,meta`, `art`, `tags`, `title`, `sync`,
+  `classify`); arbitrary combos return HTTP 400.
+- **External surfaces**: MediaCMS over HTTP (catalog source, art, tag/title writes) and
+  kryten-api-gate (playback commands, via `api_gate_url`/`api_gate_token`). **Working on the
+  MediaCMS instance and our local patches: see [scripts/AGENTS.md](scripts/AGENTS.md).**
+
+## Build and Test
+Run from the repo root (uv-managed):
+- Install deps: `uv sync`
+- Format: `uv run black .`
+- Lint (autofix): `uv run ruff check --fix .`
+- Types: `uv run mypy kryten_webqueue`
+- Tests: `uv run pytest` (add `--cov=kryten_webqueue --cov-report=term-missing` for coverage)
+
+Run all four before committing. Do not bypass checks (`--no-verify`).
+
+## Conventions
+- Python 3.12+, flat `kryten_webqueue/` package, 100% `async`/`await`, Pydantic v2 config,
+  FastAPI + uvicorn. black/ruff use their **default** line length (no override configured).
+  pytest `asyncio_mode = "auto"`.
+- Config is JSON with auto-discovery: `--config` flag → `/etc/kryten-webqueue/config.json` →
+  `./config.json`. Keep `config.example.json` in sync; never hardcode secrets, keys, or
+  MediaCMS/api-gate URLs. Notable keys: `secret_key` (JWT), `port` (default 2010),
+  `api_gate_url`/`api_gate_token`, `mediacms_url`/`mediacms_token`,
+  `mediacms_manage_all_media`, `tmdb_api_key`/`omdb_api_key`, `db_path`.
+- **High-stakes surfaces**: DB migrations, enrichment classify/title logic (affects the whole
+  catalog; needs a `force` re-run to re-apply), MediaCMS write paths, and catalog sync
+  (REPLACE semantics). Flag and version changes to these.
+- Version lives only in `pyproject.toml [project] version`. Update `CHANGELOG.md`
+  (Keep-a-Changelog + SemVer, ISO dates) for every versioned change.
+- Commit prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `ci:`.
+  Branches: `feature/…`, `fix/…`.
+
+## Deployment
+Deployed via **pipx** on `grindhouse.local` as the `kryten-webqueue` systemd service
+(uvicorn on `port`, behind nginx; `deploy/` ships the unit + nginx config). Release flow:
+1. Bump `version` in `pyproject.toml`, update `CHANGELOG.md`.
+2. Commit, `git tag vX.Y.Z`, `git push && git push origin vX.Y.Z` (also published to PyPI).
+3. Install the tag and cycle the service:
+   ```
+   ssh kryten@grindhouse.local "sudo systemctl stop kryten-webqueue; \
+     pipx runpip kryten-webqueue install 'git+https://github.com/grobertson/kryten-webqueue.git@vX.Y.Z'; \
+     sudo systemctl start kryten-webqueue; systemctl is-active kryten-webqueue"
+   ```
+Trigger enrichment/sync jobs via `POST /admin/jobs/catalog_enrich/run` (admin session
+required; jobs are single-flight — restart the service to clear a stuck run).

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-08-14
+
+### Added
+
+- **Admin manual item editor.** Admins can now directly edit catalog item metadata
+  via an "Edit" button on catalog tiles and detail pages. The modal editor allows
+  editing both core metadata (title, description, duration) and advanced enrichment
+  state (content_type, lookup fields, hosted show, TV episode details). Edits can
+  optionally sync back to MediaCMS and trigger re-enrichment. All changes are logged
+  to an audit trail (`item_edit_log` table) tracking who edited what and when. This
+  complements the existing re-enrich button for cases where auto-enrichment cannot
+  fix problematic metadata.
+
 ## [0.36.7] - 2026-08-14
 
 ### Fixed

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kryten-webqueue
-Version: 0.36.7
+Version: 0.37.0
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

kryten_webqueue-0.37.0/docs/SPEC_ADMIN_ITEM_EDITOR.md

@@ -0,0 +1,264 @@
+# Admin Manual Item Editor — Implementation Spec
+
+**Version**: 1.0  
+**Status**: Implementing  
+**Date**: 2026-08-14
+
+---
+
+## Overview
+
+Add an admin-only manual edit capability for catalog items, appearing on both list view tiles and item detail pages. This complements the existing re-enrich button by allowing admins to directly fix metadata that can't be automatically corrected.
+
+## User Requirements
+
+Based on user feedback:
+1. **Include enrichment state editing in V1** — allow editing classification fields
+2. **Include edit audit logging in V1** — track who edited what and when
+3. **"Re-enrich on save"** — optional checkbox that triggers the standard enrichment job for the edited item
+4. **Skip tag/category editing** — these are better managed on the MediaCMS side
+
+---
+
+## Architecture
+
+### What Fields Are Editable?
+
+**Core Metadata** (always editable):
+- `title` — display title
+- `description` — synopsis/overview
+- `duration_sec` — runtime in seconds
+
+**Enrichment State** (advanced):
+- `content_type` — classification (movie, tv_episode, hosted_movie, riffed_movie, archive, unknown)
+- `lookup_title` — normalized title for TMDB/OMDB search
+- `lookup_year` — year for metadata lookup
+- `hosted_show` — for hosted movies (Svengoolie, MST3K, JBB, TLDI, etc.)
+- `tv_show`, `tv_season`, `tv_episode_num` — for TV episodes
+
+### Sync Strategy
+
+- **Title/Description → MediaCMS**: Optional via "Sync to MediaCMS" checkbox (default: checked)
+- **Enrichment State**: Local catalog only (not a MediaCMS concern)
+- **Re-enrich trigger**: Optional via "Re-enrich after save" checkbox — runs the standard `catalog_enrich` job for this single item
+
+### Audit Trail
+
+New `item_edit_log` table:
+```sql
+CREATE TABLE item_edit_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    friendly_token TEXT NOT NULL,
+    username TEXT NOT NULL,
+    field_name TEXT NOT NULL,
+    old_value TEXT,
+    new_value TEXT,
+    edited_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## Implementation Plan
+
+### Files to Create
+
+1. **`kryten_webqueue/templates/catalog/edit_item_modal.html`**
+   - Modal dialog with form for editing
+   - Pre-populated with current data
+   - Two sections: Core Metadata + Advanced (enrichment state)
+
+### Files to Modify
+
+1. **Backend**
+   - `kryten_webqueue/routes/admin_catalog.py`
+     - Add `PATCH /admin/catalog/{friendly_token}/edit`
+     - Validate, update catalog + enrichment state
+     - Log changes to audit trail
+     - Optionally sync to MediaCMS
+     - Optionally trigger re-enrichment job
+
+   - `kryten_webqueue/catalog/db/_connection.py`
+     - Add migration v21: `item_edit_log` table
+
+   - `kryten_webqueue/catalog/db/_enrichment.py`
+     - Add `update_enrichment_state(token, fields)` method
+
+   - `kryten_webqueue/catalog/db/_catalog.py`
+     - Add `log_item_edit(token, username, field, old, new)` method
+     - Add `get_item_edit_history(token, limit)` method
+
+   - `kryten_webqueue/catalog/mediacms.py`
+     - Add `update_item(token, title, description)` method
+
+2. **Frontend**
+   - `kryten_webqueue/templates/catalog/browse.html`
+     - Add "Edit" button in admin actions
+     - Include modal template
+
+   - `kryten_webqueue/templates/catalog/item_detail.html`
+     - Add "Edit" button in admin actions
+     - Include modal template
+
+---
+
+## API Specification
+
+### `PATCH /admin/catalog/{friendly_token}/edit`
+
+**Auth**: Admin only (rank >= 3)
+
+**Request Body**:
+```json
+{
+  "title": "New Title (1980)",
+  "description": "Updated description...",
+  "duration_sec": 5400,
+  "content_type": "movie",
+  "lookup_title": "New Title",
+  "lookup_year": "1980",
+  "hosted_show": null,
+  "tv_show": null,
+  "tv_season": null,
+  "tv_episode_num": null,
+  "sync_to_cms": true,
+  "re_enrich": false
+}
+```
+
+**Response** (success):
+```json
+{
+  "success": true,
+  "changes_logged": 3,
+  "cms_synced": true,
+  "enrich_job_id": null
+}
+```
+
+**Response** (with re-enrich):
+```json
+{
+  "success": true,
+  "changes_logged": 2,
+  "cms_synced": false,
+  "enrich_job_id": 42
+}
+```
+
+---
+
+## UI Design
+
+### Modal Layout
+
+```
+┌─────────────────────────────────────────────────┐
+│  Edit Item                                   ✕  │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│  Core Metadata                                  │
+│  ┌───────────────────────────────────────────┐ │
+│  │ Title: [New Title (1980)                ]│ │
+│  └───────────────────────────────────────────┘ │
+│  ┌───────────────────────────────────────────┐ │
+│  │ Description:                              │ │
+│  │ [Multi-line textarea...                 ]│ │
+│  │ [                                       ]│ │
+│  └───────────────────────────────────────────┘ │
+│  Duration (sec): [5400            ]            │
+│                                                 │
+│  ──────────────────────────────────────────    │
+│                                                 │
+│  Advanced (Enrichment State)                    │
+│  Content Type: [movie ▼]                        │
+│  Lookup Title: [New Title                 ]     │
+│  Lookup Year:  [1980    ]                       │
+│  Hosted Show:  [        ] (e.g., Svengoolie)    │
+│                                                 │
+│  TV Episode (if applicable):                    │
+│  Show: [             ] Season: [  ] Episode: [ ]│
+│                                                 │
+│  ──────────────────────────────────────────    │
+│                                                 │
+│  ☑ Sync title/description to MediaCMS           │
+│  ☐ Re-enrich after save (runs classify, title,  │
+│     meta, art, tags for this item)              │
+│                                                 │
+│  [ Save ]  [ Cancel ]                           │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## Security
+
+- **Authorization**: All edits require rank >= 3 (admin)
+- **Input Validation**:
+  - Title: 1-500 chars, required
+  - Description: max 5000 chars
+  - Duration: positive integer or null
+  - Content type: enum validation
+  - Years: 4-digit integers or null
+- **SQL Injection**: Parameterized queries throughout
+- **Audit Trail**: Every field change logged with username
+- **CSRF**: Session cookie + same-origin credentials
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+
+- `test_edit_item_core_metadata` — edit title/description/duration
+- `test_edit_item_enrichment_state` — edit content_type/lookup fields
+- `test_edit_item_audit_log` — verify changes are logged
+- `test_edit_item_cms_sync` — verify MediaCMS update
+- `test_edit_item_re_enrich` — verify job triggered
+- `test_edit_item_unauthorized` — 403 for non-admin
+- `test_edit_item_validation` — 400 for invalid data
+
+### Manual Testing
+
+- [ ] Edit button visible to admins only
+- [ ] Modal opens with pre-filled data
+- [ ] Core metadata edits save and reflect
+- [ ] Enrichment state edits save and reflect
+- [ ] CMS sync checkbox works
+- [ ] Re-enrich checkbox triggers job
+- [ ] Audit log records all changes
+- [ ] Toast notifications work
+- [ ] Form validation prevents bad data
+
+---
+
+## Rollout
+
+1. Implement all changes on feature branch
+2. Run full test suite (black, ruff, mypy, pytest)
+3. Manual QA on local dev instance
+4. Update version in `pyproject.toml` → `0.37.0`
+5. Update `CHANGELOG.md`
+6. Commit, tag `v0.37.0`, push to GitHub
+7. Publish to PyPI (automated via GitHub)
+8. **DO NOT DEPLOY** — long-running job in progress
+
+---
+
+## Future Enhancements (V2)
+
+- Edit history viewer (show all past edits for an item)
+- Bulk edit mode (edit multiple items at once)
+- Tag/category editing (requires CMS bulk API improvements)
+- Revert to previous version (undo an edit)
+- Export edit log as CSV
+
+---
+
+## Open Questions (Resolved)
+
+1. ✅ Include enrichment state in V1? → **Yes**
+2. ✅ Include audit logging in V1? → **Yes**
+3. ✅ How should re-enrich work? → **Simple: trigger standard job for single item**
+4. ✅ Include tag editing? → **No, defer to CMS side**

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/db/_catalog.py

@@ -793,21 +793,26 @@ class _CatalogMixin:
 
     async def update_catalog(self, friendly_token: str, row: dict):
         """Update catalog item with partial or full field set.
-        
+
         Only fields present in *row* are updated. Always adds friendly_token
         and updates updated_at to current time when any field changes.
         """
         if not row:
             return
-        
+
         # Build SET clause from provided fields
         allowed = {
-            "title", "description", "duration_sec", "manifest_url",
-            "thumbnail_url", "added_at", "synced_at"
+            "title",
+            "description",
+            "duration_sec",
+            "manifest_url",
+            "thumbnail_url",
+            "added_at",
+            "synced_at",
         }
         updates = []
         params = {"friendly_token": friendly_token}
-        
+
         for key in row:
             if key in allowed:
                 # added_at uses COALESCE to preserve existing if None
@@ -816,20 +821,21 @@ class _CatalogMixin:
                 else:
                     updates.append(f"{key}=:{key}")
                 params[key] = row[key]
-        
+
         # Always update updated_at when modifying
         updates.append("updated_at=:updated_at")
         params["updated_at"] = row.get("synced_at") or params.get("synced_at")
         if not params["updated_at"]:
             from datetime import datetime, UTC
+
             params["updated_at"] = datetime.now(UTC).isoformat()
-        
+
         if not updates:
             return
-        
+
         sql = f"UPDATE catalog SET {', '.join(updates)} WHERE friendly_token=:friendly_token"
         await self._db.execute(sql, params)
-        
+
         # Rebuild FTS for this row if title or description changed
         if "title" in row or "description" in row:
             await self._db.execute(
@@ -850,10 +856,10 @@ class _CatalogMixin:
 
     async def delete_stale_catalog_items(self, sync_started_at: str) -> int:
         """Delete catalog items that weren't updated during the sync.
-        
+
         Items with synced_at older than sync_started_at are no longer present
         in MediaCMS and should be removed. Returns count of deleted items.
-        
+
         Foreign key CASCADE will automatically remove related entries from:
         - catalog_fts
         - catalog_categories
@@ -866,23 +872,23 @@ class _CatalogMixin:
             [sync_started_at],
         )
         tokens = [row[0] for row in await cursor.fetchall()]
-        
+
         if not tokens:
             return 0
-        
+
         # Delete from FTS first (not automatically cascaded)
         placeholders = ",".join("?" * len(tokens))
         await self._db.execute(
             f"DELETE FROM catalog_fts WHERE friendly_token IN ({placeholders})",
             tokens,
         )
-        
+
         # Delete from catalog (cascades to join tables via ON DELETE CASCADE)
         await self._db.execute(
             f"DELETE FROM catalog WHERE friendly_token IN ({placeholders})",
             tokens,
         )
-        
+
         await self._db.commit()
         return len(tokens)
 
@@ -1049,6 +1055,37 @@ class _CatalogMixin:
             return True
         return False
 
+    # --- Item edit audit log -----------------------------------------------
+
+    async def log_item_edit(
+        self,
+        friendly_token: str,
+        username: str,
+        field_name: str,
+        old_value: str | int | None,
+        new_value: str | int | None,
+    ) -> None:
+        """Log a manual admin edit to the audit trail."""
+        # Convert to strings for storage
+        old_str = str(old_value) if old_value is not None else None
+        new_str = str(new_value) if new_value is not None else None
+
+        await self._execute(
+            "INSERT INTO item_edit_log (friendly_token, username, field_name, old_value, new_value) "
+            "VALUES (?, ?, ?, ?, ?)",
+            [friendly_token, username, field_name, old_str, new_str],
+        )
+
+    async def get_item_edit_history(
+        self, friendly_token: str, limit: int = 50
+    ) -> list[dict]:
+        """Retrieve edit history for an item, most recent first."""
+        return await self._fetch_all(
+            "SELECT * FROM item_edit_log WHERE friendly_token = ? "
+            "ORDER BY edited_at DESC LIMIT ?",
+            [friendly_token, limit],
+        )
+
     async def cleanup_expired_otps(self):
         await self._execute(
             "DELETE FROM otps WHERE expires_at < datetime('now') OR used=1"

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/db/_connection.py

@@ -399,6 +399,19 @@ MIGRATIONS = [
     """
     ALTER TABLE item_enrichment_state ADD COLUMN last_categories_at TEXT;
     """,
+    # v21: Item edit audit log (track manual admin edits)
+    """
+    CREATE TABLE IF NOT EXISTS item_edit_log (
+        id             INTEGER PRIMARY KEY AUTOINCREMENT,
+        friendly_token TEXT NOT NULL,
+        username       TEXT NOT NULL,
+        field_name     TEXT NOT NULL,
+        old_value      TEXT,
+        new_value      TEXT,
+        edited_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_item_edit_log_token ON item_edit_log(friendly_token, edited_at DESC);
+    """,
 ]
 
 

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/db/_enrichment.py

@@ -55,6 +55,33 @@ class _EnrichmentMixin:
             [*safe.values(), token],
         )
 
+    async def update_enrichment_state(self, token: str, fields: dict) -> None:
+        """Update specific enrichment state fields for an item.
+
+        Unlike save_enrichment_state (which is for the enrichment pipeline),
+        this is for manual admin edits and only accepts a subset of fields.
+        """
+        if not fields:
+            return
+        allowed = {
+            "content_type",
+            "hosted_show",
+            "lookup_title",
+            "lookup_year",
+            "tv_show",
+            "tv_season",
+            "tv_episode_num",
+        }
+        safe = {k: v for k, v in fields.items() if k in allowed}
+        if not safe:
+            return
+        await self.ensure_enrichment_state(token)
+        sets = ", ".join(f"{k} = ?" for k in safe)
+        await self._execute(
+            f"UPDATE item_enrichment_state SET {sets} WHERE friendly_token = ?",
+            [*safe.values(), token],
+        )
+
     async def get_catalog_for_enrichment(
         self,
         *,
@@ -113,10 +140,13 @@ class _EnrichmentMixin:
             return json.loads(raw)
         except (ValueError, TypeError) as exc:
             import logging
+
             logger = logging.getLogger(__name__)
             token = (row or {}).get("friendly_token", "?")
             logger.warning(
                 "Failed to parse meta_json for %s: %s. Raw value (first 200 chars): %r",
-                token, exc, raw[:200] if isinstance(raw, str) else raw
+                token,
+                exc,
+                raw[:200] if isinstance(raw, str) else raw,
             )
             return None

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/enrichment/providers.py

@@ -173,7 +173,9 @@ class TMDBProvider:
             first_air = tv_show.get("first_air_date", "")
             meta.year = first_air[:4] if first_air else None
             if tv_show.get("poster_path"):
-                meta.poster_url = f"https://image.tmdb.org/t/p/w780{tv_show['poster_path']}"
+                meta.poster_url = (
+                    f"https://image.tmdb.org/t/p/w780{tv_show['poster_path']}"
+                )
             return meta
         except (httpx.HTTPError, json.JSONDecodeError, ValueError) as exc:
             logger.debug("TMDB TV show search error for %r: %s", show, exc)

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/enrichment/steps/art.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import asyncio
 import hashlib
 import io
 import logging
@@ -115,12 +114,12 @@ class ArtStep:
 
     async def _resolve_poster(self, cls: ItemClassification) -> str | None:
         """Query TMDB then OMDB using lookup_title (the key fix for hosted movies).
-        
+
         For TV episodes, search for the show poster (not episode-specific art).
         """
         if not cls.lookup_title:
             return None
-        
+
         # TV episodes: get the show poster
         if cls.content_type == "tv_episode":
             meta = await self._tmdb.search_tv_show(cls.lookup_title)
@@ -128,7 +127,7 @@ class ArtStep:
                 return meta.poster_url
             meta = await self._omdb.search_tv_show(cls.lookup_title)
             return meta.poster_url
-        
+
         # Movies and other content: search as movie
         meta = await self._tmdb.search_movie(cls.lookup_title, cls.lookup_year)
         if meta.poster_url:

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/enrichment/steps/meta.py

@@ -164,7 +164,9 @@ class MetaStep:
                         e,
                         meta_json[:300],
                     )
-                    result.record_error(f"{cls.friendly_token}: malformed meta_json ({e})")
+                    result.record_error(
+                        f"{cls.friendly_token}: malformed meta_json ({e})"
+                    )
                     continue
 
                 logger.info(

{kryten_webqueue-0.36.7 → kryten_webqueue-0.37.0}/kryten_webqueue/catalog/mediacms.py

@@ -122,3 +122,44 @@ class MediaCMSClient:
                 )
             await self._restore_owner(client, friendly_token, owner)
             return ok
+
+    async def update_item(
+        self,
+        friendly_token: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+    ) -> bool:
+        """Update item title and/or description in MediaCMS.
+
+        Returns True if the remote write succeeded.
+        """
+        if not title and not description:
+            return True
+
+        async with httpx.AsyncClient(headers=self._headers, timeout=_TIMEOUT) as client:
+            media = await self._get_media(client, friendly_token)
+            if media is None:
+                return False
+
+            owner = media.get("user")
+            payload = {}
+            if title is not None:
+                payload["title"] = title
+            if description is not None:
+                payload["description"] = description
+
+            resp = await client.put(
+                f"{self._base}/api/v1/media/{friendly_token}",
+                data=payload,
+            )
+            ok = resp.status_code in (200, 201)
+            if not ok:
+                logger.warning(
+                    "MediaCMS update for %s failed: HTTP %s — %s",
+                    friendly_token,
+                    resp.status_code,
+                    resp.text[:200],
+                )
+            await self._restore_owner(client, friendly_token, owner)
+            return ok