Abc to booklet errors

.github/skills/booklet-song-from-abc/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: booklet-song-from-abc
+description: 'Create or fix a Sea Shanties booklet song page/spread from its ABC-notation source, keeping chords in sync. USE WHEN: generating a new booklet/*.md song from a songs/*.txt ABC file; auditing or fixing chord transcription errors (wrong chord, wrong word, missing/extra chord) between a booklet markdown and its ABC; aligning [chord] placements to the ABC "chord"-before-note positions; transposing a booklet song to a new key. Covers both formats (ABC and booklet markdown), the note→syllable→chord alignment procedure, caller-vs-crew (`>`) refrain marking, and the common pitfalls (late chords vs pickup placement, dropped internal returns, key-signature accidentals, transposition drift, held-note melisma).'
+---
+
+# Booklet Song from ABC
+
+Build or repair a song in `booklet/` so its `[chord]` placements match the harmony encoded in the corresponding `songs/*.txt` ABC file. **The ABC is the primary reference for chords and lyrics** — but the songbook maintainer may deliberately override it by ear (see pitfall 11).
+
+## When to use
+
+- **Initial generation** — a `songs/<slug>.txt` ABC exists and you need a new `booklet/<slug>.md` spread.
+- **Audit / fix** — a `booklet/<slug>.md` already exists and you're checking or correcting its chords against the ABC (the task that produced [SongAnalysis.md](../../../SongAnalysis.md)).
+- **Transpose** — moving a booklet song to a different key for the singers' range while staying faithful to the ABC's progression.
+
+## The two formats
+
+### ABC source (`songs/*.txt`)
+
+Header fields: `X:` index, `T:` title, `M:` metre, `L:` default note length, `K:` key, `Q:` tempo, `V:` voice, `P:` part label (e.g. `Verse` / `Chorus`), `%%…` render directives.
+
+Body:
+- Notes are letters (`A`–`G`, `a`–`g`, `,`/`'` shift octave). Digits/fractions after a note set duration (`e2`, `b,3/2`, `A4`).
+- **Chords** are quoted text placed *immediately before the note they attach to*: `"F"ABcA` → the `F` chord starts on the `A`.
+- `w:` is a lyric line aligned **one syllable per note, left to right**. Within a word, hyphens split syllables (`John-ny`); spaces separate words. `~`, `*`, `_` mark a **held note / melisma** (the previous syllable continues — do NOT advance to the next syllable). `\` continues a `w:` onto the next line. `y`/`z` are spacers/rests.
+- `W:` (capital) holds extra verses as plain text (no note alignment).
+- **Key signature changes which letter means which pitch.** In `K:Eb`, a written `A` note is actually **A♭** — this decides whether a passage fits, say, `Fm` vs `Cm`. Never infer the chord from the melody letter without applying the key signature.
+- Multi-voice songs (`V: 1`, `V: 2`) put the melody usually in `V: 1`; read chords from the melody voice.
+
+### Booklet markdown (`booklet/*.md`)
+
+- `# Title` first line; optional credit as an italic line `*Artist, year*`.
+- Verse lines are plain text lines.
+- `{chorus}` opens a boxed chorus block (styled by `shanties.css`).
+- `[Chorus]` on its own line is a **cue** ("repeat the chorus here").
+- A line beginning with `> ` renders in the **refrain style** (indented italic). Use it to mark everything the **crew** sings versus the **caller/lead**: the echoed repeats of a call line, the response refrains, and — in a traditional call-and-response shanty — *every* line of the `{chorus}`. Leave the caller's unique lead lines un-prefixed (roman). A modern verse/chorus song that isn't call-and-response (e.g. Joli Rouge) keeps its chorus un-prefixed.
+- `[Chord]` is placed **immediately before the syllable it sits on**: `to[G]bacco` → `G` on the "bac" syllable. Put it on the note's **downbeat syllable**, not a pickup word before it (`There [Cm]once`, not `[Cm]There`).
+- Separate stanzas within a long verse with a **blank line**.
+- `---` marks the **spread/page break** inside the song.
+
+## Procedure: ABC → booklet
+
+1. **Read headers.** Note `K` (key + accidentals), `M`, `L`, and any `P:` (Verse/Chorus) and `V:` (which voice is the melody).
+2. **Walk each melodic line note-by-note**, pairing every note with its `w:` syllable in order. Skip nothing: held-note markers (`~ * _`) keep the pointer on the current syllable.
+3. **Record each chord's syllable** — the syllable of the note *immediately after* each `"chord"`.
+4. **Emit booklet lines**, putting `[Chord]` right before that syllable. Copy the ABC's `w:` (and `W:`) text as the lyrics; prefer `w:` wording over `W:` when they differ.
+5. **Structure & roles:** wrap the refrain in `{chorus}`; mark every **crew** line with `> ` (echoed call repeats, refrain answers, and all chorus lines of a call-and-response shanty), leaving the **caller's** lead lines un-prefixed; use `[Chorus]` as the repeat cue for later verses; break long verses into stanzas with a blank line; insert `---` near the middle so the song fills a two-page spread.
+6. **House style for verses:** the booklet normally leaves verses **unchorded**, showing chords once (in the `{chorus}`, or on the first chorded instance). Keep verses unchorded **unless** the ABC's verse and chorus have genuinely different progressions, or the ABC only harmonizes the verse — then chord whichever section carries the harmony.
+7. **Register the page** in [book.yaml](../../../booklet/book.yaml) (`pages:` list, `type: song`) if this is a new song.
+
+## Procedure: audit / fix an existing page
+
+1. Do the same note→syllable→chord alignment from the ABC.
+2. Diff the booklet's `[chord]` positions against the derived positions. Classify each mismatch: **wrong chord**, **wrong word** (misaligned), **missing**, or **extra**.
+3. Fix minimally — move/replace only the offending `[chord]`; don't rewrite lyrics unless they diverge from the ABC.
+4. Record findings (per-song verdict) as in [SongAnalysis.md](../../../SongAnalysis.md).
+
+## Common pitfalls (ranked by how often they bite)
+
+1. **Late chords (the #1 error).** Put the chord on the exact syllable of the note the ABC attaches it to — *not* the next stressed word or the end of the line. Verify by the melody note sitting under the chord.
+2. **Dropping an internal return.** `C → F → C` easily collapses to `C … F` with the `F` parked on the last word and the return to `C` lost. Preserve every change in the ABC.
+3. **Key-signature accidentals.** e.g. `K:Eb` ⇒ written `A` = A♭. This flips which chord fits. Always apply the key signature before judging a chord.
+4. **Transposition drift.** If the booklet is in a different key from the ABC, transpose **every** chord by the **same** interval. Keep a minor tonic minor (don't swap in the relative major), and **keep dominants** (a `V7`/`E7`/`A7` before the tonic must survive the transposition).
+5. **Held notes / melisma.** `~ * _` extend the previous syllable — they do not consume a new lyric syllable. Miscounting them shifts every following chord.
+6. **Chord on the downbeat, not the pickup.** The mirror image of pitfall 1: put the `[chord]` on the exact note the ABC attaches it to. When a pickup/anacrusis precedes that note (`And we'll`, `There`, `Oh`), the chord belongs on the following downbeat word (`roll`, `once`), not the pickup.
+7. **Prefer whole-word placement; don't over-split.** Put the `[chord]` before the whole word when the change falls at/near the word start (`[Dm]swinging`, not `swing[Dm]ing`). Only split a word when the change genuinely occurs mid-word *and* it matters. If the ABC chord lands mid-word (e.g. the `B` on "whaler-**men**") but the booklet writes the word as one token, place the `[chord]` at the nearest word boundary.
+8. **Shared verse/chorus tunes.** Many shanties reuse the verse melody for the chorus; a chord that's on word *N* of the verse maps to the *analogous* chorus word, which may differ in syllable count — align by melodic position, not word index.
+9. **Fast response lines.** Call-and-response refrains change chords quickly (watch `G`/`D`/`D7` clusters); it's where misalignments concentrate.
+10. **Modern / copyrighted songs.** The booklet may intentionally follow the artist's official chart rather than the ABC. Flag divergences and confirm with the user before "fixing".
+11. **The maintainer's committed chords win.** The ABC is the reference, but the songbook owner may deliberately differ — adding passing chords by ear, re-voicing a section, or choosing the ABC's *own* key over a prior transposition. When asked to "err toward the ABC," adopt the ABC's actual key and chords rather than transposing an existing booklet version; and don't silently revert a maintainer's deliberate choice back to the ABC.
+
+## Verification / keeping in sync
+
+- Re-derive the booklet chords from the ABC and confirm each `[chord]` sits on the ABC-attached syllable.
+- Build a proof and eyeball it: `npm run booklet:proof` (reading-order, one page per page) or `npm run booklet` (imposed), then open `booklet/sea-shanties.html`.
+- If you added a song, make sure it's in `booklet/book.yaml` and the contents/page numbers still line up.
+
+## References
+
+- `ABCquickRefv0_6.pdf` and `abc_standard_v2.1 [abc wiki].mht` in the repo root — ABC notation reference.
+- [booklet/README.md](../../../booklet/README.md) — build/print instructions and file roles.

.gitignore

@@ -4,3 +4,6 @@
 node_modules
 yarn.lock
 package-lock.json
+
+# Playwright MCP scratch (page snapshots, console logs)
+/.playwright-mcp/

booklet/barretts-privateers.md

@@ -9,10 +9,10 @@ To the scummiest vessel I've ever [F]seen
 > God [C]damn [G]them [C]all!
 
 {chorus}
-> [C]I was [F]told we'd [G]cruise the [F]seas for A[C]merican [F]gold
+> [C]I was told we'd [G]cruise the seas for [Am]American gold
 > We'd [C]fire [G]no [C]guns, shed no [F]tears
 > Now I'm a [C]broken [F]man on a [C]Halifax [F]pier
-> The last of Barrett's [G7]priva[C]teers
+> The [Am]last of Barrett's [G7]priva[C]teers
 
 On the ninety-sixth day we sailed again
 > How I wish I was in Sherbrooke now!

booklet/bully-boys.md

@@ -2,9 +2,9 @@
 
 {chorus}
 > And it's [C]row me bully boys [F]we're in a hurry boys
-> [C]we've got a long way to [G]go
+> [C]we've got a long way to [G7]go
 > And we'll [C]sing and we'll dance
-> And bid [F]farewell to France
+> and bid [F]farewell to France
 > [G7]row me bully boys [C]row
 
 And we sailed away in the roughest of water,

booklet/bully-in-the-alley.md

@@ -9,7 +9,7 @@ Sally is the girl that I spliced nearly,
 > [G]So help me ba ba bully in the alley,
 > [C]way [G]hey [D]bully in the alley
 > [G]So help me ba ba bully in the alley,
-> [C]bully down in [G]shinbone [D7]al[G]—
+> [C]bully down in [G]shin[D7]bone [G]al—
 
 Seven long years I've courted Sally
 > way hey bully in the alley

booklet/contents.md

@@ -28,15 +28,25 @@ title: Contents
 
 <div class="warn-block">
 
+<div class="warn-text">
+
 <h2 class="warn-title">Warning</h2>
 
-<p>These shanties are a product of their time,<br>some may represent regressive views.</p>
+<p>These shanties are a product of their time, some may represent regressive views.</p>
+
+<p>This shanty songbook strives to ride the line between authentic but also not problematic. We did our best.</p>
+
+</div>
 
-<p>This shanty songbook strives to ride the line between<br>authentic but also not problematic. We did our best.</p>
+<div class="warn-aside">
+
+<p class="qr-label">Scan for PDF</p>
 
 <p class="toc-qr"><img src="qr.png" alt="QR code"></p>
 
-<p class="colophon">June 2026, Version 6</p>
+<p class="colophon">July 2026, Version 7</p>
+
+</div>
 
 </div>
 

booklet/cover.html

@@ -2,6 +2,7 @@
 type: html
 showPageNumber: false
 -->
+<link rel="stylesheet" href="shanties.css">
 <div class="cover">
   <div class="cover-title">Sea<br>Shanties</div>
   <div class="cover-art">

booklet/joli-rouge.md

@@ -2,36 +2,36 @@
 
 *The Dreadnoughts, 2019*
 
-From France we get the Brandy, from Martinique the rum
-Sweet red Cabernet from Italy does come
-But the fairest of them all, me boys, the one to beat the day
-…is made from apples up the mighty Saguenay.
+From [Dm]France we get the [Am]Brandy, from [Dm]Martinique the [Am]rum
+[Dm]Sweet red [C]Cabernet from [Dm]Italy does [C]come
+But the [Dm]fairest of them [C]all, me boys, the [F]one to beat the [C]day…
+…is [Dm]made from [F]apples up the [C7]mighty [F]Saguenay.
 
 {chorus}
-> [Dm]So follow me lads… cause this [Am]ain't no grog or ale
-> [Dm]One pint down you'll be [C]swinging in the gale
-> [Dm]Five pints bully you'll be [C]shaking in your [F]shoes
-> [Dm]…We're half-seas [C7]over on the [Dm]Joli Rouge.
+> [Dm]So follow me lads [Am]… cause this [Dm]ain't no grog or [Am]ale
+> [Dm]One pint [C]down you'll be [Dm]swinging in the [C]gale
+> [Dm]Five pints [C]bully you'll be [F]shaking in your [C]shoes
+> …We're [Dm]half-seas [F]over on the [C]Joli [Dm]Rouge.
 
 ---
 
 She's called the Dreadnought Cider, she's proper and she's fine
 And when the day is over sure I wish that she were mine
-Or in the dark of winter, or on a summer's eve
+Or in the dark of winter, or on a summer's eve…
 …One hand giveth and the other does receive.
 
 [Chorus]
 
 So turn your sails over and bring her hard to port
 Find that little star and fly straight into the North
-The wild sun upon your back the wind a-blowing free
+The wild sun upon your back the wind a-blowing free…
 …You're rolling up the river boys to old Chicoutimi.
 
 [Chorus]
 
 So you can have a Magners and pour it over ice
 Or you can have a Strongbow if it's sadness that you like
-Or join us up the river and we'll set your heart aglow
+Or join us up the river and we'll set your heart aglow…
 …And how you'll feel when the real cider starts to flow.
 
 [Chorus]

booklet/leave-her-johnny.md

@@ -1,7 +1,7 @@
 # Leave Her Johnny
 
 I [C]thought I heard the old man say
-> [G]Leave her Johnny [C]leave her
+> [F]Leave her Johnny [C]leave her
 To[F]morrow [C]ye will [G]get yer [C]pay
 > And it's [C]time for us to [G7]leave [C]her
 

booklet/old-maui.md

@@ -4,6 +4,7 @@ It's a [Em]damn tough [B]life full of [G]toil and [D]strife,
 We [Em]whalermen [B]under[Em]go
 And we [Em]don't give a [B]damn when the [G]gale is [D]done,
 How [Em]hard the [B]winds did [Em]blow
+
 For we're [G]homeward bound from the [D]Arctic ground,
 With a [Em]good ship taut and [B]free
 And we [Em]don't give a [B]damn when we [G]drink our [D]rum,
@@ -15,12 +16,13 @@ With the [Em]girls of [B]old Mau[Em]i
 > We're [Em]homeward [B]bound from the [G]Arctic [D]ground
 > Rolling [Em]down to [B]old Mau[Em]i
 
----
-
 Once more we sail with a Northerly gale,
 Through the ice and wind and rain
 Them coconut fronds, the tropical shores,
 We soon shall see again
+
+---
+
 For six hellish months we passed away
 On the cold Kamchatka sea
 But now we're bound from the Arctic ground,
@@ -32,6 +34,7 @@ Once more we sail the Northerly gale,
 Towards our island home
 Our whaling done, our mainmast sprung,
 And we ain't got far to roam
+
 Our stuns'l bones is carried away,
 What care we for that sound?
 A living gale is after us,
@@ -43,6 +46,7 @@ How soft the breeze through the island trees,
 Now the ice is far astern
 Them native maids, them tropical glades,
 Is awaiting our return
+
 Even now their big brown eyes look out,
 Hoping some fine day to see
 Our baggy sails running 'fore the gales,

booklet/randy-dandy-o.md

@@ -1,14 +1,13 @@
 # Randy Dandy O
 
-
 Now we are ready to sail for the Horn
 > Way hey roll and go
 Our boots an' our clothes, boys, are all in the pawn
 > To me rollickin' randy dandy O
 
 {chorus}
 > [Am]Heave a pawl oh heave a way
-> Way [G]hey [Am]roll and go
+> [G]Way hey [C]roll and go
 > The [C]anchor's on board and the [G]cable's all stored
 > To me [Am]rollickin' randy [E7]dandy [Am]O
 

booklet/roll-the-old-chariot-along.md

@@ -9,7 +9,7 @@ We'd be all right if the wind was in our sails.
 > And we'll [Dm]roll the old chariot along
 > We'll [C]roll the old chariot along
 > We'll [Dm]roll the old chariot along
-> And we'll [F]all hang [C]on be[Dm]hind
+> And we'll [F]all hang [A7]on be[Dm]hind
 
 We'll be all right if we make it round The Horn.
 > We'll be all right if we make it round The Horn.