@tayo-dev/rtl 1.3.1 → 1.4.1

package/README.md

@@ -1,8 +1,8 @@
-# Taro
+# Tayo
 
-Install Taro into Claude Code, OpenCode, Gemini CLI, or Codex, then generate React Testing Library tests from Testing Library Recorder recordings.
+Install Tayo into Claude Code, OpenCode, Gemini CLI, or Codex, then generate React Testing Library tests from Testing Library Recorder JS exports.
 
-Taro ships as an installer-first package. The package entrypoint bootstraps runtime-native commands or skills into your agent environment, and the generated runtime surface still routes back to `taro generate` when you want Recorder-to-RTL output.
+Tayo ships as an installer-first package. The package entrypoint bootstraps runtime-native commands or skills into your agent environment, and those runtime entrypoints execute Tayo's internal JS-only generation flow for Recorder-to-RTL output.
 
 ## Getting Started
 
@@ -33,7 +33,7 @@ Re-run the installer package to refresh owned assets and repair missing ones:
 npx @tayo-dev/rtl@latest
 ```
 
-Taro refreshes unchanged owned files automatically, restores missing owned files, and protects manual edits instead of overwriting them silently.
+Tayo refreshes unchanged owned files automatically, restores missing owned files, and protects manual edits instead of overwriting them silently.
 
 ## Non-interactive Install
 
@@ -80,15 +80,20 @@ npm run build
 node dist/index.js --all --local
 
 # Or verify the publish boundary with a tarball
-env NPM_CONFIG_CACHE=/tmp/taro-npm-cache npm pack --pack-destination /tmp/taro-pack
-npx /tmp/taro-pack/tayo-dev-rtl-1.0.0.tgz --codex --local
+env NPM_CONFIG_CACHE=/tmp/tayo-npm-cache npm pack --pack-destination /tmp/tayo-pack
+npx /tmp/tayo-pack/tayo-dev-rtl-1.0.0.tgz --codex --local
 ```
 
 The tarball flow is the closest match to what end users get from npm.
 
 ## Generate RTL Tests
 
-After installation, use `taro generate` directly or call the runtime-native installed command/skill that routes to it.
+After installation, use the runtime-native installed generate command or skill for your agent:
+
+- Claude Code: `/@tayo-dev/rtl:generate`
+- Gemini CLI: `/@tayo-dev/rtl:generate`
+- OpenCode: `/@tayo-dev/rtl-generate`
+- Codex: `$@tayo-dev/rtl-generate`
 
 ### Prerequisites
 
@@ -100,89 +105,37 @@ After installation, use `taro generate` directly or call the runtime-native inst
 
 Open Chrome DevTools → Recorder panel → click "Start new recording" → perform your user flow → click "End recording".
 
-Taro supports two export paths:
+Tayo supports one export path:
 
-- Testing Library Recorder JS baseline export: save as `recording.js`
-- Chrome Recorder JSON export: save as `recording.json`
+- Testing Library Recorder JS export: save as `recording.js`
 
 ### Generate the test
 
-```bash
-# JS baseline path
-taro generate ./recording.js
-
-# Supported JSON path
-taro generate ./recording.json
-```
+Run your runtime-native generate entrypoint against `recording.js`. Tayo writes `recording.test.tsx` next to the recording and refuses to overwrite an existing file, so rename or delete the previous generated file before rerunning.
 
 Expected output:
 
 ```text
 Parsed: my user flow — 8 steps
-[taro] Score: 78/100 (B) — query: 80, assertions: 70, structure: 85
+[tayo] Score: 78/100 (B) — query: 80, assertions: 70, structure: 85
 Created: src/components/MyComponent.test.tsx
-[taro] ✓ post-write verified
+[tayo] ✓ post-write verified
 ```
 
-On subsequent runs in the same project, Taro reads `.taro/conventions.json` to match your test style automatically.
+On subsequent runs in the same project, Tayo reads `.tayo/conventions.json` to match your test style automatically.
 
 ### Draft-quality output is explicit
 
-When Taro cannot prove the final render/query boundary yet, it keeps the output writable but marks it as draft-quality instead of pretending the gaps are solved.
+When Tayo cannot prove the final render/query boundary yet, it keeps the output writable but marks it as draft-quality instead of pretending the gaps are solved.
 
 ```text
-[taro] Score: 77/100 (C) — query: 100, assertions: 30, structure: 70, boundary: 100
-[taro] Manual review required — this generated test is still a draft (77/100, C).
-[taro] Top blockers: The generated test still renders <App /> instead of a resolved repo target. | Boundary warnings remain in the generated file, so the render/mock boundary still needs cleanup.
-// taro-query-checkpoint: click step requires manual RTL query recovery
-```
-
-That draft banner is advisory. Taro does not block writes, but it does tell you when import targets, placeholder queries, or unresolved boundaries still need cleanup.
-
-## CLI Reference
-
-### `taro generate <file>`
-
-Generates a React Testing Library test from a Testing Library Recorder JS export or a Chrome Recorder JSON export.
-
-**Arguments:**
-
-| Argument | Description |
-|----------|-------------|
-| `<file>` | Path to the recording file. Accepts Testing Library Recorder JS files (`.js`) and Chrome Recorder JSON files (`.json`). |
-
-**Options:**
-
-| Flag | Short | Default | Description |
-|------|-------|---------|-------------|
-| `--output <path>` | `-o` | Same directory as input, `{name}.test.tsx` | Override the output file path for the generated test. |
-| `--dry-run` | `-d` | `false` | Print the generated test to stdout and show the score without writing to disk. Useful for previewing output before committing. |
-| `--force` | `-f` | `false` | Overwrite an existing test file. Without this flag, Taro exits with an error if the output file already exists. |
-| `--version` | `-v` | — | Print the installed version and exit. |
-| `--help` | `-h` | — | Display command help and exit. |
-
-**Examples:**
-
-```bash
-# Generate and write a test next to the recording
-taro generate ./recordings/checkout-flow.js
-
-# Preview without writing (dry run)
-taro generate --dry-run ./recordings/checkout-flow.js
-
-# Write to a specific path
-taro generate --output src/__tests__/checkout.test.tsx ./recordings/checkout-flow.js
-
-# Overwrite an existing test
-taro generate --force ./recordings/checkout-flow.js
+[tayo] Score: 77/100 (C) — query: 100, assertions: 30, structure: 70, boundary: 100
+[tayo] Manual review required — this generated test is still a draft (77/100, C).
+[tayo] Top blockers: The generated test still renders <App /> instead of a resolved repo target. | Boundary warnings remain in the generated file, so the render/mock boundary still needs cleanup.
+// tayo-query-checkpoint: click step requires manual RTL query recovery
 ```
 
-**Output file naming:**
-If `--output` is not provided, Taro derives the output path from the input file: `{input-dir}/{input-basename}.test.tsx`. For example, `./recordings/login.js` → `./recordings/login.test.tsx`.
-
-**Supported input formats:**
-- Testing Library Recorder JS (`.js`) — primary v1.3 path; Taro treats this as a baseline artifact to parse, enrich, and transform into a project-shaped RTL test
-- Chrome Recorder JSON (`.json`) — supported parity path; Taro preserves the existing JSON generate flow while JS fidelity improves
+That draft banner is advisory. Tayo does not block writes, but it does tell you when import targets, placeholder queries, or unresolved boundaries still need cleanup.
 
 ## Worked Example
 
@@ -204,24 +157,22 @@ test('login flow', async () => {
 })
 ```
 
-### Command
+### Runtime command
 
-```bash
-taro generate ./login-flow.js
-```
+Run your installed runtime-native generate entrypoint with `./login-flow.js`.
 
 ### Terminal output
 
 ```
 Parsed: login flow — 7 steps
-[taro] Score: 82/100 (B) — query: 90, assertions: 75, structure: 80
+[tayo] Score: 82/100 (B) — query: 90, assertions: 75, structure: 80
 Created: login-flow.test.tsx
-[taro] ✓ post-write verified
+[tayo] ✓ post-write verified
 ```
 
 ### Output: Generated test (`login-flow.test.tsx`)
 
-Taro generates a convention-aware RTL test with accessible queries:
+Tayo generates a convention-aware RTL test with accessible queries:
 
 ```typescript
 import { render, screen } from '@testing-library/react'
@@ -244,7 +195,7 @@ describe('login flow', () => {
 })
 ```
 
-### What Taro did here
+### What Tayo did here
 
 - Parsed the navigate step and inferred the component under test
 - Upgraded CSS selectors (`#email`, `#password`) to accessible `getByRole` queries using aria attributes from the recording
@@ -252,30 +203,20 @@ describe('login flow', () => {
 - Mapped the `waitForElement` step to a `toBeInTheDocument()` assertion
 - Scored the output (82/100) and emitted no blocking errors
 
-> **Note:** The component import path (`../LoginPage`) is a placeholder. Taro generates a comment in the file indicating where to update it.
-
-### JSON is also supported
-
-If you export Chrome Recorder JSON instead, the command surface stays the same:
-
-```bash
-taro generate ./login-flow.json --dry-run
-```
-
-JSON generation is still supported, but it does not inherit the repo-aware JS recovery stack. When the generated preview contains placeholder queries or weak assertions, Taro keeps those gaps explicit with score and manual-review messaging instead of fabricating stronger evidence.
+> **Note:** The component import path (`../LoginPage`) is a placeholder. Tayo generates a comment in the file indicating where to update it.
 
 ## Agent Usage
 
-After installation, each runtime gets a namespaced help entrypoint plus a generate command or skill that routes back to `taro generate`.
+After installation, each runtime gets a namespaced help entrypoint plus a generate command or skill that runs Tayo's internal JS generator.
 
 ### Tips
 
-- Use `--dry-run` first to preview output before committing generated files
-- If you record multiple flows, run Taro on each to build up convention state in `.taro/conventions.json` — later runs benefit from earlier ones
-- Pass `--force` when re-recording an updated flow to overwrite the old test
-- The `.taro/` directory should be committed to your repo so convention learning persists across team members
+- Tayo writes the generated test next to the recording file using the same basename
+- If you re-record a flow, rename or delete the old generated test before running Tayo again
+- If you record multiple flows, run Tayo on each to build up convention state in `.tayo/conventions.json` — later runs benefit from earlier ones
+- The `.tayo/` directory should be committed to your repo so convention learning persists across team members
 
 ### Notes
 
-- Taro does not require network access at generation time (DOM inspection via Playwright is optional and only runs when a live URL is in the recording)
-- All state is local to `.taro/` — no external service is contacted
+- Tayo does not require network access at generation time (DOM inspection via Playwright is optional and only runs when a live URL is in the recording)
+- All state is local to `.tayo/` — no external service is contacted

package/assets/claude/commands/@tayo-dev/rtl/generate.md

@@ -1,15 +1,52 @@
 ---
 name: "@tayo-dev/rtl:generate"
-description: "Generate RTL tests from Recorder exports with Taro"
+description: "Generate RTL tests from Recorder exports with Tayo"
 ---
 
 <objective>
-Generate a React Testing Library test from a Recorder export.
+Generate a React Testing Library test from a Testing Library Recorder JS export, interpret the score output, and guide the user through any required manual fixes.
 </objective>
 
 <process>
-1. Confirm the recording path before running anything destructive.
-2. Run `taro generate <recording-file>` by default.
-3. Add `--dry-run`, `--output <path>`, or `--force` only when the user asks for them or the context requires them.
-4. Report the generated file path and score output.
+1. Confirm the recording file path and extension (`.js` only).
+2. Tayo writes `{recording-name}.test.tsx` next to the recording. If that file already exists, stop and tell the user to rename or delete it before rerunning generation.
+3. Run `tayo __generate <recording-file>`.
+4. Parse and report the score, grade, and blockers.
+5. Work through the post-generation checklist for any issues found.
 </process>
+
+<scoring>
+Tayo scores on four weighted dimensions. Grade: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F < 60.
+Score below 80 or QUAL-02 marker failure → Tayo emits "Manual review required".
+
+Query dimension (30%): getByRole = 100pts, getByLabelText = 80pts, getByText = 60pts, getByPlaceholderText = 50pts, getByTestId = 20pts. Each tayo-query-checkpoint comment deducts 3pts (capped at −40).
+
+Assertion dimension (25%): toHaveValue/toBeChecked/toHaveTextContent/toBeVisible = full credit. toBeInTheDocument = 30% credit. No assertions = 0.
+
+Structure dimension (20%): Base 50. describe() block +20. Each extra it() block +15 (cap +30). render(<App />) −25. tayo-boundary-warning −20. Single test >2000 chars −20.
+
+Boundary dimension (25%): Start 100. leaf-render-boundary −35. inline-hook-mock −30. helper-embedded-assertion −20. positional-control-selection −15.
+</scoring>
+
+<boundary-issues>
+tayo-boundary-warning comments mark one of four issues:
+
+leaf-render-boundary (−35): Test renders *Form, *Dialog, *Modal, or *Drawer directly while the flow involves container-level interaction. Fix: render the nearest page/module component that owns the trigger button and the dialog lifecycle.
+
+inline-hook-mock (−30): vi.mock/jest.mock defines use*Query or use*Mutation hooks inline. Fix: move hook mocks to a shared fixture or raise the render boundary.
+
+helper-embedded-assertion (−20): A helper function outside the test body contains expect(). Fix: assertions belong in the it() body; helpers handle setup and navigation only.
+
+positional-control-selection (−15): getAllByRole('button')[2] positional indexing. Fix: scope with within(container) or use a more specific accessible name.
+</boundary-issues>
+
+<post-generation-checklist>
+1. Fix render(<App />) — find the narrowest component that owns the trigger and expected outcome.
+2. Resolve tayo-query-checkpoint comments — apply the query hierarchy: getByRole > getByLabelText > getByText > getByPlaceholderText > getByTestId.
+3. Upgrade toBeInTheDocument() — replace with toHaveTextContent(), toHaveValue(), or toBeVisible() when the expected value is known.
+4. Fix tayo-boundary-warning comments — apply the boundary fix from the boundary-issues section above.
+</post-generation-checklist>
+
+<response-contract>
+Report: the command run, the generated file path, the score and grade (e.g. 82/100 B — query: 90 assertions: 75 structure: 80 boundary: 85), whether manual review is required, the top blockers, and which post-generation steps apply with specific guidance for each.
+</response-contract>

package/assets/claude/commands/@tayo-dev/rtl/help.md

@@ -10,7 +10,7 @@ Help the user install and use @tayo-dev/rtl from Claude Code.
 <process>
 1. Explain that `/@tayo-dev/rtl:help` is the installed help entrypoint for @tayo-dev/rtl.
 2. For installation or updates, tell the user to run `npx @tayo-dev/rtl@latest`.
-3. For test generation, use `/@tayo-dev/rtl:generate` or run `taro generate <recording-file>`.
-4. Mention `--dry-run`, `--output <path>`, and `--force` only when they fit the request.
+3. For test generation, use `/@tayo-dev/rtl:generate` with a Testing Library Recorder `.js` export.
+4. Tell the user Tayo writes `{recording-name}.test.tsx` next to the recording and will not overwrite an existing file.
 5. When generation runs, report the score and generated file path.
 </process>

package/assets/codex/@tayo-dev/rtl-conventions/SKILL.md

@@ -1,19 +1,51 @@
 ---
 name: "@tayo-dev/rtl-conventions"
-description: "Explain how Tayo learns project test conventions and how to keep them stable."
+description: "Explain and stabilize how Tayo learns project test conventions from `.tayo/conventions.json` and nearby repo examples. Use when generated output style, imports, file placement, helpers, or mock structure differ from expectations, or when the user wants Tayo to follow local testing conventions more closely."
 ---
 
 # Tayo Conventions
 
-Use `$@tayo-dev/rtl-conventions` when the user asks why generated tests follow a certain style or how `.taro/conventions.json` affects output.
+Invoke this skill with `$@tayo-dev/rtl-conventions`.
 
-## Focus
+## What `.tayo/conventions.json` Controls
 
-- explain that Tayo learns local test conventions from the codebase
-- call out when `.taro/conventions.json` will influence generated imports, mocks, and file placement
-- recommend `--dry-run` when the user wants to inspect convention alignment before writing files
+Tayo reads `.tayo/conventions.json` on every generation and uses it to align output with the project's test style. Key fields:
+
+| Field | Values | Effect |
+|-------|--------|--------|
+| `importStyle` | `"esm"` (default) / `"cjs"` | Controls `import` vs `require` in generated tests |
+| Render helper name | learned from repo | Tayo reuses existing render wrapper functions instead of writing `render(...)` directly |
+| File placement | learned from repo | Tayo matches `__tests__/`, `*.test.tsx` co-location, or `src/tests/` depending on what exists |
+| Mock shape | learned from repo | Tayo aligns factory shapes with existing `vi.mock` or `jest.mock` examples |
+
+Tayo accumulates knowledge from existing test files in the project. Commit `.tayo/conventions.json` to your repo so convention learning persists for all team members.
+
+## Investigation Workflow
+
+1. Check whether `.tayo/conventions.json` exists. If it is missing, Tayo falls back to generic defaults — the fix is to run Tayo on a few existing flows so it can learn the project style.
+2. Sample nearby existing tests when repo context is available.
+3. Compare generated output against local patterns for imports, render helpers, user-event setup, mocks, naming, and file placement.
+4. Explain whether the mismatch comes from learned repo conventions, missing examples, or a current Tayo limitation.
+
+## How to Correct Convention Drift
+
+- **Wrong import style** — set `importStyle` in `.tayo/conventions.json` to `"esm"` or `"cjs"`.
+- **Wrong file placement** — move one generated test to the correct location and re-run; Tayo picks up placement from the nearest examples.
+- **Missing render wrapper** — if the project uses a custom `renderWithProviders` helper, add one test that uses it; subsequent generations will prefer it.
+- **Before re-running generation** — make sure the sibling `{recording-name}.test.tsx` path is free, because Tayo writes next to the recording and will not overwrite an existing file.
 
 ## Guardrails
 
 - prefer existing project conventions over generic defaults
 - surface missing context instead of inventing project-specific patterns
+- if there is no stable local pattern, say that directly instead of claiming Tayo has a single correct style
+- tell the user what repo examples or config need to exist for future generations to improve
+
+## Response Contract
+
+Summarize:
+
+- what conventions Tayo is currently picking up (importStyle, render helper, file placement)
+- where the generated output matches or diverges from local patterns
+- whether `.tayo/conventions.json` or repo examples are driving the current behavior
+- the specific field or example the user needs to add or fix to improve future generations

package/assets/codex/@tayo-dev/rtl-generate/SKILL.md

@@ -1,28 +1,140 @@
 ---
 name: "@tayo-dev/rtl-generate"
-description: "Generate React Testing Library tests from Recorder JS or Chrome Recorder JSON exports with Tayo."
+description: "Generate deterministic, repository-aware React Testing Library tests from Testing Library Recorder JS exports with Tayo. Use when a user provides a Recorder `.js` file, asks to turn a recorded flow into an RTL test, needs render-boundary or mock strategy guidance, or needs score and verification output interpreted precisely."
 ---
 
 # Tayo Generate
 
-Use `$@tayo-dev/rtl-generate` when the user wants to turn a Recorder JS export or Chrome Recorder JSON export into a React Testing Library test.
+Invoke this skill with `$@tayo-dev/rtl-generate`.
 
-## Inputs
+## Purpose
 
-- path to the recording file (`.js` or `.json`)
-- optional `--output <path>`
-- optional `--dry-run`
-- optional `--force`
+Transform a Testing Library Recorder `.js` recording into a maintainable, project-aware RTL test without losing behavioral fidelity.
 
-## Execution
+Non-negotiable expectations:
 
-Run `taro generate <recording-file>` with the requested flags.
+- parse recordings deterministically through the Tayo pipeline; do not improvise a second parser
+- prefer semantic user intent over DOM mechanics
+- treat semantic `dblClick` checkpoints as assertion evidence, not as UI actions to replay
+- preserve the real entry path when the recording opens UI through a parent trigger or route flow
+- never solve a generation problem by reimplementing design-system or shared UI-library components in mocks
+- keep low-confidence gaps explicit instead of pretending the output is finished
 
-## Response contract
+## Reference Map
+
+Read only the files that apply to the current problem:
+
+- `references/intent-model.md` for parsed-step normalization and interaction-intent recovery
+- `references/assertion-markers.md` for converting semantic `dblClick` checkpoints into explicit assertions
+- `references/entry-path-fidelity.md` when deciding parent trigger flow versus direct dialog/form harnesses
+- `references/conventions-schema.md` when interpreting `.tayo/conventions.json` or convention drift
+- `references/mock-store.md` when deciding fixture reuse or persistent mock storage
+- `references/quality-scoring.md` when explaining score changes, grade drops, or blocker priorities
+- `references/verification-gate.md` when deciding whether generated output is acceptable to hand off
+- `references/auth.md` only when live URL inspection or screenshots hit an authentication wall
+- `references/state-schema.md` and `references/test-index.md` only when state/history questions matter
+
+## Working Style
+
+Keep discovery narrow and deliberate.
+
+- Default cap: inspect at most 5 repo files before generation planning.
+- Prioritize target source, nearest sibling test, shared mock setup, nearest fixture store, then config.
+- If uncertainty remains after that cap, stop expanding scope and report the limitation instead of scanning blindly.
+
+When you do repo inspection beyond Tayo's own console output, report:
+
+- `Surface scan: {N}/5 files`
+- `Selected files: [...]`
+- `Skipped expansions: [...]`
+
+## Preflight
+
+1. Accept only Testing Library Recorder `.js` exports.
+2. Tayo writes `{recording-name}.test.tsx` next to the recording.
+3. If that sibling output file already exists, stop and tell the user to rename or delete it before rerunning generation.
+4. If the user is asking for convention diagnosis or mock review instead of generation, route them to the more specific Tayo skill when that is the better fit.
+
+## Generation Workflow
+
+1. Validate the input recording and confirm it is the intended flow.
+2. Recover semantic intent from the recording before discussing code changes.
+3. Resolve render boundary and mock plan with entry-path fidelity in mind.
+4. Run `tayo __generate <recording-file>`.
+5. Interpret score, blockers, marker coverage, and verification output before calling the result complete.
+
+## Intent Recovery Rules
+
+- Prefer accessible role/name and visible-text evidence over CSS evidence.
+- Use semantic marker guidance from `references/assertion-markers.md` when the recording preserves checkpoint intent.
+- Treat unresolved selector evidence as an explicit checkpoint to explain, not something to hide with fabricated queries.
+- Use `getByTestId` only as a last resort and only when the repo conventions justify it.
+
+## Entry-Path Fidelity
+
+Use `references/entry-path-fidelity.md` whenever the recording opens a form, drawer, dialog, or route through earlier trigger steps.
+
+Default behavior:
+
+- if the recording clicks a parent trigger first, prefer rendering the parent/module composition and replaying that trigger
+- do not replace a real parent-trigger flow with a directly-open dialog harness when the parent path is available
+- if Tayo emits boundary warnings or falls back to `render(<App />)`, explain that as a fidelity or context gap, not a finished solution
+
+## Mock Boundary Policy
+
+This policy is mandatory on every run.
+
+Allowed mock targets:
+
+- data/query/mutation boundaries
+- auth/session boundaries
+- router/navigation boundaries
+- environment/browser gaps
+- explicit local child modules when isolation clearly requires them
+
+Forbidden:
+
+- reimplementing design-system or shared UI-library components in generated test mocks
+- swapping an entire UI package with fake replacement components just to satisfy verification
+
+If a mock plan would violate that boundary, stop and call out the violation clearly. Use `references/verification-gate.md` and `references/mock-store.md` before suggesting alternatives.
+
+## Score and Verification
+
+Read these references when interpreting output quality:
+
+- `references/quality-scoring.md`
+- `references/verification-gate.md`
+
+Minimum reporting standard after generation:
+
+- generated file path
+- score and grade
+- whether manual review is still required
+- top blockers
+- whether marker coverage or boundary fidelity is still incomplete
+
+If Tayo reports draft-quality output, QUAL-02 failure, or unresolved marker/boundary gaps, state plainly that the result is not production-ready yet.
+
+## Auth and Screenshots
+
+Only read `references/auth.md` when live URL inspection or screenshot capture is relevant.
+
+Rules:
+
+- auth is optional support for debugging, not a prerequisite for generation
+- never block basic generation on unavailable auth
+- never ask the user for secrets in plain text
+
+## Response Contract
 
 Report:
 
+- the command you ran
 - the generated test path
-- the Tayo score
-- whether the output still needs manual review and the top blockers if present
-- any follow-up work required to fix component imports, placeholder queries, or flaky selectors
+- the score and grade
+- whether manual review is required
+- the top blockers
+- the smallest concrete next fixes, ordered by impact
+
+When repo context was limited, say so explicitly instead of inventing certainty.

package/assets/codex/@tayo-dev/rtl-generate/references/assertion-markers.md

@@ -0,0 +1,62 @@
+# Assertion Markers (Tayo)
+
+Purpose:
+Allow non-technical users to mark "this should be asserted" during recording
+without opening advanced Recorder assertion settings.
+
+---
+
+## Primary Marker: `dblClick`
+
+User action pattern:
+
+1. Trigger UI change (open modal, submit form, continue, save, etc.).
+2. Double-click the visible target that proves the expected result.
+
+Interpretation:
+
+- Tayo treats semantic `dblClick` events as `assertExists` markers.
+- Marker assertions are generated as explicit RTL expectations in the closest
+  relevant test block.
+
+---
+
+## Mapping Rules (Deterministic)
+
+1. Identify `userEvent.dblClick(...)` events in parsed steps.
+2. Use the dblClick target itself as the marker target (no copy chord required).
+3. Build query hints in this order:
+   - role + name (if `aria/` evidence exists)
+   - text (if `text/` evidence exists)
+   - label/placeholder (if input context is explicit)
+4. If only CSS evidence exists, skip marker-to-assertion conversion and log
+   limitation.
+
+Important reliability note:
+
+- DblClick markers on generic targets like modal containers, table rows, icons
+  (`svg/path`), or dynamic radix/css selectors are often ambiguous.
+- These ambiguous markers should be reported as unresolved rather than silently
+  converted into weak assertions.
+
+---
+
+## Example Outcomes
+
+- Marker dblClick on modal title after "Add Sale" click
+  - Generate: assert dialog heading/title exists.
+- Marker dblClick on validation text after empty submit
+  - Generate: assert required-field error exists.
+- Marker dblClick on success toast after save
+  - Generate: assert success message exists.
+
+---
+
+## Guardrails
+
+- Marker assertions are additive; they do not replace required happy/validation/failure tests.
+- `highlight + copy` is not used for marker conversion.
+- Never generate assertions from screenshots.
+- Never infer hidden/internal implementation details from marker actions.
+- If marker conversion fails due to ambiguous selectors, emit a clear warning
+  with unresolved marker line references.

package/assets/codex/@tayo-dev/rtl-generate/references/auth.md

@@ -0,0 +1,92 @@
+# Authentication Checkpoint (Provider-Agnostic)
+
+Purpose:
+Enable optional browser-based screenshot capture on authenticated routes.
+
+Important:
+Authentication must never block test generation.
+Secrets are never stored in state.
+Only environment variable NAMES are stored.
+
+Auth recipes are stored inside:
+.tayo/state.json → auth.recipes[]
+
+---
+
+## Auth Recipe Structure (stored in state.json)
+
+Each recipe looks like:
+
+{
+"id": "string",
+"label": "string",
+"scope": ["string"],
+"strategy": "none | ui_email_password | ui_oauth_manual | cookie | header",
+"detectAuthRequired": {
+"urlIncludes": ["string"],
+"pageTextIncludes": ["string"]
+},
+"detectAuthenticated": {
+"urlExcludes": ["string"],
+"pageTextExcludes": ["string"]
+},
+"ui": {
+"emailSelectors": ["string"],
+"passwordSelectors": ["string"],
+"submitSelectors": ["string"],
+"postLoginWait": {
+"urlNotIncludes": ["string"],
+"pageTextIncludes": ["string"],
+"timeoutMs": 8000
+}
+},
+"credentials": {
+"emailEnv": "string | null",
+"passwordEnv": "string | null",
+"cookieEnv": "string | null",
+"headerEnv": "string | null"
+},
+"confidence": 0.0,
+"evidence": [],
+"createdAt": "ISO-8601",
+"updatedAt": "ISO-8601"
+}
+
+---
+
+## First Run Behavior
+
+If Tayo detects a login page but no recipe exists:
+
+- Create a recipe with:
+  - strategy = "ui_oauth_manual"
+  - scope = current site origin
+  - detection fields filled from observed URL/text
+  - low confidence (0.4)
+- If browser tools are available, run a manual checkpoint:
+  - navigate to the protected route
+  - instruct the user to complete authentication in-browser
+  - wait/poll `detectAuthenticated` until timeout
+- If authenticated during checkpoint:
+  - set auth status to `authenticated`
+  - continue with screenshot capture
+- If not authenticated by timeout:
+  - keep auth status `unknown_recipe`
+  - skip screenshots and continue test generation.
+
+## Manual OAuth Checkpoint (ui_oauth_manual)
+
+When `strategy` is `ui_oauth_manual`:
+
+- Tayo must open the browser and pause for user completion of login.
+- Tayo must poll `detectAuthenticated` conditions (URL/text) until timeout.
+- Tayo must not capture screenshots before authentication succeeds.
+- On success, set auth status `authenticated`; on timeout, set `failed` (or `unknown_recipe` for first-run templates).
+
+---
+
+## Security Rules
+
+- Never store passwords in files.
+- Never print credential values.
+- Only read credentials from environment variables.