PyPI long_description is stale: README shows 16 CLI commands, installed 0.1.40 has 23

[ashfulcra]

The README rendered on PyPI for fulcra-api 0.1.40 documents a fulcra --help output that does not match the CLI shipped in that same version. Anyone reading the PyPI page -- or an agent scraping it -- gets an incomplete picture of the command surface.

Reproduce

pip install fulcra-api==0.1.40
fulcra --help

Then compare with the Commands: block in the README at https://pypi.org/project/fulcra-api/

What differs

The README lists 16 commands. The installed CLI has 23. Missing from the README:

Command	Help text (from the installed CLI)
data-updates	Return data/file updates that occurred during a period
record	Record data for a data type
delete	Delete records for a data type
file	File management sub-commands (list, download, delete, restore, share, stat)
share	Data sharing management sub-commands (create, update, delete, leave, list-incoming, list-outgoing)
tag	Tag management sub-commands (create, get, list, delete)
data-type	Data type management sub-commands

The README also omits the top-level --beta option ("Enable beta features"), which the installed CLI advertises.

Why it matters beyond cosmetics

The omissions are not minor commands -- they are the entire write and sharing surface, plus data-updates. A reader of the PyPI page would reasonably conclude the CLI is read-only and query-oriented. We reached exactly that wrong conclusion while writing developer documentation from the PyPI README, and published copy stating "every command reads" before catching it against the installed package.

data-updates is arguably the single most consequential command for agent workflows -- it returns which data types had records processed, the count for each, and which uploaded files changed over a given window (3h, 2 days, 1 week, or two ISO-8601 timestamps). It being absent from the published README means the capability is effectively undiscoverable for anyone who starts at PyPI.

Suggested fix

Regenerate the Commands: block in the README from fulcra --help as part of the release process, so the long description cannot drift from the shipped CLI again. A pre-release check that diffs the README block against fulcra --help output would catch it automatically.

I verified all of the above by installing the package in a clean container and running the CLI -- the command list and help strings above are copied from that output, not paraphrased.

[ashfulcra]

Re-verified today (2026-08-18) against the published package — still reproduces, and here is the exact list.

PyPI fulcra-api is now 0.1.40. The installed binary exposes 23 commands; the README rendered on the PyPI page (2,132 chars) never mentions 7 of them:

data-type  data-updates  delete  file  record  share  tag

Checked with word-boundary matching, not substring — record otherwise appears inside get-records, and tag inside unrelated words, which makes a naive grep report them as documented.

Reproduce:

pip install --upgrade fulcra-api
fulcra --help | sed -n '/^Commands:/,$p' | grep -E '^  [a-z]' | awk '{print $1}' | sort > installed.txt
python3 - <<'PY'
import json,re,urllib.request
r = json.load(urllib.request.urlopen("https://pypi.org/pypi/fulcra-api/json"))["info"]["description"] or ""
for c in [l.strip() for l in open("installed.txt") if l.strip()]:
    if not re.search(r'(?<![\w-])'+re.escape(c)+r'(?![\w-])', r):
        print("missing from README:", c)
PY

The 16 that are documented all match, so the README isn't wrong about what it covers — it just stops short. Worth noting the gap is the write and file surface specifically (record, delete, file, share, tag, data-type), which is the part a reader is least likely to guess exists.