// BEFORE — bare ? was a normal character glued onto the word
<Start> = what is the time? -> { actionName: "getTime" };
// matched:  "what is the time?"

// AFTER — bare ? is illegal; escape the literal question mark
<Start> = what is the time\? -> { actionName: "getTime" };
// matched:  "what is the time?"
// parse error:  what is the time?     (forgot the backslash)

// NOT how you write a "quoted string" in patterns —
// quotes are match characters, so this looks for quote glyphs in the utterance:
//   <Start> = "what is the time?" -> …
// matches:  "what is the time?"   ← includes the " characters
// misses:   what is the time?

// BEFORE — <Song> required; trailing ? was literal punctuation
<Song> = hello | goodbye | bohemian rhapsody;
<Start> = who sings song <Song>? -> {
    actionName: "lookupSong",
    parameters: { song: Song }
};
// ✅ "who sings song hello?"
// ❌ "who sings song?"          (missing song)

// AFTER — same structure; literal ? must be escaped
<Song> = hello | goodbye | bohemian rhapsody;
<Start> = who sings song <Song>\? -> {
    actionName: "lookupSong",
    parameters: { song: Song }
};
// ✅ "who sings song hello?"
// ❌ "who sings song?"
// ❌ "who sings song hello"     (missing ?)

// BEFORE — must group the optional rule; ? after ) is quantifier;
//          another ? (or \?) is the punctuation
<Song> = hello | goodbye;
<Start> = who sings song (<Song>)? \? -> {
    actionName: "lookupSong",
    parameters: { song }
};

// AFTER — optional via <Song>? or prettier (<Song>)?;
//          punctuation always escaped
<Song> = hello | goodbye;

// RIGHT — optional Song + literal ?
<Start> = who sings song (<Song>)?\? -> {
    actionName: "lookupSong",
    parameters: { song }
};
// ✅ "who sings song?"
// ✅ "who sings song hello?"

// WRONG if you wanted the above — this is REQUIRED Song + "?"
//   who sings song <Song>\?

// Looks like a question, but under the new rules it means:
//   optional <Song>, NO literal "?" in the pattern
<Start> = who sings song <Song>? -> { actionName: "lookupSong" };

// matches:  "who sings song"
// matches:  "who sings song hello"
// does NOT require a trailing "?" in the pattern
// (matcher may still accept trailing utterance punct via flex-space)

// BEFORE — <Polite>? was BROKEN (became literal "?" after the rule name)
// authors often wrote this by mistake; it did not make Polite optional
<Polite> = please | can you | would you;
<Start> = <Polite>? open outlook -> {
    actionName: "openApp",
    parameters: { app: "outlook" }
};
// was: required <Polite> + literal "?"   ❌ not optional

// AFTER — <Polite>? is optional (same as (<Polite>)?)
<Polite> = please | can you | would you;
<Start> = <Polite>? open outlook -> {
    actionName: "openApp",
    parameters: { app: "outlook" }
};

// ✅ "open outlook"
// ✅ "please open outlook"
// ✅ "can you open outlook"

// Prettier / writer / LSP format always prefers the grouped form (same meaning):
//   <Polite>? open outlook
// becomes:
//   (<Polite>)? open outlook

// These already worked and stay the same
<Start> =
    (the | a)? item -> { actionName: "pick" }
  | measure $(units:word)? -> { actionName: "measure", parameters: { units } }
  | tag (bug | feature)* -> { actionName: "tag" }
  | need (reviewer)+ -> { actionName: "needReview" }
  | mute (notifications)? -> { actionName: "mute" }
  ;

// NEW — bare word/string + ? is a hard error (was a common silent bug)
//   pause the? music        → PARSE ERROR  (use (the)? )
//   "please"?               → PARSE ERROR  (quotes are not string syntax)
//   'really?'               → PARSE ERROR  (bare ? inside)
//   one* two                → PARSE ERROR

// Captures only support )? today; * / + need the group form
//   measure $(u:word)*      → PARSE ERROR
//   measure ($(u:word))+    → OK

<Polite> = please | can you | would you;
<App> = outlook | teams | spotify;
<Owner> = alice | bob | carol;
<Song> = hello | goodbye | bohemian rhapsody;
<Label> = bug | feature | docs;

<Start> =
    <Polite>? open <App>
        -> { actionName: "openApp", parameters: { app: App } }

  | what is the time\?
        -> { actionName: "getTime" }

  | who sings song <Song>\?
        -> { actionName: "lookupSong", parameters: { song: Song } }

  | who sings song (<Song>)?\?
        -> { actionName: "lookupSongOptional", parameters: { song } }

  | show <Owner>? files
        -> { actionName: "showFiles", parameters: { owner } }

  | tag <Label>+
        -> { actionName: "tag", parameters: { labels: Label } }

  | mute (notifications)?
        -> { actionName: "mute" }
  ;

<Polite> = please | can you | would you;
<App> = outlook | teams | spotify;
<Owner> = alice | bob | carol;
<Song> = hello | goodbye | bohemian rhapsody;
<Label> = bug | feature | docs;
<Start> =
    (<Polite>)? open <App> -> { actionName: "openApp", parameters: { app: App } }
  | what is the time\? -> { actionName: "getTime" }
  | who sings song <Song>\? -> { actionName: "lookupSong", parameters: { song: Song } }
  | who sings song (<Song>)?\? -> {
        actionName: "lookupSongOptional",
        parameters: { song }
    }
  | show (<Owner>)? files -> { actionName: "showFiles", parameters: { owner } }
  | tag (<Label>)+ -> { actionName: "tag", parameters: { labels: Label } }
  | mute (notifications)? -> { actionName: "mute" };

// Colon is NOT special in patterns (no ambiguity outside $() type position)
<Start> [spacing=optional] = $(h:number) : $(m:number) -> { h, m };

// import * is not a pattern quantifier
import * from "./shared.agr";

// Value-side ? / ?. / ?? after -> are not pattern quantifiers
<Start> = $(h:number) pm -> { hours: h < 12 ? h + 12 : h };
<Start> = lookup $(obj:word) -> obj.value?.name;
<Start> = get $(x:word) -> x ?? "default";