shelve

Previous value: -"The rest, at any length. Optional."New value: +"The rest, at any length. Optional. See `title`'s own note on `retire`."

Previous value: -"CORRECT AN ENTRY THAT ALREADY EXISTS instead of filing a new one: its number, as the shelf\nlisting shows it. The fields given replace what is there; the number stays, and the version\nreplaced stays readable. Use this whenever a filed entry turns out wrong, badly worded or\nmissing a label - a second entry saying the same thing better makes a shelf unreadable. Omit\nit to file something new."New value: +"CORRECT AN ENTRY THAT ALREADY EXISTS instead of filing a new one: its number, as the shelf\nlisting shows it. The fields given replace what is there; the number stays, and the version\nreplaced stays readable. Use this whenever a filed entry turns out wrong, badly worded or\nmissing a label - a second entry saying the same thing better makes a shelf unreadable. Omit\nit to file something new. Required together with `retire`."

Previous value: -"Optional labels for filtering inside a shelf."New value: +"Optional labels for filtering inside a shelf. See `title`'s own note on `retire`."

Added value: +{
+  "default": null,
+  "description": "THE OWNER JUST NAMED A NEW SHELF - repeat that name here exactly as he gave it, and it is\ncreated (the shelf ceiling still applies) and this entry filed onto it in the same call.\nTHE GAP THIS CLOSES: creating a shelf used to live only behind the `library` command-line\nbinary's own `shelf-new` - an agent that asked and was answered still had no way to act on the\nanswer, which was a dead end at a new user's very first recipe. Never fill this in on your own\njudgement or to get past a refusal - only after the owner himself named it. Must match `shelf`\non this same call, or the write is refused. Meaningless together with `id`: correcting or\nretiring an entry never creates a shelf.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Added value: +{
+  "default": false,
+  "description": "Take this entry out of the shelf listing and out of search, without deleting it - `library`\nstill returns it whole, marked retired, when asked for by its number. Works only together\nwith `id`, and only alone: refused together with a title, body or label change (one thing per\ncall), and refused without `id`. Requires `retire_because`.",
+  "type": "boolean"
+}

Added value: +{
+  "default": null,
+  "description": "Required together with `retire: true`: why this entry no longer belongs on the shelf, in a\nreal sentence - the same requirement `retract` makes on the code lane, and for the same\nreason: without it nobody can tell a decision from an accident later. Ignored when retire is\nnot set.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Previous value: -"An EXISTING shelf. If none fits, ask the owner - you may not create one."New value: +"An EXISTING shelf, or the one just named in `new_shelf_named_by_owner` on this same call."

Previous value: -"One line that stands on its own. This is the index. When correcting an\nentry (see `id`), leave it empty to keep the title it has."New value: +"One line that stands on its own. This is the index. When correcting an entry (see `id`),\nleave it empty to keep the title it has. Leave it empty on a `retire` too - retire is refused\ntogether with a title, body or label change."