docs(agents): add ko-* static-expression freeze gotcha to guide.md

[brianmhunt]

What

Adds one bullet to the ## Gotchas section of tko.io/public/agents/guide.md:

Pass the observable itself to ko-* attrs — not a called expression. ko-text={obs()} calls obs() once at render time and gives TKO a static value; the DOM never updates after the initial render. Write ko-text={obs} (pass the observable). For derived expressions, hoist to a ko.pureComputed: const label = ko.pureComputed(() => a() + b()), then ko-text={label}.

Why

llms.txt already warns "Derived ko-* values must stay observable/computed — inline expressions freeze" (line 47), but guide.md's ## Gotchas section had no equivalent entry — the two agent-facing docs were out of sync.

NativeProvider.ts:44 confirms the behaviour:

const valueFn = isObservable(value) ? value : () => value

Non-observable values are wrapped as a static () => value, so ko-text={obs()} silently passes a plain string and the DOM never updates. This is a common, invisible mistake in agent-generated TSX.

Scope

Single-line addition to one agent-facing doc file. No code changes, no API changes, no changeset needed.

https://claude.ai/code/session_018q2onX3ZYrxrr768L26hSH

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Added clarification on proper usage of observables with JSX ko-* attributes to ensure reactive DOM updates work correctly, including guidance on handling derived expressions with computed properties.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f62b8530-225d-42f6-b84c-2949aa525aca

📥 Commits

Reviewing files that changed from the base of the PR and between a25d564 and 0395977.

📒 Files selected for processing (1)

• tko.io/public/agents/guide.md

---

📝 Walkthrough

Walkthrough

Documentation update to the TKO guide adding a "Gotchas" entry. The clarification warns that JSX ko-* attributes must receive observable or computed values directly, not called expressions, since calling during render freezes the initial value and breaks reactivity. Derived values should be wrapped in ko.pureComputed.

Changes

JSX Binding Documentation

Layer / File(s)	Summary
JSX ko- binding gotcha clarification* tko.io/public/agents/guide.md	Adds gotcha documentation entry explaining that ko-* JSX attributes require observable/computed values directly (e.g., ko-text={obs}) rather than called expressions (e.g., ko-text={obs()}), and instructs hoisting derived expressions into ko.pureComputed.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

• knockout/tko#263: Both PRs update TKO's TSX documentation to clarify that ko-* bindings must receive observable/computed values directly rather than called expressions for proper reactivity.

Poem

🐰 A gotcha caught and now made clear,
For JSX bindings, hold the observer dear—
Don't call it now, just pass it through,
And pureComputed for derived views too! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding documentation about a gotcha related to ko-* attributes and static expression freezing to guide.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/ecstatic-einstein-TV40A

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}