pageship 0.1.1 → 0.2.0

package/dist/skills/pageship-key-figures/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: pageship-key-figures
+description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for the few numbers and callouts a Pageship HTML document opens with, loaded by a pageship- kind skill before it writes key figures.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Key figures
+
+Key figures are the few numbers a reader needs before the detail. Each one is a claim, so it carries what the reader needs to read it right: a label, the value, its unit, its kind, its period and its source.
+
+Unless another pageship- skill loaded this one, start as [pageship-docs says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## 1. Pick the figures
+
+- Take figures only from the source: its numbers, and plain arithmetic on two of them of the same kind, unit and basis, such as the change between two periods of the same length. A change and its percentage are one figure, such as "−89 (−29.6%)". A derived figure names both inputs and their periods in its meta line.
+- Pick the ones the document's main point rests on, usually three to six: results, volumes, rates, estimates, targets and forecasts. A number that only describes the subject, such as how many items a list holds, or that needs a paragraph of context, stays in the body.
+- The strip holds as many figures as the source supports, even when the user asked for more. Fill no slot with a date, a descriptive count or a number you would have to guess. A number the reader would expect but the source lacks is an open question.
+- A statement without a number that matters as much as a figure, such as a gap the reader must know about, goes in a `.callout` paragraph right after the strip, in the source's words; two at most.
+
+## 2. Record each figure
+
+Note for each figure:
+
+- **Label**: what was counted, in the glossary's term or the source's words.
+- **Value and unit**: as the source gives them. Keep its rounding and qualifiers, so "about 140" stays "about 140" and "under 2 h 30 min" keeps "under".
+- **Kind**: from the table below, by the word the source uses for the number. Where a number comes from, such as an export, and qualifiers such as "about" go in the meta line and the value; they don't set the kind. A number whose kind the source doesn't state gets no kind label.
+- **Period or date, and source**: as the source names them. When the source gives a comparison, such as the previous quarter, add it.
+
+| Kind         | The source calls it            | Kind label                                                                                            | Left border |
+| ------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------- | ----------- |
+| Measured     | measured, counted              | Measured                                                                                              | solid       |
+| Estimate     | estimate, rule of thumb, guess | The source's own word when it names one, such as "Rule of thumb", otherwise Estimate; and who made it | dashed      |
+| Target       | target, goal, aim              | Target                                                                                                | double      |
+| Forecast     | forecast, projection           | Forecast, and who made it                                                                             | dotted      |
+| Illustrative | example, illustrative          | Illustrative                                                                                          | dashed      |
+
+Use the same kind word wherever the document mentions the figure. A derived figure takes the kind of its inputs, with "derived" added to the kind label, such as "Measured, derived". A target's label starts with "Target", such as "Target: median first response". A figure's status, such as "Off track", is a `.status` line that follows [the design rules' statuses](../pageship-docs/references/design.md#the-looks-colour-variables).
+
+## 3. Write the strip
+
+Place the strip right after the summary, before the detail:
+
+```html
+<dl class="figures">
+  <div class="figure" data-kind="measured">
+    <dt>Tickets opened</dt>
+    <dd class="value">1,690</dd>
+    <dd class="kind">Measured</dd>
+    <dd class="meta">1 to 30 Sep 2026, help desk export</dd>
+  </div>
+  <div class="figure" data-kind="measured" data-status="bad">
+    <dt>Breach rate</dt>
+    <dd class="value">14%</dd>
+    <dd class="kind">Measured</dd>
+    <dd class="status">Off track</dd>
+    <dd class="meta">1 to 30 Sep 2026, help desk export</dd>
+  </div>
+</dl>
+```
+
+```css
+.figures {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 13rem), 1fr));
+  gap: 0.75rem;
+  margin: 1.5rem 0;
+}
+.figure {
+  margin: 0;
+  padding: 0.75rem 1rem;
+  border: 1px solid var(--line);
+  break-inside: avoid;
+}
+.figure:is([data-kind], [data-status]) {
+  border-left: 6px solid var(--accent);
+}
+.figure[data-status="good"] {
+  border-left-color: var(--good);
+}
+.figure[data-status="warn"] {
+  border-left-color: var(--warn);
+}
+.figure[data-status="bad"] {
+  border-left-color: var(--bad);
+}
+.figure dd {
+  margin: 0;
+}
+.figure .value {
+  font-size: 1.75rem;
+  line-height: 1.2;
+  font-weight: 650;
+  font-variant-numeric: tabular-nums;
+  overflow-wrap: anywhere;
+}
+.figure :is(.kind, .status) {
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+.figure .meta {
+  font-size: 0.8125rem;
+  color: var(--muted);
+}
+.figure[data-kind="estimate"],
+.figure[data-kind="illustrative"] {
+  border-left-style: dashed;
+}
+.figure[data-kind="target"] {
+  border-left-style: double;
+}
+.figure[data-kind="forecast"] {
+  border-left-style: dotted;
+}
+```
+
+- `data-kind` is `measured`, `estimate`, `target`, `forecast` or `illustrative`. A figure whose kind the source doesn't state has no `data-kind` and no `.kind` line.
+- Colours: the frame `--line`; the left border `--accent` as each figure's focus, or its status colour; the meta line `--muted`; the label, value and kind `--fg`. A design skill may change type and spacing. Keep the label text, a distinct border style per kind and text sizes of at least 13px.
+
+## Check
+
+With print media emulated, every figure keeps its label, kind label and border.
+
+## Hand over
+
+Say how many figures you showed, which ones you derived, and any the user asked for that the source could not support.

package/dist/skills/pageship-media/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: pageship-media
+description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for images, video and audio in a Pageship HTML document, loaded by a pageship- kind skill before it shows media.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Media
+
+A source file shows images, video and audio so the reader sees or hears what the source points to. The document still reads in full when the media fails to load, when it is printed, and when the reader can't see or hear it. Nothing plays until the reader starts it.
+
+When the user named this skill to add media to an existing HTML source file, edit that file and keep its [document marker](../pageship-docs/references/file.md#the-document-marker). Otherwise, unless another pageship- skill loaded this one, start as [pageship-docs says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## 1. List the media
+
+For each image, video or audio file the source gives, note where it is, its size in pixels, its length, what the source says it shows or says, its caption file or transcript, and its credit. Measure local files with a command, such as `file` for images and `ffprobe` for video and audio. Take the sizes of hosted media from the source, or download the file to the system temporary folder and measure it there.
+
+Then decide how each one appears, taking the first rule that applies:
+
+1. **A page on a video or audio site**, such as YouTube, Vimeo or Loom. The Pageship sandbox blanks embedded players, so write a link to the page with its figure caption.
+2. **An `https://` URL to the file itself.** Embed it from that URL.
+3. **A local file** that keeps the source file under 5 MB once inlined. Embed it as a `data:` URL. Encoding adds a third to a file's size.
+4. **A local file too large for that, an `http://` URL, or no file at all.** Embed nothing. Keep its figure caption and any transcript in the text, and add an open question asking where the reader can find it, such as "Where is the onboarding recording hosted?".
+
+An animated image (GIF, animated WebP or PNG) moves on its own. Embed it only inside a `<picture>` with a still version for reduced motion (`<source media="(prefers-reduced-motion: reduce)" srcset="...">`). Without a still, link to it instead.
+
+## 2. Write the text that stands in for it
+
+- **Alt text** on every image says what the image shows that the reader needs, in one or two sentences. Take it from the source's description, or from what you see when you open the image yourself. When you can do neither, name only what the source calls it, such as "Screenshot of the billing page". An image that adds nothing to the text gets `alt=""`.
+- **A figure caption** in a `<figcaption>` under every image, video and audio says what the source says about it: what it shows, who made it, when and where, and its credit. It draws no conclusion of its own about what the media is or where it came from. A URL is an address, not a source of facts: name a host, owner or licence only when the source states it.
+- **Timed captions** for video come from a caption file the source gives (WebVTT, `.vtt`), attached as a `<track>`.
+- **A transcript** goes under every video and audio whose source gives one, or whose caption file has text: the words exactly as the source has them, in a `<details>` element with the summary "Transcript".
+
+Write timed captions and transcripts only from the source. When media has speech and the source gives neither, add an open question asking for a transcript.
+
+## 3. Write the markup
+
+Use these shapes, with the sizes you measured as `width` and `height`:
+
+```html
+<figure>
+  <img src="https://example.com/billing-page.png" width="960" height="540" alt="..." />
+  <figcaption>...</figcaption>
+</figure>
+
+<figure>
+  <video controls preload="metadata" width="960" height="540">
+    <source src="https://example.com/clip.webm" type="video/webm" />
+    <source src="https://example.com/clip.mp4" type="video/mp4" />
+    <track kind="captions" srclang="en" label="English" default src="data:text/vtt;base64,..." />
+  </video>
+  <figcaption>...</figcaption>
+</figure>
+<details>
+  <summary>Transcript</summary>
+  <p>...</p>
+</details>
+
+<figure>
+  <audio controls preload="metadata" src="https://example.com/memo.mp3"></audio>
+  <figcaption>...</figcaption>
+</figure>
+```
+
+- **Starts paused.** Every `video` and `audio` has `controls` and `preload="metadata"`, and no `autoplay`, in markup or in script.
+- **Keeps its space.** When you couldn't measure an `img` or `video`, give it `aspect-ratio: 16 / 9` and `object-fit: contain` in CSS in place of `width` and `height`.
+- **One `<source>` per format** the source gives, each with its `type`.
+- **Timed captions load inline.** A caption file from another host fails to load in a Pageship document, so attach the `.vtt` file as a `data:text/vtt;base64,` URL. When you can't read it, link to it under the player.
+- **Inline data comes from a command.** Build every `data:` URL with a command, such as `base64 -w0 <file>`, and splice it into the file with a short script, keeping working files in the system temporary folder. Never type encoded data by hand.
+
+Add these rules to the stylesheet:
+
+```css
+figure {
+  margin: 1.5rem 0;
+  min-width: 0;
+}
+figure img,
+figure video {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  background: var(--surface);
+}
+audio {
+  display: block;
+  width: 100%;
+  max-width: 40rem;
+}
+@media print {
+  video,
+  audio {
+    display: none;
+  }
+}
+```
+
+## Check
+
+Run this in the browser console and fix every item it returns:
+
+```js
+[
+  ...[...document.images]
+    .filter((i) => !(i.complete && i.naturalWidth > 0))
+    .map((i) => `image failed: ${i.src.slice(0, 60)}`),
+  ...[...document.querySelectorAll("video, audio")]
+    .filter((m) => m.error || m.readyState < 1)
+    .map((m) => `media failed: ${m.currentSrc.slice(0, 60)}`),
+  ...[...document.querySelectorAll("track")]
+    .filter((t) => t.readyState !== 2)
+    .map((t) => `captions failed: ${t.label}`),
+  ...[...document.querySelectorAll("video, audio")]
+    .filter((m) => !m.paused)
+    .map((m) => `playing on its own: ${m.currentSrc.slice(0, 60)}`),
+];
+```
+
+## Hand over
+
+List each piece of media with its outcome from step 1: embedded, inlined, linked, or an open question.

package/dist/skills/pageship-motion/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: pageship-motion
+description: Later step of pageship-docs: for a request to write or edit a document, load pageship-docs first; load this skill first only when the user names it. Pattern for animation and transitions in a Pageship HTML document, such as playing a change over time or moving a marker along a path, loaded by a pageship- kind skill before anything on the page moves.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Motion
+
+Motion shows the reader something they would otherwise have to work out: what caused what, the order things happen in, or how a value changes over time. Everything else on the page holds still.
+
+Unless another pageship- skill loaded this one, start as [pageship-docs says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill). Named for just an animation, the file holds the animation and the content it moves.
+
+## 1. Decide what moves
+
+Motion has exactly three jobs, and each starts when the reader acts:
+
+- **Change.** A value or series changing over time, such as a backlog building week by week, played from a Play button.
+- **Order.** Stages or a path appearing in sequence as the reader steps or plays through them.
+- **Cause.** An event and its effect, such as a marker moving from one stage to the next when the reader presses Next.
+
+A transition of 300 ms or less may also carry the eye across a change the reader just made, such as the highlight moving to the new stage.
+
+Everything else is still:
+
+- Nothing moves on page load or as the reader scrolls.
+- Numbers show their final value and text shows in full from the start.
+- Nothing pulses, bounces, loops, lifts on hover or drifts in the background. Emphasis comes from position, size, weight and the accent colour.
+
+A request to make a document more engaging, lively or polished asks for clearer content and layout: a stronger summary, key figures up front, better headings, a table or a chart where it helps. It adds no motion. When the user or a design skill asks for motion this section rules out, leave it out and say so in your hand-over.
+
+Done when every planned motion has its job and the reader action that starts it, or you planned none.
+
+## 2. Build it so the still page tells the whole story
+
+- **The whole picture first.** Before the reader presses anything, the page shows the complete result: every week of the series, every stage of the path, with its values.
+- **Ends complete.** Playback stops at the end and shows the full picture again. It never loops.
+- **Paused keeps context.** When the reader pauses or steps part way, the parts not yet reached stay visible but faint, such as the later weeks drawn in a pale line.
+- **The values in text.** Every value a frame shows is also in text on the page, such as a table under the chart or labels on the path. A position line, such as "Week 5 of 13: 2 Aug, 162 open tickets", names the current frame, with `aria-live="polite"`.
+- **Controls.** Playback has a Play/Pause button whose label says what it will do, and Previous and Next buttons that step one frame, by the [controls rules](../pageship-interaction/SKILL.md#controls) of `pageship-interaction`.
+- **Pace.** A frame holds long enough to read its value: about 500 to 800 ms. A full playback takes about 10 seconds or less. Transitions between states take 150 to 300 ms with an ease-out curve.
+- **One thing at a time.** Animate only the element that carries the change, using `transform`, `opacity` or SVG attributes.
+
+## 3. Respect reduced motion
+
+Under `prefers-reduced-motion: reduce`, nothing tweens. Every control still works and changes the state at once: Next jumps to the next frame, and Play advances frame by frame with no movement between them.
+
+- In CSS, turn off every animation and transition under that media query.
+- In script, check `matchMedia("(prefers-reduced-motion: reduce)").matches` each time before you animate, and set the end state directly when it is true.
+
+## Check
+
+- Load the page and wait two seconds without touching it. Nothing moved, and the screenshot shows the whole picture.
+- Press Play and let it run to the end. It stops on the full picture. Play again and pause part way: the parts not yet reached are still visible.
+- Emulate `prefers-reduced-motion: reduce` and use every control. Each state appears at once.
+- Emulate print media. The full picture prints, with no controls.
+- Without a browser, read the CSS and script against steps 1 to 3.

package/dist/skills/pageship-plan/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: pageship-plan
+description: HTML plans, as the second step of pageship-docs. For any request to write, regenerate, edit or move a plan, load pageship-docs first; load this skill first only when the user names it.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Plan
+
+A plan tells the reader where the work is going, what is decided, which steps to take in what order, what is still open and what it leaves out. The reader acts on it, so every commitment keeps the strength, order and wording its author gave it. It is the author's plan made easier to follow, never a bigger one.
+
+Write it by [step 4 of pageship-docs](../pageship-docs/SKILL.md#4-write-the-file). Unless `pageship-docs` loaded this skill, start as [it says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## Gather
+
+Take an inventory. An item is a goal, decision, assumption, step, owner, date, dependency, question, exclusion, supporting fact or hedge ("might", "if there's time", "I can", "ideally", "not agreed yet").
+
+## Parts
+
+- **Goal.** The outcome the plan aims for, in the source's words. When the source states none, the missing goal is an open question.
+- **Decisions.** What the source says is decided or agreed, with who decided and when, as given. A decision that needs work to carry out stays here; the step may name it.
+- **Steps.** Actions someone is to take, with their owners, dates and conditions.
+- **Assumptions.** What the source takes as true without checking, or says it believes, expects or guesses.
+- **Open questions.** What the source asks or says it doesn't know, and every gap the reader needs closed to act, such as a step that waits on something the source never settles.
+- **Out of scope.** What the source says the plan won't do or change.
+
+A supporting fact, such as a reason, a baseline or a past figure, sits beside the item it explains, never as an assumption or decision of its own.
+
+Each item keeps its strength:
+
+- A hedged or unassigned action stays in the plan, with the source's hedge beside it ("if there's time", "not agreed yet").
+- A hedge keeps its speaker and its reach: "I haven't checked" stays the author's own, never "nobody has checked".
+- A step's owner is whoever the source gives that work to. When the assignment sits outside the step, such as in a decision, show the owner and quote where it comes from. An offer ("I can take the export") stays an offer in its own words, and someone who could do a step, such as the only one with access, stays a fact beside it; neither is its owner.
+
+## Order and dependencies
+
+- **Order.** Steps keep the source's order and numbers. When it has no numbers, number them in the order given and report the numbering as yours.
+- **Dependencies.** A step depends on another step or event only when the source says it needs, waits for, follows or uses the result of it ("after step 2", "once legal signs off", "using the pilot results"). Show each with the words that state it. A step the source gives no dependency shows none, even when it sits later or seems related.
+- **Dates.** A step carries a date only when the source gives one, at the source's precision: "in spring" stays "in spring".
+
+## Order of the file
+
+1. **Title and goal.** An `h1` naming the plan, then the goal and the main decisions in the source's words, with the date and author when the source gives them.
+2. **Decisions.**
+3. **Steps.** An ordered list, or a table when most steps share fields such as owner, date and dependency. Each step shows its owner, date and dependency as visible text, only where the source gives them. When the dependencies branch or join, you may add a diagram of them beside the list, never instead of it.
+4. **Assumptions.**
+5. **Open questions.**
+6. **Out of scope.**
+
+Every visual element shows a fact the source gives. A timeline or Gantt chart needs a source date for every item it places, a progress bar or percentage the source's figure, and a status badge, colour or icon the source's status for that item. The same holds for priorities, effort estimates, risk ratings and summary dashboards. Without those facts, the plan is plain lists and tables.
+
+## Check
+
+The steps are in the source's order, and every status, date and dependency quotes the source.

package/dist/skills/pageship-report/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: pageship-report
+description: HTML reports, as the second step of pageship-docs. For any request to write, regenerate, edit or move a report, load pageship-docs first; load this skill first only when the user names it.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Report
+
+A report tells the reader what was found, what it means, what to do about it and how sure anyone can be. The reader weighs each part separately, so the four never mix.
+
+Write it by [step 4 of pageship-docs](../pageship-docs/SKILL.md#4-write-the-file). Unless `pageship-docs` loaded this skill, start as [it says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## Parts
+
+- **Observation.** What was seen or measured, with where and when.
+- **Interpretation.** What the source says the observations mean, such as a cause, a trend or a comparison, attributed to whoever made it when the source does.
+- **Recommendation.** What the source says to do, with any owner and date it gives.
+- **Uncertainty.** What limits confidence: missing data, small samples, unverified claims, disagreements between sources. Every gap becomes an open question here.
+
+## Order
+
+1. **Title and summary.** An `h1` naming the subject, then the main finding and the main recommendation in the source's words, with the date and author when the source gives them.
+2. **Observations.**
+3. **Interpretation.**
+4. **Recommendations.** Numbered when the source gives an order.
+5. **Uncertainty and open questions.**
+6. **Sources.** As the source names them.

package/dist/skills/pageship-review-report/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: pageship-review-report
+description: HTML review reports, as the second step of pageship-docs. For any request to review a change or a plan and write up the findings, or to write, regenerate, edit or move a review report, load pageship-docs first; load this skill first only when the user names it.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Review report
+
+A review report tells the reader whether a change or a plan is ready, what is wrong with it, how much each problem matters and how sure the reviewer is. The reader fixes the worst finding first and trusts each finding as far as its evidence goes.
+
+Write it by [step 4 of pageship-docs](../pageship-docs/SKILL.md#4-write-the-file), with steps 2 and 3 below in place of its Sort. Unless `pageship-docs` loaded this skill, start as [it says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## Who reviews
+
+- **You review.** The user asks you to review a change, a plan or another document. The findings, severities and verdict are yours, and the summary says so. Every fact you state about the subject still traces to the subject or to a command you ran.
+- **You write up a review.** The user gives you someone else's review, such as notes or comments. That review is the source: keep its findings, severities, statuses and verdict in its words.
+
+## 1. Gather
+
+The subject is what is under review: for a change, the diff, its description, the files it touches, their callers and their tests; for a plan, the plan and every document it cites or relies on.
+
+The review leaves the subject exactly as it found it. To run something, such as the tests with a change applied, copy the project to the system temporary folder, work there and delete the copy when done.
+
+Done when you can name every file in the subject, and every file or dataset it relies on that you can't read.
+
+## 2. Record the findings
+
+When you review, check the subject against its own claims and what it relies on. For a change: it does what its description says, its callers and tests still work, its tests can fail, and it handles the edge cases its inputs allow. For a plan: its facts match their sources, its steps reach its goal without contradicting each other, and it names its costs, risks and owners.
+
+Record each problem as one finding with these fields:
+
+- **Where.** The file and line, or the plan's section heading.
+- **Checked.** What you compared or ran, in one line.
+- **Evidence.** The quoted lines from the subject and from the source you compared it with, or the command you ran and the part of its output that shows the problem.
+- **Status.** One of:
+  - _Verified_: the evidence shows the problem by itself. A command's output shows it, two quoted passages contradict each other, or a file the subject needs is missing.
+  - _Not verified_: it rests on reading or reasoning you could not confirm, or on information the project doesn't hold. Say what would confirm it.
+  - _Not stated_: only when you write up a review that doesn't say whether the finding was confirmed.
+- **Fix.** What would resolve it, only when the evidence points to one.
+
+A claim in the subject that nothing you can read supports is a finding, not verified, naming the claim and what would confirm it. A concern you can't tie to a place in the subject goes under open questions.
+
+A finding states only what its evidence shows. A cause, consequence, history or intent the evidence doesn't show becomes an open question. Run the example behind each consequence you state, and state what it shows. A claim about a whole set, with words such as "only", "no", "every" or "never", names where you looked, as in "no other file in `src/` imports it". Quote the subject in its own words, and write your own sentences in the glossary's terms even where the subject uses a word the glossary avoids.
+
+Keep two more lists: **reviewed**, each part of the subject with how you checked it, and **not reviewed**, each part of the subject or what it relies on that you didn't check, with the reason.
+
+When you write up a review, take each of its findings into the same fields. A field the source leaves empty stays empty.
+
+Done when every finding has its fields, and every part of the subject is on one of the two lists.
+
+## 3. Rate each finding and reach the verdict
+
+When you write up a review, keep its severities and verdict, write "not stated" for any it leaves out, and skip this step.
+
+When you review, rate each finding on this scale, and report the scale as structure you introduced:
+
+- **Blocker.** Fix it before the change merges or the plan goes ahead. Left as it is, the change gives wrong results, breaks something that works today, loses data or opens a security hole, or the plan cannot reach its goal. A wrong fact is a blocker only when correcting it would change what the subject decides or does.
+- **Major.** Fix it first unless there is a reason not to. It is wrong in some cases, leaves out something the goal needs, relies on a claim with no support, or states a wrong fact whose correction leaves the decision as it is.
+- **Minor.** Worth fixing and blocks nothing, such as unclear wording, naming, or a small gap in tests or detail.
+- **Note.** An observation that asks for no change.
+
+A finding that is not verified keeps the severity it would have if confirmed. The verdict follows from the most severe finding:
+
+- **Not ready**: at least one blocker.
+- **Ready after changes**: no blocker, at least one major.
+- **Ready**: only minor findings and notes, or none.
+
+When the project defines its own severity scale or verdict words, use them: map each of its levels to one above, say which, and reach the verdict through that mapping.
+
+Then list what would change the verdict: the fixes that would raise it, and the findings not verified and parts not reviewed that could lower or raise it once checked.
+
+## Order
+
+1. **Title and summary.** An `h1` naming what was reviewed, with its version, commit or date when the source gives one. Then the verdict in one sentence, the number of findings at each severity, the most severe finding, and who reviewed it: you, or the reviewer the source names.
+2. **Findings.** Most severe first, and in the subject's order within a severity. Each finding is an `article` with an `id`, a heading stating the problem in one sentence, and its severity and status as words beside the heading; colour may repeat those words, never replace them. The other fields follow as a definition list, with quoted code and passages in `pre` or `blockquote`. With more than five findings, put a table after the summary with each finding's severity, status and heading, linked to the finding.
+3. **Open questions.**
+4. **Scope.** The reviewed and not-reviewed lists.
+5. **Verdict.** The last section: the verdict, the rule it follows from, and what would change it.
+
+Done when every finding is in the file with all its fields.
+
+## Check
+
+Reread each finding and the verdict section sentence by sentence: each sentence is a quote, a command result, or a conclusion its evidence shows for every case it covers. Narrow or delete the rest.
+
+## Hand over
+
+Add the verdict and what was not reviewed.

package/dist/skills/pageship-slide-deck/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: pageship-slide-deck
+description: HTML slide decks, as the second step of pageship-docs. For any request to make slides or a presentation, or to regenerate, edit or move a deck, load pageship-docs first; load this skill first only when the user names it.
+license: MIT
+metadata:
+  version: "0.2.0"
+---
+
+# Slide deck
+
+A slide deck is one HTML file that presents from a browser, one slide per screen. Each slide carries one main idea the audience takes in at a glance, and together the slides carry everything the source says.
+
+Write it by [step 4 of pageship-docs](../pageship-docs/SKILL.md#4-write-the-file), with step 2 below in place of its Sort. Unless `pageship-docs` loaded this skill, start as [it says](../pageship-docs/SKILL.md#starting-at-a-kind-or-pattern-skill).
+
+## 1. Gather
+
+Take an inventory. An item is a finding, figure, reading, disagreement, decision, action, owner, date, status, target, question, gap or hedge. A reading keeps who holds it.
+
+## 2. Map every item to a slide
+
+Plan the slides before writing any HTML: for each, its headline and the inventory items it carries.
+
+- **One main idea per slide.** The headline states it as a sentence in the source's terms, such as "Median first response rose to 3 h 40 min". It is true of every item on the slide and says no more than they do, and a reading keeps its owner ("Priya: billing drove most of the slowdown"). Slide 1 states the deck's main point under its title.
+- **Every item on a slide.** Give the source's gaps a slide of open questions.
+- **The source's order.** Slides follow the source's order unless the user asks for another. You may group items by a field the source gives them, such as status or owner, when that gives each slide one idea; keep the source's order inside each group. Add no agenda slide; the engine's outline lists the slides.
+- **A slide's budget.** Below the headline, a slide holds one of: up to five bullets of at most two lines each; a table of up to six rows and four columns; up to four key figures; one diagram or chart; or a quote of up to 30 words. Add one line of source or date only where the source gives one for the slide's items.
+- **Slide count.** When the items need more slides than the user asked for, add slides. Never drop, merge away or shorten an item, or mix unrelated items on one slide, to meet a count.
+
+Done when every inventory item is mapped to a slide and no slide exceeds its budget.
+
+## 3. Write the slides
+
+Copy the markup, stylesheet and script from [the slide engine](references/engine.md) unchanged, then write the slides into it:
+
+- One `section class="slide"` per planned slide, with IDs `slide-1`, `slide-2` and on in order. Slide 1 holds the deck's `h1`; every other slide starts with an `h2` holding its headline.
+- Size text inside a slide in `em` only, so it scales with the frame, and nothing smaller than `0.875em`.
+- Each slide shows all its content as soon as it appears: no builds, no transitions between slides, nothing that advances by itself.
+- Keep everything on the slide: no speaker notes, presenter view or saved position.
+- A table, diagram or chart fits the frame without scrolling.
+
+Load `pageship-interaction` before writing: its rules cover the engine's controls and any control you put on a slide. The engine owns the frame, type scale, controls, navigation and print layout, and colours them from [the look's colour variables](../pageship-docs/references/design.md#the-looks-colour-variables): `--surface` around the slide, `--bg` on it, `--accent` for the progress bar, `--accent-2` for the rule under slide 1's title, and `--line` and `--muted` for rules and control borders. A design skill's choices go into those variables and the slide content, never into the engine. Charts, diagrams, key figures, tables and statuses on a slide take their colours as their own skills say. Add no step-through around the slides.
+
+## Check
+
+- At 1280 by 800 and at 1920 by 1080, step through every slide with the arrow keys and read the console: the engine logs an error for each slide whose content overflows its frame. Split that slide, or cut words that are yours, not the source's. Keep the engine's type sizes.
+- Open the link to one slide, such as `#slide-3`, and confirm the deck opens on it.
+- At 390px wide, every slide shows on one scrolling page.
+- Print to PDF with the page size the stylesheet sets (in Playwright, `page.pdf({ preferCSSPageSize: true })`) and confirm one 16:9 page per slide.
+- Without a browser, read every slide against its budget.
+
+## Hand over
+
+Add the number of slides and, when it differs from a count the user asked for, why.