docs(agents): add KO/ViewComponent guidelines from review

tko.io/public/agents/contract.md

@@ -40,6 +40,80 @@ In those cases:
 - let the custom binding read observables and update the DOM
 - avoid making the custom binding the authoritative owner of app state
 
+## DOM Mutation Containment
+
+DOM mutation and direct DOM-API calls belong inside a `BindingHandler` (a class that extends `LifeCycle` and is registered as a binding). They do not belong in component view models, utility modules, or arbitrary class methods.
+
+Violations (do not do outside a `BindingHandler`):
+- `document.createElement`, `document.body.appendChild` — bypasses the binding pipeline
+- `element.querySelector` / `querySelectorAll` — except to find a mount root for `applyBindings`
+- `element.style.*`, `element.classList.*` — use the `style` / `css` bindings
+- `element.addEventListener` — use `click`, `event:{…}`, or a binding handler
+- `appendChild` / `insertBefore` / `replaceWith` — use `foreach`, `if`, `template`
+- `element.innerHTML = …` — use `text` or (when trusted markup is the point) `html`; also flag XSS if content is external
+- `element.focus()` / `element.select()` — use `hasFocus` or a focus-orchestration binding
+- `requestAnimationFrame` for DOM scheduling — move inside a binding that owns the frame loop
+- Storing `HTMLElement` references as component view-model fields — the element belongs to the binding
+
+Where these calls are safe:
+- inside a class that extends `BindingHandler` (its `constructor`/`init`/`update` receive the owning element)
+- reading observables whose values drive DOM updates via bindings — that is the whole point
+- direct DOM reads in tests/verification code after bindings are active
+
+Binding handlers are the prescribed escape hatch for imperative DOM work: they receive the exact element, participate in the lifecycle, and dispose cleanly. Mutating the DOM from elsewhere creates a second source of truth for DOM state and the reactive graph loses sight of it.
+
+## Component Design: Binding Handlers and Component View Models
+
+### Binding handlers — narrow scope, one DOM task
+
+Each `BindingHandler` subclass should do one thing to its element. A handler that sanitizes HTML *and* walks the DOM for citations *and* renders diagrams *and* rewrites tables should be split into separate handlers, each composable on the same element.
+
+Violations:
+- a binding handler performing multiple unrelated DOM operations — split by concern
+- using a binding handler where a component with JSX would suffice — prefer declarative JSX when the rendering can be expressed that way
+
+Not a violation:
+- a handler that is complex because its single DOM task is inherently complex (rich-text editor, canvas renderer, third-party widget bridge)
+
+### Component view models — rendering only
+
+A component view model (a class registered with `components.register(...)`, typically extending `ComponentABC`) should contain only code that produces its template output. Data transformation, parsing, business rules, and utilities belong in standalone `.ts` files the component imports.
+
+Violations:
+- template method exceeding ~80 lines of JSX without decomposition — extract nested child components
+- manipulating the DOM directly from a component method — delegate to a binding handler
+- non-rendering logic (parsing, domain rules, formatting of structured data) embedded in the component — move to utilities
+- instantiating a child component with `params={{ ... }}` wrapping every prop (see "Component Params in JSX" in `/agents/guide.md`)
+
+Not a violation:
+- a component that is large because it composes many small child components
+- simple inline computeds that only map data for the template (`const label = ko.pureComputed(() => format(value()))`)
+
+## Component Communication via `subscribable`
+
+When a component needs to trigger an imperative action inside a binding handler (for example "print this iframe", "scroll to top", "focus on demand"), pass a `ko.subscribable` owned by the component into the handler. The handler subscribes in its constructor and disposes the subscription in `dispose`.
+
+Do not model the command as an `observable` holding a function (`observable<(() => void) | null>(null)`). Function-valued observables capture closures that may retain DOM references, muddle cleanup, and do not broadcast.
+
+```js
+// Component owns the channel and fires events
+class PrintableCard extends ComponentABC {
+  printChannel = new ko.subscribable()
+  onPrintClick = () => this.printChannel.notifySubscribers(null, 'print')
+}
+
+// Binding handler subscribes and disposes with its lifecycle
+class PrintIframe extends BindingHandler {
+  constructor (params) {
+    super(params)
+    const channel = this.value
+    this.addDisposable(channel.subscribe(() => this.$element.contentWindow.print(), null, 'print'))
+  }
+}
+```
+
+The element reference stays inside the binding handler, `dispose` cleans up naturally, and multiple elements can listen on the same channel without coordination.
+
 ## Security Preference
 
 - Prefer `text` over `html`.

tko.io/public/agents/guide.md

@@ -33,6 +33,13 @@ ko.when(viewModel.isReady, () => console.log('Ready'))
 ko.when(() => viewModel.isReady() && viewModel.hasData()).then(() => console.log('Ready'))
 ```
 
+### Observables vs computed dependency management
+
+- Bare `ko.observable()` and `ko.observableArray()` are safe anywhere — they are containers and do not re-evaluate.
+- Inside a class using the `LifeCycle` mixin (for example `BindingHandler`, `ComponentABC`, or anything produced by `LifeCycle.mixInto`), prefer `this.computed(...)` over standalone `ko.computed(...)` and `this.subscribe(observable, cb)` over `observable.subscribe(cb)` — both are auto-disposed when the instance is torn down.
+- In plain view models without `LifeCycle`, `ko.computed(...)` and `observable.subscribe(...)` are fine; call `dispose()` on them when you are done.
+- **Never** create `ko.observable()`, `ko.computed()`, or call `.subscribe()` inside a computed's evaluator. The evaluator runs on every dependency change, so new observables/subscriptions pile up and never dispose — memory and CPU grow unbounded. Create them once outside the computed, or in a `LifeCycle`-enabled constructor.
+
 ## Bindings
 
 Activate with `ko.applyBindings(viewModel, element)`.
@@ -65,6 +72,63 @@ When the goal is to demonstrate TKO itself, keep the state flow inside observabl
 - If an example contrasts reactive models, the counters and highlighted state should also be observable-driven so the example demonstrates the pattern instead of bypassing it.
 - The line to avoid is using the DOM itself as the mutable source of truth after bindings are active.
 
+### Computed styling via attributes
+
+Do not use computeds to switch CSS class names or inline style strings. Drive a computed attribute (typically `data-*`) and let CSS select on it.
+
+```tsx
+// Bad: computed className
+const className = this.computed(() => this.isActive() ? classes.active : classes.inactive)
+return <div class={className}>...</div>
+
+// Bad: computed inline style
+const style = this.computed(() => this.isExpanded() ? 'display: block' : 'display: none')
+return <div style={style}>...</div>
+
+// Good: computed attribute + CSS selector
+const isActive = this.computed(() => this.isActive() || undefined)
+return <div data-active={isActive}>...</div>
+```
+
+```css
+.my-component { opacity: 0.5; }
+.my-component[data-active] { opacity: 1; }
+```
+
+This keeps styling logic in CSS, avoids class-name string juggling inside computeds, and pairs naturally with the `|| undefined` pattern for binary attributes (see Gotchas). For classic `data-bind`, the equivalent writer is the `attr` binding: `data-bind="attr: { 'data-active': isActive }"`.
+
+### JSX scope rule
+
+Use JSX inside component view models (classes registered with `components.register(...)`, typically extending `ComponentABC`) or in functions whose output is immediately passed to `tko.jsx.render(...)` and mounted. Do not leave JSX in standalone utility functions that outlive a component lifecycle — without `LifeCycle`, subscriptions and computeds created for that JSX have no owner to dispose them.
+
+```tsx
+// Good: component owns the JSX and its lifecycle
+class MyCard extends ComponentABC {
+  template = () => <div ko-text={this.message} />
+}
+
+// Also fine: top-level render for a fixed mount
+const { node } = tko.jsx.render(<div ko-text={message} />)
+document.getElementById('root').appendChild(node)
+
+// Avoid: JSX returned from a utility module without a clear owner
+export const myView = () => <div ko-text={message} />
+```
+
+### Component params in JSX
+
+When instantiating a component from JSX, pass each constructor parameter as its own attribute. Do **not** wrap them in a single `params={{ ... }}` attribute — JSX collects attributes into one object and hands that object to the component constructor, so wrapping in `params` delivers `{ params: { … } }` instead of the flat shape the constructor expects.
+
+```tsx
+// Bad — wrapped in params
+<my-report-card params={{ output, onView, onEdit }} />
+
+// Good — each prop is its own attribute
+<my-report-card output={output} onView={onView} onEdit={onEdit} />
+```
+
+The constructor receives `{ output, onView, onEdit }` directly.
+
 ## Classic data-bind parsing and CSP
 
 Classic `data-bind` parsing is provider-driven. Use `DataBindProvider` when you need binding strings, and combine it with other providers through `MultiProvider` as needed.
@@ -222,6 +286,9 @@ tko.applyBindings({ removeTodo: t => todos.remove(t) }, root)
 - **Observable children in JSX** are reactive — when an observable's value changes, the DOM updates. If it becomes `undefined`, a placeholder comment is rendered.
 - **Cannot apply bindings twice** to the same DOM node — throws error.
 - **`dispose()` on computed/subscriptions** stops updates. After disposal, reading returns last cached value.
+- **HTML-producing computeds** should return `null` for empty output, not `false` or an empty fragment — bindings and JSX observers handle `null` cleanly.
+- **Binary HTML attributes** (`disabled`, `readonly`, `hidden`, `required`, `checked`, `selected`) omit the attribute when the value is `null`, `undefined`, or `false`. Use `|| undefined` in computeds to make "no attribute" explicit: `disabled={this.computed(() => shouldBeDisabled() || undefined)}`. Never return the string `"false"` — it keeps the attribute set.
+- **Prefer named computed variables over inline computeds in JSX.** A computed created inline in JSX is easier to accidentally recreate on each render than one bound to a class field or `const`.
 
 ## Testing
 

tko.io/public/agents/verified-behaviors/computed.md

@@ -30,3 +30,22 @@ Read this when you need test-backed behavior for `@tko/computed`, especially `co
 - `when(predicate, callback)` runs the callback once, then disposes its subscription.
   Notes: The predicate may be either a function or an observable. The return value exposes `dispose()` to cancel the pending notification. With deferred updates enabled, the callback runs in a later task.
   Specs: `packages/computed/spec/observableUtilsBehaviors.ts`, `packages/computed/spec/asyncBehaviors.ts`
+
+## Anti-patterns
+
+- Creating observables, computeds, or subscriptions **inside** a computed's evaluator leaks instances. The evaluator re-runs on every dependency change, producing a new un-disposed subscriber each time, so memory and subscriber count grow without bound.
+  Test sketch:
+  ```ts
+  const dep = ko.observable(0)
+  const instances: KnockoutObservable<number>[] = []
+  const leaky = ko.computed(() => {
+    const obs = ko.observable(dep() + 1)
+    instances.push(obs)
+    return obs()
+  })
+  expect(instances.length).toBe(1)
+  dep(1); expect(instances.length).toBe(2)
+  dep(2); expect(instances.length).toBe(3)
+  ```
+  Fix: create the observable/subscription once outside the computed, or inside a `LifeCycle` subclass constructor where `this.subscribe` / `this.computed` own disposal.
+  Related specs: `packages/lifecycle/spec/LifeCycleBehaviors.ts` (disposal semantics).

tko.io/public/agents/verified-behaviors/debug.md

@@ -0,0 +1,19 @@
+# Verified Behaviors: @tko/debug
+
+> Generated from package discovery plus package-local curated unit-test-backed JSON.
+> If a behavior is not covered by unit tests, it does not belong in this directory.
+
+Verified behaviors for @tko/debug.
+
+## When to Read This
+
+Read this when you need test-backed behavior for `@tko/debug`, especially verified behaviors for @tko/debug.
+
+## Status
+
+- Status: no-tests-found
+- Summary: No tests found for this package.
+
+## Next Step
+
+Add tests first, then publish curated verified behaviors once the behavior contract is covered.

tko.io/public/agents/verified-behaviors/lifecycle.md

@@ -28,3 +28,9 @@ Read this when you need test-backed behavior for `@tko/lifecycle`, especially li
   Specs: `packages/lifecycle/spec/LifeCycleBehaviors.ts`
 - Anchoring one lifecycle object to another with `anchorTo(...)` causes disposal of the parent lifecycle to dispose the anchored child as well.
   Specs: `packages/lifecycle/spec/LifeCycleBehaviors.ts`
+
+## Usage guidance
+
+- Prefer `this.computed(...)` over standalone `ko.computed(...)` inside a `LifeCycle` subclass — the computed is added to the instance's disposal set automatically.
+- Prefer `this.subscribe(observable, callback)` over `observable.subscribe(callback)` inside a `LifeCycle` subclass for the same reason.
+- Do not create observables, computeds, or subscriptions inside a computed's evaluator — see the anti-pattern in `computed.md`.

tko.io/public/agents/verified-behaviors/utils-jsx.md

@@ -30,3 +30,5 @@ Read this when you need test-backed behavior for `@tko/utils.jsx`, especially JS
   Specs: `packages/utils.jsx/spec/jsxBehaviors.ts`
 - JSX-created nodes can carry native bindings and participate in component rendering and observable-array diff updates.
   Specs: `packages/utils.jsx/spec/jsxBehaviors.ts`
+- Binary HTML attributes (`disabled`, `readonly`, `hidden`, `required`, `checked`, `selected`) omit the attribute when the observable/computed value is `null`, `undefined`, or `false`; any other value (including the string `"false"`) sets the attribute. Use `|| undefined` in computeds to express "no attribute" explicitly.
+  Specs: `packages/utils.jsx/spec/jsxBehaviors.ts`

tko.io/public/llms.txt

@@ -46,6 +46,9 @@
 - Derived `ko-*` values must stay observable/computed — inline expressions freeze
 - `ko.applyBindings(...)` returns a Promise
 - Inside `ko-foreach`, binding-context vars use strings: `ko-text="$data"` (not `{$data}`)
+- Component JSX params: pass each constructor param as its own attribute (`<my-card out={x} onEdit={fn} />`), never wrap in `params={{...}}` — JSX attrs flatten into one constructor arg, so wrapping double-nests to `{ params: {...} }`
+- Never create `ko.observable()`, `ko.computed()`, or `.subscribe()` inside a computed evaluator — re-runs leak instances
+- Binary HTML attrs (`disabled`, `hidden`, …): return `|| undefined` from computed; `false` renders the string `"false"` and keeps the attribute
 
 ## Browser JSX (esbuild-wasm)