{"owner":"QwikDev","repo":"qwik","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"<!-- Generated by Ruler -->\n\n\n<!-- Source: .ruler/AGENTS.md -->\n\n# Qwik v2 agents reference, instructions and rules\n\n> [!IMPORTANT]\n> **ALWAYS RUN `ruler apply` AT THE START OF A SESSION.** The agent skills are gitignored, not\n> committed, so a fresh clone/worktree has none until you generate them (once per worktree):\n>\n> ```bash\n> pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n> ```\n\n> Canonical source for repo-wide AI coding agent rules. For contributor setup, see\n> [CONTRIBUTING.md](./CONTRIBUTING.md). For package-specific workflows, load the relevant\n> `.ruler/skills/*/SKILL.md` file.\n\n## Source Of Truth\n\n- Shared AI guidance lives in `.ruler/`.\n- Only the root `AGENTS.md` and `CLAUDE.md` are committed generated outputs; the `.claude/`/`.codex/`\n  skill copies are gitignored and regenerated locally with `ruler apply` (see Setup below).\n- Never hand-edit a generated output — edit `.ruler/` and regenerate with `ruler apply`. A CI check\n  re-runs it and fails if the committed root files drift.\n- To change assistant behavior, edit `.ruler/AGENTS.md`, `.ruler/README.md`, or `.ruler/skills/**`,\n  then regenerate with Ruler when needed.\n\n## Project Snapshot\n\nQwik is a resumable web framework. SSR serializes application and framework state into HTML, and\nthe client resumes without re-running component code. Qwik v2 is a rewrite with VNode-based\nruntime work, rewritten reactive primitives, a new serialization mechanism, and package names under\n`@qwik.dev/*`.\n\nKey concepts: resumability, QRLs, `$`-suffixed optimizer boundaries, fine-grained signals, VNodes,\nthe cursor system, and the Rust optimizer.\n\n## Monorepo Map\n\n- Base branch and release branch for v2 PRs: `main`. V1 lives on the `v1` branch.\n\n| Package | Path | Notes |\n| --- | --- | --- |\n| `@qwik.dev/core` | `packages/qwik` | Core runtime, SSR, optimizer-facing code |\n| `@qwik.dev/router` | `packages/qwik-router` | Routing, middleware, adapters, SSG |\n| `@qwik.dev/react` | `packages/qwik-react` | React integration |\n| `@qwik.dev/dom` | `packages/qwik-dom` | Server-side DOM implementation |\n| `@qwik.dev/qwik-vite` | `packages/qwik-vite` | `vite-plugin-qwik`, private, bundled into `@qwik.dev/core/optimizer` |\n| `@qwik.dev/optimizer` | `packages/optimizer` | Rust optimizer, WASM, NAPI bindings |\n| `eslint-plugin-qwik` | `packages/eslint-plugin-qwik` | ESLint rules |\n| `create-qwik` | `packages/create-qwik` | Project scaffolding CLI |\n| `qwik-docs` | `packages/docs` | Docs site, private package |\n| `insights` | `packages/insights` | Analytics dashboard, private package |\n\nUse v2 package names (`@qwik.dev/core`, `@qwik.dev/router`, etc.). Do not introduce v1\n`@builder.io/qwik` or `@builder.io/qwik-city` imports except when working on explicit\ncompatibility override code.\n\n## Setup And Iteration Loop\n\nThis is the canonical loop for nearly all framework work. Default to it; do not substitute broader\ncommands:\n\n### getting started\n\n```bash\npnpm i\n```\n\n```bash\n# Materialize the agent skills into .claude/.codex (gitignored) — run once per fresh clone/worktree.\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\n```bash\npnpm build.core # for a fresh start\npnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)\n```\n### Iterating\n\nPrefer focused commands and builds over repo-wide commands and builds.\n\n```bash\n# Fast dev build — required once before any tests can run, and again after framework\n# source changes when the verification consumes build output (all e2e suites do)\npnpm build.core.dev\n\n# Closest focused unit/spec test\npnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx\n\n# Focused e2e test\npnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts\n```\n\n`build.core.dev` also re-emits fresh Qwik and Router `.d.ts` incrementally (via `tscDevDts` + re-export shims), so editing a public signature no longer leaves stale types — `build.watch` skips the type pass to stay instant.\n\nFor Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.\n\nRe-run `pnpm build.full` when you are touching the optimizer rust code.\n\n### When making a PR\n\n```bash\n# for type-level verification when no focused test covers the change\npnpm tsc.check\n\n# update the API\npnpm api.update\n\n# Verify the build passes\npnpm build.core\n\n# Verify unit tests pass\npnpm test.unit\n\n# Verify the E2Es pass\npnpm test.e2e.chromium\n\n# In case of html output change, update the ssg snapshot\npnpm test.e2e.router.ssg.update\n\n# In case of a new feature, run the test.bench\npnpm test.bench\n\n# In case of qwikloader changes\npnpm vitest packages/qwik/src/qwikloader.unit.ts -u\n```\n\nIf any of those fail, fix and push your changes.\n\n## Rules\n\nRecent Qwik v2 work by core maintainers favors small, behavior-shaped changes with regression proof.\nFollow that bias:\n\n### Guidance Freshness\n\n- If a skill or reference you used is stale, incomplete, or contradicted by current source, update\n  the `.ruler` source guidance before finishing the task unless the user explicitly restricted the\n  scope.\n- Keep new durable lessons in the most specific skill or reference that future agents are likely to\n  load. Do not add package-specific details to these always-on rules unless they affect most tasks.\n- Only add a lesson to a skill when it generalizes to future tasks. Keep single-PR specifics (one\n  module's protocol, one fix's mechanics) in the code and its tests, not in a skill.\n- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,\n  where things live, and how to verify — rather than describing how the code currently works. Omit \"don't do X\" prohibitions for anything a test already enforces; the\n  suite is the guardrail, so reserve notes for what it can't self-enforce.\n- When updating guidance, load the `qwik-guidance-maintenance` skill.\n\n### Skill Selection\n\nLoad the relevant skill before non-trivial work in that area:\n\n| Skill | Use when |\n| --- | --- |\n| `qwik-core-development` | Editing/reviewing `packages/qwik/**` core runtime code |\n| `qwik-router-development` | Editing/reviewing router runtime, buildtime, middleware, adapters, or SSG |\n| `qwik-optimizer-development` | Editing/reviewing Rust optimizer, WASM, NAPI, or optimizer-facing behavior |\n| `qwik-e2e-verification` | Creating, debugging, or running Playwright e2e suites |\n| `qwik-docs-development` | Writing/editing docs content, docs site routes, or docs LLM outputs |\n| `qwik-guidance-maintenance` | Editing `.ruler/**`, generated-output guidance, or stale skill/reference content |\n\nIf no skill fits, stay with these repo-wide rules and inspect local source before changing code.\n\nIf a skill above is not loadable, its copy has not been generated in this worktree yet — run the\n`ruler apply` step from Setup, or read the source directly at `.ruler/skills/<name>/SKILL.md`.\n\nKeep the `qwik-` prefix on committed source skill names. Ruler copies these skills into\nagent-native skill directories where they may coexist with user or plugin skills, so the prefix keeps\nthe skill list unambiguous outside the repo-local `.ruler` tree.\n\n### Changesets\n\nWhen a change affects published packages, add a changeset under `.changeset/`.\n\n- Use `patch` for bug fixes: focus on the issue rather than the solution.\n- `minor` for new features: explain the new feature.\n- `major` for API removal: may also include a new feature, but it must remove or break a public API.\n- Enforce 1 changeset per change.\n- Write the changeset summary in lowercase (e.g. `fix:`)\n- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.\n\n### Code Quality\n\n\n#### Sanity\n\n- Remember to keep your code DRY.\n- Do not leave debug logging or temporary names in the final diff.\n- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.  \n- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.\n\n#### Naming\n\n- Use names that explain the domain idea, not the implementation trick.\n- Prefer specific names over short names when the value crosses more than a few lines.\n- Name booleans as questions or states, such as `isReady`, `hasSubscribers`, or `shouldFlush`.\n- Name functions by the action they perform, such as `resolveLoaderData()` or\n  `markContainerReady()`.\n- Avoid vague names like `data`, `item`, `temp`, `handle`, `process`, or `doWork` unless the local\n  scope makes the meaning obvious.\n- Keep existing public API names unless the task is intentionally changing the API.\n\n#### Control Flow\n\n- Prefer early returns for invalid, empty, unsupported, or already-handled cases.\n- Avoid deep nesting when a guard clause can make the main path easier to read.\n- Keep the success path visible at the outer indentation level when possible.\n- Do not use clever boolean expressions when a named condition or small helper would be clearer.\n- Keep error and compatibility branches explicit so reviewers can see why they exist.\n\n#### Modularity\n\n- Keep functions focused on one responsibility.\n- Extract a helper when a block has a clear name, is reused, or hides the main path.\n- Do not extract helpers only to move complexity around; the caller should become easier to read.\n- Keep helpers close to their first use unless they are shared across files.\n- Prefer local semantic helpers over broad abstractions.\n- Keep consumer- or framework-specific carve-outs (magic values, special cases) at the boundary that\n  owns that knowledge; do not push them into a generic lower-level utility that should stay agnostic.\n\n#### Review Standard\n\nBefore finishing, read the changed code as if you are new to the package:\n\n1. Can a junior developer explain what each name represents?\n2. Can an AI agent identify the main path without following deeply nested branches?\n3. Are edge cases handled by clear guard clauses or named helpers?\n4. Is the change modular without hiding important state or protocol boundaries?\n\nIf the answer is no, simplify the code before calling the task complete.\n\n### Code Style\n\nPrettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing\ncommas where configured, and always use braces for control flow.\n\nNaming conventions:\n\n| Pattern | Usage |\n| --- | --- |\n| `use*` | Hooks called in component/task scope |\n| `*$` | QRL boundary extracted by the optimizer |\n| `create*` | Factory functions |\n| `*.unit.ts(x)` | Vitest unit files |\n| `*.spec.ts(x)` | Vitest spec files |\n| `*.e2e.ts` | Playwright e2e files |\n\n### Security And Supply Chain\n\nTreat security-sensitive changes as behavior changes even when they look like config, dependency,\nor CI maintenance.\n\n#### Security Review Trigger\n\nPause for a focused security pass when a change touches:\n\n- authentication, authorization, sessions, cookies, redirects, URL parsing, filesystem paths, SSR,\n  serialization, HTML/script output, request handling, or server adapters\n- dependency versions, lockfiles, package manager settings, release scripts, publishing scripts, or\n  build tooling\n- GitHub Actions, reusable workflows, workflow permissions, tokens, secrets, cache keys, artifact\n  upload/download, or deployment credentials\n\nUse the changed diff as the starting point. Check directly supporting files when needed, but do not\nturn a small change into a repository-wide security scan unless the user asks.\n\n#### What To Check\n\n- Identify the trust boundary: attacker-controlled input, untrusted dependency code, untrusted CI\n  event data, secrets, tokens, publish credentials, or generated output.\n- Find the closest existing guard and the sink it protects. Do not claim safety from a broad\n  intuition; point to the concrete validation, escaping, permission, or isolation boundary.\n- Prefer fail-closed behavior for malformed input, unknown modes, unsupported hosts, and missing\n  config.\n- Keep secrets out of logs, snapshots, artifacts, caches, generated files, browser output, and error\n  messages.\n- When changing dependencies or build tools, check for new install scripts, binary downloads,\n  network fetches, transitive tool execution, license or provenance surprises, and lockfile drift.\n\n#### GitHub Actions\n\nWhen editing `.github/workflows/**` or action-related scripts:\n\n- Keep `permissions:` least-privilege at the workflow or job level.\n- Do not introduce `pull_request_target` for code checkout/build/test of untrusted PR content unless\n  the workflow is explicitly designed to avoid running attacker-controlled code with secrets.\n- Avoid passing secrets to forked PRs, third-party actions, shell commands that print env, or\n  generated artifacts.\n- Prefer trusted first-party actions. For new third-party actions, pin to a full commit SHA or\n  document why a moving tag is acceptable.\n- Treat cache restore keys and artifact paths as untrusted input surfaces. Avoid broad paths that can\n  poison future jobs or expose credentials.\n- Quote shell variables and avoid `eval`, curl-piped shells, and unchecked interpolation of GitHub\n  context values into shell commands.\n\n#### Verification\n\nFor security-sensitive changes, record the focused security reasoning in the final response:\n\n1. What boundary changed?\n2. What guard or invariant prevents abuse?\n3. What focused test, lint, config check, or manual inspection covered it?\n\nIf you cannot verify the security property locally, say exactly what remains unverified.\n\n### Test Driven Development\n\nUse test-driven development for behavior changes and bug fixes.\n\n#### Required Workflow\n\n1. Identify the observable behavior or invariant before editing implementation code.\n2. Add or update the closest focused test that proves the behavior.\n3. Run that test before the implementation change when feasible and confirm it fails for the\n   expected reason.\n4. Make the smallest implementation change that satisfies the test.\n5. Rerun the focused test and keep iterating until it passes.\n6. Run any broader verification required by the touched surface, such as API docs, optimizer\n   snapshots, build output, or e2e coverage.\n\n#### Test Selection\n\n- Prefer unit/spec tests next to the changed code.\n- Use optimizer fixtures and snapshots for Rust transform behavior.\n- Use e2e tests only when the behavior depends on a real browser, navigation, streaming, SSR/CSR\n  integration, adapter behavior, or fixture app wiring.\n- For serialization, hydration, streaming, or loader protocol changes, test both the writer and the\n  reader path.\n- For compatibility behavior, test both the current API path and the supported deprecated path.\n\n#### Exceptions\n\nDocs-only, rules-only, formatting-only, dependency metadata, and generated-output maintenance\nchanges do not need a failing product test first. They still need the narrowest relevant\nverification, such as formatting, Ruler dry-run, generated-output checks, or docs build checks.\n\nIf dependencies, missing generated artifacts, or local environment constraints prevent a pre-fix\ntest run, write the focused test first, record the blocker, and run the test as soon as the blocker\nis resolved.\n\n### Boundaries\n\n- Preserve user work and unrelated changes. Do not reset or revert unrelated files.\n- Keep edits scoped to the package, generated-file boundary, and verification surface implied by the\n  task.\n- Do not commit `.only` tests.\n- Do not skip tests for behavior changes; use the closest focused test first.\n\n### No Hydration Terminology\n\nNever describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is\nresumable: the server serializes application state and listeners into the HTML, and the client\nresumes execution exactly where the server left off, without re-running component code or\nrebuilding the framework state.\n\n- Do not call any Qwik mechanism \"hydration\", \"hydrating\", \"rehydration\", \"partial hydration\",\n  \"progressive hydration\", \"selective hydration\", or \"island hydration\".\n- Do not describe Qwik components, containers, or apps as \"hydrated\" or \"needing to hydrate\".\n- Use the Qwik terminilogy instead: \"javascript streaming\", \"JIT preloading\", \"resumability\", \"resume\", \"resuming\", \"serialization\", \"deserialization\", and \"lazy execution\".\n- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,\n  or hydrating the app.\n\n#### Allowed Mentions\n\nThe word \"hydration\" may appear only when explicitly contrasting Qwik with hydration-based\nframeworks, and the sentence must make clear that hydration is what other frameworks do and what\nQwik avoids. For example: \"Unlike frameworks that hydrate on the client, Qwik resumes from\nserialized state.\" Never use hydration vocabulary, even casually or by analogy, to explain what\nQwik itself does.\n\n\n\n<!-- Source: .ruler/README.md -->\n\n# Ruler Setup\n\nThis project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.\n\n## Source Of Truth\n\n```\n.ruler/\n├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)\n├── skills/        # Shared source skills propagated by Ruler\n└── ruler.toml     # Ruler agent configuration\n```\n\nUse `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the\nend of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when\nrelevant.\n\nAlways-on rules currently in `.ruler/AGENTS.md`:\n\n- `changeset-conventions`\n- `code-quality`\n- `generated-output-boundaries`\n- `guidance-source-of-truth`\n- `no-hydration-terminology`\n- `security-and-supply-chain`\n- `test-driven-development`\n\nCurrent source skills:\n\n- `qwik-core-development`\n- `qwik-router-development`\n- `qwik-optimizer-development`\n- `qwik-e2e-verification`\n- `qwik-docs-development`\n- `qwik-guidance-maintenance`\n\nThe `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they\ncan appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable\noutside the `.ruler/` tree.\n\nRoot `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees\nhave the always-on guidance immediately). The generated skill directories (`.claude/skills/`,\n`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run\n`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,\nrun `ruler apply`, and commit the regenerated root files.\n\n## AI Config Builder\n\nTreat Ruler as the source layer and the selected assistant as the output layer.\n\nWhen you are setting up or debugging an assistant-specific config:\n\n1. Identify the target assistant and Ruler agent id.\n2. Read this file and `.ruler/ruler.toml`.\n3. Research the target assistant's current native instruction, rule, skill, config, and policy\n   formats when the mapping is ambiguous.\n4. Map `.ruler` files by semantic role, not by filename.\n5. Run `ruler apply --agents <agent>`.\n6. Verify that the generated files contain the expected source guidance and skills.\n\n| Ruler source | Semantic role | Builder action |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |\n| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |\n| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |\n\nDifferent tools use words like \"rules\" for different things. A native rules file may mean\nnatural-language guidance, directory-scoped steering, MCP config, hooks, or command execution\npolicy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific\nfile.\n\n## Markdown Guidance Bundle\n\nThe AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on\nrules appended at its end) together with this `.ruler/README.md`.\n\nRuler concatenates that bundle and writes it to each selected assistant's native AI guidance file.\nUse source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these\nMarkdown files into a tool-specific directory whose format has not been verified.\n\nIf you are an AI assistant building local config for a target tool, research that tool's current\nnative guidance, skill, config, and policy formats before adding any tool-specific output. Map\n`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's\nnative AI guidance surface, skills belong in native skills if supported, and command-permission\npolicy belongs only in a separately researched policy format. For Codex, Ruler includes all\n`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not\nMarkdown guidance.\n\n### Worked Example: Codex\n\nCurrent Ruler and OpenAI Codex behavior maps this repo's sources as follows:\n\n| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |\n| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |\n| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |\n\nCodex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a\ntarget for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a\nseparate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler\nMarkdown guidance.\n\nExpected Codex check:\n\n```bash\nruler apply --agents codex\nrg -n 'Source: .ruler/AGENTS.md' AGENTS.md\nfind .codex/skills -name SKILL.md\n```\n\n## What Is Committed vs Regenerated\n\nOnly the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or\nworktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`\nso Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,\n`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill\nand note edits from appearing three times (source plus two copies) in every PR.\n\nTo change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files\nalongside your `.ruler/` change. Never hand-edit the generated files. A CI check\n(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files\ndrift from `.ruler/`.\n\n## Generate Local Assistant Files\n\nInstall Ruler if you do not already have it:\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\nOr run it without installing (the form used by fresh worktrees and CI):\n\n```bash\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\nGenerate files for the default configured agents:\n\n```bash\nruler apply\n```\n\nGenerate files for a specific assistant:\n\n```bash\nruler apply --agents claude\nruler apply --agents codex\n```\n\nGenerate files for multiple assistants:\n\n```bash\nruler apply --agents claude,codex\n```\n\n## Project And Personal Configuration\n\nUse `.ruler/` for team-shared instructions and project conventions that should travel with the repo.\n\nUse `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:\n\n```bash\nruler init --global\n```\n\nIf it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,\nkeep it in your global Ruler config.\n\n## Updating Instructions\n\nEdit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at\nthe end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for\npackage-specific or workflow-specific guidance.\n\nIf a code task proves a skill or reference stale, update that guidance as part of the same task when\nthe scope allows it.\n\nThen regenerate the local assistant files:\n\n```bash\nruler apply --agents <your-tool>\n```\n\nDo not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the\nnext time Ruler runs.\n\n## Skills\n\nAuthor shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each\nenabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those\ncopies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.\nNever hand-edit the copies — edit `.ruler/skills/` and regenerate.\n\nKeep each skill focused:\n\n- Use frontmatter with `name` and a trigger-oriented `description`.\n- Put the fast path in `SKILL.md`.\n- Move long notes into `references/` only when progressive disclosure helps.\n- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.\n- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was\n  wrong over adding broad prose here.\n","CLAUDE.md":"\n\n<!-- Source: .ruler/AGENTS.md -->\n\n# Qwik v2 agents reference, instructions and rules\n\n> [!IMPORTANT]\n> **ALWAYS RUN `ruler apply` AT THE START OF A SESSION.** The agent skills are gitignored, not\n> committed, so a fresh clone/worktree has none until you generate them (once per worktree):\n>\n> ```bash\n> pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n> ```\n\n> Canonical source for repo-wide AI coding agent rules. For contributor setup, see\n> [CONTRIBUTING.md](./CONTRIBUTING.md). For package-specific workflows, load the relevant\n> `.ruler/skills/*/SKILL.md` file.\n\n## Source Of Truth\n\n- Shared AI guidance lives in `.ruler/`.\n- Only the root `AGENTS.md` and `CLAUDE.md` are committed generated outputs; the `.claude/`/`.codex/`\n  skill copies are gitignored and regenerated locally with `ruler apply` (see Setup below).\n- Never hand-edit a generated output — edit `.ruler/` and regenerate with `ruler apply`. A CI check\n  re-runs it and fails if the committed root files drift.\n- To change assistant behavior, edit `.ruler/AGENTS.md`, `.ruler/README.md`, or `.ruler/skills/**`,\n  then regenerate with Ruler when needed.\n\n## Project Snapshot\n\nQwik is a resumable web framework. SSR serializes application and framework state into HTML, and\nthe client resumes without re-running component code. Qwik v2 is a rewrite with VNode-based\nruntime work, rewritten reactive primitives, a new serialization mechanism, and package names under\n`@qwik.dev/*`.\n\nKey concepts: resumability, QRLs, `$`-suffixed optimizer boundaries, fine-grained signals, VNodes,\nthe cursor system, and the Rust optimizer.\n\n## Monorepo Map\n\n- Base branch and release branch for v2 PRs: `main`. V1 lives on the `v1` branch.\n\n| Package | Path | Notes |\n| --- | --- | --- |\n| `@qwik.dev/core` | `packages/qwik` | Core runtime, SSR, optimizer-facing code |\n| `@qwik.dev/router` | `packages/qwik-router` | Routing, middleware, adapters, SSG |\n| `@qwik.dev/react` | `packages/qwik-react` | React integration |\n| `@qwik.dev/dom` | `packages/qwik-dom` | Server-side DOM implementation |\n| `@qwik.dev/qwik-vite` | `packages/qwik-vite` | `vite-plugin-qwik`, private, bundled into `@qwik.dev/core/optimizer` |\n| `@qwik.dev/optimizer` | `packages/optimizer` | Rust optimizer, WASM, NAPI bindings |\n| `eslint-plugin-qwik` | `packages/eslint-plugin-qwik` | ESLint rules |\n| `create-qwik` | `packages/create-qwik` | Project scaffolding CLI |\n| `qwik-docs` | `packages/docs` | Docs site, private package |\n| `insights` | `packages/insights` | Analytics dashboard, private package |\n\nUse v2 package names (`@qwik.dev/core`, `@qwik.dev/router`, etc.). Do not introduce v1\n`@builder.io/qwik` or `@builder.io/qwik-city` imports except when working on explicit\ncompatibility override code.\n\n## Setup And Iteration Loop\n\nThis is the canonical loop for nearly all framework work. Default to it; do not substitute broader\ncommands:\n\n### getting started\n\n```bash\npnpm i\n```\n\n```bash\n# Materialize the agent skills into .claude/.codex (gitignored) — run once per fresh clone/worktree.\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\n```bash\npnpm build.core # for a fresh start\npnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)\n```\n### Iterating\n\nPrefer focused commands and builds over repo-wide commands and builds.\n\n```bash\n# Fast dev build — required once before any tests can run, and again after framework\n# source changes when the verification consumes build output (all e2e suites do)\npnpm build.core.dev\n\n# Closest focused unit/spec test\npnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx\n\n# Focused e2e test\npnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts\n```\n\n`build.core.dev` also re-emits fresh Qwik and Router `.d.ts` incrementally (via `tscDevDts` + re-export shims), so editing a public signature no longer leaves stale types — `build.watch` skips the type pass to stay instant.\n\nFor Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.\n\nRe-run `pnpm build.full` when you are touching the optimizer rust code.\n\n### When making a PR\n\n```bash\n# for type-level verification when no focused test covers the change\npnpm tsc.check\n\n# update the API\npnpm api.update\n\n# Verify the build passes\npnpm build.core\n\n# Verify unit tests pass\npnpm test.unit\n\n# Verify the E2Es pass\npnpm test.e2e.chromium\n\n# In case of html output change, update the ssg snapshot\npnpm test.e2e.router.ssg.update\n\n# In case of a new feature, run the test.bench\npnpm test.bench\n\n# In case of qwikloader changes\npnpm vitest packages/qwik/src/qwikloader.unit.ts -u\n```\n\nIf any of those fail, fix and push your changes.\n\n## Rules\n\nRecent Qwik v2 work by core maintainers favors small, behavior-shaped changes with regression proof.\nFollow that bias:\n\n### Guidance Freshness\n\n- If a skill or reference you used is stale, incomplete, or contradicted by current source, update\n  the `.ruler` source guidance before finishing the task unless the user explicitly restricted the\n  scope.\n- Keep new durable lessons in the most specific skill or reference that future agents are likely to\n  load. Do not add package-specific details to these always-on rules unless they affect most tasks.\n- Only add a lesson to a skill when it generalizes to future tasks. Keep single-PR specifics (one\n  module's protocol, one fix's mechanics) in the code and its tests, not in a skill.\n- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,\n  where things live, and how to verify — rather than describing how the code currently works. Omit \"don't do X\" prohibitions for anything a test already enforces; the\n  suite is the guardrail, so reserve notes for what it can't self-enforce.\n- When updating guidance, load the `qwik-guidance-maintenance` skill.\n\n### Skill Selection\n\nLoad the relevant skill before non-trivial work in that area:\n\n| Skill | Use when |\n| --- | --- |\n| `qwik-core-development` | Editing/reviewing `packages/qwik/**` core runtime code |\n| `qwik-router-development` | Editing/reviewing router runtime, buildtime, middleware, adapters, or SSG |\n| `qwik-optimizer-development` | Editing/reviewing Rust optimizer, WASM, NAPI, or optimizer-facing behavior |\n| `qwik-e2e-verification` | Creating, debugging, or running Playwright e2e suites |\n| `qwik-docs-development` | Writing/editing docs content, docs site routes, or docs LLM outputs |\n| `qwik-guidance-maintenance` | Editing `.ruler/**`, generated-output guidance, or stale skill/reference content |\n\nIf no skill fits, stay with these repo-wide rules and inspect local source before changing code.\n\nIf a skill above is not loadable, its copy has not been generated in this worktree yet — run the\n`ruler apply` step from Setup, or read the source directly at `.ruler/skills/<name>/SKILL.md`.\n\nKeep the `qwik-` prefix on committed source skill names. Ruler copies these skills into\nagent-native skill directories where they may coexist with user or plugin skills, so the prefix keeps\nthe skill list unambiguous outside the repo-local `.ruler` tree.\n\n### Changesets\n\nWhen a change affects published packages, add a changeset under `.changeset/`.\n\n- Use `patch` for bug fixes: focus on the issue rather than the solution.\n- `minor` for new features: explain the new feature.\n- `major` for API removal: may also include a new feature, but it must remove or break a public API.\n- Enforce 1 changeset per change.\n- Write the changeset summary in lowercase (e.g. `fix:`)\n- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.\n\n### Code Quality\n\n\n#### Sanity\n\n- Remember to keep your code DRY.\n- Do not leave debug logging or temporary names in the final diff.\n- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.  \n- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.\n\n#### Naming\n\n- Use names that explain the domain idea, not the implementation trick.\n- Prefer specific names over short names when the value crosses more than a few lines.\n- Name booleans as questions or states, such as `isReady`, `hasSubscribers`, or `shouldFlush`.\n- Name functions by the action they perform, such as `resolveLoaderData()` or\n  `markContainerReady()`.\n- Avoid vague names like `data`, `item`, `temp`, `handle`, `process`, or `doWork` unless the local\n  scope makes the meaning obvious.\n- Keep existing public API names unless the task is intentionally changing the API.\n\n#### Control Flow\n\n- Prefer early returns for invalid, empty, unsupported, or already-handled cases.\n- Avoid deep nesting when a guard clause can make the main path easier to read.\n- Keep the success path visible at the outer indentation level when possible.\n- Do not use clever boolean expressions when a named condition or small helper would be clearer.\n- Keep error and compatibility branches explicit so reviewers can see why they exist.\n\n#### Modularity\n\n- Keep functions focused on one responsibility.\n- Extract a helper when a block has a clear name, is reused, or hides the main path.\n- Do not extract helpers only to move complexity around; the caller should become easier to read.\n- Keep helpers close to their first use unless they are shared across files.\n- Prefer local semantic helpers over broad abstractions.\n- Keep consumer- or framework-specific carve-outs (magic values, special cases) at the boundary that\n  owns that knowledge; do not push them into a generic lower-level utility that should stay agnostic.\n\n#### Review Standard\n\nBefore finishing, read the changed code as if you are new to the package:\n\n1. Can a junior developer explain what each name represents?\n2. Can an AI agent identify the main path without following deeply nested branches?\n3. Are edge cases handled by clear guard clauses or named helpers?\n4. Is the change modular without hiding important state or protocol boundaries?\n\nIf the answer is no, simplify the code before calling the task complete.\n\n### Code Style\n\nPrettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing\ncommas where configured, and always use braces for control flow.\n\nNaming conventions:\n\n| Pattern | Usage |\n| --- | --- |\n| `use*` | Hooks called in component/task scope |\n| `*$` | QRL boundary extracted by the optimizer |\n| `create*` | Factory functions |\n| `*.unit.ts(x)` | Vitest unit files |\n| `*.spec.ts(x)` | Vitest spec files |\n| `*.e2e.ts` | Playwright e2e files |\n\n### Security And Supply Chain\n\nTreat security-sensitive changes as behavior changes even when they look like config, dependency,\nor CI maintenance.\n\n#### Security Review Trigger\n\nPause for a focused security pass when a change touches:\n\n- authentication, authorization, sessions, cookies, redirects, URL parsing, filesystem paths, SSR,\n  serialization, HTML/script output, request handling, or server adapters\n- dependency versions, lockfiles, package manager settings, release scripts, publishing scripts, or\n  build tooling\n- GitHub Actions, reusable workflows, workflow permissions, tokens, secrets, cache keys, artifact\n  upload/download, or deployment credentials\n\nUse the changed diff as the starting point. Check directly supporting files when needed, but do not\nturn a small change into a repository-wide security scan unless the user asks.\n\n#### What To Check\n\n- Identify the trust boundary: attacker-controlled input, untrusted dependency code, untrusted CI\n  event data, secrets, tokens, publish credentials, or generated output.\n- Find the closest existing guard and the sink it protects. Do not claim safety from a broad\n  intuition; point to the concrete validation, escaping, permission, or isolation boundary.\n- Prefer fail-closed behavior for malformed input, unknown modes, unsupported hosts, and missing\n  config.\n- Keep secrets out of logs, snapshots, artifacts, caches, generated files, browser output, and error\n  messages.\n- When changing dependencies or build tools, check for new install scripts, binary downloads,\n  network fetches, transitive tool execution, license or provenance surprises, and lockfile drift.\n\n#### GitHub Actions\n\nWhen editing `.github/workflows/**` or action-related scripts:\n\n- Keep `permissions:` least-privilege at the workflow or job level.\n- Do not introduce `pull_request_target` for code checkout/build/test of untrusted PR content unless\n  the workflow is explicitly designed to avoid running attacker-controlled code with secrets.\n- Avoid passing secrets to forked PRs, third-party actions, shell commands that print env, or\n  generated artifacts.\n- Prefer trusted first-party actions. For new third-party actions, pin to a full commit SHA or\n  document why a moving tag is acceptable.\n- Treat cache restore keys and artifact paths as untrusted input surfaces. Avoid broad paths that can\n  poison future jobs or expose credentials.\n- Quote shell variables and avoid `eval`, curl-piped shells, and unchecked interpolation of GitHub\n  context values into shell commands.\n\n#### Verification\n\nFor security-sensitive changes, record the focused security reasoning in the final response:\n\n1. What boundary changed?\n2. What guard or invariant prevents abuse?\n3. What focused test, lint, config check, or manual inspection covered it?\n\nIf you cannot verify the security property locally, say exactly what remains unverified.\n\n### Test Driven Development\n\nUse test-driven development for behavior changes and bug fixes.\n\n#### Required Workflow\n\n1. Identify the observable behavior or invariant before editing implementation code.\n2. Add or update the closest focused test that proves the behavior.\n3. Run that test before the implementation change when feasible and confirm it fails for the\n   expected reason.\n4. Make the smallest implementation change that satisfies the test.\n5. Rerun the focused test and keep iterating until it passes.\n6. Run any broader verification required by the touched surface, such as API docs, optimizer\n   snapshots, build output, or e2e coverage.\n\n#### Test Selection\n\n- Prefer unit/spec tests next to the changed code.\n- Use optimizer fixtures and snapshots for Rust transform behavior.\n- Use e2e tests only when the behavior depends on a real browser, navigation, streaming, SSR/CSR\n  integration, adapter behavior, or fixture app wiring.\n- For serialization, hydration, streaming, or loader protocol changes, test both the writer and the\n  reader path.\n- For compatibility behavior, test both the current API path and the supported deprecated path.\n\n#### Exceptions\n\nDocs-only, rules-only, formatting-only, dependency metadata, and generated-output maintenance\nchanges do not need a failing product test first. They still need the narrowest relevant\nverification, such as formatting, Ruler dry-run, generated-output checks, or docs build checks.\n\nIf dependencies, missing generated artifacts, or local environment constraints prevent a pre-fix\ntest run, write the focused test first, record the blocker, and run the test as soon as the blocker\nis resolved.\n\n### Boundaries\n\n- Preserve user work and unrelated changes. Do not reset or revert unrelated files.\n- Keep edits scoped to the package, generated-file boundary, and verification surface implied by the\n  task.\n- Do not commit `.only` tests.\n- Do not skip tests for behavior changes; use the closest focused test first.\n\n### No Hydration Terminology\n\nNever describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is\nresumable: the server serializes application state and listeners into the HTML, and the client\nresumes execution exactly where the server left off, without re-running component code or\nrebuilding the framework state.\n\n- Do not call any Qwik mechanism \"hydration\", \"hydrating\", \"rehydration\", \"partial hydration\",\n  \"progressive hydration\", \"selective hydration\", or \"island hydration\".\n- Do not describe Qwik components, containers, or apps as \"hydrated\" or \"needing to hydrate\".\n- Use the Qwik terminilogy instead: \"javascript streaming\", \"JIT preloading\", \"resumability\", \"resume\", \"resuming\", \"serialization\", \"deserialization\", and \"lazy execution\".\n- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,\n  or hydrating the app.\n\n#### Allowed Mentions\n\nThe word \"hydration\" may appear only when explicitly contrasting Qwik with hydration-based\nframeworks, and the sentence must make clear that hydration is what other frameworks do and what\nQwik avoids. For example: \"Unlike frameworks that hydrate on the client, Qwik resumes from\nserialized state.\" Never use hydration vocabulary, even casually or by analogy, to explain what\nQwik itself does.\n\n\n\n<!-- Source: .ruler/README.md -->\n\n# Ruler Setup\n\nThis project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.\n\n## Source Of Truth\n\n```\n.ruler/\n├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)\n├── skills/        # Shared source skills propagated by Ruler\n└── ruler.toml     # Ruler agent configuration\n```\n\nUse `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the\nend of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when\nrelevant.\n\nAlways-on rules currently in `.ruler/AGENTS.md`:\n\n- `changeset-conventions`\n- `code-quality`\n- `generated-output-boundaries`\n- `guidance-source-of-truth`\n- `no-hydration-terminology`\n- `security-and-supply-chain`\n- `test-driven-development`\n\nCurrent source skills:\n\n- `qwik-core-development`\n- `qwik-router-development`\n- `qwik-optimizer-development`\n- `qwik-e2e-verification`\n- `qwik-docs-development`\n- `qwik-guidance-maintenance`\n\nThe `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they\ncan appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable\noutside the `.ruler/` tree.\n\nRoot `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees\nhave the always-on guidance immediately). The generated skill directories (`.claude/skills/`,\n`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run\n`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,\nrun `ruler apply`, and commit the regenerated root files.\n\n## AI Config Builder\n\nTreat Ruler as the source layer and the selected assistant as the output layer.\n\nWhen you are setting up or debugging an assistant-specific config:\n\n1. Identify the target assistant and Ruler agent id.\n2. Read this file and `.ruler/ruler.toml`.\n3. Research the target assistant's current native instruction, rule, skill, config, and policy\n   formats when the mapping is ambiguous.\n4. Map `.ruler` files by semantic role, not by filename.\n5. Run `ruler apply --agents <agent>`.\n6. Verify that the generated files contain the expected source guidance and skills.\n\n| Ruler source | Semantic role | Builder action |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |\n| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |\n| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |\n\nDifferent tools use words like \"rules\" for different things. A native rules file may mean\nnatural-language guidance, directory-scoped steering, MCP config, hooks, or command execution\npolicy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific\nfile.\n\n## Markdown Guidance Bundle\n\nThe AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on\nrules appended at its end) together with this `.ruler/README.md`.\n\nRuler concatenates that bundle and writes it to each selected assistant's native AI guidance file.\nUse source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these\nMarkdown files into a tool-specific directory whose format has not been verified.\n\nIf you are an AI assistant building local config for a target tool, research that tool's current\nnative guidance, skill, config, and policy formats before adding any tool-specific output. Map\n`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's\nnative AI guidance surface, skills belong in native skills if supported, and command-permission\npolicy belongs only in a separately researched policy format. For Codex, Ruler includes all\n`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not\nMarkdown guidance.\n\n### Worked Example: Codex\n\nCurrent Ruler and OpenAI Codex behavior maps this repo's sources as follows:\n\n| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |\n| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |\n| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |\n\nCodex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a\ntarget for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a\nseparate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler\nMarkdown guidance.\n\nExpected Codex check:\n\n```bash\nruler apply --agents codex\nrg -n 'Source: .ruler/AGENTS.md' AGENTS.md\nfind .codex/skills -name SKILL.md\n```\n\n## What Is Committed vs Regenerated\n\nOnly the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or\nworktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`\nso Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,\n`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill\nand note edits from appearing three times (source plus two copies) in every PR.\n\nTo change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files\nalongside your `.ruler/` change. Never hand-edit the generated files. A CI check\n(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files\ndrift from `.ruler/`.\n\n## Generate Local Assistant Files\n\nInstall Ruler if you do not already have it:\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\nOr run it without installing (the form used by fresh worktrees and CI):\n\n```bash\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\nGenerate files for the default configured agents:\n\n```bash\nruler apply\n```\n\nGenerate files for a specific assistant:\n\n```bash\nruler apply --agents claude\nruler apply --agents codex\n```\n\nGenerate files for multiple assistants:\n\n```bash\nruler apply --agents claude,codex\n```\n\n## Project And Personal Configuration\n\nUse `.ruler/` for team-shared instructions and project conventions that should travel with the repo.\n\nUse `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:\n\n```bash\nruler init --global\n```\n\nIf it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,\nkeep it in your global Ruler config.\n\n## Updating Instructions\n\nEdit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at\nthe end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for\npackage-specific or workflow-specific guidance.\n\nIf a code task proves a skill or reference stale, update that guidance as part of the same task when\nthe scope allows it.\n\nThen regenerate the local assistant files:\n\n```bash\nruler apply --agents <your-tool>\n```\n\nDo not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the\nnext time Ruler runs.\n\n## Skills\n\nAuthor shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each\nenabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those\ncopies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.\nNever hand-edit the copies — edit `.ruler/skills/` and regenerate.\n\nKeep each skill focused:\n\n- Use frontmatter with `name` and a trigger-oriented `description`.\n- Put the fast path in `SKILL.md`.\n- Move long notes into `references/` only when progressive disclosure helps.\n- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.\n- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was\n  wrong over adding broad prose here.\n"},"files":{"AGENTS.md":"<!-- Generated by Ruler -->\n\n\n<!-- Source: .ruler/AGENTS.md -->\n\n# Qwik v2 agents reference, instructions and rules\n\n> [!IMPORTANT]\n> **ALWAYS RUN `ruler apply` AT THE START OF A SESSION.** The agent skills are gitignored, not\n> committed, so a fresh clone/worktree has none until you generate them (once per worktree):\n>\n> ```bash\n> pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n> ```\n\n> Canonical source for repo-wide AI coding agent rules. For contributor setup, see\n> [CONTRIBUTING.md](./CONTRIBUTING.md). For package-specific workflows, load the relevant\n> `.ruler/skills/*/SKILL.md` file.\n\n## Source Of Truth\n\n- Shared AI guidance lives in `.ruler/`.\n- Only the root `AGENTS.md` and `CLAUDE.md` are committed generated outputs; the `.claude/`/`.codex/`\n  skill copies are gitignored and regenerated locally with `ruler apply` (see Setup below).\n- Never hand-edit a generated output — edit `.ruler/` and regenerate with `ruler apply`. A CI check\n  re-runs it and fails if the committed root files drift.\n- To change assistant behavior, edit `.ruler/AGENTS.md`, `.ruler/README.md`, or `.ruler/skills/**`,\n  then regenerate with Ruler when needed.\n\n## Project Snapshot\n\nQwik is a resumable web framework. SSR serializes application and framework state into HTML, and\nthe client resumes without re-running component code. Qwik v2 is a rewrite with VNode-based\nruntime work, rewritten reactive primitives, a new serialization mechanism, and package names under\n`@qwik.dev/*`.\n\nKey concepts: resumability, QRLs, `$`-suffixed optimizer boundaries, fine-grained signals, VNodes,\nthe cursor system, and the Rust optimizer.\n\n## Monorepo Map\n\n- Base branch and release branch for v2 PRs: `main`. V1 lives on the `v1` branch.\n\n| Package | Path | Notes |\n| --- | --- | --- |\n| `@qwik.dev/core` | `packages/qwik` | Core runtime, SSR, optimizer-facing code |\n| `@qwik.dev/router` | `packages/qwik-router` | Routing, middleware, adapters, SSG |\n| `@qwik.dev/react` | `packages/qwik-react` | React integration |\n| `@qwik.dev/dom` | `packages/qwik-dom` | Server-side DOM implementation |\n| `@qwik.dev/qwik-vite` | `packages/qwik-vite` | `vite-plugin-qwik`, private, bundled into `@qwik.dev/core/optimizer` |\n| `@qwik.dev/optimizer` | `packages/optimizer` | Rust optimizer, WASM, NAPI bindings |\n| `eslint-plugin-qwik` | `packages/eslint-plugin-qwik` | ESLint rules |\n| `create-qwik` | `packages/create-qwik` | Project scaffolding CLI |\n| `qwik-docs` | `packages/docs` | Docs site, private package |\n| `insights` | `packages/insights` | Analytics dashboard, private package |\n\nUse v2 package names (`@qwik.dev/core`, `@qwik.dev/router`, etc.). Do not introduce v1\n`@builder.io/qwik` or `@builder.io/qwik-city` imports except when working on explicit\ncompatibility override code.\n\n## Setup And Iteration Loop\n\nThis is the canonical loop for nearly all framework work. Default to it; do not substitute broader\ncommands:\n\n### getting started\n\n```bash\npnpm i\n```\n\n```bash\n# Materialize the agent skills into .claude/.codex (gitignored) — run once per fresh clone/worktree.\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\n```bash\npnpm build.core # for a fresh start\npnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)\n```\n### Iterating\n\nPrefer focused commands and builds over repo-wide commands and builds.\n\n```bash\n# Fast dev build — required once before any tests can run, and again after framework\n# source changes when the verification consumes build output (all e2e suites do)\npnpm build.core.dev\n\n# Closest focused unit/spec test\npnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx\n\n# Focused e2e test\npnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts\n```\n\n`build.core.dev` also re-emits fresh Qwik and Router `.d.ts` incrementally (via `tscDevDts` + re-export shims), so editing a public signature no longer leaves stale types — `build.watch` skips the type pass to stay instant.\n\nFor Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.\n\nRe-run `pnpm build.full` when you are touching the optimizer rust code.\n\n### When making a PR\n\n```bash\n# for type-level verification when no focused test covers the change\npnpm tsc.check\n\n# update the API\npnpm api.update\n\n# Verify the build passes\npnpm build.core\n\n# Verify unit tests pass\npnpm test.unit\n\n# Verify the E2Es pass\npnpm test.e2e.chromium\n\n# In case of html output change, update the ssg snapshot\npnpm test.e2e.router.ssg.update\n\n# In case of a new feature, run the test.bench\npnpm test.bench\n\n# In case of qwikloader changes\npnpm vitest packages/qwik/src/qwikloader.unit.ts -u\n```\n\nIf any of those fail, fix and push your changes.\n\n## Rules\n\nRecent Qwik v2 work by core maintainers favors small, behavior-shaped changes with regression proof.\nFollow that bias:\n\n### Guidance Freshness\n\n- If a skill or reference you used is stale, incomplete, or contradicted by current source, update\n  the `.ruler` source guidance before finishing the task unless the user explicitly restricted the\n  scope.\n- Keep new durable lessons in the most specific skill or reference that future agents are likely to\n  load. Do not add package-specific details to these always-on rules unless they affect most tasks.\n- Only add a lesson to a skill when it generalizes to future tasks. Keep single-PR specifics (one\n  module's protocol, one fix's mechanics) in the code and its tests, not in a skill.\n- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,\n  where things live, and how to verify — rather than describing how the code currently works. Omit \"don't do X\" prohibitions for anything a test already enforces; the\n  suite is the guardrail, so reserve notes for what it can't self-enforce.\n- When updating guidance, load the `qwik-guidance-maintenance` skill.\n\n### Skill Selection\n\nLoad the relevant skill before non-trivial work in that area:\n\n| Skill | Use when |\n| --- | --- |\n| `qwik-core-development` | Editing/reviewing `packages/qwik/**` core runtime code |\n| `qwik-router-development` | Editing/reviewing router runtime, buildtime, middleware, adapters, or SSG |\n| `qwik-optimizer-development` | Editing/reviewing Rust optimizer, WASM, NAPI, or optimizer-facing behavior |\n| `qwik-e2e-verification` | Creating, debugging, or running Playwright e2e suites |\n| `qwik-docs-development` | Writing/editing docs content, docs site routes, or docs LLM outputs |\n| `qwik-guidance-maintenance` | Editing `.ruler/**`, generated-output guidance, or stale skill/reference content |\n\nIf no skill fits, stay with these repo-wide rules and inspect local source before changing code.\n\nIf a skill above is not loadable, its copy has not been generated in this worktree yet — run the\n`ruler apply` step from Setup, or read the source directly at `.ruler/skills/<name>/SKILL.md`.\n\nKeep the `qwik-` prefix on committed source skill names. Ruler copies these skills into\nagent-native skill directories where they may coexist with user or plugin skills, so the prefix keeps\nthe skill list unambiguous outside the repo-local `.ruler` tree.\n\n### Changesets\n\nWhen a change affects published packages, add a changeset under `.changeset/`.\n\n- Use `patch` for bug fixes: focus on the issue rather than the solution.\n- `minor` for new features: explain the new feature.\n- `major` for API removal: may also include a new feature, but it must remove or break a public API.\n- Enforce 1 changeset per change.\n- Write the changeset summary in lowercase (e.g. `fix:`)\n- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.\n\n### Code Quality\n\n\n#### Sanity\n\n- Remember to keep your code DRY.\n- Do not leave debug logging or temporary names in the final diff.\n- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.  \n- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.\n\n#### Naming\n\n- Use names that explain the domain idea, not the implementation trick.\n- Prefer specific names over short names when the value crosses more than a few lines.\n- Name booleans as questions or states, such as `isReady`, `hasSubscribers`, or `shouldFlush`.\n- Name functions by the action they perform, such as `resolveLoaderData()` or\n  `markContainerReady()`.\n- Avoid vague names like `data`, `item`, `temp`, `handle`, `process`, or `doWork` unless the local\n  scope makes the meaning obvious.\n- Keep existing public API names unless the task is intentionally changing the API.\n\n#### Control Flow\n\n- Prefer early returns for invalid, empty, unsupported, or already-handled cases.\n- Avoid deep nesting when a guard clause can make the main path easier to read.\n- Keep the success path visible at the outer indentation level when possible.\n- Do not use clever boolean expressions when a named condition or small helper would be clearer.\n- Keep error and compatibility branches explicit so reviewers can see why they exist.\n\n#### Modularity\n\n- Keep functions focused on one responsibility.\n- Extract a helper when a block has a clear name, is reused, or hides the main path.\n- Do not extract helpers only to move complexity around; the caller should become easier to read.\n- Keep helpers close to their first use unless they are shared across files.\n- Prefer local semantic helpers over broad abstractions.\n- Keep consumer- or framework-specific carve-outs (magic values, special cases) at the boundary that\n  owns that knowledge; do not push them into a generic lower-level utility that should stay agnostic.\n\n#### Review Standard\n\nBefore finishing, read the changed code as if you are new to the package:\n\n1. Can a junior developer explain what each name represents?\n2. Can an AI agent identify the main path without following deeply nested branches?\n3. Are edge cases handled by clear guard clauses or named helpers?\n4. Is the change modular without hiding important state or protocol boundaries?\n\nIf the answer is no, simplify the code before calling the task complete.\n\n### Code Style\n\nPrettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing\ncommas where configured, and always use braces for control flow.\n\nNaming conventions:\n\n| Pattern | Usage |\n| --- | --- |\n| `use*` | Hooks called in component/task scope |\n| `*$` | QRL boundary extracted by the optimizer |\n| `create*` | Factory functions |\n| `*.unit.ts(x)` | Vitest unit files |\n| `*.spec.ts(x)` | Vitest spec files |\n| `*.e2e.ts` | Playwright e2e files |\n\n### Security And Supply Chain\n\nTreat security-sensitive changes as behavior changes even when they look like config, dependency,\nor CI maintenance.\n\n#### Security Review Trigger\n\nPause for a focused security pass when a change touches:\n\n- authentication, authorization, sessions, cookies, redirects, URL parsing, filesystem paths, SSR,\n  serialization, HTML/script output, request handling, or server adapters\n- dependency versions, lockfiles, package manager settings, release scripts, publishing scripts, or\n  build tooling\n- GitHub Actions, reusable workflows, workflow permissions, tokens, secrets, cache keys, artifact\n  upload/download, or deployment credentials\n\nUse the changed diff as the starting point. Check directly supporting files when needed, but do not\nturn a small change into a repository-wide security scan unless the user asks.\n\n#### What To Check\n\n- Identify the trust boundary: attacker-controlled input, untrusted dependency code, untrusted CI\n  event data, secrets, tokens, publish credentials, or generated output.\n- Find the closest existing guard and the sink it protects. Do not claim safety from a broad\n  intuition; point to the concrete validation, escaping, permission, or isolation boundary.\n- Prefer fail-closed behavior for malformed input, unknown modes, unsupported hosts, and missing\n  config.\n- Keep secrets out of logs, snapshots, artifacts, caches, generated files, browser output, and error\n  messages.\n- When changing dependencies or build tools, check for new install scripts, binary downloads,\n  network fetches, transitive tool execution, license or provenance surprises, and lockfile drift.\n\n#### GitHub Actions\n\nWhen editing `.github/workflows/**` or action-related scripts:\n\n- Keep `permissions:` least-privilege at the workflow or job level.\n- Do not introduce `pull_request_target` for code checkout/build/test of untrusted PR content unless\n  the workflow is explicitly designed to avoid running attacker-controlled code with secrets.\n- Avoid passing secrets to forked PRs, third-party actions, shell commands that print env, or\n  generated artifacts.\n- Prefer trusted first-party actions. For new third-party actions, pin to a full commit SHA or\n  document why a moving tag is acceptable.\n- Treat cache restore keys and artifact paths as untrusted input surfaces. Avoid broad paths that can\n  poison future jobs or expose credentials.\n- Quote shell variables and avoid `eval`, curl-piped shells, and unchecked interpolation of GitHub\n  context values into shell commands.\n\n#### Verification\n\nFor security-sensitive changes, record the focused security reasoning in the final response:\n\n1. What boundary changed?\n2. What guard or invariant prevents abuse?\n3. What focused test, lint, config check, or manual inspection covered it?\n\nIf you cannot verify the security property locally, say exactly what remains unverified.\n\n### Test Driven Development\n\nUse test-driven development for behavior changes and bug fixes.\n\n#### Required Workflow\n\n1. Identify the observable behavior or invariant before editing implementation code.\n2. Add or update the closest focused test that proves the behavior.\n3. Run that test before the implementation change when feasible and confirm it fails for the\n   expected reason.\n4. Make the smallest implementation change that satisfies the test.\n5. Rerun the focused test and keep iterating until it passes.\n6. Run any broader verification required by the touched surface, such as API docs, optimizer\n   snapshots, build output, or e2e coverage.\n\n#### Test Selection\n\n- Prefer unit/spec tests next to the changed code.\n- Use optimizer fixtures and snapshots for Rust transform behavior.\n- Use e2e tests only when the behavior depends on a real browser, navigation, streaming, SSR/CSR\n  integration, adapter behavior, or fixture app wiring.\n- For serialization, hydration, streaming, or loader protocol changes, test both the writer and the\n  reader path.\n- For compatibility behavior, test both the current API path and the supported deprecated path.\n\n#### Exceptions\n\nDocs-only, rules-only, formatting-only, dependency metadata, and generated-output maintenance\nchanges do not need a failing product test first. They still need the narrowest relevant\nverification, such as formatting, Ruler dry-run, generated-output checks, or docs build checks.\n\nIf dependencies, missing generated artifacts, or local environment constraints prevent a pre-fix\ntest run, write the focused test first, record the blocker, and run the test as soon as the blocker\nis resolved.\n\n### Boundaries\n\n- Preserve user work and unrelated changes. Do not reset or revert unrelated files.\n- Keep edits scoped to the package, generated-file boundary, and verification surface implied by the\n  task.\n- Do not commit `.only` tests.\n- Do not skip tests for behavior changes; use the closest focused test first.\n\n### No Hydration Terminology\n\nNever describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is\nresumable: the server serializes application state and listeners into the HTML, and the client\nresumes execution exactly where the server left off, without re-running component code or\nrebuilding the framework state.\n\n- Do not call any Qwik mechanism \"hydration\", \"hydrating\", \"rehydration\", \"partial hydration\",\n  \"progressive hydration\", \"selective hydration\", or \"island hydration\".\n- Do not describe Qwik components, containers, or apps as \"hydrated\" or \"needing to hydrate\".\n- Use the Qwik terminilogy instead: \"javascript streaming\", \"JIT preloading\", \"resumability\", \"resume\", \"resuming\", \"serialization\", \"deserialization\", and \"lazy execution\".\n- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,\n  or hydrating the app.\n\n#### Allowed Mentions\n\nThe word \"hydration\" may appear only when explicitly contrasting Qwik with hydration-based\nframeworks, and the sentence must make clear that hydration is what other frameworks do and what\nQwik avoids. For example: \"Unlike frameworks that hydrate on the client, Qwik resumes from\nserialized state.\" Never use hydration vocabulary, even casually or by analogy, to explain what\nQwik itself does.\n\n\n\n<!-- Source: .ruler/README.md -->\n\n# Ruler Setup\n\nThis project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.\n\n## Source Of Truth\n\n```\n.ruler/\n├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)\n├── skills/        # Shared source skills propagated by Ruler\n└── ruler.toml     # Ruler agent configuration\n```\n\nUse `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the\nend of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when\nrelevant.\n\nAlways-on rules currently in `.ruler/AGENTS.md`:\n\n- `changeset-conventions`\n- `code-quality`\n- `generated-output-boundaries`\n- `guidance-source-of-truth`\n- `no-hydration-terminology`\n- `security-and-supply-chain`\n- `test-driven-development`\n\nCurrent source skills:\n\n- `qwik-core-development`\n- `qwik-router-development`\n- `qwik-optimizer-development`\n- `qwik-e2e-verification`\n- `qwik-docs-development`\n- `qwik-guidance-maintenance`\n\nThe `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they\ncan appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable\noutside the `.ruler/` tree.\n\nRoot `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees\nhave the always-on guidance immediately). The generated skill directories (`.claude/skills/`,\n`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run\n`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,\nrun `ruler apply`, and commit the regenerated root files.\n\n## AI Config Builder\n\nTreat Ruler as the source layer and the selected assistant as the output layer.\n\nWhen you are setting up or debugging an assistant-specific config:\n\n1. Identify the target assistant and Ruler agent id.\n2. Read this file and `.ruler/ruler.toml`.\n3. Research the target assistant's current native instruction, rule, skill, config, and policy\n   formats when the mapping is ambiguous.\n4. Map `.ruler` files by semantic role, not by filename.\n5. Run `ruler apply --agents <agent>`.\n6. Verify that the generated files contain the expected source guidance and skills.\n\n| Ruler source | Semantic role | Builder action |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |\n| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |\n| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |\n\nDifferent tools use words like \"rules\" for different things. A native rules file may mean\nnatural-language guidance, directory-scoped steering, MCP config, hooks, or command execution\npolicy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific\nfile.\n\n## Markdown Guidance Bundle\n\nThe AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on\nrules appended at its end) together with this `.ruler/README.md`.\n\nRuler concatenates that bundle and writes it to each selected assistant's native AI guidance file.\nUse source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these\nMarkdown files into a tool-specific directory whose format has not been verified.\n\nIf you are an AI assistant building local config for a target tool, research that tool's current\nnative guidance, skill, config, and policy formats before adding any tool-specific output. Map\n`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's\nnative AI guidance surface, skills belong in native skills if supported, and command-permission\npolicy belongs only in a separately researched policy format. For Codex, Ruler includes all\n`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not\nMarkdown guidance.\n\n### Worked Example: Codex\n\nCurrent Ruler and OpenAI Codex behavior maps this repo's sources as follows:\n\n| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |\n| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |\n| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |\n\nCodex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a\ntarget for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a\nseparate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler\nMarkdown guidance.\n\nExpected Codex check:\n\n```bash\nruler apply --agents codex\nrg -n 'Source: .ruler/AGENTS.md' AGENTS.md\nfind .codex/skills -name SKILL.md\n```\n\n## What Is Committed vs Regenerated\n\nOnly the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or\nworktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`\nso Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,\n`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill\nand note edits from appearing three times (source plus two copies) in every PR.\n\nTo change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files\nalongside your `.ruler/` change. Never hand-edit the generated files. A CI check\n(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files\ndrift from `.ruler/`.\n\n## Generate Local Assistant Files\n\nInstall Ruler if you do not already have it:\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\nOr run it without installing (the form used by fresh worktrees and CI):\n\n```bash\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\nGenerate files for the default configured agents:\n\n```bash\nruler apply\n```\n\nGenerate files for a specific assistant:\n\n```bash\nruler apply --agents claude\nruler apply --agents codex\n```\n\nGenerate files for multiple assistants:\n\n```bash\nruler apply --agents claude,codex\n```\n\n## Project And Personal Configuration\n\nUse `.ruler/` for team-shared instructions and project conventions that should travel with the repo.\n\nUse `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:\n\n```bash\nruler init --global\n```\n\nIf it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,\nkeep it in your global Ruler config.\n\n## Updating Instructions\n\nEdit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at\nthe end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for\npackage-specific or workflow-specific guidance.\n\nIf a code task proves a skill or reference stale, update that guidance as part of the same task when\nthe scope allows it.\n\nThen regenerate the local assistant files:\n\n```bash\nruler apply --agents <your-tool>\n```\n\nDo not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the\nnext time Ruler runs.\n\n## Skills\n\nAuthor shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each\nenabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those\ncopies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.\nNever hand-edit the copies — edit `.ruler/skills/` and regenerate.\n\nKeep each skill focused:\n\n- Use frontmatter with `name` and a trigger-oriented `description`.\n- Put the fast path in `SKILL.md`.\n- Move long notes into `references/` only when progressive disclosure helps.\n- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.\n- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was\n  wrong over adding broad prose here.\n","CLAUDE.md":"\n\n<!-- Source: .ruler/AGENTS.md -->\n\n# Qwik v2 agents reference, instructions and rules\n\n> [!IMPORTANT]\n> **ALWAYS RUN `ruler apply` AT THE START OF A SESSION.** The agent skills are gitignored, not\n> committed, so a fresh clone/worktree has none until you generate them (once per worktree):\n>\n> ```bash\n> pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n> ```\n\n> Canonical source for repo-wide AI coding agent rules. For contributor setup, see\n> [CONTRIBUTING.md](./CONTRIBUTING.md). For package-specific workflows, load the relevant\n> `.ruler/skills/*/SKILL.md` file.\n\n## Source Of Truth\n\n- Shared AI guidance lives in `.ruler/`.\n- Only the root `AGENTS.md` and `CLAUDE.md` are committed generated outputs; the `.claude/`/`.codex/`\n  skill copies are gitignored and regenerated locally with `ruler apply` (see Setup below).\n- Never hand-edit a generated output — edit `.ruler/` and regenerate with `ruler apply`. A CI check\n  re-runs it and fails if the committed root files drift.\n- To change assistant behavior, edit `.ruler/AGENTS.md`, `.ruler/README.md`, or `.ruler/skills/**`,\n  then regenerate with Ruler when needed.\n\n## Project Snapshot\n\nQwik is a resumable web framework. SSR serializes application and framework state into HTML, and\nthe client resumes without re-running component code. Qwik v2 is a rewrite with VNode-based\nruntime work, rewritten reactive primitives, a new serialization mechanism, and package names under\n`@qwik.dev/*`.\n\nKey concepts: resumability, QRLs, `$`-suffixed optimizer boundaries, fine-grained signals, VNodes,\nthe cursor system, and the Rust optimizer.\n\n## Monorepo Map\n\n- Base branch and release branch for v2 PRs: `main`. V1 lives on the `v1` branch.\n\n| Package | Path | Notes |\n| --- | --- | --- |\n| `@qwik.dev/core` | `packages/qwik` | Core runtime, SSR, optimizer-facing code |\n| `@qwik.dev/router` | `packages/qwik-router` | Routing, middleware, adapters, SSG |\n| `@qwik.dev/react` | `packages/qwik-react` | React integration |\n| `@qwik.dev/dom` | `packages/qwik-dom` | Server-side DOM implementation |\n| `@qwik.dev/qwik-vite` | `packages/qwik-vite` | `vite-plugin-qwik`, private, bundled into `@qwik.dev/core/optimizer` |\n| `@qwik.dev/optimizer` | `packages/optimizer` | Rust optimizer, WASM, NAPI bindings |\n| `eslint-plugin-qwik` | `packages/eslint-plugin-qwik` | ESLint rules |\n| `create-qwik` | `packages/create-qwik` | Project scaffolding CLI |\n| `qwik-docs` | `packages/docs` | Docs site, private package |\n| `insights` | `packages/insights` | Analytics dashboard, private package |\n\nUse v2 package names (`@qwik.dev/core`, `@qwik.dev/router`, etc.). Do not introduce v1\n`@builder.io/qwik` or `@builder.io/qwik-city` imports except when working on explicit\ncompatibility override code.\n\n## Setup And Iteration Loop\n\nThis is the canonical loop for nearly all framework work. Default to it; do not substitute broader\ncommands:\n\n### getting started\n\n```bash\npnpm i\n```\n\n```bash\n# Materialize the agent skills into .claude/.codex (gitignored) — run once per fresh clone/worktree.\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\n```bash\npnpm build.core # for a fresh start\npnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)\n```\n### Iterating\n\nPrefer focused commands and builds over repo-wide commands and builds.\n\n```bash\n# Fast dev build — required once before any tests can run, and again after framework\n# source changes when the verification consumes build output (all e2e suites do)\npnpm build.core.dev\n\n# Closest focused unit/spec test\npnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx\n\n# Focused e2e test\npnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts\n```\n\n`build.core.dev` also re-emits fresh Qwik and Router `.d.ts` incrementally (via `tscDevDts` + re-export shims), so editing a public signature no longer leaves stale types — `build.watch` skips the type pass to stay instant.\n\nFor Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.\n\nRe-run `pnpm build.full` when you are touching the optimizer rust code.\n\n### When making a PR\n\n```bash\n# for type-level verification when no focused test covers the change\npnpm tsc.check\n\n# update the API\npnpm api.update\n\n# Verify the build passes\npnpm build.core\n\n# Verify unit tests pass\npnpm test.unit\n\n# Verify the E2Es pass\npnpm test.e2e.chromium\n\n# In case of html output change, update the ssg snapshot\npnpm test.e2e.router.ssg.update\n\n# In case of a new feature, run the test.bench\npnpm test.bench\n\n# In case of qwikloader changes\npnpm vitest packages/qwik/src/qwikloader.unit.ts -u\n```\n\nIf any of those fail, fix and push your changes.\n\n## Rules\n\nRecent Qwik v2 work by core maintainers favors small, behavior-shaped changes with regression proof.\nFollow that bias:\n\n### Guidance Freshness\n\n- If a skill or reference you used is stale, incomplete, or contradicted by current source, update\n  the `.ruler` source guidance before finishing the task unless the user explicitly restricted the\n  scope.\n- Keep new durable lessons in the most specific skill or reference that future agents are likely to\n  load. Do not add package-specific details to these always-on rules unless they affect most tasks.\n- Only add a lesson to a skill when it generalizes to future tasks. Keep single-PR specifics (one\n  module's protocol, one fix's mechanics) in the code and its tests, not in a skill.\n- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,\n  where things live, and how to verify — rather than describing how the code currently works. Omit \"don't do X\" prohibitions for anything a test already enforces; the\n  suite is the guardrail, so reserve notes for what it can't self-enforce.\n- When updating guidance, load the `qwik-guidance-maintenance` skill.\n\n### Skill Selection\n\nLoad the relevant skill before non-trivial work in that area:\n\n| Skill | Use when |\n| --- | --- |\n| `qwik-core-development` | Editing/reviewing `packages/qwik/**` core runtime code |\n| `qwik-router-development` | Editing/reviewing router runtime, buildtime, middleware, adapters, or SSG |\n| `qwik-optimizer-development` | Editing/reviewing Rust optimizer, WASM, NAPI, or optimizer-facing behavior |\n| `qwik-e2e-verification` | Creating, debugging, or running Playwright e2e suites |\n| `qwik-docs-development` | Writing/editing docs content, docs site routes, or docs LLM outputs |\n| `qwik-guidance-maintenance` | Editing `.ruler/**`, generated-output guidance, or stale skill/reference content |\n\nIf no skill fits, stay with these repo-wide rules and inspect local source before changing code.\n\nIf a skill above is not loadable, its copy has not been generated in this worktree yet — run the\n`ruler apply` step from Setup, or read the source directly at `.ruler/skills/<name>/SKILL.md`.\n\nKeep the `qwik-` prefix on committed source skill names. Ruler copies these skills into\nagent-native skill directories where they may coexist with user or plugin skills, so the prefix keeps\nthe skill list unambiguous outside the repo-local `.ruler` tree.\n\n### Changesets\n\nWhen a change affects published packages, add a changeset under `.changeset/`.\n\n- Use `patch` for bug fixes: focus on the issue rather than the solution.\n- `minor` for new features: explain the new feature.\n- `major` for API removal: may also include a new feature, but it must remove or break a public API.\n- Enforce 1 changeset per change.\n- Write the changeset summary in lowercase (e.g. `fix:`)\n- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.\n\n### Code Quality\n\n\n#### Sanity\n\n- Remember to keep your code DRY.\n- Do not leave debug logging or temporary names in the final diff.\n- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.  \n- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.\n\n#### Naming\n\n- Use names that explain the domain idea, not the implementation trick.\n- Prefer specific names over short names when the value crosses more than a few lines.\n- Name booleans as questions or states, such as `isReady`, `hasSubscribers`, or `shouldFlush`.\n- Name functions by the action they perform, such as `resolveLoaderData()` or\n  `markContainerReady()`.\n- Avoid vague names like `data`, `item`, `temp`, `handle`, `process`, or `doWork` unless the local\n  scope makes the meaning obvious.\n- Keep existing public API names unless the task is intentionally changing the API.\n\n#### Control Flow\n\n- Prefer early returns for invalid, empty, unsupported, or already-handled cases.\n- Avoid deep nesting when a guard clause can make the main path easier to read.\n- Keep the success path visible at the outer indentation level when possible.\n- Do not use clever boolean expressions when a named condition or small helper would be clearer.\n- Keep error and compatibility branches explicit so reviewers can see why they exist.\n\n#### Modularity\n\n- Keep functions focused on one responsibility.\n- Extract a helper when a block has a clear name, is reused, or hides the main path.\n- Do not extract helpers only to move complexity around; the caller should become easier to read.\n- Keep helpers close to their first use unless they are shared across files.\n- Prefer local semantic helpers over broad abstractions.\n- Keep consumer- or framework-specific carve-outs (magic values, special cases) at the boundary that\n  owns that knowledge; do not push them into a generic lower-level utility that should stay agnostic.\n\n#### Review Standard\n\nBefore finishing, read the changed code as if you are new to the package:\n\n1. Can a junior developer explain what each name represents?\n2. Can an AI agent identify the main path without following deeply nested branches?\n3. Are edge cases handled by clear guard clauses or named helpers?\n4. Is the change modular without hiding important state or protocol boundaries?\n\nIf the answer is no, simplify the code before calling the task complete.\n\n### Code Style\n\nPrettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing\ncommas where configured, and always use braces for control flow.\n\nNaming conventions:\n\n| Pattern | Usage |\n| --- | --- |\n| `use*` | Hooks called in component/task scope |\n| `*$` | QRL boundary extracted by the optimizer |\n| `create*` | Factory functions |\n| `*.unit.ts(x)` | Vitest unit files |\n| `*.spec.ts(x)` | Vitest spec files |\n| `*.e2e.ts` | Playwright e2e files |\n\n### Security And Supply Chain\n\nTreat security-sensitive changes as behavior changes even when they look like config, dependency,\nor CI maintenance.\n\n#### Security Review Trigger\n\nPause for a focused security pass when a change touches:\n\n- authentication, authorization, sessions, cookies, redirects, URL parsing, filesystem paths, SSR,\n  serialization, HTML/script output, request handling, or server adapters\n- dependency versions, lockfiles, package manager settings, release scripts, publishing scripts, or\n  build tooling\n- GitHub Actions, reusable workflows, workflow permissions, tokens, secrets, cache keys, artifact\n  upload/download, or deployment credentials\n\nUse the changed diff as the starting point. Check directly supporting files when needed, but do not\nturn a small change into a repository-wide security scan unless the user asks.\n\n#### What To Check\n\n- Identify the trust boundary: attacker-controlled input, untrusted dependency code, untrusted CI\n  event data, secrets, tokens, publish credentials, or generated output.\n- Find the closest existing guard and the sink it protects. Do not claim safety from a broad\n  intuition; point to the concrete validation, escaping, permission, or isolation boundary.\n- Prefer fail-closed behavior for malformed input, unknown modes, unsupported hosts, and missing\n  config.\n- Keep secrets out of logs, snapshots, artifacts, caches, generated files, browser output, and error\n  messages.\n- When changing dependencies or build tools, check for new install scripts, binary downloads,\n  network fetches, transitive tool execution, license or provenance surprises, and lockfile drift.\n\n#### GitHub Actions\n\nWhen editing `.github/workflows/**` or action-related scripts:\n\n- Keep `permissions:` least-privilege at the workflow or job level.\n- Do not introduce `pull_request_target` for code checkout/build/test of untrusted PR content unless\n  the workflow is explicitly designed to avoid running attacker-controlled code with secrets.\n- Avoid passing secrets to forked PRs, third-party actions, shell commands that print env, or\n  generated artifacts.\n- Prefer trusted first-party actions. For new third-party actions, pin to a full commit SHA or\n  document why a moving tag is acceptable.\n- Treat cache restore keys and artifact paths as untrusted input surfaces. Avoid broad paths that can\n  poison future jobs or expose credentials.\n- Quote shell variables and avoid `eval`, curl-piped shells, and unchecked interpolation of GitHub\n  context values into shell commands.\n\n#### Verification\n\nFor security-sensitive changes, record the focused security reasoning in the final response:\n\n1. What boundary changed?\n2. What guard or invariant prevents abuse?\n3. What focused test, lint, config check, or manual inspection covered it?\n\nIf you cannot verify the security property locally, say exactly what remains unverified.\n\n### Test Driven Development\n\nUse test-driven development for behavior changes and bug fixes.\n\n#### Required Workflow\n\n1. Identify the observable behavior or invariant before editing implementation code.\n2. Add or update the closest focused test that proves the behavior.\n3. Run that test before the implementation change when feasible and confirm it fails for the\n   expected reason.\n4. Make the smallest implementation change that satisfies the test.\n5. Rerun the focused test and keep iterating until it passes.\n6. Run any broader verification required by the touched surface, such as API docs, optimizer\n   snapshots, build output, or e2e coverage.\n\n#### Test Selection\n\n- Prefer unit/spec tests next to the changed code.\n- Use optimizer fixtures and snapshots for Rust transform behavior.\n- Use e2e tests only when the behavior depends on a real browser, navigation, streaming, SSR/CSR\n  integration, adapter behavior, or fixture app wiring.\n- For serialization, hydration, streaming, or loader protocol changes, test both the writer and the\n  reader path.\n- For compatibility behavior, test both the current API path and the supported deprecated path.\n\n#### Exceptions\n\nDocs-only, rules-only, formatting-only, dependency metadata, and generated-output maintenance\nchanges do not need a failing product test first. They still need the narrowest relevant\nverification, such as formatting, Ruler dry-run, generated-output checks, or docs build checks.\n\nIf dependencies, missing generated artifacts, or local environment constraints prevent a pre-fix\ntest run, write the focused test first, record the blocker, and run the test as soon as the blocker\nis resolved.\n\n### Boundaries\n\n- Preserve user work and unrelated changes. Do not reset or revert unrelated files.\n- Keep edits scoped to the package, generated-file boundary, and verification surface implied by the\n  task.\n- Do not commit `.only` tests.\n- Do not skip tests for behavior changes; use the closest focused test first.\n\n### No Hydration Terminology\n\nNever describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is\nresumable: the server serializes application state and listeners into the HTML, and the client\nresumes execution exactly where the server left off, without re-running component code or\nrebuilding the framework state.\n\n- Do not call any Qwik mechanism \"hydration\", \"hydrating\", \"rehydration\", \"partial hydration\",\n  \"progressive hydration\", \"selective hydration\", or \"island hydration\".\n- Do not describe Qwik components, containers, or apps as \"hydrated\" or \"needing to hydrate\".\n- Use the Qwik terminilogy instead: \"javascript streaming\", \"JIT preloading\", \"resumability\", \"resume\", \"resuming\", \"serialization\", \"deserialization\", and \"lazy execution\".\n- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,\n  or hydrating the app.\n\n#### Allowed Mentions\n\nThe word \"hydration\" may appear only when explicitly contrasting Qwik with hydration-based\nframeworks, and the sentence must make clear that hydration is what other frameworks do and what\nQwik avoids. For example: \"Unlike frameworks that hydrate on the client, Qwik resumes from\nserialized state.\" Never use hydration vocabulary, even casually or by analogy, to explain what\nQwik itself does.\n\n\n\n<!-- Source: .ruler/README.md -->\n\n# Ruler Setup\n\nThis project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.\n\n## Source Of Truth\n\n```\n.ruler/\n├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)\n├── skills/        # Shared source skills propagated by Ruler\n└── ruler.toml     # Ruler agent configuration\n```\n\nUse `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the\nend of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when\nrelevant.\n\nAlways-on rules currently in `.ruler/AGENTS.md`:\n\n- `changeset-conventions`\n- `code-quality`\n- `generated-output-boundaries`\n- `guidance-source-of-truth`\n- `no-hydration-terminology`\n- `security-and-supply-chain`\n- `test-driven-development`\n\nCurrent source skills:\n\n- `qwik-core-development`\n- `qwik-router-development`\n- `qwik-optimizer-development`\n- `qwik-e2e-verification`\n- `qwik-docs-development`\n- `qwik-guidance-maintenance`\n\nThe `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they\ncan appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable\noutside the `.ruler/` tree.\n\nRoot `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees\nhave the always-on guidance immediately). The generated skill directories (`.claude/skills/`,\n`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run\n`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,\nrun `ruler apply`, and commit the regenerated root files.\n\n## AI Config Builder\n\nTreat Ruler as the source layer and the selected assistant as the output layer.\n\nWhen you are setting up or debugging an assistant-specific config:\n\n1. Identify the target assistant and Ruler agent id.\n2. Read this file and `.ruler/ruler.toml`.\n3. Research the target assistant's current native instruction, rule, skill, config, and policy\n   formats when the mapping is ambiguous.\n4. Map `.ruler` files by semantic role, not by filename.\n5. Run `ruler apply --agents <agent>`.\n6. Verify that the generated files contain the expected source guidance and skills.\n\n| Ruler source | Semantic role | Builder action |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |\n| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |\n| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |\n\nDifferent tools use words like \"rules\" for different things. A native rules file may mean\nnatural-language guidance, directory-scoped steering, MCP config, hooks, or command execution\npolicy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific\nfile.\n\n## Markdown Guidance Bundle\n\nThe AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on\nrules appended at its end) together with this `.ruler/README.md`.\n\nRuler concatenates that bundle and writes it to each selected assistant's native AI guidance file.\nUse source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these\nMarkdown files into a tool-specific directory whose format has not been verified.\n\nIf you are an AI assistant building local config for a target tool, research that tool's current\nnative guidance, skill, config, and policy formats before adding any tool-specific output. Map\n`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's\nnative AI guidance surface, skills belong in native skills if supported, and command-permission\npolicy belongs only in a separately researched policy format. For Codex, Ruler includes all\n`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not\nMarkdown guidance.\n\n### Worked Example: Codex\n\nCurrent Ruler and OpenAI Codex behavior maps this repo's sources as follows:\n\n| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |\n| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |\n| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |\n\nCodex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a\ntarget for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a\nseparate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler\nMarkdown guidance.\n\nExpected Codex check:\n\n```bash\nruler apply --agents codex\nrg -n 'Source: .ruler/AGENTS.md' AGENTS.md\nfind .codex/skills -name SKILL.md\n```\n\n## What Is Committed vs Regenerated\n\nOnly the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or\nworktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`\nso Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,\n`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill\nand note edits from appearing three times (source plus two copies) in every PR.\n\nTo change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files\nalongside your `.ruler/` change. Never hand-edit the generated files. A CI check\n(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files\ndrift from `.ruler/`.\n\n## Generate Local Assistant Files\n\nInstall Ruler if you do not already have it:\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\nOr run it without installing (the form used by fresh worktrees and CI):\n\n```bash\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\nGenerate files for the default configured agents:\n\n```bash\nruler apply\n```\n\nGenerate files for a specific assistant:\n\n```bash\nruler apply --agents claude\nruler apply --agents codex\n```\n\nGenerate files for multiple assistants:\n\n```bash\nruler apply --agents claude,codex\n```\n\n## Project And Personal Configuration\n\nUse `.ruler/` for team-shared instructions and project conventions that should travel with the repo.\n\nUse `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:\n\n```bash\nruler init --global\n```\n\nIf it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,\nkeep it in your global Ruler config.\n\n## Updating Instructions\n\nEdit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at\nthe end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for\npackage-specific or workflow-specific guidance.\n\nIf a code task proves a skill or reference stale, update that guidance as part of the same task when\nthe scope allows it.\n\nThen regenerate the local assistant files:\n\n```bash\nruler apply --agents <your-tool>\n```\n\nDo not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the\nnext time Ruler runs.\n\n## Skills\n\nAuthor shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each\nenabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those\ncopies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.\nNever hand-edit the copies — edit `.ruler/skills/` and regenerate.\n\nKeep each skill focused:\n\n- Use frontmatter with `name` and a trigger-oriented `description`.\n- Put the fast path in `SKILL.md`.\n- Move long notes into `references/` only when progressive disclosure helps.\n- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.\n- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was\n  wrong over adding broad prose here.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"<!-- Generated by Ruler -->\n\n\n<!-- Source: .ruler/AGENTS.md -->\n\n# Qwik v2 agents reference, instructions and rules\n\n> [!IMPORTANT]\n> **ALWAYS RUN `ruler apply` AT THE START OF A SESSION.** The agent skills are gitignored, not\n> committed, so a fresh clone/worktree has none until you generate them (once per worktree):\n>\n> ```bash\n> pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n> ```\n\n> Canonical source for repo-wide AI coding agent rules. For contributor setup, see\n> [CONTRIBUTING.md](./CONTRIBUTING.md). For package-specific workflows, load the relevant\n> `.ruler/skills/*/SKILL.md` file.\n\n## Source Of Truth\n\n- Shared AI guidance lives in `.ruler/`.\n- Only the root `AGENTS.md` and `CLAUDE.md` are committed generated outputs; the `.claude/`/`.codex/`\n  skill copies are gitignored and regenerated locally with `ruler apply` (see Setup below).\n- Never hand-edit a generated output — edit `.ruler/` and regenerate with `ruler apply`. A CI check\n  re-runs it and fails if the committed root files drift.\n- To change assistant behavior, edit `.ruler/AGENTS.md`, `.ruler/README.md`, or `.ruler/skills/**`,\n  then regenerate with Ruler when needed.\n\n## Project Snapshot\n\nQwik is a resumable web framework. SSR serializes application and framework state into HTML, and\nthe client resumes without re-running component code. Qwik v2 is a rewrite with VNode-based\nruntime work, rewritten reactive primitives, a new serialization mechanism, and package names under\n`@qwik.dev/*`.\n\nKey concepts: resumability, QRLs, `$`-suffixed optimizer boundaries, fine-grained signals, VNodes,\nthe cursor system, and the Rust optimizer.\n\n## Monorepo Map\n\n- Base branch and release branch for v2 PRs: `main`. V1 lives on the `v1` branch.\n\n| Package | Path | Notes |\n| --- | --- | --- |\n| `@qwik.dev/core` | `packages/qwik` | Core runtime, SSR, optimizer-facing code |\n| `@qwik.dev/router` | `packages/qwik-router` | Routing, middleware, adapters, SSG |\n| `@qwik.dev/react` | `packages/qwik-react` | React integration |\n| `@qwik.dev/dom` | `packages/qwik-dom` | Server-side DOM implementation |\n| `@qwik.dev/qwik-vite` | `packages/qwik-vite` | `vite-plugin-qwik`, private, bundled into `@qwik.dev/core/optimizer` |\n| `@qwik.dev/optimizer` | `packages/optimizer` | Rust optimizer, WASM, NAPI bindings |\n| `eslint-plugin-qwik` | `packages/eslint-plugin-qwik` | ESLint rules |\n| `create-qwik` | `packages/create-qwik` | Project scaffolding CLI |\n| `qwik-docs` | `packages/docs` | Docs site, private package |\n| `insights` | `packages/insights` | Analytics dashboard, private package |\n\nUse v2 package names (`@qwik.dev/core`, `@qwik.dev/router`, etc.). Do not introduce v1\n`@builder.io/qwik` or `@builder.io/qwik-city` imports except when working on explicit\ncompatibility override code.\n\n## Setup And Iteration Loop\n\nThis is the canonical loop for nearly all framework work. Default to it; do not substitute broader\ncommands:\n\n### getting started\n\n```bash\npnpm i\n```\n\n```bash\n# Materialize the agent skills into .claude/.codex (gitignored) — run once per fresh clone/worktree.\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\n```bash\npnpm build.core # for a fresh start\npnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)\n```\n### Iterating\n\nPrefer focused commands and builds over repo-wide commands and builds.\n\n```bash\n# Fast dev build — required once before any tests can run, and again after framework\n# source changes when the verification consumes build output (all e2e suites do)\npnpm build.core.dev\n\n# Closest focused unit/spec test\npnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx\n\n# Focused e2e test\npnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts\n```\n\n`build.core.dev` also re-emits fresh Qwik and Router `.d.ts` incrementally (via `tscDevDts` + re-export shims), so editing a public signature no longer leaves stale types — `build.watch` skips the type pass to stay instant.\n\nFor Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.\n\nRe-run `pnpm build.full` when you are touching the optimizer rust code.\n\n### When making a PR\n\n```bash\n# for type-level verification when no focused test covers the change\npnpm tsc.check\n\n# update the API\npnpm api.update\n\n# Verify the build passes\npnpm build.core\n\n# Verify unit tests pass\npnpm test.unit\n\n# Verify the E2Es pass\npnpm test.e2e.chromium\n\n# In case of html output change, update the ssg snapshot\npnpm test.e2e.router.ssg.update\n\n# In case of a new feature, run the test.bench\npnpm test.bench\n\n# In case of qwikloader changes\npnpm vitest packages/qwik/src/qwikloader.unit.ts -u\n```\n\nIf any of those fail, fix and push your changes.\n\n## Rules\n\nRecent Qwik v2 work by core maintainers favors small, behavior-shaped changes with regression proof.\nFollow that bias:\n\n### Guidance Freshness\n\n- If a skill or reference you used is stale, incomplete, or contradicted by current source, update\n  the `.ruler` source guidance before finishing the task unless the user explicitly restricted the\n  scope.\n- Keep new durable lessons in the most specific skill or reference that future agents are likely to\n  load. Do not add package-specific details to these always-on rules unless they affect most tasks.\n- Only add a lesson to a skill when it generalizes to future tasks. Keep single-PR specifics (one\n  module's protocol, one fix's mechanics) in the code and its tests, not in a skill.\n- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,\n  where things live, and how to verify — rather than describing how the code currently works. Omit \"don't do X\" prohibitions for anything a test already enforces; the\n  suite is the guardrail, so reserve notes for what it can't self-enforce.\n- When updating guidance, load the `qwik-guidance-maintenance` skill.\n\n### Skill Selection\n\nLoad the relevant skill before non-trivial work in that area:\n\n| Skill | Use when |\n| --- | --- |\n| `qwik-core-development` | Editing/reviewing `packages/qwik/**` core runtime code |\n| `qwik-router-development` | Editing/reviewing router runtime, buildtime, middleware, adapters, or SSG |\n| `qwik-optimizer-development` | Editing/reviewing Rust optimizer, WASM, NAPI, or optimizer-facing behavior |\n| `qwik-e2e-verification` | Creating, debugging, or running Playwright e2e suites |\n| `qwik-docs-development` | Writing/editing docs content, docs site routes, or docs LLM outputs |\n| `qwik-guidance-maintenance` | Editing `.ruler/**`, generated-output guidance, or stale skill/reference content |\n\nIf no skill fits, stay with these repo-wide rules and inspect local source before changing code.\n\nIf a skill above is not loadable, its copy has not been generated in this worktree yet — run the\n`ruler apply` step from Setup, or read the source directly at `.ruler/skills/<name>/SKILL.md`.\n\nKeep the `qwik-` prefix on committed source skill names. Ruler copies these skills into\nagent-native skill directories where they may coexist with user or plugin skills, so the prefix keeps\nthe skill list unambiguous outside the repo-local `.ruler` tree.\n\n### Changesets\n\nWhen a change affects published packages, add a changeset under `.changeset/`.\n\n- Use `patch` for bug fixes: focus on the issue rather than the solution.\n- `minor` for new features: explain the new feature.\n- `major` for API removal: may also include a new feature, but it must remove or break a public API.\n- Enforce 1 changeset per change.\n- Write the changeset summary in lowercase (e.g. `fix:`)\n- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.\n\n### Code Quality\n\n\n#### Sanity\n\n- Remember to keep your code DRY.\n- Do not leave debug logging or temporary names in the final diff.\n- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.  \n- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.\n\n#### Naming\n\n- Use names that explain the domain idea, not the implementation trick.\n- Prefer specific names over short names when the value crosses more than a few lines.\n- Name booleans as questions or states, such as `isReady`, `hasSubscribers`, or `shouldFlush`.\n- Name functions by the action they perform, such as `resolveLoaderData()` or\n  `markContainerReady()`.\n- Avoid vague names like `data`, `item`, `temp`, `handle`, `process`, or `doWork` unless the local\n  scope makes the meaning obvious.\n- Keep existing public API names unless the task is intentionally changing the API.\n\n#### Control Flow\n\n- Prefer early returns for invalid, empty, unsupported, or already-handled cases.\n- Avoid deep nesting when a guard clause can make the main path easier to read.\n- Keep the success path visible at the outer indentation level when possible.\n- Do not use clever boolean expressions when a named condition or small helper would be clearer.\n- Keep error and compatibility branches explicit so reviewers can see why they exist.\n\n#### Modularity\n\n- Keep functions focused on one responsibility.\n- Extract a helper when a block has a clear name, is reused, or hides the main path.\n- Do not extract helpers only to move complexity around; the caller should become easier to read.\n- Keep helpers close to their first use unless they are shared across files.\n- Prefer local semantic helpers over broad abstractions.\n- Keep consumer- or framework-specific carve-outs (magic values, special cases) at the boundary that\n  owns that knowledge; do not push them into a generic lower-level utility that should stay agnostic.\n\n#### Review Standard\n\nBefore finishing, read the changed code as if you are new to the package:\n\n1. Can a junior developer explain what each name represents?\n2. Can an AI agent identify the main path without following deeply nested branches?\n3. Are edge cases handled by clear guard clauses or named helpers?\n4. Is the change modular without hiding important state or protocol boundaries?\n\nIf the answer is no, simplify the code before calling the task complete.\n\n### Code Style\n\nPrettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing\ncommas where configured, and always use braces for control flow.\n\nNaming conventions:\n\n| Pattern | Usage |\n| --- | --- |\n| `use*` | Hooks called in component/task scope |\n| `*$` | QRL boundary extracted by the optimizer |\n| `create*` | Factory functions |\n| `*.unit.ts(x)` | Vitest unit files |\n| `*.spec.ts(x)` | Vitest spec files |\n| `*.e2e.ts` | Playwright e2e files |\n\n### Security And Supply Chain\n\nTreat security-sensitive changes as behavior changes even when they look like config, dependency,\nor CI maintenance.\n\n#### Security Review Trigger\n\nPause for a focused security pass when a change touches:\n\n- authentication, authorization, sessions, cookies, redirects, URL parsing, filesystem paths, SSR,\n  serialization, HTML/script output, request handling, or server adapters\n- dependency versions, lockfiles, package manager settings, release scripts, publishing scripts, or\n  build tooling\n- GitHub Actions, reusable workflows, workflow permissions, tokens, secrets, cache keys, artifact\n  upload/download, or deployment credentials\n\nUse the changed diff as the starting point. Check directly supporting files when needed, but do not\nturn a small change into a repository-wide security scan unless the user asks.\n\n#### What To Check\n\n- Identify the trust boundary: attacker-controlled input, untrusted dependency code, untrusted CI\n  event data, secrets, tokens, publish credentials, or generated output.\n- Find the closest existing guard and the sink it protects. Do not claim safety from a broad\n  intuition; point to the concrete validation, escaping, permission, or isolation boundary.\n- Prefer fail-closed behavior for malformed input, unknown modes, unsupported hosts, and missing\n  config.\n- Keep secrets out of logs, snapshots, artifacts, caches, generated files, browser output, and error\n  messages.\n- When changing dependencies or build tools, check for new install scripts, binary downloads,\n  network fetches, transitive tool execution, license or provenance surprises, and lockfile drift.\n\n#### GitHub Actions\n\nWhen editing `.github/workflows/**` or action-related scripts:\n\n- Keep `permissions:` least-privilege at the workflow or job level.\n- Do not introduce `pull_request_target` for code checkout/build/test of untrusted PR content unless\n  the workflow is explicitly designed to avoid running attacker-controlled code with secrets.\n- Avoid passing secrets to forked PRs, third-party actions, shell commands that print env, or\n  generated artifacts.\n- Prefer trusted first-party actions. For new third-party actions, pin to a full commit SHA or\n  document why a moving tag is acceptable.\n- Treat cache restore keys and artifact paths as untrusted input surfaces. Avoid broad paths that can\n  poison future jobs or expose credentials.\n- Quote shell variables and avoid `eval`, curl-piped shells, and unchecked interpolation of GitHub\n  context values into shell commands.\n\n#### Verification\n\nFor security-sensitive changes, record the focused security reasoning in the final response:\n\n1. What boundary changed?\n2. What guard or invariant prevents abuse?\n3. What focused test, lint, config check, or manual inspection covered it?\n\nIf you cannot verify the security property locally, say exactly what remains unverified.\n\n### Test Driven Development\n\nUse test-driven development for behavior changes and bug fixes.\n\n#### Required Workflow\n\n1. Identify the observable behavior or invariant before editing implementation code.\n2. Add or update the closest focused test that proves the behavior.\n3. Run that test before the implementation change when feasible and confirm it fails for the\n   expected reason.\n4. Make the smallest implementation change that satisfies the test.\n5. Rerun the focused test and keep iterating until it passes.\n6. Run any broader verification required by the touched surface, such as API docs, optimizer\n   snapshots, build output, or e2e coverage.\n\n#### Test Selection\n\n- Prefer unit/spec tests next to the changed code.\n- Use optimizer fixtures and snapshots for Rust transform behavior.\n- Use e2e tests only when the behavior depends on a real browser, navigation, streaming, SSR/CSR\n  integration, adapter behavior, or fixture app wiring.\n- For serialization, hydration, streaming, or loader protocol changes, test both the writer and the\n  reader path.\n- For compatibility behavior, test both the current API path and the supported deprecated path.\n\n#### Exceptions\n\nDocs-only, rules-only, formatting-only, dependency metadata, and generated-output maintenance\nchanges do not need a failing product test first. They still need the narrowest relevant\nverification, such as formatting, Ruler dry-run, generated-output checks, or docs build checks.\n\nIf dependencies, missing generated artifacts, or local environment constraints prevent a pre-fix\ntest run, write the focused test first, record the blocker, and run the test as soon as the blocker\nis resolved.\n\n### Boundaries\n\n- Preserve user work and unrelated changes. Do not reset or revert unrelated files.\n- Keep edits scoped to the package, generated-file boundary, and verification surface implied by the\n  task.\n- Do not commit `.only` tests.\n- Do not skip tests for behavior changes; use the closest focused test first.\n\n### No Hydration Terminology\n\nNever describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is\nresumable: the server serializes application state and listeners into the HTML, and the client\nresumes execution exactly where the server left off, without re-running component code or\nrebuilding the framework state.\n\n- Do not call any Qwik mechanism \"hydration\", \"hydrating\", \"rehydration\", \"partial hydration\",\n  \"progressive hydration\", \"selective hydration\", or \"island hydration\".\n- Do not describe Qwik components, containers, or apps as \"hydrated\" or \"needing to hydrate\".\n- Use the Qwik terminilogy instead: \"javascript streaming\", \"JIT preloading\", \"resumability\", \"resume\", \"resuming\", \"serialization\", \"deserialization\", and \"lazy execution\".\n- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,\n  or hydrating the app.\n\n#### Allowed Mentions\n\nThe word \"hydration\" may appear only when explicitly contrasting Qwik with hydration-based\nframeworks, and the sentence must make clear that hydration is what other frameworks do and what\nQwik avoids. For example: \"Unlike frameworks that hydrate on the client, Qwik resumes from\nserialized state.\" Never use hydration vocabulary, even casually or by analogy, to explain what\nQwik itself does.\n\n\n\n<!-- Source: .ruler/README.md -->\n\n# Ruler Setup\n\nThis project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.\n\n## Source Of Truth\n\n```\n.ruler/\n├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)\n├── skills/        # Shared source skills propagated by Ruler\n└── ruler.toml     # Ruler agent configuration\n```\n\nUse `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the\nend of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when\nrelevant.\n\nAlways-on rules currently in `.ruler/AGENTS.md`:\n\n- `changeset-conventions`\n- `code-quality`\n- `generated-output-boundaries`\n- `guidance-source-of-truth`\n- `no-hydration-terminology`\n- `security-and-supply-chain`\n- `test-driven-development`\n\nCurrent source skills:\n\n- `qwik-core-development`\n- `qwik-router-development`\n- `qwik-optimizer-development`\n- `qwik-e2e-verification`\n- `qwik-docs-development`\n- `qwik-guidance-maintenance`\n\nThe `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they\ncan appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable\noutside the `.ruler/` tree.\n\nRoot `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees\nhave the always-on guidance immediately). The generated skill directories (`.claude/skills/`,\n`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run\n`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,\nrun `ruler apply`, and commit the regenerated root files.\n\n## AI Config Builder\n\nTreat Ruler as the source layer and the selected assistant as the output layer.\n\nWhen you are setting up or debugging an assistant-specific config:\n\n1. Identify the target assistant and Ruler agent id.\n2. Read this file and `.ruler/ruler.toml`.\n3. Research the target assistant's current native instruction, rule, skill, config, and policy\n   formats when the mapping is ambiguous.\n4. Map `.ruler` files by semantic role, not by filename.\n5. Run `ruler apply --agents <agent>`.\n6. Verify that the generated files contain the expected source guidance and skills.\n\n| Ruler source | Semantic role | Builder action |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |\n| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |\n| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |\n\nDifferent tools use words like \"rules\" for different things. A native rules file may mean\nnatural-language guidance, directory-scoped steering, MCP config, hooks, or command execution\npolicy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific\nfile.\n\n## Markdown Guidance Bundle\n\nThe AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on\nrules appended at its end) together with this `.ruler/README.md`.\n\nRuler concatenates that bundle and writes it to each selected assistant's native AI guidance file.\nUse source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these\nMarkdown files into a tool-specific directory whose format has not been verified.\n\nIf you are an AI assistant building local config for a target tool, research that tool's current\nnative guidance, skill, config, and policy formats before adding any tool-specific output. Map\n`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's\nnative AI guidance surface, skills belong in native skills if supported, and command-permission\npolicy belongs only in a separately researched policy format. For Codex, Ruler includes all\n`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not\nMarkdown guidance.\n\n### Worked Example: Codex\n\nCurrent Ruler and OpenAI Codex behavior maps this repo's sources as follows:\n\n| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |\n| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |\n| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |\n\nCodex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a\ntarget for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a\nseparate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler\nMarkdown guidance.\n\nExpected Codex check:\n\n```bash\nruler apply --agents codex\nrg -n 'Source: .ruler/AGENTS.md' AGENTS.md\nfind .codex/skills -name SKILL.md\n```\n\n## What Is Committed vs Regenerated\n\nOnly the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or\nworktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`\nso Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,\n`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill\nand note edits from appearing three times (source plus two copies) in every PR.\n\nTo change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files\nalongside your `.ruler/` change. Never hand-edit the generated files. A CI check\n(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files\ndrift from `.ruler/`.\n\n## Generate Local Assistant Files\n\nInstall Ruler if you do not already have it:\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\nOr run it without installing (the form used by fresh worktrees and CI):\n\n```bash\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\nGenerate files for the default configured agents:\n\n```bash\nruler apply\n```\n\nGenerate files for a specific assistant:\n\n```bash\nruler apply --agents claude\nruler apply --agents codex\n```\n\nGenerate files for multiple assistants:\n\n```bash\nruler apply --agents claude,codex\n```\n\n## Project And Personal Configuration\n\nUse `.ruler/` for team-shared instructions and project conventions that should travel with the repo.\n\nUse `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:\n\n```bash\nruler init --global\n```\n\nIf it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,\nkeep it in your global Ruler config.\n\n## Updating Instructions\n\nEdit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at\nthe end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for\npackage-specific or workflow-specific guidance.\n\nIf a code task proves a skill or reference stale, update that guidance as part of the same task when\nthe scope allows it.\n\nThen regenerate the local assistant files:\n\n```bash\nruler apply --agents <your-tool>\n```\n\nDo not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the\nnext time Ruler runs.\n\n## Skills\n\nAuthor shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each\nenabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those\ncopies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.\nNever hand-edit the copies — edit `.ruler/skills/` and regenerate.\n\nKeep each skill focused:\n\n- Use frontmatter with `name` and a trigger-oriented `description`.\n- Put the fast path in `SKILL.md`.\n- Move long notes into `references/` only when progressive disclosure helps.\n- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.\n- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was\n  wrong over adding broad prose here.\n","category":"root","tokens":6356},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"\n\n<!-- Source: .ruler/AGENTS.md -->\n\n# Qwik v2 agents reference, instructions and rules\n\n> [!IMPORTANT]\n> **ALWAYS RUN `ruler apply` AT THE START OF A SESSION.** The agent skills are gitignored, not\n> committed, so a fresh clone/worktree has none until you generate them (once per worktree):\n>\n> ```bash\n> pnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n> ```\n\n> Canonical source for repo-wide AI coding agent rules. For contributor setup, see\n> [CONTRIBUTING.md](./CONTRIBUTING.md). For package-specific workflows, load the relevant\n> `.ruler/skills/*/SKILL.md` file.\n\n## Source Of Truth\n\n- Shared AI guidance lives in `.ruler/`.\n- Only the root `AGENTS.md` and `CLAUDE.md` are committed generated outputs; the `.claude/`/`.codex/`\n  skill copies are gitignored and regenerated locally with `ruler apply` (see Setup below).\n- Never hand-edit a generated output — edit `.ruler/` and regenerate with `ruler apply`. A CI check\n  re-runs it and fails if the committed root files drift.\n- To change assistant behavior, edit `.ruler/AGENTS.md`, `.ruler/README.md`, or `.ruler/skills/**`,\n  then regenerate with Ruler when needed.\n\n## Project Snapshot\n\nQwik is a resumable web framework. SSR serializes application and framework state into HTML, and\nthe client resumes without re-running component code. Qwik v2 is a rewrite with VNode-based\nruntime work, rewritten reactive primitives, a new serialization mechanism, and package names under\n`@qwik.dev/*`.\n\nKey concepts: resumability, QRLs, `$`-suffixed optimizer boundaries, fine-grained signals, VNodes,\nthe cursor system, and the Rust optimizer.\n\n## Monorepo Map\n\n- Base branch and release branch for v2 PRs: `main`. V1 lives on the `v1` branch.\n\n| Package | Path | Notes |\n| --- | --- | --- |\n| `@qwik.dev/core` | `packages/qwik` | Core runtime, SSR, optimizer-facing code |\n| `@qwik.dev/router` | `packages/qwik-router` | Routing, middleware, adapters, SSG |\n| `@qwik.dev/react` | `packages/qwik-react` | React integration |\n| `@qwik.dev/dom` | `packages/qwik-dom` | Server-side DOM implementation |\n| `@qwik.dev/qwik-vite` | `packages/qwik-vite` | `vite-plugin-qwik`, private, bundled into `@qwik.dev/core/optimizer` |\n| `@qwik.dev/optimizer` | `packages/optimizer` | Rust optimizer, WASM, NAPI bindings |\n| `eslint-plugin-qwik` | `packages/eslint-plugin-qwik` | ESLint rules |\n| `create-qwik` | `packages/create-qwik` | Project scaffolding CLI |\n| `qwik-docs` | `packages/docs` | Docs site, private package |\n| `insights` | `packages/insights` | Analytics dashboard, private package |\n\nUse v2 package names (`@qwik.dev/core`, `@qwik.dev/router`, etc.). Do not introduce v1\n`@builder.io/qwik` or `@builder.io/qwik-city` imports except when working on explicit\ncompatibility override code.\n\n## Setup And Iteration Loop\n\nThis is the canonical loop for nearly all framework work. Default to it; do not substitute broader\ncommands:\n\n### getting started\n\n```bash\npnpm i\n```\n\n```bash\n# Materialize the agent skills into .claude/.codex (gitignored) — run once per fresh clone/worktree.\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\n```bash\npnpm build.core # for a fresh start\npnpm build.full # for a fresh start and you are working on the docs (the docs run the optimizer)\n```\n### Iterating\n\nPrefer focused commands and builds over repo-wide commands and builds.\n\n```bash\n# Fast dev build — required once before any tests can run, and again after framework\n# source changes when the verification consumes build output (all e2e suites do)\npnpm build.core.dev\n\n# Closest focused unit/spec test\npnpm vitest run packages/qwik/src/core/tests/use-task.spec.tsx\n\n# Focused e2e test\npnpm playwright test e2e/qwik-e2e/tests/events.e2e.ts --browser=chromium --config e2e/qwik-e2e/playwright.config.ts\n```\n\n`build.core.dev` also re-emits fresh Qwik and Router `.d.ts` incrementally (via `tscDevDts` + re-export shims), so editing a public signature no longer leaves stale types — `build.watch` skips the type pass to stay instant.\n\nFor Qwik e2e tests, use `--browser=chromium` with `e2e/qwik-e2e/playwright.config.ts`.\n\nRe-run `pnpm build.full` when you are touching the optimizer rust code.\n\n### When making a PR\n\n```bash\n# for type-level verification when no focused test covers the change\npnpm tsc.check\n\n# update the API\npnpm api.update\n\n# Verify the build passes\npnpm build.core\n\n# Verify unit tests pass\npnpm test.unit\n\n# Verify the E2Es pass\npnpm test.e2e.chromium\n\n# In case of html output change, update the ssg snapshot\npnpm test.e2e.router.ssg.update\n\n# In case of a new feature, run the test.bench\npnpm test.bench\n\n# In case of qwikloader changes\npnpm vitest packages/qwik/src/qwikloader.unit.ts -u\n```\n\nIf any of those fail, fix and push your changes.\n\n## Rules\n\nRecent Qwik v2 work by core maintainers favors small, behavior-shaped changes with regression proof.\nFollow that bias:\n\n### Guidance Freshness\n\n- If a skill or reference you used is stale, incomplete, or contradicted by current source, update\n  the `.ruler` source guidance before finishing the task unless the user explicitly restricted the\n  scope.\n- Keep new durable lessons in the most specific skill or reference that future agents are likely to\n  load. Do not add package-specific details to these always-on rules unless they affect most tasks.\n- Only add a lesson to a skill when it generalizes to future tasks. Keep single-PR specifics (one\n  module's protocol, one fix's mechanics) in the code and its tests, not in a skill.\n- Write those notes **prescriptively** — the invariants to keep, the traps that cause false passes,\n  where things live, and how to verify — rather than describing how the code currently works. Omit \"don't do X\" prohibitions for anything a test already enforces; the\n  suite is the guardrail, so reserve notes for what it can't self-enforce.\n- When updating guidance, load the `qwik-guidance-maintenance` skill.\n\n### Skill Selection\n\nLoad the relevant skill before non-trivial work in that area:\n\n| Skill | Use when |\n| --- | --- |\n| `qwik-core-development` | Editing/reviewing `packages/qwik/**` core runtime code |\n| `qwik-router-development` | Editing/reviewing router runtime, buildtime, middleware, adapters, or SSG |\n| `qwik-optimizer-development` | Editing/reviewing Rust optimizer, WASM, NAPI, or optimizer-facing behavior |\n| `qwik-e2e-verification` | Creating, debugging, or running Playwright e2e suites |\n| `qwik-docs-development` | Writing/editing docs content, docs site routes, or docs LLM outputs |\n| `qwik-guidance-maintenance` | Editing `.ruler/**`, generated-output guidance, or stale skill/reference content |\n\nIf no skill fits, stay with these repo-wide rules and inspect local source before changing code.\n\nIf a skill above is not loadable, its copy has not been generated in this worktree yet — run the\n`ruler apply` step from Setup, or read the source directly at `.ruler/skills/<name>/SKILL.md`.\n\nKeep the `qwik-` prefix on committed source skill names. Ruler copies these skills into\nagent-native skill directories where they may coexist with user or plugin skills, so the prefix keeps\nthe skill list unambiguous outside the repo-local `.ruler` tree.\n\n### Changesets\n\nWhen a change affects published packages, add a changeset under `.changeset/`.\n\n- Use `patch` for bug fixes: focus on the issue rather than the solution.\n- `minor` for new features: explain the new feature.\n- `major` for API removal: may also include a new feature, but it must remove or break a public API.\n- Enforce 1 changeset per change.\n- Write the changeset summary in lowercase (e.g. `fix:`)\n- 1 short sentence (10-ish words) focused on the bug fix or feature. Don't include implementation details.\n\n### Code Quality\n\n\n#### Sanity\n\n- Remember to keep your code DRY.\n- Do not leave debug logging or temporary names in the final diff.\n- Only add comments for crucial information that is not self-explanatory. Keep your comments constrained to 1 short sentence (10-ish words) maximum. Focus on explaning the why/issue rather than implementation details.  \n- Write one changeset per patch/minor/major change. Keep the changeset message constrained to 1 short sentence or 2 maximum, focused on the bug fix, feature or breaking changes. Don't explain the internals or implementation details.\n\n#### Naming\n\n- Use names that explain the domain idea, not the implementation trick.\n- Prefer specific names over short names when the value crosses more than a few lines.\n- Name booleans as questions or states, such as `isReady`, `hasSubscribers`, or `shouldFlush`.\n- Name functions by the action they perform, such as `resolveLoaderData()` or\n  `markContainerReady()`.\n- Avoid vague names like `data`, `item`, `temp`, `handle`, `process`, or `doWork` unless the local\n  scope makes the meaning obvious.\n- Keep existing public API names unless the task is intentionally changing the API.\n\n#### Control Flow\n\n- Prefer early returns for invalid, empty, unsupported, or already-handled cases.\n- Avoid deep nesting when a guard clause can make the main path easier to read.\n- Keep the success path visible at the outer indentation level when possible.\n- Do not use clever boolean expressions when a named condition or small helper would be clearer.\n- Keep error and compatibility branches explicit so reviewers can see why they exist.\n\n#### Modularity\n\n- Keep functions focused on one responsibility.\n- Extract a helper when a block has a clear name, is reused, or hides the main path.\n- Do not extract helpers only to move complexity around; the caller should become easier to read.\n- Keep helpers close to their first use unless they are shared across files.\n- Prefer local semantic helpers over broad abstractions.\n- Keep consumer- or framework-specific carve-outs (magic values, special cases) at the boundary that\n  owns that knowledge; do not push them into a generic lower-level utility that should stay agnostic.\n\n#### Review Standard\n\nBefore finishing, read the changed code as if you are new to the package:\n\n1. Can a junior developer explain what each name represents?\n2. Can an AI agent identify the main path without following deeply nested branches?\n3. Are edge cases handled by clear guard clauses or named helpers?\n4. Is the change modular without hiding important state or protocol boundaries?\n\nIf the answer is no, simplify the code before calling the task complete.\n\n### Code Style\n\nPrettier and ESLint define style. Keep semicolons, single quotes, two-space indentation, trailing\ncommas where configured, and always use braces for control flow.\n\nNaming conventions:\n\n| Pattern | Usage |\n| --- | --- |\n| `use*` | Hooks called in component/task scope |\n| `*$` | QRL boundary extracted by the optimizer |\n| `create*` | Factory functions |\n| `*.unit.ts(x)` | Vitest unit files |\n| `*.spec.ts(x)` | Vitest spec files |\n| `*.e2e.ts` | Playwright e2e files |\n\n### Security And Supply Chain\n\nTreat security-sensitive changes as behavior changes even when they look like config, dependency,\nor CI maintenance.\n\n#### Security Review Trigger\n\nPause for a focused security pass when a change touches:\n\n- authentication, authorization, sessions, cookies, redirects, URL parsing, filesystem paths, SSR,\n  serialization, HTML/script output, request handling, or server adapters\n- dependency versions, lockfiles, package manager settings, release scripts, publishing scripts, or\n  build tooling\n- GitHub Actions, reusable workflows, workflow permissions, tokens, secrets, cache keys, artifact\n  upload/download, or deployment credentials\n\nUse the changed diff as the starting point. Check directly supporting files when needed, but do not\nturn a small change into a repository-wide security scan unless the user asks.\n\n#### What To Check\n\n- Identify the trust boundary: attacker-controlled input, untrusted dependency code, untrusted CI\n  event data, secrets, tokens, publish credentials, or generated output.\n- Find the closest existing guard and the sink it protects. Do not claim safety from a broad\n  intuition; point to the concrete validation, escaping, permission, or isolation boundary.\n- Prefer fail-closed behavior for malformed input, unknown modes, unsupported hosts, and missing\n  config.\n- Keep secrets out of logs, snapshots, artifacts, caches, generated files, browser output, and error\n  messages.\n- When changing dependencies or build tools, check for new install scripts, binary downloads,\n  network fetches, transitive tool execution, license or provenance surprises, and lockfile drift.\n\n#### GitHub Actions\n\nWhen editing `.github/workflows/**` or action-related scripts:\n\n- Keep `permissions:` least-privilege at the workflow or job level.\n- Do not introduce `pull_request_target` for code checkout/build/test of untrusted PR content unless\n  the workflow is explicitly designed to avoid running attacker-controlled code with secrets.\n- Avoid passing secrets to forked PRs, third-party actions, shell commands that print env, or\n  generated artifacts.\n- Prefer trusted first-party actions. For new third-party actions, pin to a full commit SHA or\n  document why a moving tag is acceptable.\n- Treat cache restore keys and artifact paths as untrusted input surfaces. Avoid broad paths that can\n  poison future jobs or expose credentials.\n- Quote shell variables and avoid `eval`, curl-piped shells, and unchecked interpolation of GitHub\n  context values into shell commands.\n\n#### Verification\n\nFor security-sensitive changes, record the focused security reasoning in the final response:\n\n1. What boundary changed?\n2. What guard or invariant prevents abuse?\n3. What focused test, lint, config check, or manual inspection covered it?\n\nIf you cannot verify the security property locally, say exactly what remains unverified.\n\n### Test Driven Development\n\nUse test-driven development for behavior changes and bug fixes.\n\n#### Required Workflow\n\n1. Identify the observable behavior or invariant before editing implementation code.\n2. Add or update the closest focused test that proves the behavior.\n3. Run that test before the implementation change when feasible and confirm it fails for the\n   expected reason.\n4. Make the smallest implementation change that satisfies the test.\n5. Rerun the focused test and keep iterating until it passes.\n6. Run any broader verification required by the touched surface, such as API docs, optimizer\n   snapshots, build output, or e2e coverage.\n\n#### Test Selection\n\n- Prefer unit/spec tests next to the changed code.\n- Use optimizer fixtures and snapshots for Rust transform behavior.\n- Use e2e tests only when the behavior depends on a real browser, navigation, streaming, SSR/CSR\n  integration, adapter behavior, or fixture app wiring.\n- For serialization, hydration, streaming, or loader protocol changes, test both the writer and the\n  reader path.\n- For compatibility behavior, test both the current API path and the supported deprecated path.\n\n#### Exceptions\n\nDocs-only, rules-only, formatting-only, dependency metadata, and generated-output maintenance\nchanges do not need a failing product test first. They still need the narrowest relevant\nverification, such as formatting, Ruler dry-run, generated-output checks, or docs build checks.\n\nIf dependencies, missing generated artifacts, or local environment constraints prevent a pre-fix\ntest run, write the focused test first, record the blocker, and run the test as soon as the blocker\nis resolved.\n\n### Boundaries\n\n- Preserve user work and unrelated changes. Do not reset or revert unrelated files.\n- Keep edits scoped to the package, generated-file boundary, and verification surface implied by the\n  task.\n- Do not commit `.only` tests.\n- Do not skip tests for behavior changes; use the closest focused test first.\n\n### No Hydration Terminology\n\nNever describe Qwik or any part of how Qwik works as hydration. Qwik does not hydrate. Qwik is\nresumable: the server serializes application state and listeners into the HTML, and the client\nresumes execution exactly where the server left off, without re-running component code or\nrebuilding the framework state.\n\n- Do not call any Qwik mechanism \"hydration\", \"hydrating\", \"rehydration\", \"partial hydration\",\n  \"progressive hydration\", \"selective hydration\", or \"island hydration\".\n- Do not describe Qwik components, containers, or apps as \"hydrated\" or \"needing to hydrate\".\n- Use the Qwik terminilogy instead: \"javascript streaming\", \"JIT preloading\", \"resumability\", \"resume\", \"resuming\", \"serialization\", \"deserialization\", and \"lazy execution\".\n- Describe client startup as Qwik resuming from serialized state, not as Qwik booting, mounting,\n  or hydrating the app.\n\n#### Allowed Mentions\n\nThe word \"hydration\" may appear only when explicitly contrasting Qwik with hydration-based\nframeworks, and the sentence must make clear that hydration is what other frameworks do and what\nQwik avoids. For example: \"Unlike frameworks that hydrate on the client, Qwik resumes from\nserialized state.\" Never use hydration vocabulary, even casually or by analogy, to explain what\nQwik itself does.\n\n\n\n<!-- Source: .ruler/README.md -->\n\n# Ruler Setup\n\nThis project uses [Ruler](https://github.com/intellectronica/ruler) to keep AI assistant instructions in one committed source of truth.\n\n## Source Of Truth\n\n```\n.ruler/\n├── AGENTS.md      # Repo-wide guidance + always-on rules (appended at the end)\n├── skills/        # Shared source skills propagated by Ruler\n└── ruler.toml     # Ruler agent configuration\n```\n\nUse `.ruler/AGENTS.md` for always-on repository context and rules (the rules live as sections at the\nend of that file). Use `.ruler/skills/` for task-specific workflows that should be loaded only when\nrelevant.\n\nAlways-on rules currently in `.ruler/AGENTS.md`:\n\n- `changeset-conventions`\n- `code-quality`\n- `generated-output-boundaries`\n- `guidance-source-of-truth`\n- `no-hydration-terminology`\n- `security-and-supply-chain`\n- `test-driven-development`\n\nCurrent source skills:\n\n- `qwik-core-development`\n- `qwik-router-development`\n- `qwik-optimizer-development`\n- `qwik-e2e-verification`\n- `qwik-docs-development`\n- `qwik-guidance-maintenance`\n\nThe `qwik-` prefix is intentional. Ruler copies skills into assistant-native directories where they\ncan appear beside personal and plugin skills, so the prefix keeps these repo skills recognizable\noutside the `.ruler/` tree.\n\nRoot `AGENTS.md` and `CLAUDE.md` are generated by Ruler but committed (so fresh clones and worktrees\nhave the always-on guidance immediately). The generated skill directories (`.claude/skills/`,\n`.codex/skills/`) and the rest of `.claude/`/`.codex/`/`.cursor/` stay local and gitignored — run\n`ruler apply` to materialize the skills. Never edit a generated file directly — update `.ruler/`,\nrun `ruler apply`, and commit the regenerated root files.\n\n## AI Config Builder\n\nTreat Ruler as the source layer and the selected assistant as the output layer.\n\nWhen you are setting up or debugging an assistant-specific config:\n\n1. Identify the target assistant and Ruler agent id.\n2. Read this file and `.ruler/ruler.toml`.\n3. Research the target assistant's current native instruction, rule, skill, config, and policy\n   formats when the mapping is ambiguous.\n4. Map `.ruler` files by semantic role, not by filename.\n5. Run `ruler apply --agents <agent>`.\n6. Verify that the generated files contain the expected source guidance and skills.\n\n| Ruler source | Semantic role | Builder action |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Repo-wide AI guidance + always-on rules | Generate into the target assistant's primary native guidance file. |\n| `.ruler/skills/*/SKILL.md` | Task-triggered workflows | Copy to the target assistant's native skills directory when supported. |\n| `.ruler/ruler.toml` and Ruler MCP config | Agent selection, output paths, MCP/config | Generate or merge native config only where Ruler and the target assistant support it. |\n\nDifferent tools use words like \"rules\" for different things. A native rules file may mean\nnatural-language guidance, directory-scoped steering, MCP config, hooks, or command execution\npolicy. Check current docs or the installed Ruler adapter before creating or copying a tool-specific\nfile.\n\n## Markdown Guidance Bundle\n\nThe AI-agnostic Markdown guidance bundle is `.ruler/AGENTS.md` (repo-wide context plus the always-on\nrules appended at its end) together with this `.ruler/README.md`.\n\nRuler concatenates that bundle and writes it to each selected assistant's native AI guidance file.\nUse source markers in the generated file to verify inclusion. Do not bypass Ruler by copying these\nMarkdown files into a tool-specific directory whose format has not been verified.\n\nIf you are an AI assistant building local config for a target tool, research that tool's current\nnative guidance, skill, config, and policy formats before adding any tool-specific output. Map\n`.ruler` files by what they mean, not by filename: Markdown guidance belongs in the assistant's\nnative AI guidance surface, skills belong in native skills if supported, and command-permission\npolicy belongs only in a separately researched policy format. For Codex, Ruler includes all\n`.ruler` Markdown guidance in generated `AGENTS.md`; `.codex/rules/*.rules` is command policy, not\nMarkdown guidance.\n\n### Worked Example: Codex\n\nCurrent Ruler and OpenAI Codex behavior maps this repo's sources as follows:\n\n| Ruler source | Codex-native output | Verify after `ruler apply --agents codex` |\n| --- | --- | --- |\n| `.ruler/AGENTS.md` | Generated root `AGENTS.md` | `rg -n 'Source: .ruler/AGENTS.md' AGENTS.md` |\n| `.ruler/skills/*/SKILL.md` | `.codex/skills/*/SKILL.md` | `find .codex/skills -name SKILL.md` |\n| Ruler MCP config | `.codex/config.toml` when MCP config is generated | `test -f .codex/config.toml` when MCP/config is expected |\n\nCodex `.rules` files are command execution policy files that use `prefix_rule(...)`. They are not a\ntarget for `.ruler/AGENTS.md` prose guidance. If Codex command policy is needed, maintain it as a\nseparate local or team policy using OpenAI Codex's `.rules` format; do not treat it as Ruler\nMarkdown guidance.\n\nExpected Codex check:\n\n```bash\nruler apply --agents codex\nrg -n 'Source: .ruler/AGENTS.md' AGENTS.md\nfind .codex/skills -name SKILL.md\n```\n\n## What Is Committed vs Regenerated\n\nOnly the root `AGENTS.md` and `CLAUDE.md` are **committed** generated outputs, so a fresh clone or\nworktree has the always-on guidance immediately (`.ruler/ruler.toml` keeps `[gitignore] enabled = false`\nso Ruler leaves those two files tracked). The generated skill copies (`.claude/skills/`,\n`.codex/skills/`) are **gitignored** — regenerate them locally with `ruler apply`. This keeps skill\nand note edits from appearing three times (source plus two copies) in every PR.\n\nTo change guidance, edit `.ruler/`, run `ruler apply`, and commit the regenerated root files\nalongside your `.ruler/` change. Never hand-edit the generated files. A CI check\n(`.github/workflows/ruler-check.yml`) re-runs `ruler apply` and fails if the committed root files\ndrift from `.ruler/`.\n\n## Generate Local Assistant Files\n\nInstall Ruler if you do not already have it:\n\n```bash\nnpm install -g @intellectronica/ruler\n```\n\nOr run it without installing (the form used by fresh worktrees and CI):\n\n```bash\npnpm dlx @intellectronica/ruler@0.3.42 apply --no-gitignore --no-mcp\n```\n\nGenerate files for the default configured agents:\n\n```bash\nruler apply\n```\n\nGenerate files for a specific assistant:\n\n```bash\nruler apply --agents claude\nruler apply --agents codex\n```\n\nGenerate files for multiple assistants:\n\n```bash\nruler apply --agents claude,codex\n```\n\n## Project And Personal Configuration\n\nUse `.ruler/` for team-shared instructions and project conventions that should travel with the repo.\n\nUse `~/.config/ruler/` for personal preferences, local workflow shortcuts, API keys, and personal MCP servers:\n\n```bash\nruler init --global\n```\n\nIf it helps everyone working in this repo, add it to `.ruler/`. If it only helps your local setup,\nkeep it in your global Ruler config.\n\n## Updating Instructions\n\nEdit `.ruler/AGENTS.md` for repository-wide guidance and always-on rules (the rules are sections at\nthe end of that file). Edit the relevant `.ruler/skills/<skill-name>/SKILL.md` file for\npackage-specific or workflow-specific guidance.\n\nIf a code task proves a skill or reference stale, update that guidance as part of the same task when\nthe scope allows it.\n\nThen regenerate the local assistant files:\n\n```bash\nruler apply --agents <your-tool>\n```\n\nDo not update generated files like `CLAUDE.md` or `AGENTS.md` by hand. They will be overwritten the\nnext time Ruler runs.\n\n## Skills\n\nAuthor shared skills under `.ruler/skills/` (the committed source). Ruler copies them into each\nenabled agent's skill directory (`.claude/skills/` for Claude, `.codex/skills/` for Codex); those\ncopies are gitignored, so run `ruler apply` once per fresh clone or worktree to materialize them.\nNever hand-edit the copies — edit `.ruler/skills/` and regenerate.\n\nKeep each skill focused:\n\n- Use frontmatter with `name` and a trigger-oriented `description`.\n- Put the fast path in `SKILL.md`.\n- Move long notes into `references/` only when progressive disclosure helps.\n- Keep always-on policy in `.ruler/AGENTS.md`, not duplicated in every skill.\n- Keep durable maintainer lessons current. Prefer updating the specific skill/reference that was\n  wrong over adding broad prose here.\n","category":"root","tokens":6349}]}