chore: lint, ci, doc updates.

.github/workflows/ci.yml

@@ -34,6 +34,8 @@ jobs:
           path: npm-debug.log
       - name: Lint
         run: npm run lint
+      - name: Check Cycles
+        run: npm run check:cycles
       - name: Test
         run: npm test
       - name: Report Coverage

.oxlintrc.json

@@ -1,11 +1,91 @@
 {
   "$schema": "https://json.schemastore.org/oxlintrc",
-  "plugins": ["typescript", "unicorn", "oxc"],
+  "plugins": ["typescript", "unicorn", "oxc", "react", "node", "import", "vitest"],
   "env": {
     "es2022": true,
     "node": true
   },
   "globals": {
     "process": "readonly"
-  }
+  },
+  "rules": {
+    "unicorn/filename-case": [
+      "error",
+      {
+        "cases": {
+          "camelCase": true,
+          "kebabCase": true,
+          "pascalCase": true
+        }
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["**/packages/css/types.d.ts"],
+      "rules": {
+        "@typescript-eslint/triple-slash-reference": "off"
+      }
+    },
+    {
+      "files": ["packages/css/src/**/*.{ts,tsx,js,jsx}", "packages/css/src/**/*.d.ts"],
+      "rules": {
+        "unicorn/filename-case": [
+          "error",
+          {
+            "cases": { "camelCase": true }
+          }
+        ]
+      }
+    },
+    {
+      "files": ["packages/css/scripts/**/*.js"],
+      "rules": {
+        "unicorn/filename-case": [
+          "error",
+          {
+            "cases": { "kebabCase": true }
+          }
+        ]
+      }
+    },
+    {
+      "files": ["packages/css/test/**/*.ts"],
+      "rules": {
+        "unicorn/filename-case": [
+          "error",
+          {
+            "cases": { "camelCase": true }
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "packages/css/dist/**",
+        "packages/css/types-stub/**",
+        "packages/css/stable/**",
+        "packages/css/coverage/**"
+      ],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
+    },
+    {
+      "files": ["packages/css/src/loader-helpers.ts", "packages/css/src/types-stub/**"],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
+    },
+    {
+      "files": [
+        "packages/css/test/__snapshots__/**",
+        "packages/css/test/fixtures/**",
+        "packages/css/test/helpers/**"
+      ],
+      "rules": {
+        "unicorn/filename-case": "off"
+      }
+    }
+  ]
 }

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to @knighted/css
+
+Thanks for spending time on the Knighted CSS suite! This document highlights the conventions that are hardest to infer from the codebase so you can ship fixes without guesswork.
+
+## Local setup
+
+1. Use Node 22+ and npm (the repo scripts assume npm).
+2. Install dependencies from the repo root: `npm install`.
+3. Run lint and tests before sending a PR:
+   - `npm run lint` (oxlint across every package)
+   - `npm test` (delegates to each package's test runner)
+
+## File naming policy
+
+We enforce naming gradually with `unicorn/filename-case` so existing camelCase modules keep working while new code stays consistent.
+
+- **New files**: default to kebab-case (e.g., `module-info.ts`). PascalCase is reserved for files that export React-style components or top-level docs such as `README.md`.
+- **Legacy folders**: some directories (especially `packages/css/src/**`) still contain camelCase files. They remain whitelisted in `.oxlintrc.json`. When you touch one of those files, feel free to rename it to kebab-case in a dedicated commit and then tighten the ignore glob.
+- **Special cases**: directories such as `__snapshots__` and `.husky/_` intentionally keep underscores—leave those alone.
+
+## Type stub directories
+
+The CSS package ships two `types-stub` directories on purpose:
+
+- `packages/css/src/types-stub/` is the source stub checked into git. The entire repo references this file during development so editors and TypeScript builds succeed before generated selectors exist.
+- `packages/css/types-stub/` is a build artifact copied by `packages/css/scripts/copy-types-stub.js` during `npm run build`. It **must** stay in git because npm publishes from `packages/css/` directly; removing it would strip the placeholder declarations that consumers need on fresh installs.
+
+When editing the stub, always update the version under `src/types-stub/` and let the copy script mirror it.
+
+## Type entrypoint strategy
+
+`packages/css/types.d.ts` currently uses triple-slash references to pull in `loader-queries.d.ts` and the stub above. This is intentional for the entire 1.x line so downstream TypeScript consumers enjoy stable behavior. We silence the `typescript-eslint/triple-slash-reference` warning via `.oxlintrc.json`. When we design 2.0.0 we will switch to ESM-style imports and remove that override—please keep that in mind if you are touching the type entrypoint.
+
+## Pull request checklist
+
+- Follow the naming rules above for any new files.
+- Confirm `npm run lint` emits zero warnings.
+- Describe any behavioral changes in the relevant package README or docs (e.g., `docs/combined-queries.md`).
+- If you touch the type stub or generator, call it out explicitly in the PR so we can double-check publish artifacts.
+
+Happy hacking!

README.md

@@ -17,10 +17,10 @@ See the [docs/](./docs) directory for deep dives on loaders, type generation, sp
 
 ## Workspaces in this repo
 
-| Workspace             | NPM Name                                                       | What it contains                                                                                                                                                                          |
-| --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `packages/css`        | [`@knighted/css`](https://www.npmjs.com/package/@knighted/css) | The production library: graph walker, compilation pipeline, loader helpers, CLI, and docs. Published to npm and meant for real builds.                                                    |
-| `packages/playwright` | `@knighted/css-playwright-fixture`                             | The end-to-end demo + regression suite. Playwright drives Lit + React examples, hash-import workspace scenarios, and SSR checks to ensure the core package keeps working across bundlers. |
+| Workspace             | NPM Name                                                              | What it contains                                                                                                                                                                          |
+| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `packages/css`        | [`@knighted/css`](./packages/css/README.md)                           | The production library: graph walker, compilation pipeline, loader helpers, CLI, and docs. Published to npm and meant for real builds.                                                    |
+| `packages/playwright` | [`@knighted/css-playwright-fixture`](./packages/playwright/README.md) | The end-to-end demo + regression suite. Playwright drives Lit + React examples, hash-import workspace scenarios, and SSR checks to ensure the core package keeps working across bundlers. |
 
 Each workspace is a standalone npm project. Run commands from the repo root with `npm run <script> -w <workspace>` or `npm run <script> --workspaces` to fan out when needed.
 
@@ -39,7 +39,7 @@ console.log(sheet) // use during SSR, static builds, or to inline Shadow DOM sty
 
 - Need runtime imports? See [docs/loader.md](./docs/loader.md).
 - Want strong selector types? Run `npx knighted-css-generate-types` and follow [docs/type-generation.md](./docs/type-generation.md).
-- Hash-prefixed or Sass-specific specifiers? Guidance lives in [docs/hash-import-fixture.md](./docs/hash-import-fixture.md) and [docs/sass-import-aliases.md](./docs/sass-import-aliases.md).
+- Need the rundown on Node `exports`/`imports`, Sass prefixes, or custom resolver hooks? Start with [docs/resolution.md](./docs/resolution.md).
 
 ## Contributing & Support