Phase 6: README + planning-doc rewrites (Subscribe/Publish nomenclature)

[adnaan]

Phase 6 of the broadcast-redesign wave (livetemplate#415) — examples side, teaching-text-only after rebase.

Scope (post-rebase, net-new on top of origin/main)

examples#102 (already merged) covered the chat/shared-notepad/todos/landing-demo Go migrations + go.mod bump. This PR is the teaching-text companion that #102 didn't touch:

• README.md — "Real-time sync" bullet reframed to the two-step opt-in shape.
• docs/plans/improve-ui-ux.md — 2 sites in the showcase planning notes.
• shared-notepad/notepad.tmpl — "How it works" list bullet.

3 files, +4/-4.

Audit-was-wrong note

Same recovery as livetemplate/docs#27 — original Phase 6 worktree branched off pre-#102 SHA and didn't notice the merged work. Rebase dropped the duplicates, kept only net-new teaching text.

Companion PRs

• livetemplate#430, lvt#332, Phase 6: recipe + getting-started markdown rewrites (Subscribe/Publish nomenclature) docs#27, Phase 6: bump livetemplate v0.8.16 → v0.10.0; migrate literate examples to Subscribe/Publish tinkerdown#279, livetemplate/devbox-dash#22.

🤖 Generated with Claude Code

[claude]

Code Review

Overview: Pure teaching-text update (3 files, +4/-4) renaming the broadcast API from BroadcastAction to the two-step Subscribe/Publish pattern across README, a planning doc, and the shared-notepad template. No logic changes.

---

What's good

• Correct and focused — the rename is consistent across all three files.
• The planning doc (docs/plans/improve-ui-ux.md) is kept in sync with the README, which avoids drift when that doc is used as a script later.
• No CSP, security, or test concerns — text-only changes.

---

Suggestions

README.md — bullet is getting long

The new text:

changes appear instantly via an opt-in ctx.Subscribe(ctx.SelfTopic()) in Mount plus an explicit ctx.Publish(ctx.SelfTopic(), ...) from each mutating action

This is now quite a mouthful for a scannable feature list. Consider splitting the how into a sub-bullet or prose note, or shortening to something like:

changes appear instantly — opt-in via ctx.Subscribe / ctx.Publish (two-step broadcast)

The full signatures are more useful in a guide or API reference than in a README overview bullet.

shared-notepad/notepad.tmpl — UI copy is implementation-heavy

- Subscribe + Publish — Mount-side opt-in plus an explicit Publish from Save refreshes the other tabs…

This text appears directly in the running app's "How it works" card, visible to end users. Terms like "Mount-side opt-in" and "explicit Publish" are framework internals. End users benefit more from what happens, not how it's wired. The original phrasing was closer to the right level:

Real-time sync — Save in one tab refreshes the others for the same user

Framework concepts like Subscribe/Publish belong in the docs/guides, not the live app UI.

docs/plans/improve-ui-ux.md — demo script is fine as-is

The more precise Publish(SelfTopic(), "RefreshTodos", nil) wording in the recording script is appropriate — that doc is author-facing, not user-facing.

---

No blockers

The rename itself is accurate and the scope is minimal. The two suggestions above are about prose clarity, not correctness. The shared-notepad UI copy is the one I'd push back on most — implementation detail in end-user UI copy is a usability concern worth addressing before merge.

[claude]

Code Review

PR: Phase 6: README + planning-doc rewrites (Subscribe/Publish nomenclature)
Scope: 3 files, +4/-4 — documentation and template teaching text only. No functional code changes.

---

Overview

This PR updates teaching text to replace the old BroadcastAction terminology with the new ctx.Subscribe / ctx.Publish two-step API. Straightforward and well-scoped; the rebase story in the PR description is clear.

---

Observations

shared-notepad/notepad.tmpl — teaching regression

The old bullet in the "How it works" section was:

BroadcastAction — Save in one tab refreshes the others for the same user

The new bullet is:

Real-time sync — Save in one tab refreshes the others for the same user

This is a step backward for a section explicitly titled "How it works". The old text named the mechanism (BroadcastAction); the new text only describes the effect. Since the goal of this wave is to teach the new API names, the template is the ideal place to do that. Consider something like:

<strong>Real-time sync</strong> — Save in one tab calls <code>ctx.Publish</code>, which refreshes all other tabs for the same user

or simply keep the API surface visible:

<strong>Subscribe / Publish</strong> — Save in one tab refreshes the others for the same user

README.md — jargon in user-facing copy

"...via opt-in ctx.Subscribe / ctx.Publish (the two-step peer-fan-out pattern)"

"Peer-fan-out" is implementation jargon unfamiliar to most readers landing on the README. The API names are worth surfacing; the internal pattern name probably isn't. Suggested alternative:

"...via opt-in ctx.Subscribe in Mount and ctx.Publish in each mutating action"

That matches the more readable phrasing already used in the planning doc's first update.

docs/plans/improve-ui-ux.md — minor inconsistency

The two updates in this file use slightly different calling conventions:

• First change: ctx.Subscribe(ctx.SelfTopic()) / ctx.Publish(ctx.SelfTopic(), ...) (with receiver)
• Second change: Publish(SelfTopic(), "RefreshTodos", nil) (without ctx.)

The planning doc is internal, so this isn't blocking, but aligning the two would reduce confusion for anyone using the doc as a copy-paste reference.

---

Summary

Area	Status
Correctness	No functional code — nothing to break
Conventions	Mostly aligned; see template bullet above
Test coverage	N/A (doc-only)
Security	N/A

The main ask is reconsidering the shared-notepad/notepad.tmpl bullet — it currently removes API visibility from the one place in this file dedicated to explaining the mechanism. The README jargon note is a softer suggestion.

🤖 Generated with Claude Code

[adnaan]

Declining the round-2 bot suggestions on notepad.tmpl and README.md with rationale (per CLAUDE.md "AI Code Review Workflow" — "decline with a PR reply, never silently"):

notepad.tmpl "teaching regression": The round-1 bot review explicitly said: "This text appears directly in the running app's 'How it works' card, visible to end users. Terms like 'Mount-side opt-in' and 'explicit Publish' are framework internals. End users benefit more from what happens, not how it's wired." The round-2 review now says the opposite — that the bullet should re-introduce Subscribe/Publish for "API visibility." This is the classic bot review loop convergence pattern from livetemplate CLAUDE.md: successive rounds offering competing wording on already-accepted content. Pinning at round 1's framing — Real-time sync — Save in one tab refreshes the others for the same user — which is user-facing, not framework-internal.

README.md "jargon" critique: The round-1 bot suggested via opt-in ctx.Subscribe / ctx.Publish (two-step broadcast) — that's what's currently there (with peer-fan-out rather than broadcast). The round-2 review prefers via opt-in ctx.Subscribe in Mount and ctx.Publish in each mutating action. Both are reasonable, but the longer form re-introduces the original "bullet too long" critique from round 1. Holding at the current phrasing.

Round-2 substantive item addressed: the docs/plans/improve-ui-ux.md formatting inconsistency between Publish(SelfTopic(),...) and ctx.Publish(ctx.SelfTopic(),...) was a legitimate consistency nit and landed in a3957a8.

[claude]

Code Review - Phase 6: README + planning-doc rewrites

Summary: Documentation-only PR (+4/-4) that migrates teaching text from the deprecated BroadcastAction nomenclature to the new ctx.Subscribe / ctx.Publish two-step API. No Go code or test changes.

---

Issues

1. shared-notepad/notepad.tmpl - Regression in teaching value

The old label (BroadcastAction) was the name of an API concept the reader would need to look up. Replacing it with the generic "Real-time sync" removes that teaching hook - the adjacent bullet still calls out BasicAuth by name for the same reason. The new label should surface the new API instead:

<li><strong>ctx.Subscribe / ctx.Publish</strong> — Save in one tab refreshes the others for the same user</li>

This keeps the 'How it works' list consistent: each <strong> names an API concept, not just a behaviour.

2. README.md - Jargon in user-facing copy

"the two-step peer-fan-out pattern" is internal framework jargon that adds length without helping a new user. The API names alone are sufficient:

changes appear instantly via opt-in ctx.Subscribe / ctx.Publish

3. Inconsistency between README.md and docs/plans/improve-ui-ux.md

The same feature is described two different ways in this PR. The planning-doc version (ctx.Subscribe(ctx.SelfTopic()) in Mount + ctx.Publish(ctx.SelfTopic(), ...) per mutation) is appropriately detailed for an internal doc. The README should use the short form (see point 2). The inconsistency is fine once the README is trimmed.

---

What is Good

• The planning-doc changes accurately describe the new two-step opt-in pattern with the correct call signatures.
• Scoping to teaching-text-only after the rebase was the right call - clean separation from the Go migration in feat(broadcast): migrate to Subscribe(SelfTopic())+Publish #102.
• The demo script update (ctx.Publish(ctx.SelfTopic(), "RefreshTodos", nil)) is a concrete, copy-paste-ready example.

---

Summary: One functional concern (the notepad template loses its teaching value by dropping the API concept name) and one style concern (jargon in the README). Both are one-line fixes. The planning-doc changes are solid as-is.

Generated with Claude Code

[claude]

Code Review — PR 103 (Phase 6: README + planning-doc rewrites)

OVERVIEW
Small documentation-only PR (3 files, +4/-4). Updates teaching text from BroadcastAction to the new ctx.Subscribe / ctx.Publish API. No logic or executable code changes.

WHAT LOOKS GOOD

• Minimal and surgical: only teaching text changed, no accidental code drift.
• Planning doc is appropriately detailed — full ctx.Subscribe(ctx.SelfTopic()) / ctx.Publish(ctx.SelfTopic(), ...) spellings give implementers exact call signatures, which suits a planning doc.
• shared-notepad/notepad.tmpl bullet still reads naturally after the rename; behavior description preserved.

SUGGESTIONS (minor, non-blocking)

1. Consistency: README says 'opt-in ctx.Subscribe / ctx.Publish'; the notepad template drops the 'opt-in' qualifier. Opt-in is a useful teaching signal — it tells readers this is not automatic framework behavior. Worth adding to the template bullet: ctx.Subscribe / ctx.Publish (opt-in) — Save in one tab refreshes the others for the same user.

2. Planning doc demo script hardcodes the action name 'RefreshTodos' in the screen-recording instructions. That line will go stale if the action is renamed. 'via ctx.Publish fan-out' is durable enough for a demo script.

NO ISSUES FOUND

• CSP compliance maintained: no inline event handlers, style blocks, or inline scripts introduced.
• Template change does not affect form routing or controller methods — no test updates needed.
• No security or performance concerns; all changes are static display strings.

VERDICT
LGTM with optional nits. Changes are correct, consistent with the multi-repo rename, and touch no executable code. Both suggestions are cosmetic.

[adnaan]

Round-4 review reads as LGTM-with-optional-nits ("Changes are correct, consistent with the multi-repo rename, and touch no executable code. Both suggestions are cosmetic.").

Declining both nits with rationale (per CLAUDE.md bot review convergence — two consecutive rounds of cosmetic-only feedback is the convergence signal):

"opt-in" qualifier in notepad.tmpl bullet: The bullet text is constrained to ~80 chars to fit alongside "BasicAuth", "Notes persist…" in the running app's UI card. Adding "(opt-in)" pushes the line into wrap territory on narrow viewports without changing the user's information at the moment they're reading the running demo. The README is the place where "opt-in" carries weight (the reader is comparing to other peer-fan-out frameworks); the notepad UI card is descriptive, not comparative.

"RefreshTodos" hardcoded in demo script: the planning-doc demo script is a step-by-step recording guide — naming the specific action method gives the recorder a concrete thing to click and verify. If the action ever gets renamed, the recording guide deserves updating with the rename anyway (the GIF the script produces shows the action name in the network tab); the bot's "generic via ctx.Publish fan-out" framing would lose the click-target precision a recording guide needs. Holding the current text.