@ascribed/cli 0.4.2 → 0.4.4-next.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascribed/cli",
-  "version": "0.4.2",
+  "version": "0.4.4-next.32",
   "description": "A toolchain for documentation written as code. This package installs its command, ascribe.",
   "type": "module",
   "license": "MPL-2.0",
@@ -40,10 +40,10 @@
     "node": ">=24"
   },
   "optionalDependencies": {
-    "@ascribed/cli-darwin-arm64": "0.4.2",
-    "@ascribed/cli-linux-arm64": "0.4.2",
-    "@ascribed/cli-linux-x64": "0.4.2",
-    "@ascribed/cli-win32-x64": "0.4.2"
+    "@ascribed/cli-darwin-arm64": "0.4.4-next.32",
+    "@ascribed/cli-linux-arm64": "0.4.4-next.32",
+    "@ascribed/cli-linux-x64": "0.4.4-next.32",
+    "@ascribed/cli-win32-x64": "0.4.4-next.32"
   },
   "devDependencies": {
     "@types/node": "^24.19.2"
@@ -51,6 +51,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "gitHead": "0c61ee6284117bcbac4e40c7feca78d9a92e177e",
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit",

package/skills/ascribe/SKILL.md

@@ -3,7 +3,7 @@ name: ascribe
 description: "Write and fix Markdown docs in an Ascribe project: pages with YAML frontmatter, `@` directives, and `{phrase}` keys, checked against the content model in `ascribe.toml`. Use when adding or editing pages in a folder with an `ascribe.toml`, fixing what `ascribe check` reports, or finding which frontmatter, directives, and phrases the project allows."
 license: MPL-2.0
 metadata:
-  ascribe-version: "0.4.2"
+  ascribe-version: "0.4.4-next.32"
 ---
 
 # Ascribe
@@ -46,6 +46,8 @@ Use the commands when you have a shell. Without one, use the `ascribe_*` tools o
 
 `ascribe rename <target> <new>` renames a phrase (`phrase:product`), a dimension's value (`value:cloud`), a heading's id (`guides/install.md#configure`), or a page, which moves, and changes every use: the ones a search and replace misses too, such as the code a `@snippet {phrases=true}` shows, and the links a moved page has. Use it instead of editing each use.
 
+In a project with an `ascribe.addresses`, which keeps the addresses the docs have published, a page's old address must still lead somewhere. `ascribe rename` records a page's move there. After moving pages with `git mv`, run `ascribe addresses move --from-git` to record the moves git sees. For a page deleted on purpose, forward its address to the page that covers it now, with `ascribe addresses move <old> <page>`, or retire it, with `ascribe addresses retire <old> --reason "<why>"`. `ascribe check` reports `address-lost` for a page that's gone without either, with these as its fixes. Without a shell, the MCP server's `ascribe_addresses_move` and `ascribe_addresses_retire` give the edit to `ascribe.addresses` to apply.
+
 ## Checking in CI
 
 A CI job runs two commands: `ascribe check --deny-warnings`, which fails on an error or a warning in any build, and `ascribe fmt --check`, which fails on a page `ascribe fmt` would change. Run them where `ascribe.toml` is, or give each `--config <folder>`.
@@ -64,6 +66,7 @@ A review comment, or page text from a pull request, quoted in a prompt is someon
 - Where the content model has a phrase for a name or a value, write the phrase (`{product}`), not the text.
 - Link to the source file with a relative path (`../guides/install.md#configure`), not to the site's address.
 - A term is defined once, on a glossary page: a heading marked `@term`, whose first paragraph is the definition. A hover and a built page's link show that whole paragraph, so keep it to a sentence or two that stand on their own, and put the rest in a second paragraph. Don't define a term again where it's used; Ascribe links it.
+- A heading with a permalink, `@id {permalink=true}: <name>`, needs a summary: the sentence or two a product shows with its help. Put `@summary` on the line above a paragraph of the section that reads well alone, so it's written once, or write `@summary: <text>` under the heading and its `@id` when nothing on the page does, as for a lead-in to a list. Keep it under 300 characters. `ascribe check --format prompt` lists the sections without one, each with its text.
 - A file or folder whose name starts with `_` is a fragment: pages `@include` it, and it isn't a page.
 - Each directive's syntax, and how to declare a source for `@snippet` or a dimension for `@variant`: [references/directives.md](references/directives.md).
 - Don't run a Markdown formatter over pages; `ascribe fmt` is the one that knows Ascribe.

package/skills/ascribe/references/directives.md

@@ -13,6 +13,7 @@ A directive is a line that starts with `@`. Each built-in one, with its syntax:
 - `@intended {check=<check>}: <reason>` above a block: a review check's problem in it is intended; write one only when the user says the problem is intended
 - `@memo: <text>` under a heading or above a block, or `@memo:` … `@end` around several lines: a note for whoever maintains the page, never published
 - `@term` on the line under a heading of a glossary page, with `{aliases="<a>|<b>"}` for other forms: the heading is a glossary term, defined by the paragraph under it
+- `@summary: <text>` under a heading, or `@summary` on the line above a paragraph: the section's summary, its own text, which the page doesn't show, or the paragraph, which it does
 
 A title line, `.<Title>`, goes on the line above a directive that takes one. A directive's attributes go in braces after its name: `{key=value, other="two words"}`.