[codex] Add TKO 5 direction plan

plans/tko-5-agent-first-release.md

@@ -0,0 +1,134 @@
+# Plan: TKO 5.0 as an Agent-First Modern Reference Release
+
+TKO 5.0 should make the current modern path official instead of continuing to balance two equal identities. The release should center on `@tko/build.reference`, freeze `@tko/build.knockout` on the 4.x line, and define TKO as a zero-runtime-dependency, browser-native, AI-friendly reactive UI framework with a fast path from idea to verified behavior.
+
+The goal is not to add novelty AI features around the framework. It is to make TKO unusually legible to both humans and agents by reducing legacy ambiguity, simplifying the product story, and tightening the development and verification loop.
+
+## Why 5.0 Exists Now
+
+TKO already contains most of the ingredients for a sharper 5.0 direction:
+
+- the reference build already reads as the modern path
+- the repository already frames TKO as zero-runtime-dependency software
+- the agent docs, verified behaviors, and browser-native TSX flows already exist
+- the biggest remaining drag is historical ambiguity rather than missing capability
+
+4.0 is the right place to stabilize and publish the current architecture. 5.0 is the right place to declare a center of gravity: one canonical build, one primary docs path, one clearer standard for how TKO is authored, tested, documented, and verified.
+
+## Core Product Stance
+
+TKO 5.0 should optimize first for modern builders, especially AI-assisted and agentic workflows, without giving up the framework's existing strengths in modularity, explicit state-to-DOM contracts, and zero-runtime-dependency discipline.
+
+In practice, that means treating `@tko/build.reference` as the canonical package, keeping `@tko/build.knockout` on the 4.x line, preferring standardized modern JavaScript and native browser APIs, protecting the no-new-runtime-dependencies rule, and treating agent-facing docs plus verified behaviors as part of the product contract. High-OODA development matters: contributors should be able to move quickly from prompt or spec to executable example to focused verification.
+
+This makes TKO 5.0 less about a rewrite and more about removing uncertainty about what the project is for and how it should be used.
+
+## Major Changes
+
+### 1. Make the reference build the only first-class 5.0 build
+
+5.0 should stop presenting the reference build and the Knockout compatibility build as equal answers to the same question.
+
+- `@tko/build.reference` becomes the default install, default documentation target, and default recommendation in all product messaging
+- `@tko/build.knockout` stays maintained on 4.x with explicit support boundaries, but it is no longer positioned as a co-equal future-facing build
+- new examples, docs, and feature work should target the reference build unless there is a specific compatibility reason not to
+
+### 1.1 Version the docs experience around the release line
+
+The docs site should stop asking the top-level reader to choose between historical and modern product stories.
+
+- top-level `tko.io/` becomes the canonical TKO 5 documentation experience
+- the current TKO 4 documentation moves under `tko.io/4/`
+- TKO 4 docs should be sourced from a long-lived `v4` branch rather than kept interleaved with v5 docs in the same working tree
+- the GitHub Pages deploy process should assemble the published site by building v5 from `main` and v4 from the `v4` branch, then publishing a combined artifact with v4 rooted at `/4`
+- old unversioned v4-oriented documentation URLs should redirect into `/4/...` during the transition
+
+This keeps v5 free to speak clearly in the singular while preserving a stable, versioned place for migration and compatibility guidance.
+
+### 2. Preserve zero-runtime-dependency discipline
+
+TKO already operates very close to true runtime zero-dependency status. 5.0 should protect that property aggressively.
+
+- do not add new runtime dependencies to core packages or builds
+- prefer native platform features over helper libraries where practical
+- treat any remaining runtime-support dependencies as exceptions that must earn their place
+
+The real dependency reduction opportunity in 5.0 is likely to be in development and testing tooling, not in the runtime surface itself.
+
+### 3. Modernize around standard JavaScript and browser-native patterns
+
+TKO 5.0 should lean into the strengths already visible in the reference build:
+
+- ESM-first usage and distribution
+- CSP-safe parsing and provider-driven binding evaluation
+- native DOM and event paths by default
+- native-provider and TSX-based authoring for modern browser-native UI development
+- removal of historical special cases that exist primarily to preserve older Knockout expectations
+
+The standard should be clear: modern JavaScript first, compatibility second.
+
+### 4. Treat agent-facing documentation as a public interface
+
+TKO is unusually well-positioned for AI-assisted development because its core abstractions are explicit and testable. 5.0 should make that an intentional product advantage.
+
+- `llms.txt` should advertise the modern canonical path
+- the agent guide should remain concise and code-first
+- verified behaviors should serve as machine-readable behavioral truth
+- the agent testing guide should document fast, focused verification flows
+
+The flagship AI workflow for 5.0 is not "chat with TKO." It is "spec to verified behavior" with minimal ambiguity.
+
+## Test And OODA Strategy
+
+5.0 should improve development speed and verification confidence without turning the release into a tooling rewrite project.
+
+The testing strategy should be:
+
+- standardize on one primary behavior authoring style
+- keep runner migration incremental rather than making it the gating item for 5.0
+- preserve coverage while reducing the cognitive overhead of mixed legacy and modern test patterns
+- expand fast browser-level verification where it improves confidence, especially for docs and playground-style examples
+
+This implies a layered approach:
+
+1. unify the style and shape of behavior tests
+2. keep existing coverage intact during migration
+3. adopt additional runners or browser-verification tools only when they improve the OODA loop
+
+The release should not be blocked on a full runner rewrite. If existing work is already moving tests toward a more unified style, 5.0 should benefit from that momentum without depending on total completion.
+
+## Migration Approach
+
+TKO 5.0 should make a clean product decision without forcing a harsh user experience.
+
+The migration posture should be documentation-first:
+
+- ship a strong migration guide for Knockout-style and older TKO users moving to the reference build
+- publish a clear compatibility matrix that explains which path stays on 4.x and which path moves to 5.0
+- use before-and-after examples to show modern equivalents for legacy build choices and authoring patterns
+- keep migration help focused on guides, examples, and explicit support boundaries rather than on a long-lived compatibility layer
+- align the docs with that posture by treating `/4/` as the preserved TKO 4 reference and `/` as the v5 canonical path
+- clean up the npm package surface so deprecated or legacy package names clearly point users toward the canonical 5.0 path
+
+This keeps the release honest. The break is real, but the path forward is well lit.
+
+## Acceptance Criteria
+
+TKO 5.0 is ready as a direction when the following statements are true:
+
+- there is one obvious answer to "which TKO build should I use?" and it is `@tko/build.reference`
+- the legacy Knockout build has a clearly documented 4.x maintenance position
+- no new runtime dependencies have been introduced for the 5.0 line
+- the human docs path and the agent docs path tell the same story
+- the published docs have a clear version boundary: v5 at `/` and v4 preserved at `/4/`
+- verified behaviors and agent-facing docs are maintained as part of the public contract
+- contributors can move from idea to example to focused verification without navigating multiple historical product paths
+- migration guidance is strong enough that the clean break feels intentional instead of abrupt
+
+## Assumptions And Defaults
+
+- keep the canonical package identity as `@tko/build.reference` for 5.0 rather than introducing a package rename during the same release
+- prefer migration guides and compatibility documentation over shipping a long-lived compatibility layer
+- continue test modernization incrementally and do not make a complete runner replacement a hard prerequisite for 5.0
+- use the docs deployment pipeline to assemble a versioned published site rather than forcing v4 and v5 to coexist as one undifferentiated docs tree
+- treat this document as a north-star product plan, not a fully sequenced execution program

tko.io/public/agents/concepts.md

@@ -0,0 +1,144 @@
+# TKO Concepts
+
+Use `/llms.txt` as the index for the full agent docs set. This file explains TKO's core concepts: what TKO is responsible for, what the consuming application is responsible for, and how TKO systems are typically composed.
+
+## Core Contract
+
+TKO's core contract is simple:
+
+- reactive state stays explicit
+- DOM wiring stays explicit
+- rendered behavior stays verifiable
+
+In practice, that means:
+
+- observables, observableArrays, subscribables, and computeds hold state and derived state
+- bindings turn that state into DOM behavior
+- providers decide how bindings are discovered on DOM nodes
+- `ko.applyBindings(...)` activates that contract on a DOM subtree
+
+TKO does not prescribe routing, data loading, SSR or hydration strategy, styling system, or the application shell. Those are application concerns built around TKO's primitives.
+
+## Core Split
+
+TKO provides reactive primitives and DOM wiring. It does not provide a full application architecture.
+
+- TKO owns observables, computeds, bindings, providers, and DOM activation
+- the consuming application owns routing, data loading, SSR strategy, application shell, and large-scale feature composition
+
+This is the main architectural boundary to keep in mind when designing with TKO.
+
+## Primitives
+
+The primitives that define TKO's model are:
+
+- `observable`, `observableArray`, and `subscribable`
+  Stateful values and notification sources.
+- `computed`, `pureComputed`, and `when`
+  Derived state and reactive coordination.
+- bindings and binding handlers
+  The DOM integration layer. Built-in bindings cover text, attributes, events, control flow, forms, templates, and components. Custom behavior can be added with binding handlers.
+- `BindingContext`
+  The scope object that bindings read from as control-flow bindings create nested contexts.
+- providers
+  Binding-discovery primitives. `DataBindProvider`, `NativeProvider`, `VirtualProvider`, `ComponentProvider`, mustache providers, and `MultiProvider` all map DOM nodes to binding accessors.
+- `ko.applyBindings(...)`
+  Activates bindings against a DOM subtree and its binding context.
+- `tko.jsx.render(...)`, `createElement`, and `Fragment`
+  The JSX/native render path that creates DOM nodes before binding activation.
+
+These primitives are intended to stay small, explicit, and composable. Higher-level application structure is built from them rather than imposed above them.
+
+## State, Binding, And Activation
+
+TKO is built around a direct state-to-DOM model.
+
+- observables and computed values hold reactive state
+- bindings define how that state affects text, attributes, events, structure, and child contexts
+- providers discover those bindings on DOM nodes
+- `ko.applyBindings(...)` activates the resulting binding graph on a DOM subtree
+
+The important idea is that reactive dependencies should stay visible. State is explicit. DOM wiring is explicit. Behavior can be verified from rendered output.
+
+## Two Authoring Paths
+
+TKO supports two main authoring styles.
+
+- `data-bind`
+  Runtime binding strings. Best for migration, comparison work, and HTML-first code.
+- `ko-*` in TSX
+  Compile-time expressions carried through the native provider path. Best for new UI where you want explicit variables in scope and browser-native TSX authoring.
+
+These are different authoring surfaces for the same underlying state-to-DOM model.
+
+## Providers
+
+Providers determine how TKO discovers bindings on DOM nodes.
+
+- `DataBindProvider` supports classic `data-bind`
+- `NativeProvider` supports `ko-*` attributes on JSX-generated DOM
+- `VirtualProvider` supports comment bindings
+- `ComponentProvider` supports custom elements
+- mustache providers support mustache-style interpolation
+- `MultiProvider` composes multiple provider strategies into one binding pipeline
+
+Providers are part of TKO's flexibility. They let the same runtime model appear through different syntaxes without changing the underlying reactive contract. A provider maps DOM nodes to binding accessors; provider composition lets one app support multiple syntaxes at once.
+
+## View Components
+
+TKO supports view components today, and they are likely to become more central as TKO 5 strengthens lifecycle boundaries.
+
+The current component surface includes:
+
+- the `component` binding
+- `ComponentProvider` for custom-element style component discovery
+- `ComponentABC` and the component registry utilities
+- class-based `BindingHandler` and `AsyncBindingHandler` patterns for component-like DOM ownership
+
+The important concept is that a view component is a DOM ownership boundary, not a replacement for the core contract. Components still sit on top of the same primitives:
+
+- observable and computed state
+- bindings and binding contexts
+- provider-driven node discovery
+- DOM activation and disposal
+
+In that sense, components are a composition tool for packaging UI, local state, template structure, and lifecycle-sensitive DOM work into a reusable unit.
+
+For TKO 5, the likely direction is stronger lifecycle clarity around those units:
+
+- clearer setup and disposal boundaries
+- stronger ownership of subscriptions, computeds, DOM listeners, and descendant activation
+- more explicit component-level contracts for mount, update, and cleanup
+
+The core idea does not change. Components should make the primitive model easier to organize at scale, not hide it behind a separate framework layer.
+
+## Composition
+
+TKO composes well when boundaries stay explicit.
+
+- use observables and computeds for local feature state
+- keep DOM ownership boundaries coherent
+- prefer modules and feature slices that are easy to inspect independently
+- treat bindings as the visible contract between state and UI
+
+Large systems can be built from these pieces, but TKO does not impose the top-level structure for doing so.
+
+## Verification Model
+
+TKO is designed to be verified from behavior rather than hidden internal machinery.
+
+- inspect state through observables and computeds
+- inspect provider and binding choice when syntax questions matter
+- inspect UI behavior through DOM output
+- use verified behaviors when questions of contract matter
+- use guide and testing docs for API and execution details
+
+For agents, the normal reading order is:
+
+1. find the state
+2. find the binding and provider path
+3. inspect the rendered behavior
+
+## Index
+
+Use `/llms.txt` as the index for the rest of the agent docs.

tko.io/public/agents/guide.md

@@ -1,6 +1,6 @@
 # TKO Agent Guide
 
-Test-backed behavior summaries live under `/agents/verified-behaviors/`. Treat those files as the contract layer when prose docs and implementation need reconciliation.
+Use `/llms.txt` as the index for the full agent docs set. Treat the verified behaviors docs as the contract layer when prose docs and implementation need reconciliation.
 
 ## Setup
 

tko.io/public/agents/testing.md

@@ -1,6 +1,6 @@
 # TKO Agent Testing Guide
 
-How to run and verify TKO code without human interaction.
+Use `/llms.txt` as the index for the full agent docs set. This file explains how to run and verify TKO code without human interaction.
 
 ## Option 1: Static HTML file (data-bind, no JSX)
 

tko.io/public/agents/thesis.md

@@ -0,0 +1,68 @@
+# TKO Thesis
+
+Use `/llms.txt` as the index for the full agent docs set. This file explains why TKO exists, what direction it follows, and what kinds of contributions align with that direction.
+
+## Core Thesis
+
+TKO treats the Knockout observable and binding model as a foundational design principle for building complex interactions at high velocity:
+
+- observables and computeds are explicit state primitives
+- bindings are an explicit bridge between state and the DOM
+- the runtime surface is comparatively small and inspectable
+- behavior can be verified directly at the DOM and contract level
+
+TKO builds from that substrate for a modern environment: modern JavaScript, CSP-safe parsing, native browser APIs, TSX authoring, verified behavior contracts, and fast browser-level feedback loops.
+
+## Why This Matters Now
+
+Frontend frameworks after Knockout often specialized around the needs of human-operated organizations: stronger framework ownership of structure, deeper build pipelines, and abstractions designed around handwritten code at team scale.
+
+TKO is not a rejection of those systems. It is a different bet.
+
+TKO is designed to enable AI to OODA faster: observe, orient, decide, and act by keeping state, DOM wiring, and runtime behavior explicit and verifiable.
+
+## Design Principles
+
+- prefer explicit contracts over hidden machinery
+- prefer browser-native flows over mandatory toolchain complexity
+- prefer verifiable examples over illustrative but fragile snippets
+- prefer modular primitives over abstractions shaped mainly by organizational overhead
+- prefer machine-readable behavior contracts alongside human docs
+
+## What This Means For Agents
+
+Agents should be able to understand a TKO program by following a short chain:
+
+1. find the observables and computeds
+2. find the bindings that connect that state to the DOM
+3. run the code and verify the resulting behavior
+
+This favors explicit contracts, local reasoning, and examples that can be executed and verified with minimal hidden scaffolding.
+
+## Contribution Alignment
+
+Contributions that align with the thesis usually:
+
+- make reactive contracts clearer
+- improve runtime inspectability
+- strengthen verified behavior coverage
+- make examples more runnable and easier to prove
+- reduce unnecessary dependency or toolchain burden
+- improve migration clarity or interop with surrounding systems
+
+Contributions that move away from the thesis usually:
+
+- hide reactive behavior behind opaque abstractions
+- add framework-owned architecture by default
+- increase toolchain burden without improving verification or clarity
+- multiply package, version, or docs ambiguity
+
+TKO should continue optimizing for regeneration, inspection, and proof: runnable examples, stable behavior contracts, clear docs routing, and lower ambiguity around packages, versions, and migration paths.
+
+## Evolutionary Analogy
+
+In biology, early ancestors are often more general and later descendants become more specialized for a particular environment. A classic example is feathers: early feathers appear to have evolved before bird flight, likely serving functions such as insulation, communication, or water repellency, and only later became aerodynamic structures for flight. The earlier substrate was not obsolete. It became newly valuable when the environment and use case changed.
+
+TKO treats Knockout in that way. Knockout appeared early in the evolution of frontend frameworks, before the ecosystem specialized around virtual DOMs, framework-owned application shells, and large convention-heavy toolchains. Its observable and binding model remained closer to a general reactive DOM substrate: explicit state, explicit DOM wiring, and direct behavioral verification.
+
+Later frontend frameworks specialized for different environmental pressures: larger human organizations, heavier build systems, framework-managed application structure, and ecosystem-scale coordination. The thesis of TKO is that AI-assisted development changes the environment. Agents need systems they can inspect, regenerate, verify, and evolve directly. In that environment, Knockout's earlier observable-and-binding substrate becomes newly fit for the same reason early feathers did: a general structure developed under one set of pressures becomes newly fit under another.