mostlyright-data 0.16.3__tar.gz → 0.17.1__tar.gz

{mostlyright_data-0.16.3 → mostlyright_data-0.17.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.16.3
+Version: 0.17.1
 Summary: Mostly Right CLI for reproducible, reviewed Parquet datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.16.3 → mostlyright_data-0.17.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.16.3"
+version = "0.17.1"
 description = "Mostly Right CLI for reproducible, reviewed Parquet datasets"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{mostlyright_data-0.16.3 → mostlyright_data-0.17.1}/skills/mr-data-build/SKILL.md

@@ -112,7 +112,7 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data whoami` | Use the compatibility alias for the remotely validated `auth status` answer. |
 | `mr-data clarify` | Say whether one clarifying question may be put to the user right now, and compose the record of their answer. It reaches nothing, asks nobody and waits for nothing. Exits non-zero when no person can answer or when a recipe is already registered. |
 | `mr-data probe` | Ask one registered source one question and print the answer. **Currently unusable:** it reaches `/v3/sessions`, which Studio refuses, and it takes a question identifier that no v4 receipt returns. Do not plan a source inspection around it. |
-| `mr-data dataset` | Bring the dataset page into existence before there is anything on it, then fill it in while somebody watches. `dataset create --name TEXT` mints it and prints the `dataset_id`; `dataset show ID` reads it back; `dataset set ID --name TEXT --description-file F` writes the title and the description under the version it was read at, retrying once if somebody else wrote first; `dataset note ID --heading H --blocks-file B` writes one cell of the decision record that OUTLIVES every run, and `--list` reads it back; `dataset watch ID` follows the page's own event stream; `dataset activity ID --phase P --message TEXT` says what is happening right now, silently, and is never a chat message and never a cell; `dataset archive ID --confirm-name TITLE` retires the page and frees its title, deleting nothing. |
+| `mr-data dataset` | Bring the dataset page into existence before there is anything on it, then fill it in while somebody watches. `dataset create --name TEXT` mints it and prints the `dataset_id`; `dataset show ID` reads it back; `dataset set ID --name TEXT --topics "a,b,c" --license ID --description-file F` writes the title, the categories, the SPDX licence and the description under the version it was read at, retrying once if somebody else wrote first, and an empty `--topics` or `--license` takes that value off the page; `dataset note ID --heading H --blocks-file B` writes one cell of the decision record that OUTLIVES every run, and `--list` reads it back; `dataset watch ID` follows the page's own event stream; `dataset activity ID --phase P --message TEXT` says what is happening right now, silently, and is never a chat message and never a cell; `dataset archive ID --confirm-name TITLE` retires the page and frees its title, deleting nothing. |
 | `mr-data recipe` | Register one recipe document — dataset, question, table plan, sources, transform, checks and units — in one call, and print the identifiers the server derived. `mr-data recipe show ID` reads one back. |
 | `mr-data cover` | Generate and attach one branded 1200×630 dataset cover. Give it the dataset ID and what the image should depict; Studio fixes the model, single-color style, curated random palette, dimensions and storage. |
 | `mr-data run` | Start one run against a registered recipe, named as `--recipe RECIPE_ID --digest RECIPE_DIGEST` — both required, neither positional, and the digest is the bare hex the registration receipt printed. The command accepts `--sample`, `--full`, `--refresh`, `--backfill` and `--window`, and the worker executes `--sample`, `--full` and `--refresh`. A refresh narrows each source that declares a supported address window and merges its returned relation into retained source state; unwindowed sources are conditionally revalidated or re-acquired whole, then the full declared transform runs. `--backfill` and a `--window` on a sample or full are refused before acquisition. `--max-rows` and `--max-source-bytes` remain supported, and each bounds ONE SOURCE rather than the finished table. A large run is held for a spend confirmation, which `--confirm` settles; a sample-first held full requires Studio's interactive human approval instead. `--cancel RUN` stops one. |
@@ -307,7 +307,8 @@ and a title that never changes is fine too. Where the address cannot be minted,
 plain dashboard address rather than blocking.
 
 Hold the `dataset_id` for the rest of the session: stage 3 writes the decision record to it, stage
-4 writes its title, description and cover, and the recipe binds to it by naming it as `dataset.id`.
+4 writes its title, topics, licence, description and cover, and the recipe binds to it by naming
+it as `dataset.id`.
 
 ### 2. Probe — read a source before committing to it
 
@@ -470,18 +471,63 @@ and is settled once, at stage 4.
 Every grain, key, join and cutoff settled after stage 3 is a further `decision` block on the
 DATASET's record — `mr-data dataset note DATASET_ID` — because the fact outlives every run.
 
-**Write the title and the description before the first run, one call each.** The page has been
-open since stage 1 under a working title; this is where it settles:
+**Write the title, the topics, the licence and the description before the first run.** The page has
+been open since stage 1 under a working title. This is where it settles. One call carries the title,
+the topics and the licence, so the title and the chips land together; the description arrives after
+it, through the draft snapshots and the final commit. (The worked example below is a different
+dataset from the Kathmandu one the earlier stages follow, chosen because its numbers are easy to
+count.)
 
 ```sh
-mr-data dataset set DATASET_ID --name "Kathmandu monsoon flooding, 2015-2026" --json
-mr-data dataset set DATASET_ID --description-file DESCRIPTION.md --json
+mr-data dataset set DATASET_ID --name "Hourly weather at Prague Airport (LKPR), 2000-2026" \
+  --topics "weather,prague,czech republic,metar,iowa environmental mesonet" \
+  --license "CC-BY-4.0" --json
 ```
 
-Two calls rather than one, so the person watching sees the title land and then the text arrive.
-Each call reads the version first and writes under it, so a description you wrote against a page
-somebody else has since edited is retried once and then reported rather than silently overwriting
-them. While composing, send bounded snapshots with `mr-data dataset draft DATASET_ID --description-file DRAFT.md --expected-version VERSION --json`. Chain the returned version into the next snapshot, writing a meaningful paragraph at a time. These snapshots are temporary and do not replace the saved description. Commit the complete documentation with `mr-data dataset set DATASET_ID --description-file DESCRIPTION.md --expected-version VERSION --json`. If another edit moved that version, stop the draft and reconcile it with the user’s text; never retry by blindly advancing the version. Do not send fabricated partial text or delay completed text to simulate writing.
+The call reads the version first and writes under it, so a page somebody else has since edited is
+retried once and then reported rather than silently overwritten. The licence is the SPDX identifier
+of the rights basis the sources actually grant -- for example `CC-BY-4.0`, `ODbL-1.0`, `CC0-1.0`;
+where the sources' terms are not an open licence, leave `--license` off and say so under "Source and
+rights" instead. Never invent a licence.
+
+While composing, send bounded snapshots with `mr-data dataset draft DATASET_ID --description-file DRAFT.md --expected-version VERSION --json`. Chain the returned version into the next snapshot, writing a meaningful paragraph at a time. These snapshots are temporary and do not replace the saved description. Commit the complete documentation with `mr-data dataset set DATASET_ID --description-file DESCRIPTION.md --expected-version VERSION --json`. If another edit moved that version, stop the draft and reconcile it with the user’s text; never retry by blindly advancing the version. Do not send fabricated partial text or delay completed text to simulate writing.
+
+**What search engines and answer engines read.** These are the three fields search engines and
+answer engines index. A search engine (Google, Bing) ranks the page by the words a person types.
+An answer engine (ChatGPT, Perplexity, Claude, Google AI Overviews) quotes the page as a source
+when a person asks a question. Making the page rank is called SEO. Making the page quotable is
+called GEO. Both read the same three fields, and each field lands in fixed places with fixed
+limits. The rules below are mechanical: apply them, then run the check at the end. Do not
+interpret them.
+
+| You write | Where it appears | Limit |
+| --- | --- | --- |
+| `--name` | browser tab title (`{name} \| Mostly Right`), the page heading, the JSON-LD `name` | at most 60 characters, or search results cut it |
+| the opening paragraph of DESCRIPTION.md | the meta description, the social card, the JSON-LD `description`, the `Summary:` line answer engines fetch | search engines cut at 300 characters; answer engines cut at 240 |
+| `--topics` | category chips and the category filter on the /datasets directory, JSON-LD `keywords`, the `Topics:` line answer engines fetch, the `topic` filter in the public API and MCP | 3 to 8 topics, each at most 40 characters |
+
+**Title rules**
+1. Shape: subject, place, period. `Hourly weather at Prague Airport (LKPR), 2000-2026`.
+2. At most 60 characters. Count them.
+3. Use the words a person would type: the common place name, and the official identifier in
+   parentheses once if one exists (ICAO code, station id, ticker, constituency name).
+4. Never: a brand, the word "dataset" or "data", a colon, a pipe, an exclamation mark, a version
+   number, a run date.
+5. Sentence case. No trailing full stop.
+
+**Topic rules**
+1. 3 to 8 topics, comma-separated, no duplicates.
+2. Topic one is the category, chosen from this list and no other:
+   `weather, climate, air quality, hydrology, energy, transport, aviation, public health,
+   economics, finance, elections, sports, prediction markets, demographics, geospatial,
+   agriculture`.
+3. Then, in this order, one each where it applies: the city or region, the country, the
+   phenomenon or instrument, the publisher or programme. After those, up to three more, each a
+   distinct thing a person would type that none of the earlier topics already names.
+4. Form: lowercase; ASCII letters, digits, spaces and hyphens only; one to three words; at most
+   40 characters.
+5. Never: a column name, a unit, a bare year, a second word from the category list, a market or
+   venue name unless the dataset is about that market.
 
 **The dataset description is the documentation, and it is read by people and by search engines.**
 `dataset.description` is Markdown, rendered on the dataset page with headings and lists, and it
@@ -490,7 +536,7 @@ seconds -- not a paragraph, and not a report. Use exactly this shape, in this or
 section out only when there is genuinely nothing to say (shown indented here; the document
 itself carries the headings at column one):
 
-    One or two plain sentences: what each row is, where it comes from, and the period it covers.
+    Two plain sentences: what each row is, where it comes from, and the period it covers.
 
     ## Coverage
     - **Window:** the exact dates and the time zone.
@@ -510,13 +556,47 @@ itself carries the headings at column one):
     ## Source and rights
     The publisher, the programme, and the rights basis, in one or two sentences.
 
+That is six sections: the opening paragraph, and the five headings under it.
+
+**Opening paragraph rules** (everything before the first `##` heading)
+1. Two sentences, 150 to 240 characters together. The first sentence ends before character 200
+   and is complete on its own.
+2. Sentence one says what each row is, for where, over what window, from which publisher:
+   `Each row is one hourly METAR observation at Prague Václav Havel Airport (LKPR), January 2000
+   to August 2026, from the Iowa Environmental Mesonet ASOS archive.`
+3. Sentence two gives the size and the measured quantities, as numbers and nouns:
+   `43,812 rows of temperature, dew point, wind, pressure and visibility.`
+4. Full names on first use with the abbreviation in parentheses once. Never "this dataset",
+   "we", "it", "here".
+5. No Markdown in the opening paragraph: no bold, no links, no bullets, no code.
+
+**Body rules** (the five sections under the headings)
+1. Every sentence must stay true and complete when quoted alone, away from the page. Never
+   "as above", "see below", "it", "they", "the same".
+2. Numbers, not adjectives: `one row per hour, about 720 rows a month`, not `high-frequency`.
+3. Keep the five headings exactly as given, in that relative order, omitting only a section with
+   genuinely nothing to say. Answer engines match headings to questions: "what does it cover",
+   "what is it suitable for".
+4. Say what is absent as plainly as what is present: gaps, sentinels, the years the source did
+   not record.
+5. Everything in the paragraph below still applies.
+
 Rules that keep it readable: short sentences; no sentence over about twenty-five words; bullets
 rather than comma lists; no tables, no code blocks, no links to internal tools, no headings beyond
 the ones above. Spell out the names a reader would search for -- the place, the identifiers in
 every common form, the programme and the publisher -- once each, in the opening sentences and
-never as a keyword list. The opening sentences double as the summary cards and search engines
-show, so they must stand alone. A one-line description is a defect to fix in the revision, not a
-style choice. Give `table.description` the grain and the window.
+never as a keyword list. A one-line description is a defect to fix in the revision, not a style
+choice. Give `table.description` the grain and the window.
+
+**Check before writing.** Fix and re-check until every line passes:
+- title: at most 60 characters, contains the place, contains no colon, pipe or exclamation mark,
+  no brand, no "dataset" or "data", no version number, no run date
+- opening paragraph: 150 to 240 characters, first full stop before character 200, no Markdown
+- topics: 3 to 8, no duplicates, first one is on the category list, all lowercase, each at most
+  40 characters, none is a column name, a unit, a year, a second word from the category list, or
+  a market or venue name unless the dataset is about that market
+- licence: an SPDX identifier the sources actually grant, or `--license` left off
+- every `##` heading in DESCRIPTION.md is one of the five, in that relative order, none repeated
 
 **Every dataset gets a cover before its first run is presented.** Once the description is
 written, generate one with