Merge pull request #351 from knockout/docs/agent-docs-tighten

Trim redundant preambles in hand-authored agent docs

Author: brianmhunt

.gitignore

@@ -36,7 +36,7 @@ builds/**/meta
 .playwright-mcp
 .playwright-cli
 test-results/
-.claude/worktrees/
+.claude/
 __screenshots__
 .dts-tmp/
 .nx/

tko.io/public/agents/contract.md

@@ -1,6 +1,6 @@
 # TKO Agent Contract
 
-Use this file when deciding how state, bindings, and DOM work should be divided in TKO examples and prototypes.
+Use this file when deciding how to divide state, bindings, and DOM work in TKO examples and prototypes.
 
 ## Core Rule
 
@@ -10,7 +10,8 @@ Use this file when deciding how state, bindings, and DOM work should be divided
 
 ## Replace X With Y
 
-- This section is about replacing ad-hoc DOM/event/state handling with bindings, not about binding-syntax style.
+Replace ad-hoc DOM/event/state handling with bindings. Not about binding-syntax style.
+
 - If you are about to do `element.textContent = value`, use the `text` binding.
 - If you are about to do `element.innerHTML = markup`, first ask whether the content should be plain text instead; prefer the `text` binding by default. Use `html` only when rendering trusted HTML is truly the point.
 - If you are about to manually create, replace, or reconcile a repeated set of child nodes, use `foreach`.

tko.io/public/agents/glossary.md

@@ -1,7 +1,5 @@
 # TKO Glossary
 
-Domain-specific terms for the TKO (Typed Knockout) framework.
-
 ## Core Concepts
 
 - **Observable** (`ko.observable(value)`) — a value wrapper that notifies subscribers when it changes. The fundamental reactive primitive.

tko.io/public/agents/options.md

@@ -1,8 +1,6 @@
 # `ko.options.*` — Configurable Runtime Options
 
-`ko.options` is TKO's runtime configuration object. It is a singleton `Options`
-instance defined in `packages/utils/src/options.ts`. This page documents how
-to add new options and which of the two available mechanisms to reach for.
+`ko.options` is TKO's runtime configuration singleton, defined in `packages/utils/src/options.ts`. Two mechanisms for adding options — this page explains which to reach for.
 
 ## Two mechanisms — when to use which
 

tko.io/public/agents/process.md

@@ -77,7 +77,7 @@ For pages with runnable TSX examples, also run the headless Playwright flow:
 - Use `playwright-cli` in headless mode. Do not use headed/browser-stealing runs unless the user explicitly asks for them.
 - Prefer a live Astro dev server on `127.0.0.1:4321` so markdown/plugin edits reload while you work (`bun run dev` in `tko.io/`).
 - Verify each `Open in Playground` button on the page; if a page has multiple TSX examples, check every one, not just the first.
-- Standard flow: `playwright-cli close-all`, `playwright-cli open http://127.0.0.1:4321/...`, inspect the snapshot for playground refs, click each button, switch to the playground tab, and confirm `#esbuild-status`, `#compile-time`, and `#error-bar`.
+- Standard flow: `playwright-cli close-all`, `playwright-cli open http://127.0.0.1:4321/...`, inspect the snapshot for playground refs, click each button, switch to the playground tab, and confirm `[data-role="status"]` (shows "esbuild ready"), `[data-role="compile-time"]`, and `[data-role="error-bar"]`.
 - Treat docs example work as incomplete until the emitted playground payload compiles cleanly on the live site.
 
 Generator-owned files: see the note at the top of this document under "Never ship docs that reference things that don't exist on the target branch."

tko.io/public/agents/soul.md

@@ -1,9 +1,6 @@
 # The Soul of Knockout
 
-This document describes the philosophical foundation of Knockout and TKO.
-Read this to understand *why* the framework works the way it does, not just
-*how* to use it. If you're an AI agent working on this codebase, this is
-the context behind every design decision.
+Read this to understand *why* Knockout/TKO is shaped the way it is, not just *how* to use it. AI agents working on this codebase: this is the context behind every design decision.
 
 ## The Core Insight
 

tko.io/public/agents/testing.md

@@ -35,7 +35,7 @@ Workflow:
 3. Navigate Playwright to `http://localhost:8765/tko-test.html`
 4. Read `document.title` or snapshot the DOM to verify
 
-This is the fastest option — no esbuild and no network dependency on the playground, though Option 1 still fetches `https://tko.io/lib/tko.js` unless you vendor that file locally. Works for all `data-bind` code.
+Fastest option — no esbuild, no playground. Still fetches `https://tko.io/lib/tko.js` unless vendored locally. Works for all `data-bind` code.
 
 ## Option 2: Playground via Playwright (JSX/TSX)
 
@@ -53,22 +53,22 @@ const url = `https://tko.io/playground#${hash}`
 4. The code auto-compiles and runs in the preview iframe
 5. Read the iframe content or console output to verify
 
-The playground forwards console messages from the iframe to the parent page — look for `#console-messages` in the DOM for console.log/error output.
+The playground forwards console messages from the iframe to the parent page — look for `[data-role="console-messages"]` in the DOM for console.log/error output.
 
 ### Checking results
 
-The preview iframe is `#preview`. To read its content:
+The preview iframe is `[data-role="preview"]`. To read its content:
 
 ```js
-const iframe = document.querySelector('#preview')
+const iframe = document.querySelector('[data-role="preview"]')
 const body = iframe.contentDocument.body
 ```
 
-Console output appears in `#console-messages` as child elements.
+Console output appears in `[data-role="console-messages"]` as child elements.
 
 ### Timing
 
-esbuild-wasm takes a few seconds to initialize on first load. The playground shows "esbuild ready" in `#esbuild-status` when it's ready. Code auto-runs after compilation.
+esbuild-wasm takes a few seconds to initialize on first load. The playground shows "esbuild ready" in `[data-role="status"]` when it's ready. Code auto-runs after compilation.
 
 ## Option 3: Testing doc page examples