@ascribed/cli 0.2.1-next.14 → 0.2.1-next.16

package/README.md

@@ -9,11 +9,11 @@ npx ascribe build
 npx ascribe fmt --check
 ```
 
-The [command reference](https://ascribed-dev.com/reference/cli/) covers every command, option, output, and exit code, and [Getting started](https://ascribed-dev.com/getting-started/) sets up a project.
+The [command reference](https://ascribed-dev.com/go/cli-reference/) covers every command, option, output, and exit code, and [Getting started](https://ascribed-dev.com/go/getting-started/) sets up a project.
 
 ## The skill
 
-The package ships the Ascribe skill, in the [Agent Skills](https://agentskills.io) format, as `skills/ascribe/`, for tools that install skills from packages. It teaches an AI coding agent to check and fix Ascribe pages. In a project, `npx ascribe agents sync` writes it where agents look, with the project's own rules: see [Agents](https://ascribed-dev.com/guides/agents/).
+The package ships the Ascribe skill, in the [Agent Skills](https://agentskills.io) format, as `skills/ascribe/`, for tools that install skills from packages. It teaches an AI coding agent to check and fix Ascribe pages. In a project, `npx ascribe agents sync` writes it where agents look, with the project's own rules: see [Agents](https://ascribed-dev.com/go/agents-guide/).
 
 ## Platforms
 

package/dist/binary.d.ts

@@ -10,5 +10,3 @@ export declare function nativePackageName(currentPlatform?: string, currentArch?
  * tests; callers normally use `resolveBinary()` with no arguments.
  */
 export declare function resolveBinary(options?: BinaryPlatform): string;
-/** Backwards-compatible name for resolveBinary. */
-export declare const nativeBinaryPath: (currentPlatform?: string, currentArch?: string) => string;

package/dist/binary.js

@@ -36,11 +36,4 @@ export function resolveBinary(options = {}) {
             "dependencies are enabled. The package manager must not omit optional dependencies.", { cause: error });
     }
 }
-/** Backwards-compatible name for resolveBinary. */
-export const nativeBinaryPath = (currentPlatform, currentArch) => resolveBinary(currentPlatform === undefined && currentArch === undefined
-    ? {}
-    : {
-        ...(currentPlatform === undefined ? {} : { platform: currentPlatform }),
-        ...(currentArch === undefined ? {} : { arch: currentArch }),
-    });
 //# sourceMappingURL=binary.js.map

package/dist/binary.js.map

@@ -1 +1 @@
-{"version":3,"file":"binary.js","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,QAAQ,GAA2B;IACvC,cAAc,EAAE,4BAA4B;IAC5C,aAAa,EAAE,2BAA2B;IAC1C,WAAW,EAAE,yBAAyB;IACtC,WAAW,EAAE,yBAAyB;CACvC,CAAC;AAOF,MAAM,UAAU,iBAAiB,CAC/B,eAAe,GAAW,QAAQ,EAClC,WAAW,GAAW,IAAI;IAE1B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,eAAe,IAAI,WAAW,EAAE,CAAC,CAAC;IAC3D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,kCAAkC,eAAe,IAAI,WAAW,IAAI;YAClE,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAO,GAAmB,EAAE;IACxD,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IACzC,MAAM,WAAW,GAAG,iBAAiB,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;IACpE,MAAM,UAAU,GAAG,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,WAAW,QAAQ,UAAU,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,mDAAmD,WAAW,GAAG,MAAM,IAAI;YACzE,+BAA+B,eAAe,IAAI,WAAW,wBAAwB;YACrF,oFAAoF,EACtF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,eAAwB,EAAE,WAAoB,EAAU,EAAE,CACzF,aAAa,CACX,eAAe,KAAK,SAAS,IAAI,WAAW,KAAK,SAAS;IACxD,CAAC,CAAC,EAAE;IACJ,CAAC,CAAC;QACE,GAAG,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;QACvE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;KAC5D,CACN,CAAC","sourcesContent":["import { createRequire } from \"node:module\";\nimport { arch, platform } from \"node:process\";\n\nconst require = createRequire(import.meta.url);\n\nconst packages: Record<string, string> = {\n  \"darwin-arm64\": \"@ascribed/cli-darwin-arm64\",\n  \"linux-arm64\": \"@ascribed/cli-linux-arm64\",\n  \"linux-x64\": \"@ascribed/cli-linux-x64\",\n  \"win32-x64\": \"@ascribed/cli-win32-x64\",\n};\n\nexport interface BinaryPlatform {\n  platform?: string;\n  arch?: string;\n}\n\nexport function nativePackageName(\n  currentPlatform: string = platform,\n  currentArch: string = arch,\n): string {\n  const name = packages[`${currentPlatform}-${currentArch}`];\n  if (name === undefined) {\n    throw new Error(\n      `@ascribed/cli does not support ${currentPlatform}/${currentArch}. ` +\n        \"Supported platforms are darwin arm64, linux arm64/x64, and win32 x64.\",\n    );\n  }\n  return name;\n}\n\n/**\n * Resolve the installed native executable for the current machine.\n *\n * The optional `platform` and `arch` arguments are intended for packaging\n * tests; callers normally use `resolveBinary()` with no arguments.\n */\nexport function resolveBinary(options: BinaryPlatform = {}): string {\n  const currentPlatform = options.platform ?? platform;\n  const currentArch = options.arch ?? arch;\n  const packageName = nativePackageName(currentPlatform, currentArch);\n  const executable = currentPlatform === \"win32\" ? \"ascribe.exe\" : \"ascribe\";\n  try {\n    return require.resolve(`${packageName}/bin/${executable}`);\n  } catch (error) {\n    const reason = error instanceof Error ? ` (${error.message})` : \"\";\n    throw new Error(\n      `@ascribed/cli could not find its native package ${packageName}${reason}. ` +\n        `Reinstall @ascribed/cli for ${currentPlatform}/${currentArch}, and ensure optional ` +\n        \"dependencies are enabled. The package manager must not omit optional dependencies.\",\n      { cause: error },\n    );\n  }\n}\n\n/** Backwards-compatible name for resolveBinary. */\nexport const nativeBinaryPath = (currentPlatform?: string, currentArch?: string): string =>\n  resolveBinary(\n    currentPlatform === undefined && currentArch === undefined\n      ? {}\n      : {\n          ...(currentPlatform === undefined ? {} : { platform: currentPlatform }),\n          ...(currentArch === undefined ? {} : { arch: currentArch }),\n        },\n  );\n"]}
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,QAAQ,GAA2B;IACvC,cAAc,EAAE,4BAA4B;IAC5C,aAAa,EAAE,2BAA2B;IAC1C,WAAW,EAAE,yBAAyB;IACtC,WAAW,EAAE,yBAAyB;CACvC,CAAC;AAOF,MAAM,UAAU,iBAAiB,CAC/B,eAAe,GAAW,QAAQ,EAClC,WAAW,GAAW,IAAI;IAE1B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,eAAe,IAAI,WAAW,EAAE,CAAC,CAAC;IAC3D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,kCAAkC,eAAe,IAAI,WAAW,IAAI;YAClE,uEAAuE,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAO,GAAmB,EAAE;IACxD,MAAM,eAAe,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IACzC,MAAM,WAAW,GAAG,iBAAiB,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;IACpE,MAAM,UAAU,GAAG,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,WAAW,QAAQ,UAAU,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,mDAAmD,WAAW,GAAG,MAAM,IAAI;YACzE,+BAA+B,eAAe,IAAI,WAAW,wBAAwB;YACrF,oFAAoF,EACtF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;IACJ,CAAC;AACH,CAAC","sourcesContent":["import { createRequire } from \"node:module\";\nimport { arch, platform } from \"node:process\";\n\nconst require = createRequire(import.meta.url);\n\nconst packages: Record<string, string> = {\n  \"darwin-arm64\": \"@ascribed/cli-darwin-arm64\",\n  \"linux-arm64\": \"@ascribed/cli-linux-arm64\",\n  \"linux-x64\": \"@ascribed/cli-linux-x64\",\n  \"win32-x64\": \"@ascribed/cli-win32-x64\",\n};\n\nexport interface BinaryPlatform {\n  platform?: string;\n  arch?: string;\n}\n\nexport function nativePackageName(\n  currentPlatform: string = platform,\n  currentArch: string = arch,\n): string {\n  const name = packages[`${currentPlatform}-${currentArch}`];\n  if (name === undefined) {\n    throw new Error(\n      `@ascribed/cli does not support ${currentPlatform}/${currentArch}. ` +\n        \"Supported platforms are darwin arm64, linux arm64/x64, and win32 x64.\",\n    );\n  }\n  return name;\n}\n\n/**\n * Resolve the installed native executable for the current machine.\n *\n * The optional `platform` and `arch` arguments are intended for packaging\n * tests; callers normally use `resolveBinary()` with no arguments.\n */\nexport function resolveBinary(options: BinaryPlatform = {}): string {\n  const currentPlatform = options.platform ?? platform;\n  const currentArch = options.arch ?? arch;\n  const packageName = nativePackageName(currentPlatform, currentArch);\n  const executable = currentPlatform === \"win32\" ? \"ascribe.exe\" : \"ascribe\";\n  try {\n    return require.resolve(`${packageName}/bin/${executable}`);\n  } catch (error) {\n    const reason = error instanceof Error ? ` (${error.message})` : \"\";\n    throw new Error(\n      `@ascribed/cli could not find its native package ${packageName}${reason}. ` +\n        `Reinstall @ascribed/cli for ${currentPlatform}/${currentArch}, and ensure optional ` +\n        \"dependencies are enabled. The package manager must not omit optional dependencies.\",\n      { cause: error },\n    );\n  }\n}\n"]}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-export { nativeBinaryPath, nativePackageName, resolveBinary } from "./binary.js";
+export { nativePackageName, resolveBinary } from "./binary.js";
 export type { BinaryPlatform } from "./binary.js";

package/dist/index.js

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { resolveBinary } from "./binary.js";
-export { nativeBinaryPath, nativePackageName, resolveBinary } from "./binary.js";
+export { nativePackageName, resolveBinary } from "./binary.js";
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
     const child = spawn(resolveBinary(), process.argv.slice(2), {
         stdio: "inherit",

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjF,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACxF,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QAC1D,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC1B,OAAO,CAAC,KAAK,CAAC,oDAAoD,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACnF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,OAAO,CAAC,QAAQ,GAAG,IAAI,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { spawn } from \"node:child_process\";\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport { resolveBinary } from \"./binary.js\";\n\nexport { nativeBinaryPath, nativePackageName, resolveBinary } from \"./binary.js\";\nexport type { BinaryPlatform } from \"./binary.js\";\n\nif (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {\n  const child = spawn(resolveBinary(), process.argv.slice(2), {\n    stdio: \"inherit\",\n    windowsHide: false,\n  });\n  child.on(\"error\", (error) => {\n    console.error(`@ascribed/cli could not start the native binary: ${error.message}`);\n    process.exitCode = 1;\n  });\n  child.on(\"exit\", (code) => {\n    process.exitCode = code ?? 1;\n  });\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG/D,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACxF,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QAC1D,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,KAAK;KACnB,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC1B,OAAO,CAAC,KAAK,CAAC,oDAAoD,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACnF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,OAAO,CAAC,QAAQ,GAAG,IAAI,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { spawn } from \"node:child_process\";\nimport { realpathSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport { resolveBinary } from \"./binary.js\";\n\nexport { nativePackageName, resolveBinary } from \"./binary.js\";\nexport type { BinaryPlatform } from \"./binary.js\";\n\nif (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {\n  const child = spawn(resolveBinary(), process.argv.slice(2), {\n    stdio: \"inherit\",\n    windowsHide: false,\n  });\n  child.on(\"error\", (error) => {\n    console.error(`@ascribed/cli could not start the native binary: ${error.message}`);\n    process.exitCode = 1;\n  });\n  child.on(\"exit\", (code) => {\n    process.exitCode = code ?? 1;\n  });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascribed/cli",
-  "version": "0.2.1-next.14",
+  "version": "0.2.1-next.16",
   "description": "The Ascribe command-line tool.",
   "type": "module",
   "license": "MPL-2.0",
@@ -32,10 +32,10 @@
     "node": ">=24"
   },
   "optionalDependencies": {
-    "@ascribed/cli-darwin-arm64": "0.2.1-next.14",
-    "@ascribed/cli-linux-arm64": "0.2.1-next.14",
-    "@ascribed/cli-linux-x64": "0.2.1-next.14",
-    "@ascribed/cli-win32-x64": "0.2.1-next.14"
+    "@ascribed/cli-darwin-arm64": "0.2.1-next.16",
+    "@ascribed/cli-linux-arm64": "0.2.1-next.16",
+    "@ascribed/cli-linux-x64": "0.2.1-next.16",
+    "@ascribed/cli-win32-x64": "0.2.1-next.16"
   },
   "devDependencies": {
     "@types/node": "^24.0.0"
@@ -43,7 +43,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7f59c3e433d6830ddb59e07f050bd1ac21f71d11",
+  "gitHead": "0077fa1e1fcd4ef67f9c6d48575c3f06f98adce8",
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit",

package/skills/ascribe/SKILL.md

@@ -3,12 +3,12 @@ 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.2.1-next.14"
+  ascribe-version: "0.2.1-next.16"
 ---
 
 # Ascribe
 
-Ascribe pages are Markdown with YAML frontmatter, `@` directives, and `{phrase}` keys, checked against a content model, `ascribe.toml`. A project's own rules (its page types, phrases, and the directives its pages use) are in the `AGENTS.md` beside its `ascribe.toml`, and `ascribe model` shows everything the content model allows. Read them before writing frontmatter, a directive, or a phrase.
+Ascribe pages are Markdown with YAML frontmatter, `@` directives, and `{phrase}` keys, checked against a content model, `ascribe.toml`. A project's own rules (its page types, phrases, and the directives its pages use) are what `ascribe agents rules` prints, from anywhere in the project; a project that ran `ascribe agents sync` also has them in the `AGENTS.md` beside its `ascribe.toml`, and one that didn't has no such file. `ascribe model` shows everything the content model allows. Read them before writing frontmatter, a directive, or a phrase.
 
 ## The loop
 
@@ -30,18 +30,28 @@ When `ascribe` isn't on the path, the project may pin it in a `package.json`: ru
 Each changes nothing, and each takes `--format json`.
 
 - `ascribe explain <code>`: what a diagnostic means, how to fix it, and an example.
-- `ascribe model`: what the content model allows: page types and their frontmatter, dimensions, phrases, features, glossary terms, widgets, and builds.
+- `ascribe model`: what the content model allows: page types and their frontmatter, dimensions, phrases, features, glossary terms, widgets, builds, and sources.
 - `ascribe outline <page>`: a page's title, type, and headings, with the ids links use.
 - `ascribe link <target> --from <page>`: whether a link works from a page, and what to write.
 - `ascribe render <page> --build <name>`: a page as one build's readers see it.
 - `ascribe refs <target>`: where a page, a heading (`guides/install.md#configure`), a phrase (`phrase:product`), or another entry is used.
-- `ascribe check --summary`: the problems counted by code and by file, for a project with many.
+- `ascribe check --summary`: the problems counted by code and by file, for a project with many; `ascribe check --code <code>` then shows one code's, to fix one rule at a time.
+- `ascribe diff`: which pages changed since the default branch, as readers see them, block by block; `ascribe diff <page>` shows one page's. To show that a change, such as a rename or a refactor, changed nothing for readers, run `ascribe diff --exit-code`: it exits with 0 when no page changed.
+- `ascribe drift`: the pages whose code examples changed since the default branch while their words didn't. Reread each one it lists.
 
 Use the commands when you have a shell. Without one, use the `ascribe_*` tools of Ascribe's MCP server if you have them: they return the same JSON.
 
+## Renaming
+
+`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.
+
+## 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>`.
+
 ## Fixes
 
-In `ascribe check --format json`, a diagnostic's `fixes` are edits that would fix it. A fix whose `applicability` is `safe` can be applied as given. Read an `unsafe` one and decide before applying it.
+In `ascribe check --format json`, a diagnostic's `fixes` are edits that would fix it. A fix whose `applicability` is `safe` can be applied as given: `ascribe check <file> --fix` applies every safe fix, then reports what's left. Read an `unsafe` one and decide before applying it.
 
 ## Other people's text
 
@@ -53,5 +63,5 @@ 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 file or folder whose name starts with `_` is a fragment: pages `@include` it, and it isn't a page.
-- Each directive's syntax: [references/directives.md](references/directives.md).
+- 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

@@ -17,3 +17,36 @@ A title line, `.<Title>`, goes on the line above a directive that takes one. A d
 A project can declare its own directives, widgets, whose names have a hyphen: `ascribe model --section widgets` lists them, with their attributes. Which note types, dimensions, and sources a project has: `ascribe model`.
 
 The full reference, with examples: https://ascribed-dev.com/go/directives/
+
+## Declaring a source
+
+A `@snippet` reads a file through a source. Declare one in `ascribe.toml` with the folder the code is in, relative to the folder `ascribe.toml` is in:
+
+```toml
+[sources.code]
+path = ".."
+include = ["src/**", "examples/**"]
+```
+
+Mark a region in the code file with two line comments, in its own comment syntax: `:snippet-start: <region>` on the line above, and `:snippet-end:` on the line below.
+
+```ts
+// :snippet-start: connect
+const client = connect(url);
+// :snippet-end:
+```
+
+Then `@snippet: code:src/client.ts#connect` shows it, and `@snippet: code:src/client.ts` shows the whole file. `ascribe model --section sources` lists the sources a project has.
+
+## Declaring a dimension
+
+`@variant` and `@available` name a dimension's values. Declare a dimension in `ascribe.toml` with its values, and optionally the labels readers see:
+
+```toml
+[dimensions.platform]
+label = "Platform"
+values = ["linux", "macos", "windows"]
+labels = { macos = "macOS" }
+```
+
+A value belongs to one dimension only. `ascribe model --section dimensions` lists the dimensions a project has.