Clarify STEP-1 session invocation prompts

Code/{{PROJECT}}-docs/AGENTS.md

@@ -58,16 +58,19 @@ This project follows the method in **`Code/{{PROJECT}}-docs/METHOD.md`** — rea
 - The roadmap and status are in `prompts/STEP-index.md`.
 
 ## Architecture sessions  (how to run one)
-When the user says **"run session N.M"** (e.g. *"run session 1.1"*), read the matching file
-in `Code/{{PROJECT}}-docs/templates/architecture-sessions/NN-*.md` and follow it exactly:
-interview the user one decision at a time, then write the output architecture doc and
-update `prompts/STEP-index.md`. No copy-paste, no special commands.
-
-**"run session N.M" is the user's go-ahead — begin in that same reply.** Don't acknowledge,
-summarize the file, restate the plan, or ask whether to start (no "Ready when you are"). Read
-`overview.md` and any earlier architecture docs silently, then immediately **ask the
-session's first question**, calibrated to the recorded experience level. The user types one
-short command and expects the first question back, not a confirmation prompt.
+When the user says **"STEP-1.N"** or **"session N.M"**, with or without a leading "Run" and
+with or without the session label (preferred with the label, e.g.
+*"Run STEP-1.1: System Overview, Requirements & Non-Goals"*), read the matching file in
+`Code/{{PROJECT}}-docs/templates/architecture-sessions/NN-*.md` and follow it exactly:
+interview the user one decision at a time, then write the output architecture doc and update
+`prompts/STEP-index.md`. No copy-paste, no special commands.
+
+**"STEP-1.N", "Run STEP-1.N: <session label>", "session N.M", and "Run session N.M:
+<session label>" are all the user's go-ahead — begin in that same reply.** Don't
+acknowledge, summarize the file, restate the plan, or ask whether to start (no "Ready when
+you are"). Read `overview.md` and any earlier architecture docs silently, then immediately
+**ask the session's first question**, calibrated to the recorded experience level. The user
+types one short command and expects the first question back, not a confirmation prompt.
 
 **Conditional sessions** are invoked **by name**, not by number: *"run the identity-auth
 session"* → `conditional-identity-auth.md`; *"run the native-app session"* →

Code/{{PROJECT}}-docs/BOOTSTRAP-PROMPT.md

@@ -106,7 +106,7 @@ team/shared-remote project, push the `In progress` flip). **Then stop.**
 
 ### Execution (after kickoff)
 The user drives from here, one session at a time:
-> run session 1.1
+> Run STEP-1.1: System Overview, Requirements & Non-Goals
 
 Each session interviews the user and writes its architecture doc + any ADRs, then updates
 `prompts/STEP-index.md`. Encourage the user to clear the chat between sessions — state

Code/{{PROJECT}}-docs/METHOD.md

@@ -148,20 +148,23 @@ conditional by name.
 
 To run an architecture session, tell your agent:
 
-> run session 1.1
+> Run STEP-1.1: System Overview, Requirements & Non-Goals
 
 The agent reads the matching file in
 `Code/{{PROJECT}}-docs/templates/architecture-sessions/NN-*.md` and follows it exactly:
 it interviews you one decision at a time, then writes the output doc and updates
-`prompts/STEP-index.md`. No copy-paste, no special commands.
+`prompts/STEP-index.md`. No copy-paste, no special commands. The shorter
+*"STEP-1.N"* and *"session N.M"* forms also work, with or without a leading "Run" and with
+or without `: <session label>`, but the labeled form gives chat/task UIs a clearer title.
 
 Each session reads what it needs (`overview.md` + earlier architecture docs) from disk, so
 **you can clear the chat / start fresh between sessions** — the state lives in files, not
 in the conversation. This keeps STEP-1's many sessions from piling up in one context.
 
 ### Sessions are re-runnable
 A session isn't a one-time gate. If an assumption changes later — scaling needs grow, the
-threat model shifts, a phase gets re-cut — **re-run that session** (*"run session 1.5"*).
+threat model shifts, a phase gets re-cut — **re-run that session** (for example,
+*"Run STEP-1.5: Scaling & Performance"*).
 It re-interviews you, **revises the existing architecture doc in place, and records the
 change in that doc's Version Log** (and a new ADR if the decision is significant — the old
 ADR is superseded, not edited). Re-running is the normal way the living docs stay true as
@@ -504,12 +507,14 @@ Quick resolver:
 
 Resolve the next action top-down against the index — the first rule that matches wins:
 
-1. **STEP-1 has a `Planned` / `In progress` substep?** → run the lowest-numbered open one:
-   *"run session N.M"* in a fresh chat. Skip any substep marked `N/A` or `Deferred`. A substep with a
+1. **STEP-1 has a `Planned` / `In progress` substep?** → run the lowest-numbered open one
+   in a fresh chat using `Run STEP-1.N: <Session label from the index>`; the label is
+   optional but preferred because it gives the chat/task a clearer title. Skip any substep marked `N/A` or `Deferred`. A substep with a
    **letter suffix** (e.g. `1.6a`, `1.7a`) is a **conditional session** the kickoff slotted
-   in — invoke it **by name** (*"run the identity-auth session"* / *"run the native-app
-   session"* / *"run the privacy session"* or *"run the privacy-compliance session"*), since
-   its template file is named by topic, not by number (see §4).
+   in — use `Run STEP-1.Xa: <Conditional session label>` plus the invocation **by name**
+   (*"run the identity-auth session"* / *"run the native-app session"* / *"run the privacy
+   session"* or *"run the privacy-compliance session"*), since its template file is named by
+   topic, not by number (see §4).
 2. **All STEP-1 design sessions done but the Cross-Cutting Review is still open?** → run the
    substep whose Session label is **Cross-Cutting Review**.
 3. **Cross-Cutting Review done and STEP-1 complete, but only the STEP-1 row exists?** →

Code/{{PROJECT}}-docs/architecture/README.md

@@ -6,7 +6,7 @@ are point-in-time). See `METHOD.md` §3 and §6.
 
 Most of these are produced by the **architecture sessions** during STEP-1
 (`../templates/architecture-sessions/`). To create or revise one, run its session
-(e.g. *"run session 1.5"*).
+(e.g. *"Run STEP-1.5: Scaling & Performance"*).
 
 ## Conventions
 - Filenames: `NN-kebab-title.md`, numbered in the order the sessions produce them.

Code/{{PROJECT}}-docs/scripts/status.sh

@@ -173,11 +173,11 @@ elif [ -n "$lowsub" ]; then                                 # §10.1 / §10.2
     elif printf '%s' "$lowsub_se" | grep -qiE 'privacy|compliance|data governance'; then
       cond_example="run the privacy session"
     fi
-    next="run the conditional session for substep ${lowsub} — \"${lowsub_se}\"; invoke it BY NAME (e.g. \"${cond_example}\"), not by number."
+    next="Run STEP-${lowsub}: ${lowsub_se} — invoke it BY NAME (e.g. \"${cond_example}\"), not by number."
   elif printf '%s' "$lowsub_se" | grep -qiE 'cross.?cutting'; then
-    next="run session ${lowsub} — the Cross-Cutting Review."
+    next="Run STEP-${lowsub}: Cross-Cutting Review."
   else
-    next="run session ${lowsub}  (${lowsub_se})."
+    next="Run STEP-${lowsub}: ${lowsub_se}."
   fi
 elif [ "$total_sub" -gt 0 ] && [ "$done_sub" -lt "$total_sub" ]; then
   where="Architecture (STEP-1) has ${done_sub}/${total_sub} substeps final, but no runnable open substep could be resolved."
@@ -191,7 +191,7 @@ elif [ "$have_impl" -eq 0 ]; then                           # §10.3 (or STEP-1
     next="run the planning session — it outlines the Phase-1 implementation STEPs."
   else
     where="Architecture (STEP-1) not yet run."
-    next="run session 1.1 — start the architecture STEP."
+    next="Run STEP-1.1: System Overview, Requirements & Non-Goals — start the architecture STEP."
   fi
 elif [ -n "$inprog" ]; then                                 # §10.6
   where="Building — ${inprog} (${inprog_ti}) is In progress."

Code/{{PROJECT}}-docs/templates/architecture-sessions/01-system-overview.md

@@ -1,6 +1,8 @@
 # {{PROJECT}} — System Overview, Requirements & Non-Goals (Session 1.1)
 
-> **How to run:** Tell your agent *"run session 1.1"* (or *"read and run this file"*).
+> **How to run:** Tell your agent *"STEP-1.1"* or *"session 1.1"*; a leading *"Run"* and
+> `: System Overview, Requirements & Non-Goals` are optional (but the label helps chat titles).
+> You can also say *"read and run this file"*.
 > It interviews you one decision at a time, then writes
 > the System Overview, Requirements & Non-Goals architecture doc and updates
 > `prompts/STEP-index.md`.
@@ -97,8 +99,10 @@ regulated data), and **native app** (if there's a mobile or desktop app). The Ph
 and the index confirm which sessions are in play.
 
 Then point them at the next action: the lowest open STEP-1 substep in the index. Tell the
-user to **start a fresh chat** and run that substep (for a numbered core session, *"run
-session N.M"*; for a lettered conditional session, invoke it by name). See the next-action
-resolver in `METHOD.md` §10.
+user to **start a fresh chat** and run that substep with a descriptive first message. For a
+numbered core session, use `Run STEP-1.N: <Session label from the index>` (for example,
+`Run STEP-1.2: Phasing & Roadmap`). For a lettered conditional session, use
+`Run STEP-1.Xa: <Conditional session label>` and the invocation by name from that
+conditional's template. See the next-action resolver in `METHOD.md` §10.
 
-**Begin now — in this same reply.** "run session N.M" is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.
+**Begin now — in this same reply.** "STEP-1.N" or "session N.M", with or without a leading "Run" and with or without the session label, is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.

Code/{{PROJECT}}-docs/templates/architecture-sessions/02-phasing-roadmap.md

@@ -1,6 +1,7 @@
 # {{PROJECT}} — Phasing & Roadmap (Session 1.2)
 
-> **How to run:** Tell your agent *"run session 1.2"*. It interviews you one decision at a
+> **How to run:** Tell your agent *"STEP-1.2"* or *"session 1.2"*; a leading *"Run"* and
+> `: Phasing & Roadmap` are optional (but the label helps chat titles). It interviews you one decision at a
 > time, then writes the Phasing & Roadmap architecture doc and updates `prompts/STEP-index.md`.
 > Reads `overview.md` and the System Overview, Requirements & Non-Goals architecture doc
 > (`architecture/*-system-overview.md`) first.
@@ -67,8 +68,10 @@ substep 1.2 done.
 
 ## Next
 Once 1.2 is marked done, the next action is the lowest open STEP-1 substep in the index. Tell
-the user to **start a fresh chat** and run that substep (for a numbered core session, *"run
-session N.M"*; for a lettered conditional session, invoke it by name). See the next-action
-resolver in `METHOD.md` §10.
+the user to **start a fresh chat** and run that substep with a descriptive first message. For
+a numbered core session, use `Run STEP-1.N: <Session label from the index>` (for example,
+`Run STEP-1.3: Architecture Overview & Component Boundaries`). For a lettered conditional
+session, use `Run STEP-1.Xa: <Conditional session label>` and the invocation by name from
+that conditional's template. See the next-action resolver in `METHOD.md` §10.
 
-**Begin now — in this same reply.** "run session N.M" is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.
+**Begin now — in this same reply.** "STEP-1.N" or "session N.M", with or without a leading "Run" and with or without the session label, is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.

Code/{{PROJECT}}-docs/templates/architecture-sessions/03-architecture-overview.md

@@ -1,6 +1,7 @@
 # {{PROJECT}} — Architecture Overview & Component Boundaries (Session 1.3)
 
-> **How to run:** Tell your agent *"run session 1.3"*. It interviews you one decision at a
+> **How to run:** Tell your agent *"STEP-1.3"* or *"session 1.3"*; a leading *"Run"* and
+> `: Architecture Overview & Component Boundaries` are optional (but the label helps chat titles). It interviews you one decision at a
 > time, then writes the Architecture Overview architecture doc and updates `prompts/STEP-index.md`.
 > Reads `overview.md`, the System Overview, Requirements & Non-Goals architecture doc
 > (`architecture/*-system-overview.md`), and
@@ -83,9 +84,11 @@ System row.
 
 ## Next
 Once 1.3 is marked done, the next action is the lowest open STEP-1 substep in the index. Tell
-the user to **start a fresh chat** and run that substep (for a numbered core session, *"run
-session N.M"*; for a lettered conditional session, invoke it by name). This session may have
-marked the UI / Design System row `N/A` or added a Native-app row, so trust the index. See the next-action
-resolver in `METHOD.md` §10.
+the user to **start a fresh chat** and run that substep with a descriptive first message. For
+a numbered core session, use `Run STEP-1.N: <Session label from the index>` (for example,
+`Run STEP-1.4: Data Model, Ownership & Retention`). For a lettered conditional session, use
+`Run STEP-1.Xa: <Conditional session label>` and the invocation by name from that
+conditional's template. This session may have marked the UI / Design System row `N/A` or
+added a Native-app row, so trust the index. See the next-action resolver in `METHOD.md` §10.
 
-**Begin now — in this same reply.** "run session N.M" is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.
+**Begin now — in this same reply.** "STEP-1.N" or "session N.M", with or without a leading "Run" and with or without the session label, is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.

Code/{{PROJECT}}-docs/templates/architecture-sessions/04-data-model.md

@@ -1,6 +1,7 @@
 # {{PROJECT}} — Data Model, Ownership & Retention (Session 1.4)
 
-> **How to run:** Tell your agent *"run session 1.4"*. It interviews you one decision at a
+> **How to run:** Tell your agent *"STEP-1.4"* or *"session 1.4"*; a leading *"Run"* and
+> `: Data Model, Ownership & Retention` are optional (but the label helps chat titles). It interviews you one decision at a
 > time, then writes the Data Model architecture doc and updates `prompts/STEP-index.md`.
 > Reads `overview.md`, the System Overview, Requirements & Non-Goals architecture doc
 > (`architecture/*-system-overview.md`), and
@@ -68,8 +69,10 @@ the **Version Log**. Update `prompts/STEP-index.md`: mark 1.4 done.
 
 ## Next
 Once 1.4 is marked done, the next action is the lowest open STEP-1 substep in the index. Tell
-the user to **start a fresh chat** and run that substep (for a numbered core session, *"run
-session N.M"*; for a lettered conditional session, invoke it by name). See the next-action
-resolver in `METHOD.md` §10.
+the user to **start a fresh chat** and run that substep with a descriptive first message. For
+a numbered core session, use `Run STEP-1.N: <Session label from the index>` (for example,
+`Run STEP-1.5: Scaling & Performance`). For a lettered conditional session, use
+`Run STEP-1.Xa: <Conditional session label>` and the invocation by name from that
+conditional's template. See the next-action resolver in `METHOD.md` §10.
 
-**Begin now — in this same reply.** "run session N.M" is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.
+**Begin now — in this same reply.** "STEP-1.N" or "session N.M", with or without a leading "Run" and with or without the session label, is your go-ahead, not a request for acknowledgement: don't say "ready when you are", don't recap this file, don't ask whether to start. Read `overview.md` (and any earlier architecture docs) silently. Then, in this one reply: **(1)** tell the user — in the one or two sentences from **What this session does** above — what you're about to cover (plain language); then **(2)** immediately **ask decision 1**, calibrated to the recorded experience level. That orientation plus the first question is your entire first reply — nothing more.