lekha-poth-cli 2.1.0__tar.gz → 2.2.0__tar.gz

{lekha_poth_cli-2.1.0 → lekha_poth_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lekha-poth-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Production Typer CLI covering every Lekha Poth HTTP API endpoint.
 Author: Hermes Agent
 License: MIT
@@ -26,14 +26,40 @@ Replaces the old stdlib `scripts/agent/lp.py` reader CLI.
 
 ## Install
 
+Published on PyPI as [`lekha-poth-cli`](https://pypi.org/project/lekha-poth-cli/).
+No checkout needed:
+
 ```bash
-uv venv
-uv pip install -e ~/.hermes/skills/software-development/lekha-poth/lpcli
-# or: uv tool install -e that-path
-lp --help
+uv tool install lekha-poth-cli      # → $HOME/.local/bin/lp
+uv tool upgrade lekha-poth-cli      # later, to pick up new routes and flags
+$HOME/.local/bin/lp --version
 ```
 
-The wrapper `~/.local/bin/lp` should point at this package.
+On macOS `/usr/bin/lp` is the print spooler and is on `PATH`, so call the
+Lekha Poth CLI by its absolute path (`$HOME/.local/bin/lp`), or use the
+alias entry point `lekha-poth`, which nothing else claims. To try it without
+installing: `uvx --from lekha-poth-cli lp --help`.
+
+An **agent skill** that teaches an LLM agent to drive this CLI ships in the
+sdist under `skills/lp-cli/` (and in the repository at
+`scripts/agent/lpcli/skills/lp-cli/`); its `README.md` says where to put it.
+
+### Developing against a checkout
+
+```bash
+cd scripts/agent/lpcli
+uv venv .venv && uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m lekha_poth_cli --version
+# or, as a tool that tracks the working tree:  uv tool install -e .
+```
+
+### Releasing
+
+**Actions → Release (lekha-poth-cli) → Run workflow** (`bump` minor by default,
+or an exact `version`). It stamps every copy of the contract version
+(`scripts/ci/stamp-lpcli-version.py`), runs the tests, `uv build`s, commits
+and tags `lpcli-vX.Y.Z` on `main`, then `uv publish`es to PyPI. See
+`docs/CICD.md` → "Releasing the agent CLI".
 
 ## Configure (once)
 

{lekha_poth_cli-2.1.0 → lekha_poth_cli-2.2.0}/README.md

@@ -10,14 +10,40 @@ Replaces the old stdlib `scripts/agent/lp.py` reader CLI.
 
 ## Install
 
+Published on PyPI as [`lekha-poth-cli`](https://pypi.org/project/lekha-poth-cli/).
+No checkout needed:
+
 ```bash
-uv venv
-uv pip install -e ~/.hermes/skills/software-development/lekha-poth/lpcli
-# or: uv tool install -e that-path
-lp --help
+uv tool install lekha-poth-cli      # → $HOME/.local/bin/lp
+uv tool upgrade lekha-poth-cli      # later, to pick up new routes and flags
+$HOME/.local/bin/lp --version
 ```
 
-The wrapper `~/.local/bin/lp` should point at this package.
+On macOS `/usr/bin/lp` is the print spooler and is on `PATH`, so call the
+Lekha Poth CLI by its absolute path (`$HOME/.local/bin/lp`), or use the
+alias entry point `lekha-poth`, which nothing else claims. To try it without
+installing: `uvx --from lekha-poth-cli lp --help`.
+
+An **agent skill** that teaches an LLM agent to drive this CLI ships in the
+sdist under `skills/lp-cli/` (and in the repository at
+`scripts/agent/lpcli/skills/lp-cli/`); its `README.md` says where to put it.
+
+### Developing against a checkout
+
+```bash
+cd scripts/agent/lpcli
+uv venv .venv && uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m lekha_poth_cli --version
+# or, as a tool that tracks the working tree:  uv tool install -e .
+```
+
+### Releasing
+
+**Actions → Release (lekha-poth-cli) → Run workflow** (`bump` minor by default,
+or an exact `version`). It stamps every copy of the contract version
+(`scripts/ci/stamp-lpcli-version.py`), runs the tests, `uv build`s, commits
+and tags `lpcli-vX.Y.Z` on `main`, then `uv publish`es to PyPI. See
+`docs/CICD.md` → "Releasing the agent CLI".
 
 ## Configure (once)
 

{lekha_poth_cli-2.1.0 → lekha_poth_cli-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lekha-poth-cli"
-version = "2.1.0"
+version = "2.2.0"
 description = "Production Typer CLI covering every Lekha Poth HTTP API endpoint."
 readme = "README.md"
 requires-python = ">=3.12"

{lekha_poth_cli-2.1.0 → lekha_poth_cli-2.2.0}/scripts/generate_spec.py

@@ -55,6 +55,8 @@ import uuid as _uuid
 from pathlib import Path
 from typing import Any
 
+from pydantic import AwareDatetime, FutureDatetime, NaiveDatetime, PastDatetime
+
 REPO_ROOT = Path(__file__).resolve().parents[4]
 OUT = REPO_ROOT / "scripts" / "agent" / "lpcli" / "src" / "lekha_poth_cli" / "endpoints.json"
 API_V1_PREFIX = "/api/v1"
@@ -105,6 +107,15 @@ _SCALARS: dict[Any, str] = {
     bool: "bool",
     _uuid.UUID: "uuid",
     _dt.datetime: "datetime",
+    # Pydantic's constrained datetimes are distinct classes at runtime, not
+    # `Annotated[datetime, ...]`, so nothing above would unwrap them and the
+    # field would degrade to `str`. `publishedAt` is `AwareDatetime` — the API
+    # refuses a timezone-less value — and the CLI must still call it a
+    # datetime.
+    AwareDatetime: "datetime",
+    NaiveDatetime: "datetime",
+    PastDatetime: "datetime",
+    FutureDatetime: "datetime",
     _dt.date: "date",
 }
 
@@ -145,9 +156,7 @@ def _walk_annotation(annotation: Any) -> list[Any]:
     """The annotation and every type/metadata object nested inside it."""
     import typing
 
-    seen: list[Any] = [annotation]
-    for metadata in getattr(annotation, "__metadata__", ()):
-        seen.append(metadata)
+    seen: list[Any] = [annotation, *getattr(annotation, "__metadata__", ())]
     for arg in typing.get_args(annotation):
         seen.extend(_walk_annotation(arg))
     return seen

lekha_poth_cli-2.2.0/skills/lp-cli/README.md

@@ -0,0 +1,98 @@
+# lp-cli — an agent skill for the Lekha Poth CLI
+
+This directory is a self-contained [agent skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills)
+that teaches an LLM agent to operate [Lekha Poth](https://lekhapoth.com) through
+`lp`, the full-coverage command-line client published on PyPI as
+[`lekha-poth-cli`](https://pypi.org/project/lekha-poth-cli/).
+
+You do **not** need the Lekha Poth source repository to use it. You need:
+
+1. **`uv`** — `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux).
+2. **The CLI** — `uv tool install lekha-poth-cli`, which puts `lp` at
+   `$HOME/.local/bin/lp`. Keep it current with `uv tool upgrade lekha-poth-cli`.
+3. **This directory**, placed where your agent loads skills from.
+
+## Installing the skill
+
+Copy the whole `lp-cli/` directory (keep `SKILL.md`, `references/`, `scripts/`
+together) into your agent's skills location:
+
+| Agent | Where |
+|---|---|
+| Claude Code, for one user | `~/.claude/skills/lp-cli/` |
+| Claude Code, for one project | `<project>/.claude/skills/lp-cli/` |
+| Any other agent that reads `SKILL.md` frontmatter | its skills directory |
+
+Or package it as a single file with the skill-creator's
+`package_skill.py` and install the resulting `lp-cli.skill`.
+
+The agent reads `SKILL.md` first. It holds the install and pre-flight steps,
+task recipes, the exit-code table and the wire conventions, and routes to one
+of the `references/*.md` files for a command's exact flags.
+
+## Layout
+
+```
+lp-cli/
+├── SKILL.md                     # entry point: pre-flight, recipes, conventions, errors
+├── README.md                    # this file (for humans)
+├── references/
+│   ├── public-content.md        # generated — items, collections, search, tags, sitemap, stats
+│   ├── auth-account.md          # generated — auth, /me, API keys
+│   ├── library.md               # generated — reader library + reports
+│   ├── chats.md                 # generated — persona chat
+│   ├── admin.md                 # generated — every /admin/* command
+│   ├── legacy.md                # generated — deprecated /chapters, /series aliases
+│   └── vocab.md                 # hand-written — what each allowed value means
+├── scripts/
+│   └── generate_references.py   # rebuilds references/*.md from the CLI's endpoints.json
+└── evals/
+    └── evals.json               # test prompts used to evaluate the skill
+```
+
+## Keeping the references in step with your CLI
+
+The six generated reference files describe the CLI at contract **2.2.0**. If
+`lp --version` reports something newer, rebuild them from the spec that ships
+inside the installed package — no checkout required:
+
+```bash
+uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py          # rewrite
+uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py --check  # report only
+```
+
+`SKILL.md` and `references/vocab.md` are hand-written and are not touched by
+the script; where they and `lp <command> --help` disagree, `--help` is current.
+
+## For maintainers (inside the Lekha Poth repository)
+
+The skill lives at `scripts/agent/lpcli/skills/lp-cli/` and CI enforces that
+it matches the API. After any backend route or parameter change, from the
+repository root:
+
+```bash
+cd backend && uv run python ../scripts/agent/lpcli/scripts/generate_spec.py   # endpoints.json (types, choices, sentinels)
+cd .. && python3 scripts/agent/lpcli/scripts/generate_catalog_v2.py           # docs/agent/API_CATALOG_V2.md
+python3 scripts/agent/lpcli/skills/lp-cli/scripts/generate_references.py      # references/*.md
+```
+
+`backend/tests/unit/test_agent_spec_current.py` compares the spec with the
+live app; `scripts/agent/lpcli/tests/test_references_current.py` and
+`test_catalog_v2.py` check the two derived documents. When the skill is run
+from inside the checkout, `generate_references.py` reads the repository's
+`endpoints.json` rather than the installed package's, so the check is against
+the code under review. Allowed values are derived from the backend's
+`Literal` and `pattern=` validators, so a new vocabulary appears on its own.
+What still needs a human:
+
+- **Behaviour that isn't visible from the schema.** Record it in
+  `ENDPOINT_NOTES` / `FIELD_VOCAB_HINTS` in `generate_references.py`, only
+  after reading the backend code.
+- **`references/vocab.md` and `SKILL.md`.** Every claim should name the
+  source file it was checked against.
+- **A new route** needs an entry in `NEW_IDENTITY` in `generate_spec.py`; the
+  generator refuses to invent command names.
+- **A CLI behaviour change** means bumping `lpcli`'s `__version__` together
+  with the contract version in `SKILL.md`'s title and §11, the repo's
+  `agent/SKILL.md` `version` / `cli_package`, and publishing the new version
+  to PyPI — a user who only has `uv tool upgrade` sees nothing until then.

{lekha_poth_cli-2.1.0 → lekha_poth_cli-2.2.0}/skills/lp-cli/SKILL.md

@@ -1,45 +1,77 @@
 ---
 name: lp-cli
-description: Use whenever a task involves `lp`, Lekha Poth's full-coverage API CLI, or anything that CLI does from a terminal. That covers publishing, editing, scheduling (future publish date), or previewing chapters/items; reordering a serial's chapters; marking a series completed; setting or clearing covers and media (uploads, attach); tag descriptions; content rating (safe/adult) and language (bn/en) filters in search; the reader library (favorites, watch-later, history, personal collections, follows, feed); auth, account, and API keys; persona chat; admin reports, takedown, and users; and calling any Lekha Poth HTTP endpoint. Also use when someone says "lp" or "lekha poth cli", pastes an `lp` error or exit code, or asks which flags an `lp` subcommand takes, even if they only describe the task ("publish this chapter via the API", "schedule chapter 12 for Friday", "put these chapters in order"). Not for editing the backend or frontend code itself. Not for the stdlib reader CLI `scripts/agent/lp.py` or `lp_media.py`.
+description: 'Use whenever a task involves `lp`, the full-coverage CLI for Lekha Poth (lekhapoth.com, a Bangla serial-fiction platform), or anything that CLI does from a terminal, including installing or upgrading it (`uv tool install lekha-poth-cli`) and pointing it at an API with a personal API key. Covers publishing, editing, scheduling (future publish date) or previewing chapters; reordering a serial; marking a series completed; covers and media uploads; tag descriptions; content-rating (safe/adult) and language (bn/en) search filters; the reader library (favorites, watch-later, history, collections, follows, feed); auth, account and API keys; persona chat; admin reports, takedown and users; and calling any Lekha Poth HTTP endpoint. Also use when someone says "lp" or "lekha poth cli", pastes an `lp` error or exit code, or asks which flags a subcommand takes, even if they only describe the task ("schedule chapter 12 for Friday"). Needs only the CLI from PyPI, not the Lekha Poth repo. Not for editing Lekha Poth source.'
 ---
 
-# lp — Lekha Poth CLI (contract 2.1.0)
+# lp — Lekha Poth CLI (contract 2.2.0)
 
-`lp` is a Typer + Pydantic + httpx CLI. Every HTTP route of the Lekha Poth API
-is a real subcommand with real flags. The commands are generated from
-`endpoints.json`, which is derived from the live FastAPI app, so
+`lp` is a Typer + Pydantic + httpx CLI, published on PyPI as
+`lekha-poth-cli`. Every HTTP route of the Lekha Poth API is a real subcommand
+with real flags. The commands are generated from an `endpoints.json` that
+ships inside the package and is derived from the live FastAPI app, so
 `lp endpoints` is the authoritative list; do not trust a number written
 anywhere else.
 
-This file is the map: pre-flight, task recipes, conventions, and errors. The
-per-command details (every flag, type, default, allowed values, and gotchas)
-are in `references/*.md`, generated from the same spec. **Before running an
-unfamiliar write, read its reference entry.** For a command you already know,
-`lp <group> <name> --help` is current and lists allowed values as
-`(one of: …)`.
-
-## 0. Pre-flight — do this before the first command
-
-1. **Use the right binary.** On macOS, `/usr/bin/lp` is the system *print
-   spooler* and is on `PATH`, so a bare `lp` can end up there. Its reply is
-   `lp: Error - unknown option`. Invoke the Lekha Poth CLI by absolute path:
-   `$HOME/.local/bin/lp` (on this machine, `/Users/mahamudul/.local/bin/lp`).
-   That is an editable `uv tool` install of `scripts/agent/lpcli/`, so it
-   always runs the repository's current code. If that path doesn't exist, run
-   it from the repo root instead:
-   `uv run --isolated --with-editable ./scripts/agent/lpcli lp …`.
-   The examples below write `lp` for brevity.
-2. **Check the version:** `lp --version` should print `2.1.0` or newer. On an
-   older CLI, the exit codes and typed-flag behaviour in §5–§6 do not hold.
-3. **Know which API you are pointed at.** Run `lp config show` (secrets
+This skill is self-contained: it needs the CLI (installed in §0) and nothing
+else — not the Lekha Poth source repository, which is private. Where a note
+below names a backend file, that is the provenance of the claim, not
+something to open.
+
+This file is the map: install and pre-flight, task recipes, conventions, and
+errors. The per-command details (every flag, type, default, allowed values,
+and gotchas) are in `references/*.md`, generated from the same spec. **Before
+running an unfamiliar write, read its reference entry.** For a command you
+already know, `lp <group> <name> --help` is current and lists allowed values
+as `(one of: …)`.
+
+## 0. Install and pre-flight — do this before the first command
+
+1. **Install (or upgrade) the CLI from PyPI with `uv`.** No repository
+   checkout is involved; the package carries everything, including the
+   endpoint spec the commands are built from.
+   ```bash
+   uv tool install lekha-poth-cli        # first time → $HOME/.local/bin/lp
+   uv tool upgrade lekha-poth-cli        # later: pick up new routes and flags
+   $HOME/.local/bin/lp --version         # confirm it answers
+   ```
+   If `uv` itself is missing: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+   (macOS/Linux), then open a new shell. To run once without installing
+   anything permanently, `uvx --from lekha-poth-cli lp …` works too.
+2. **Use the right binary — always the absolute path.** On macOS,
+   `/usr/bin/lp` is the system *print spooler* and is on `PATH`, so a bare
+   `lp` can end up there; its reply is `lp: Error - unknown option`. Invoke
+   the Lekha Poth CLI as `$HOME/.local/bin/lp …` in every real command (the
+   examples below write `lp` for brevity). If that path does not exist, step
+   1 has not been done on this machine.
+3. **Check the version:** `lp --version` should print `2.2.0` or newer. On an
+   older CLI, the exit codes and typed-flag behaviour in §5–§6 do not hold —
+   run `uv tool upgrade lekha-poth-cli`. If it prints something *newer* than
+   the contract version in this file's title, the CLI may have commands or
+   flags this skill does not describe yet; see §11.
+4. **Point it at an API and a credential.** Nothing is compiled in: a fresh
+   install has an empty `api_base` and refuses every command with exit 2
+   until you set one.
+   ```bash
+   lp config set --api-base https://api.lekhapoth.com/api/v1 \
+                 --site-url https://lekhapoth.com --api-key lpak_…
+   ```
+   That is the hosted production site. A self-hosted or local deploy uses its
+   own origin (the base must end in `/api/v1`, e.g.
+   `http://localhost:8000/api/v1`). A personal API key (`lpak_…`) is created
+   on the website under **Account → API keys** (needs a verified email; the
+   scopes offered are the ones the account holds) — or from the CLI with a
+   JWT session: `lp auth login`, store the tokens (§4), then
+   `lp keys create-api-key`. Anonymous reads (`items`, `collections`,
+   `search`, `tags`) work with no key at all.
+5. **Know which API you are pointed at.** Run `lp config show` (secrets
    masked) and `env | grep ^LEKHA_POTH_ | cut -d= -f1`. Environment variables
-   beat the config file (§3). The default config on a developer machine often
-   targets **production**.
-4. **Confirm connectivity and identity:** run `lp status`. It returns
+   beat the config file (§3), and a config written earlier on this machine
+   may target **production**.
+6. **Confirm connectivity and identity:** run `lp status`. It returns
    health, readiness, and `/me` in one call, and reports an unreachable API
    instead of failing. Then run `lp keys permissions` to see what the current
    credential may actually do.
-5. **Don't experiment against production.** Anything under `lp admin`,
+7. **Don't experiment against production.** Anything under `lp admin`,
    `library`, `me`, `keys`, `chats` or `reports` that isn't a read changes real
    data for real readers. To try a command, point it at a local API
    (`lp --api-base http://localhost:8000/api/v1 …`), or ask first.
@@ -71,7 +103,10 @@ lp admin items update <slug> --status published --published-at 2026-10-02T12:00:
 ```
 An item is live only when `status=published` **and** `publishedAt` ≤ now.
 With a future date, the item stays hidden and appears at that time with no
-further call. Always include a UTC offset (`Z`, or `+06:00` for Dhaka).
+further call. The value **must** include a UTC offset (`Z`, or `+06:00` for
+Dhaka) — a timezone-less `2026-10-02T12:00:00` is a 422, not a guess, because
+a timestamp resolved in the wrong zone lands in the future and hides the item
+everywhere but `admin items list`.
 Convert local times yourself: 18:00 in Dhaka is 12:00Z.
 
 **Reorder a serial's chapters** (one call, not N updates)
@@ -112,6 +147,10 @@ relevance order.
 **Edit a tag's description:**
 `lp admin tags list`, then `lp admin tags update "<tag>" --description "…"`.
 Omitting `--description` **clears** the description.
+**Standing rule when publishing to Lekha Poth:** after publishing any item that introduces a tag,
+list tags and PATCH a unique ~145–165 character Bangla SEO description for every
+row with `description` null. Include the tag name, 18+, বাংলা চটি গল্প / চটি উপন্যাস /
+পানু গল্প, plus tag-specific keywords. Use `--body-file` for Bangla. Never skip this.
 
 **Reader library (signed-in key):**
 - `lp library fav list`, `lp library watch list`, `lp library history list`
@@ -221,9 +260,9 @@ code you can branch on:
 
 Branch on the exit code and on `ERROR_CODE`, never on the message wording.
 Several conditions share one HTTP status. A 410 (`CONTENT_QUARANTINED`, a
-taken-down item on a public read) exits 1. Source:
-`scripts/agent/lpcli/src/lekha_poth_cli/errors.py`, and `ErrorCode` in
-`backend/src/app/core/exceptions.py`.
+taken-down item on a public read) exits 1. The mapping is
+`lekha_poth_cli/errors.py` inside the installed package; the codes themselves
+are the backend's `ErrorCode` enum.
 
 ## 7. PATCH semantics
 
@@ -235,10 +274,11 @@ exceptions:
 - the sentinel fields in §2 clear with `null`;
 - `admin tags update` clears the description when `--description` is omitted;
 - `--attributes` and `--tag` replace the whole value you send;
-- `publishedAt` can be moved but never nulled.
+- `publishedAt` can be moved but never nulled, and only to a value with a UTC
+  offset (`Z` / `+06:00`); a timezone-less timestamp is a 422.
 
-Source: `AdminService.update_chapter` in
-`backend/src/app/services/admin_service.py`.
+Verified against the backend's `AdminService.update_chapter`
+(`backend/src/app/services/admin_service.py` in the Lekha Poth repository).
 
 ## 8. Built-in commands (not generated)
 
@@ -263,10 +303,13 @@ Source: `AdminService.update_chapter` in
 
 ## 9. Where every generated command is documented
 
-Each file is generated by `scripts/generate_references.py`. For every command
-it lists the exact syntax, each path, query, header and body field with its
-type, required/optional status, default, allowed values and wire name, and
-any command-specific notes checked against the backend.
+Each file is generated by `scripts/generate_references.py` from the CLI's
+own `endpoints.json`. For every command it lists the exact syntax, each path,
+query, header and body field with its type, required/optional status,
+default, allowed values and wire name, and any command-specific notes checked
+against the backend. The `Backend source: backend/src/app/…` footer under
+each entry names the file that note was checked against in the (private)
+Lekha Poth repository — provenance, not reading material.
 
 | File | Covers |
 |---|---|
@@ -313,28 +356,28 @@ text on `admin takedown`. `--sort` differs between `items list` and
 
 ## 11. Keeping this skill in sync
 
-Everything except this file and `references/vocab.md` is generated. After any
-backend route or parameter change:
-
-```bash
-cd backend && uv run python ../scripts/agent/lpcli/scripts/generate_spec.py   # endpoints.json (types, choices, sentinels)
-cd .. && python3 scripts/agent/lpcli/scripts/generate_catalog_v2.py           # docs/agent/API_CATALOG_V2.md
-python3 scripts/agent/lpcli/skills/lp-cli/scripts/generate_references.py      # references/*.md
-```
-
-CI enforces all three. `backend/tests/unit/test_agent_spec_current.py`
-compares the spec with the live app, and `scripts/agent/lpcli/tests/`
-(`test_catalog_v2.py`, `test_references_current.py`) checks the two derived
-documents. Allowed values are derived from the backend's `Literal` and
-`pattern=` validators, so a new vocabulary appears on its own. What still
-needs a human:
-
-- **Behaviour that isn't visible from the schema.** Record it in
-  `ENDPOINT_NOTES` / `FIELD_VOCAB_HINTS` in `generate_references.py`, only
-  after reading the backend code.
-- **`references/vocab.md` and this file.** Every claim should name the source
-  file it was checked against.
-- **A new route** needs an entry in `NEW_IDENTITY` in `generate_spec.py`; the
-  generator refuses to invent command names.
-- **A CLI behaviour change** means bumping `lpcli`'s `__version__` together
-  with `agent/SKILL.md`'s `version` and `cli_package`.
+The CLI moves with the API; this skill is a snapshot of it at contract
+**2.2.0**. Three things can drift, and each has a check:
+
+- **The CLI on this machine is behind the skill.** `lp --version` is older
+  than the title above → `uv tool upgrade lekha-poth-cli`. Flags this file
+  describes (`--published-at` scheduling, `--content-rating`, typed
+  `--attributes`, `null` sentinels, the exit codes) do not exist on 2.0.x.
+- **The CLI is ahead of the skill.** `lp --version` is newer than the title
+  → `lp endpoints` and `lp <cmd> --help` are the truth wherever they and a
+  reference file disagree. Rebuild the reference files from the installed
+  package so they match your CLI exactly:
+  ```bash
+  uv run --no-project --with lekha-poth-cli python3 scripts/generate_references.py
+  ```
+  The script reads `endpoints.json` out of the package (it needs no checkout;
+  `--check` reports staleness without writing). What it cannot refresh is the
+  hand-written prose — this file and `references/vocab.md` — so treat a value
+  that `--help` lists and `vocab.md` does not as real but unexplained.
+- **The API is ahead of the CLI.** A value the API accepts but `--help` does
+  not list still works: the CLI shows choices but never enforces them (§2).
+  `lp api request` reaches any route that has no generated command yet.
+
+Maintainers working inside the Lekha Poth repository regenerate
+`endpoints.json` itself and the derived documents there; the procedure and
+the CI checks that enforce it are in this skill's `README.md`.