@panaversity/ksor 0.0.55 → 0.0.57

package/templates/scaffold/.agents/skills/make-slides/SKILL.md

@@ -1,162 +0,0 @@
----
-name: make-slides
-description: Generate a presentation from one document and attach it, so it renders on that document's page. Use when the owner says "make slides for X", "turn this into a deck", "I need to present this", asks for a teaching aid or a slideshow, or when onboarding needs a session rather than a page.
-metadata:
-  version: "2.0.0"
----
-
-# Generating a presentation for a document
-
-You write the slides. Not an outline for somebody else to build — the actual
-deck, into `<doc>.slides.yaml`, which the site renders on that document's page.
-No browser, no third-party tool, no step where a human takes over.
-
-Run it end to end: read the document, write the deck, check every line back
-against the document, verify it builds. **The check is not optional** — it is
-the step that keeps the record's guarantee true.
-
-## The one rule everything else serves
-
-**A slide may only say what the document says.**
-
-The deck is a way of presenting the record, never a second source. A slide
-asserting a threshold the document does not contain is a claim nothing governs
-and no agent can cite — and because the deck is an attachment, the record now
-stands behind it. Every number, date, name and rule is copied from the
-document exactly, units included.
-
-If the document does not say something you want on a slide, there are two
-honest options: leave it out, or tell the owner the document is missing it.
-Never a third.
-
-## 1 · Read the document whole, first
-
-Read `<doc>.md` completely before writing anything. Note as you go:
-
-- **the decision it settles** — the reason it exists
-- **the rule, in its own words** — usually one or two sentences
-- **the numbers** — thresholds, deadlines, limits, and their units
-- **the cases** — what happens in each situation it names
-- **the boundary** — what it explicitly does NOT cover
-- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
-  the frontmatter
-
-If the document carries `<doc>.summary.md`, read that too: it is a reviewed
-compression of the same thing, and it tells you what the author thought was
-load-bearing.
-
-## 2 · Write the deck
-
-Write `<doc>.slides.yaml` beside the document:
-
-```yaml
-slides:
-  title: Expense approvals
-  description: The 15-minute version, for a room.
-deck:
-  - heading: What this settles
-    lead: One sentence, in the document's own words.
-    note: What to say here. Spoken, never shown.
-
-  - heading: The rule
-    bullets:
-      - Two approvers above the threshold, always
-      - The threshold is per invoice, including tax
-    note: Pause here. This is the slide people remember wrong.
-```
-
-**Per slide:**
-
-| Field     | Use                                                          |
-| --------- | ------------------------------------------------------------ |
-| `heading` | required — a statement, not a label. "The rule", not "Rules" |
-| `lead`    | one sentence, for a slide making a single point              |
-| `bullets` | three to five. Six is the cap, and six is already too many   |
-| `note`    | what the presenter SAYS — never a repeat of the slide        |
-
-**Per deck** — 8 to 14 slides for an ordinary policy document:
-
-1. What this settles, and for whom
-2. Why it exists — the decision behind it
-3. The rule itself, stated once
-4. One slide per case, with the real numbers
-5. What people get wrong, and what is true instead
-6. The boundary — what this document does not cover
-7. Where to find it: the route, the owner, the effective date
-
-**Habits that decide whether it is any good:**
-
-- **A heading is a claim.** "Recency is not authority" teaches; "Authority"
-  does not.
-- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
-- **The note carries the argument.** The slide holds the shape; the presenter
-  holds the reasoning. A note repeating the bullets is a wasted field.
-- **Do not pad to a target.** Five slides of substance beat twelve with three
-  that exist to reach twelve.
-
-## 3 · Check every line against the document
-
-Go back through slide by slide with the document open. For each:
-
-- Is every claim in the document? Name where.
-- Is every number identical, same units, same rounding?
-- Does any slide imply a rule the document does not state?
-- Does the boundary slide match what the document actually excludes?
-
-This pass finds real errors, reliably. A transcription slip in a deck outlives
-the session it was made for, because the next presenter trusts it.
-
-## 4 · Verify it
-
-```sh
-pnpm check     # refuses an orphan deck
-pnpm dev       # look at the page — the deck renders after the introduction,
-               # immediately before the first `##` section
-```
-
-`pnpm build` refuses — the deck's own shape is checked in the site build, not
-by `pnpm check`:
-
-- `ksor-slides-empty` — neither `deck:` nor `slides.url:`; nothing to show
-- `ksor-slides-two-sources` — both, so nothing says which one governs
-- `ksor-attachment-orphan` — no `<doc>.md` beside it
-
-## 5 · Tell the owner what you did
-
-Which document, how many slides, and **anything you left out because the
-document did not support it**. That last part is the useful half: it is how an
-owner finds out their document has a gap.
-
-## Embedding a deck made elsewhere
-
-If the owner already has a deck in Google Slides, Canva or SlideShare, use the
-linked mode — `slides.url:` and no `deck:`:
-
-```yaml
-slides:
-  title: Expense approvals
-  url: https://docs.google.com/presentation/d/<id>/edit?usp=sharing
-```
-
-The embed url is derived for those three providers; for anything else add
-`embed:` explicitly or it renders as a link. `url` must be https — a browser
-blocks a mixed-content frame silently, so an http one publishes a panel that
-never loads.
-
-**Prefer the record-owned deck.** A linked deck is not reviewed in a pull
-request, not versioned with its document, not withdrawn when the document is,
-and can rot to a dead link with nothing going red. Use the link when the deck
-already exists and somebody else maintains it — not as the default.
-
-## What NOT to do
-
-- **Do not put the deck in the document.** No `<iframe>`, no raw HTML.
-  `knowledge/` is CommonMark and must read cleanly in any markdown viewer.
-- **Do not write a slide the document cannot support**, even a true one. If it
-  is not in the record, the record cannot stand behind it.
-- **Do not make one deck for several documents.** A deck belongs to one
-  document, the way a summary does. A deck spanning five policies has no
-  document to be governed by and nothing to be withdrawn with.
-- **Do not patch a stale deck.** When the document changes materially,
-  regenerate from it. Patching is how a deck and its document drift, and a
-  deck that drifts starts winning arguments it should lose.

package/templates/scaffold/.agents/skills/make-summary/SKILL.md

@@ -1,153 +0,0 @@
----
-name: make-summary
-description: Write the summary of a document and attach it, so it renders as a second tab on that document's page. Use when the owner says "summarise X", "make a summary for this", "add summaries to the record", "give me the short version", or asks for a TL;DR, an abstract or a précis of a governed document.
-metadata:
-  version: "1.1.0"
----
-
-# Writing the summary of a document
-
-You write the summary. Not an outline for somebody else to finish — the actual
-file, `<doc>.summary.md`, which the site renders as a **Summary** tab beside
-the document's own words.
-
-Run it end to end: read the document, write the summary, check every line back
-against the document, verify it builds. **The check is not optional** — it is
-what keeps a summary from becoming a second, unreviewed copy of the record.
-
-## The one rule everything else serves
-
-**A summary may only say what the document says.**
-
-It is a compression of the record, never a second source. A summary asserting a
-threshold the document does not contain is a claim nothing governs — and
-because the summary is an attachment, the record now stands behind it. Every
-number, date, name and rule is copied exactly, units included.
-
-If the document does not say something the summary seems to need, there are two
-honest options: leave it out, or tell the owner the document is missing it.
-Never a third.
-
-## The second rule: cover every section
-
-**Every `##` section of the document is represented in the summary.**
-
-A summary that covers the opening and trails off is worse than none: a reader
-who used it believes they have the whole document. Walk the headings in order
-and check each one has landed somewhere in the summary before you call it done.
-
-A `###` subsection does not need its own line — fold it into its parent's,
-unless it carries a rule or a number of its own, in which case it does.
-
-## 1 · Read the document whole, first
-
-Read `<doc>.md` completely before writing anything. Note as you go:
-
-- **the decision it settles** — the reason it exists, usually one sentence
-- **the rule, in its own words**
-- **the numbers** — thresholds, deadlines, limits, and their units
-- **each `##` section** — and the one thing it is there to say
-- **the boundary** — what the document explicitly does NOT cover
-- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
-  the frontmatter
-
-If the document already carries `<doc>.slides.yaml`, read it: it is a reviewed
-compression of the same thing, and the two must not disagree.
-
-## 2 · Write the summary
-
-Write `<doc>.summary.md` beside the document. Its frontmatter is exactly one
-key and the checker refuses any other — a summary inherits its parent's
-audience, status and takedown, and a second key there would claim governance a
-non-document cannot carry:
-
-```markdown
----
-type: Summary
----
-
-The lead: what this document settles, in one or two sentences, in the
-document's own words. **Bold the thing a reader must not misremember.**
-
-- One line per `##` section, in the document's order.
-- Numbers exactly as the document states them, units included.
-- What the document explicitly does **not** cover.
-```
-
-**Shape:**
-
-| Part      | Use                                                      |
-| --------- | -------------------------------------------------------- |
-| lead      | one or two sentences — the decision the document settles |
-| bullets   | one per `##` section, in the document's own order        |
-| last line | the boundary: what this document does not settle         |
-
-**Length:** aim for a fifth of the document, and never more than a quarter. If
-the summary approaches the document's length, it has stopped being a summary
-— cut the elaboration, keep the rules.
-
-**Habits that decide whether it is any good:**
-
-- **Lead with the decision, not the definition.** A reader opening the Summary
-  tab wants what this settles, not what the topic is.
-- **Keep the document's own words for anything load-bearing.** Paraphrase the
-  explanation; copy the rule.
-- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
-- **Say what is excluded.** The boundary is the half a compression loses first
-  and the half a reader is most likely to get wrong.
-- **Do not add.** No context, no advice, no "note that" — the document is one
-  click away.
-
-## 3 · Check every line against the document
-
-Go back through the summary with the document open. For each line:
-
-- Is the claim in the document? Name where.
-- Is every number identical, same units, same rounding?
-- Does any line imply a rule the document does not state?
-- Walk the `##` headings in order: is each one represented?
-- Would a reader who read ONLY this be wrong about anything?
-
-That last question is the one that matters. A summary is used instead of the
-document, not before it.
-
-## 4 · Verify it
-
-```sh
-pnpm check     # refuses an orphan, or frontmatter that is not exactly `type: Summary`
-pnpm dev       # open the page — a Summary tab appears beside Document
-```
-
-The build refuses:
-
-- `ksor-attachment-orphan` — no `<doc>.md` beside it
-- `ksor-attachment-frontmatter` — anything but exactly `type: Summary`
-
-If no Summary tab appears, the file name is wrong: it must be exactly
-`<doc>.summary.md`, matching the document's own name.
-
-## 5 · Tell the owner what you did
-
-Which document, how long the summary is against the document, and **anything
-you left out because the document did not support it**. That last part is the
-useful half: it is how an owner finds out their document has a gap.
-
-Summarising several documents at once? Report them as a list with the same
-three facts each, and name any document you did NOT summarise and why — a
-document too short to compress does not need one, and saying so is the answer.
-
-## What NOT to do
-
-- **Do not summarise a document you have not read whole.** A summary written
-  from the first screen is confidently wrong about the rest.
-- **Do not write a line the document cannot support**, even a true one. If it
-  is not in the record, the record cannot stand behind it.
-- **Do not give a short document a summary.** Under roughly two screens there
-  is nothing to compress, and a Summary tab that restates the page teaches a
-  reader that the tab is not worth opening.
-- **Do not make one summary for several documents.** A summary belongs to one
-  document. One spanning five policies has no document to be governed by and
-  nothing to be withdrawn with.
-- **Do not patch a stale summary.** When the document changes materially,
-  rewrite from it. Patching is how a summary and its document drift, and a
-  reader on the Summary tab has no way to see that it happened.

package/templates/scaffold/.claude/skills/make-slides/SKILL.md

@@ -1,162 +0,0 @@
----
-name: make-slides
-description: Generate a presentation from one document and attach it, so it renders on that document's page. Use when the owner says "make slides for X", "turn this into a deck", "I need to present this", asks for a teaching aid or a slideshow, or when onboarding needs a session rather than a page.
-metadata:
-  version: "2.0.0"
----
-
-# Generating a presentation for a document
-
-You write the slides. Not an outline for somebody else to build — the actual
-deck, into `<doc>.slides.yaml`, which the site renders on that document's page.
-No browser, no third-party tool, no step where a human takes over.
-
-Run it end to end: read the document, write the deck, check every line back
-against the document, verify it builds. **The check is not optional** — it is
-the step that keeps the record's guarantee true.
-
-## The one rule everything else serves
-
-**A slide may only say what the document says.**
-
-The deck is a way of presenting the record, never a second source. A slide
-asserting a threshold the document does not contain is a claim nothing governs
-and no agent can cite — and because the deck is an attachment, the record now
-stands behind it. Every number, date, name and rule is copied from the
-document exactly, units included.
-
-If the document does not say something you want on a slide, there are two
-honest options: leave it out, or tell the owner the document is missing it.
-Never a third.
-
-## 1 · Read the document whole, first
-
-Read `<doc>.md` completely before writing anything. Note as you go:
-
-- **the decision it settles** — the reason it exists
-- **the rule, in its own words** — usually one or two sentences
-- **the numbers** — thresholds, deadlines, limits, and their units
-- **the cases** — what happens in each situation it names
-- **the boundary** — what it explicitly does NOT cover
-- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
-  the frontmatter
-
-If the document carries `<doc>.summary.md`, read that too: it is a reviewed
-compression of the same thing, and it tells you what the author thought was
-load-bearing.
-
-## 2 · Write the deck
-
-Write `<doc>.slides.yaml` beside the document:
-
-```yaml
-slides:
-  title: Expense approvals
-  description: The 15-minute version, for a room.
-deck:
-  - heading: What this settles
-    lead: One sentence, in the document's own words.
-    note: What to say here. Spoken, never shown.
-
-  - heading: The rule
-    bullets:
-      - Two approvers above the threshold, always
-      - The threshold is per invoice, including tax
-    note: Pause here. This is the slide people remember wrong.
-```
-
-**Per slide:**
-
-| Field     | Use                                                          |
-| --------- | ------------------------------------------------------------ |
-| `heading` | required — a statement, not a label. "The rule", not "Rules" |
-| `lead`    | one sentence, for a slide making a single point              |
-| `bullets` | three to five. Six is the cap, and six is already too many   |
-| `note`    | what the presenter SAYS — never a repeat of the slide        |
-
-**Per deck** — 8 to 14 slides for an ordinary policy document:
-
-1. What this settles, and for whom
-2. Why it exists — the decision behind it
-3. The rule itself, stated once
-4. One slide per case, with the real numbers
-5. What people get wrong, and what is true instead
-6. The boundary — what this document does not cover
-7. Where to find it: the route, the owner, the effective date
-
-**Habits that decide whether it is any good:**
-
-- **A heading is a claim.** "Recency is not authority" teaches; "Authority"
-  does not.
-- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
-- **The note carries the argument.** The slide holds the shape; the presenter
-  holds the reasoning. A note repeating the bullets is a wasted field.
-- **Do not pad to a target.** Five slides of substance beat twelve with three
-  that exist to reach twelve.
-
-## 3 · Check every line against the document
-
-Go back through slide by slide with the document open. For each:
-
-- Is every claim in the document? Name where.
-- Is every number identical, same units, same rounding?
-- Does any slide imply a rule the document does not state?
-- Does the boundary slide match what the document actually excludes?
-
-This pass finds real errors, reliably. A transcription slip in a deck outlives
-the session it was made for, because the next presenter trusts it.
-
-## 4 · Verify it
-
-```sh
-pnpm check     # refuses an orphan deck
-pnpm dev       # look at the page — the deck renders after the introduction,
-               # immediately before the first `##` section
-```
-
-`pnpm build` refuses — the deck's own shape is checked in the site build, not
-by `pnpm check`:
-
-- `ksor-slides-empty` — neither `deck:` nor `slides.url:`; nothing to show
-- `ksor-slides-two-sources` — both, so nothing says which one governs
-- `ksor-attachment-orphan` — no `<doc>.md` beside it
-
-## 5 · Tell the owner what you did
-
-Which document, how many slides, and **anything you left out because the
-document did not support it**. That last part is the useful half: it is how an
-owner finds out their document has a gap.
-
-## Embedding a deck made elsewhere
-
-If the owner already has a deck in Google Slides, Canva or SlideShare, use the
-linked mode — `slides.url:` and no `deck:`:
-
-```yaml
-slides:
-  title: Expense approvals
-  url: https://docs.google.com/presentation/d/<id>/edit?usp=sharing
-```
-
-The embed url is derived for those three providers; for anything else add
-`embed:` explicitly or it renders as a link. `url` must be https — a browser
-blocks a mixed-content frame silently, so an http one publishes a panel that
-never loads.
-
-**Prefer the record-owned deck.** A linked deck is not reviewed in a pull
-request, not versioned with its document, not withdrawn when the document is,
-and can rot to a dead link with nothing going red. Use the link when the deck
-already exists and somebody else maintains it — not as the default.
-
-## What NOT to do
-
-- **Do not put the deck in the document.** No `<iframe>`, no raw HTML.
-  `knowledge/` is CommonMark and must read cleanly in any markdown viewer.
-- **Do not write a slide the document cannot support**, even a true one. If it
-  is not in the record, the record cannot stand behind it.
-- **Do not make one deck for several documents.** A deck belongs to one
-  document, the way a summary does. A deck spanning five policies has no
-  document to be governed by and nothing to be withdrawn with.
-- **Do not patch a stale deck.** When the document changes materially,
-  regenerate from it. Patching is how a deck and its document drift, and a
-  deck that drifts starts winning arguments it should lose.

package/templates/scaffold/.claude/skills/make-summary/SKILL.md

@@ -1,153 +0,0 @@
----
-name: make-summary
-description: Write the summary of a document and attach it, so it renders as a second tab on that document's page. Use when the owner says "summarise X", "make a summary for this", "add summaries to the record", "give me the short version", or asks for a TL;DR, an abstract or a précis of a governed document.
-metadata:
-  version: "1.1.0"
----
-
-# Writing the summary of a document
-
-You write the summary. Not an outline for somebody else to finish — the actual
-file, `<doc>.summary.md`, which the site renders as a **Summary** tab beside
-the document's own words.
-
-Run it end to end: read the document, write the summary, check every line back
-against the document, verify it builds. **The check is not optional** — it is
-what keeps a summary from becoming a second, unreviewed copy of the record.
-
-## The one rule everything else serves
-
-**A summary may only say what the document says.**
-
-It is a compression of the record, never a second source. A summary asserting a
-threshold the document does not contain is a claim nothing governs — and
-because the summary is an attachment, the record now stands behind it. Every
-number, date, name and rule is copied exactly, units included.
-
-If the document does not say something the summary seems to need, there are two
-honest options: leave it out, or tell the owner the document is missing it.
-Never a third.
-
-## The second rule: cover every section
-
-**Every `##` section of the document is represented in the summary.**
-
-A summary that covers the opening and trails off is worse than none: a reader
-who used it believes they have the whole document. Walk the headings in order
-and check each one has landed somewhere in the summary before you call it done.
-
-A `###` subsection does not need its own line — fold it into its parent's,
-unless it carries a rule or a number of its own, in which case it does.
-
-## 1 · Read the document whole, first
-
-Read `<doc>.md` completely before writing anything. Note as you go:
-
-- **the decision it settles** — the reason it exists, usually one sentence
-- **the rule, in its own words**
-- **the numbers** — thresholds, deadlines, limits, and their units
-- **each `##` section** — and the one thing it is there to say
-- **the boundary** — what the document explicitly does NOT cover
-- **its governance** — `status`, `ksor.owner` and `ksor.effective_from` from
-  the frontmatter
-
-If the document already carries `<doc>.slides.yaml`, read it: it is a reviewed
-compression of the same thing, and the two must not disagree.
-
-## 2 · Write the summary
-
-Write `<doc>.summary.md` beside the document. Its frontmatter is exactly one
-key and the checker refuses any other — a summary inherits its parent's
-audience, status and takedown, and a second key there would claim governance a
-non-document cannot carry:
-
-```markdown
----
-type: Summary
----
-
-The lead: what this document settles, in one or two sentences, in the
-document's own words. **Bold the thing a reader must not misremember.**
-
-- One line per `##` section, in the document's order.
-- Numbers exactly as the document states them, units included.
-- What the document explicitly does **not** cover.
-```
-
-**Shape:**
-
-| Part      | Use                                                      |
-| --------- | -------------------------------------------------------- |
-| lead      | one or two sentences — the decision the document settles |
-| bullets   | one per `##` section, in the document's own order        |
-| last line | the boundary: what this document does not settle         |
-
-**Length:** aim for a fifth of the document, and never more than a quarter. If
-the summary approaches the document's length, it has stopped being a summary
-— cut the elaboration, keep the rules.
-
-**Habits that decide whether it is any good:**
-
-- **Lead with the decision, not the definition.** A reader opening the Summary
-  tab wants what this settles, not what the topic is.
-- **Keep the document's own words for anything load-bearing.** Paraphrase the
-  explanation; copy the rule.
-- **A bullet is one thought.** If it needs a comma splice, it is two bullets.
-- **Say what is excluded.** The boundary is the half a compression loses first
-  and the half a reader is most likely to get wrong.
-- **Do not add.** No context, no advice, no "note that" — the document is one
-  click away.
-
-## 3 · Check every line against the document
-
-Go back through the summary with the document open. For each line:
-
-- Is the claim in the document? Name where.
-- Is every number identical, same units, same rounding?
-- Does any line imply a rule the document does not state?
-- Walk the `##` headings in order: is each one represented?
-- Would a reader who read ONLY this be wrong about anything?
-
-That last question is the one that matters. A summary is used instead of the
-document, not before it.
-
-## 4 · Verify it
-
-```sh
-pnpm check     # refuses an orphan, or frontmatter that is not exactly `type: Summary`
-pnpm dev       # open the page — a Summary tab appears beside Document
-```
-
-The build refuses:
-
-- `ksor-attachment-orphan` — no `<doc>.md` beside it
-- `ksor-attachment-frontmatter` — anything but exactly `type: Summary`
-
-If no Summary tab appears, the file name is wrong: it must be exactly
-`<doc>.summary.md`, matching the document's own name.
-
-## 5 · Tell the owner what you did
-
-Which document, how long the summary is against the document, and **anything
-you left out because the document did not support it**. That last part is the
-useful half: it is how an owner finds out their document has a gap.
-
-Summarising several documents at once? Report them as a list with the same
-three facts each, and name any document you did NOT summarise and why — a
-document too short to compress does not need one, and saying so is the answer.
-
-## What NOT to do
-
-- **Do not summarise a document you have not read whole.** A summary written
-  from the first screen is confidently wrong about the rest.
-- **Do not write a line the document cannot support**, even a true one. If it
-  is not in the record, the record cannot stand behind it.
-- **Do not give a short document a summary.** Under roughly two screens there
-  is nothing to compress, and a Summary tab that restates the page teaches a
-  reader that the tab is not worth opening.
-- **Do not make one summary for several documents.** A summary belongs to one
-  document. One spanning five policies has no document to be governed by and
-  nothing to be withdrawn with.
-- **Do not patch a stale summary.** When the document changes materially,
-  rewrite from it. Patching is how a summary and its document drift, and a
-  reader on the Summary tab has no way to see that it happened.