The skill's links go somewhere, and WordCraft is named

content/command-line/presentations.md

@@ -33,13 +33,34 @@ There is no `--theme`: the renderer resolves the theme from the deck's own `them
 | `-o, --output <file>` | path | beside the input, `.md`; `-` for standard output |
 | `--media <dir>` | path | no extraction |
 | `--line-ending <lf\|crlf>` | `lf`, `crlf` | `lf` |
+| `--preserve-geometry` | flag | off |
 | `-h, --help` | flag | off |
 
 A line ending may also be written `unix`, `n`, `dos`, `windows` or `r`.
 
 The Markdown that comes back is the Markdown this tool writes decks in, so a deck can be read
 out, edited as text and put in again through `to-pptx` with a different theme.
 
+**`--preserve-geometry` keeps the shapes a deck placed itself.** A deck read back into Markdown
+comes back as text, and every free shape in it is left out: the shape itself disappears, not
+merely its design, so `deck.md` → `deck.pptx` → `deck.md` loses every position, colour and
+size. With the flag on, a free shape comes back as the free shape it is, with the box it was
+given and the colour it was painted:
+
+```markdown
+::roundrect{left=10% top=40% width=30% height=20% fill=4472C4}
+
+:::content{left=50% top=40% width=30% height=20%}
+Text in a free box.
+:::
+```
+
+The box is a percentage of the slide, because a shape is placed relative to the slide rather
+than in the pixels of one page size, and a shape that runs off the edge comes back with
+`bleed=true`. What still does not travel is what a shape is besides its box and its colour: the
+theme slot a colour came from, the shadow it casts, the corner radius of a rounded rectangle,
+the layer it was drawn on and the anchor of its box.
+
 ## Options for `diff`
 
 | Option | Value | Default |

content/presentation/directives.md

@@ -184,6 +184,16 @@ is refused with a message that lists all thirteen.
 attribute after another, not a list with commas in it — a comma is part of the value, so
 `{fill=red,stroke=blue}` is one attribute called `fill` whose value is `red,stroke=blue`.
 
+**A shape may run off the edge of the slide, if it says so.** A free shape lies within the slide
+unless it is written to bleed, and a negative `left` or `top` is refused with the two ways out
+named: write it as `0`, or write `bleed=true` if the shape is meant to hang off the edge. The
+grey circles behind a title that the page cuts off are a shape this can now write, and a
+mistyped `left=-20` is still caught — because the permission is on the shape, and a deck-level
+switch would silence the check for every shape in it.
+
+The Word half has the same rule for the same thing: a text box hangs off the edge of the page on
+`bleed=true` as well.
+
 `layout: blank` is what most of them want: a slide whose whole content is free shapes has no title
 to place them around. Every attribute each of them reads is in the package's own
 [README](https://github.com/markdown-office/markdown-presentation#free-shapes).
@@ -246,7 +256,7 @@ splits here the way it does there.
 
 ## Frontmatter directives
 
-Every key of every slide's frontmatter must be one of these nine:
+Every key of every slide's frontmatter must be one of these fifteen:
 
 <!-- reference: presentation.frontmatter -->
 
@@ -261,10 +271,27 @@ Every key of every slide's frontmatter must be one of these nine:
 | `description` | string | `null` | **first only** |
 | `template` | string, or a list of them | none | any |
 | `templates-file` | string | none | **first only** |
+| `template-settings` | mapping | none | a definition |
+| `background` | string | none | any |
+| `background-gradient` | string | none | any |
+| `background-angle` | integer | 180 | any |
+| `background-radial` | boolean | `false` | any |
+| `theme-variables` | mapping | the theme's | any |
 
 The layout roles are listed with the [themes](/presentation/themes/#layout-roles). Anything else —
 including Slidev's own `two-cols` — is refused with the list of what would have worked.
 
+**A background is one colour or one gradient.** `background-gradient` takes the stops of the
+gradient, one after another with a comma between them, and a stop may carry the place it is at
+as a percentage of the gradient — `accent1@50` is that stop at half of the way.
+`background-angle` says which way the gradient runs, and `background-radial` says it runs from
+the middle outwards, which is a way of running that has no angle.
+
+**A free shape may be painted with a gradient too**, with `gradient`, `gradient-angle` and
+`gradient-radial` carrying the same three things. A shape is filled with a colour **or** with
+a gradient, and the two together are refused. Every attribute each of them reads is in the
+package's own [README](https://github.com/markdown-office/markdown-presentation#free-shapes).
+
 A deck directive on a later slide is refused by name, because it is nearly always a slide that
 was meant to be the first one. The deck's own frontmatter **is the first slide's**, so `theme:`,
 `author:`, `description:` and `templates-file:` belong on the slide that opens the deck.
@@ -304,7 +331,7 @@ writing it out on every slide means changing it on every slide. A **template** i
 written once.
 
 A template is a slide of the deck's own Markdown whose frontmatter names a template and **nothing
-else**:
+but its own settings**:
 
 ```markdown
 ---
@@ -326,6 +353,24 @@ template: brand
 ---
 ```
 
+**A template's own settings are named as the template's.** A template may carry a background and
+the theme's values for itself, and every slide that draws it gets them. They go under
+`template-settings:`, which holds the same keys a slide's own settings do:
+
+```markdown
+---
+template: brand
+template-settings:
+  background: accent1
+  theme-variables:
+    dark: true
+---
+```
+
+The ordinary keys mean the **slide's** own everywhere, which is what tells a definition from a
+slide: a slide that draws a template and names a `background:` of its own is a slide, and is
+drawn with it.
+
 {% example "A deck whose wordmark is written once" %}
 ````md presentation
 ---

content/presentation/errors.md

@@ -22,6 +22,7 @@ is about both libraries, is on [Errors in general](/errors/).
 | `UnknownLayoutRole` | `layout:` is not one of the layout roles |
 | `UnknownTemplate` | a slide names a template the deck does not have — the message names the templates |
 | `MalformedChrome` | a template holds ordinary Markdown |
+| `MalformedGradient` | a gradient is not one: too few stops, a stop that names no colour, a position that is not a number, an angle that is not a whole number of degrees, stops that do not move forward, more stops than the ceiling allows, or a colour and a gradient on one shape |
 | `MalformedTemplatesFile` | the templates file a deck names holds a slide |
 | `TemplatesFileNotFound` | the templates file a deck names is not there, or is outside the roots |
 | `TemplatesFileTooLarge` | the templates file a deck names is over the ceiling |

content/presentation/index.md

@@ -62,8 +62,8 @@ slides and **cannot be a thematic break** — use `***`.
 ### Extended: frontmatter and themes
 
 The deck's own configuration goes in the frontmatter of slide 1. Every key is in a **closed set of
-nine**, and anything outside it fails the build with a message naming what would have worked. The
-nine are listed with the [directives](/presentation/directives/#frontmatter-directives).
+fifteen**, and anything outside it fails the build with a message naming what would have worked.
+The fifteen are listed with the [directives](/presentation/directives/#frontmatter-directives).
 
 {% example "The four keys that describe a deck" %}
 ````md presentation

content/presentation/themes.md

@@ -39,6 +39,17 @@ and the table names the keys as they are — the colon is YAML's and not theirs.
 `dark: yes` being refused is not pedantry. YAML 1.1 truthy strings are what make a theme written
 by hand behave differently from one written by a machine, and this one is for machines.
 
+## A slide's own values
+
+A slide may name the theme's values for itself, in its frontmatter, and what it names is a
+`theme.yml`: the four keys above that hold a value — `dark`, `colors`, `fonts` and `style` —
+read by the reader that reads the theme's own file. The three that hold the theme's identity
+— `name`, `description` and `author` — are not a slide's, so naming one is refused.
+
+A slide's values are laid over the template's, and the template's over the theme's, and one
+value laid over another leaves the rest alone: a slide that names one colour leaves the other
+eleven as they were.
+
 ## The twelve colour slots
 
 <!-- reference: presentation.theme-colours -->
@@ -118,6 +129,11 @@ title  content  two-column  section  blank  image-text  image-title  image-slide
 `blank` and `image-slide` have no title box. `layouts.yml` maps each role to a layout name in the
 master — the file may be a bare mapping or nested under a single `layouts:` key.
 
+**A slide with no title box draws the frontmatter's title as a heading in its body.** A deck
+that names no title has nothing to put one in, and a title that is not drawn is a silence —
+so the title becomes the first thing in the body, where it is a heading like any other. Write
+`title: ""` to leave it as metadata only, and the slide opens with no title at all.
+
 Only the roles a deck actually uses are built, so a ten-slide deck does not carry eight masters.
 
 ## Templates

content/word/directives.md

@@ -217,9 +217,16 @@ it is a paragraph.
 | `width`, `height` | the size in centimetres |
 | `left`, `top` | where it floats, in centimetres |
 | `border` | the colour of the line round it, six hexadecimal digits without a `#` |
+| `bleed` | whether the box may hang off the edge of the page |
 
 A box with no size is written out as its own source text.
 
+**A box hangs off the edge of the page only when it says so.** A negative `left` or `top` is
+refused with the two ways out named: write it as `0`, or write `bleed=true` if the box is meant
+to hang off the edge. The slides half has the same rule for the same thing — a free shape that
+runs off the edge of the slide is written `bleed=true` as well — so a document and a deck are
+written the same way.
+
 ## `::shape` — a shape
 
 ```markdown

content/word/errors.md

@@ -27,6 +27,7 @@ about both libraries, is on [Errors in general](/errors/).
 | `FileNotWritable` | **not** `InvalidInput`; the target cannot be written |
 | `TemplateNotFound` | `template_file:` names nothing |
 | `UnreadableTemplate` | the template holds more parts, or a larger part, than are allowed |
+| `BleedingBox` | a text box hangs off the edge of the page without saying that it means to |
 | `NoContentControl` | `--require-control`, and the template has none |
 | `MalformedTheme` | a theme file is not shaped like one |
 | `ThemeNotFound` | a theme name resolves to nothing — the message lists the ones that do |

skill/mdword/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mdword
-description: Turn Markdown into a Word document — .docx, .odt or .rtf — with the markdown-word library, and turn one back into Markdown. Use when asked to write or convert a Word document, to render Markdown into a company's own Word template or theme, to read a Word document back into Markdown, or to check that a document the library produced looks right.
+description: Turn Markdown into a Word document — .docx, .odt or .rtf — or a PowerPoint deck, with the markdown-word and markdown-presentation libraries, and turn one back to Markdown. Use when asked to write or convert a Word document or a presentation, to render Markdown into a company's own Word template or theme, to read a Word document or a deck back to Markdown, or to check that a document the library produced looks right.
 ---
 
 # mdword
@@ -26,7 +26,7 @@ documentation, not by recalling it.
 | What the two halves of the suite do with a name they know, and with one they do not | `references/directive-rules.md` |
 | The errors both halves throw | `references/errors-general.md` |
 | Where a document's files come from — the finder, the three roles, and the names the library composes | `references/general-files.md` |
-| The command line, and the options each command takes | `references/command-line-word.md`, `references/command-line-basic.md` |
+| The command line, and the options each command takes | `references/command-line-word.md`, `references/command-line-basic.md`, `references/command-line-presentations.md`, `references/command-line-theme.md` |
 | Installing the command line | `references/command-line-install.md` |
 | Installing this skill | `references/install.md` |
 
@@ -71,6 +71,17 @@ writes out of its settings folder. The script finds the key itself.
 it had to fall back**, because a renderer that cannot be trusted is worse than no renderer:
 a caller who does not know is told a layout is right when it is not.
 
+**WordCraft is not Microsoft's.** It is a clean-room implementation of Word — it draws a
+document the way Word does without being Word — and it comes from
+[storytold/wordcraft](https://github.com/storytold/wordcraft);
+[storytold/deckcraft](https://github.com/storytold/deckcraft) is its half for decks. The
+script looks for them on the path as `wordcraft-cli` and `deckcraft-cli`, and **a machine
+without them falls back to LibreOffice** and says so. Microsoft Word, where it is
+installed, is found on its own and used in preference to both.
+
+The two are separate programs: one draws a Word document and the other draws a deck, and a
+machine may have one without the other.
+
 ## What this half does differently
 
 **The Word half never refuses.** A directive it does not know is written into the document

skill/mdword/pages.json

@@ -8,9 +8,10 @@
     "",
     "The 'sections' are the pages that must all be there. A page added to one of them and",
     "not carried is a page the bundle has silently fallen behind on, and the checker says",
-    "so rather than letting it pass. The pages outside them \u2014 the command line for the",
-    "slides half, and the suite itself \u2014 are carried or not as this file says, because a",
-    "skill about the Word half has no reason to carry the slides half's command line.",
+    "The pages outside them — the suite itself — are carried or not as this file says,",
+    "because a skill about the two halves has no reason to carry the suite's own page. The",
+    "slides half's command line is carried: the bundle claims to be about decks as well as",
+    "about documents, and a page that is not there is a page an agent cannot read.",
     "",
     "The 'file' is the name the page is carried under. It is not the page's URL: the pages",
     "are flattened into one directory, and two pages of different sections can want the",
@@ -81,6 +82,14 @@
       "file": "command-line-install.md",
       "page": "command-line/installation.md"
     },
+    {
+      "file": "command-line-presentations.md",
+      "page": "command-line/presentations.md"
+    },
+    {
+      "file": "command-line-theme.md",
+      "page": "command-line/theme.md"
+    },
     {
       "file": "install.md",
       "page": "skills/index.md"