pasika 0.1.4 → 0.1.6

package/dist/eslint/pasika/index.js

@@ -1,14 +1,17 @@
+import { filenameCaseRule } from "./rules/filename-case.js";
 import { organizationImportsRule } from "./rules/organization-imports.js";
 export const pasikaConfig = {
     files: ["src/**/*.{cjs,cts,js,jsx,mjs,mts,ts,tsx}"],
     plugins: {
         pasika: {
             rules: {
+                "filename-case": filenameCaseRule,
                 "organization-imports": organizationImportsRule,
             },
         },
     },
     rules: {
+        "pasika/filename-case": "error",
         "pasika/organization-imports": "error",
     },
 };

package/dist/eslint/pasika/rules/filename-case.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "eslint";
+export declare const filenameCaseRule: Rule.RuleModule;

package/dist/eslint/pasika/rules/filename-case.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+/**
+ * Next.js App Router routing files that are exempt from filename-case checks.
+ * https://nextjs.org/docs/app/getting-started/project-structure#routing-files
+ */
+const NEXT_ROUTING_FILES = new Set([
+    "page",
+    "layout",
+    "loading",
+    "error",
+    "not-found",
+    "route",
+    "template",
+    "default",
+    "middleware",
+    "instrumentation",
+]);
+/** Suffixes that form a compound extension with the real extension (e.g. .example.tsx, .test.ts). */
+const COMPOUND_SUFFIXES = new Set(["example", "test", "spec", "stories"]);
+/**
+ * Checks whether a string is in kebab-case.
+ * Allows lowercase letters, digits, and hyphens (but not leading/trailing/double hyphens).
+ */
+function isKebabCase(str) {
+    return /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(str);
+}
+/**
+ * Checks whether a string is in PascalCase.
+ * Starts with an uppercase letter, followed by alphanumeric characters.
+ */
+function isPascalCase(str) {
+    return /^[A-Z][A-Za-z0-9]*$/.test(str);
+}
+export const filenameCaseRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+        docs: {
+            description: "Enforce pasika filename conventions: kebab-case by default, PascalCase for smart .tsx components.",
+        },
+    },
+    create(context) {
+        const filename = context.filename;
+        if (!filename) {
+            return {};
+        }
+        // Only check files under src/
+        const normalized = filename.replace(/\\/g, "/");
+        if (!normalized.includes("/src/")) {
+            return {};
+        }
+        const ext = path.extname(filename);
+        let base = path.basename(filename, ext);
+        // Strip compound suffix (e.g. ".example", ".test", ".stories", ".spec") to get the real base name
+        const baseExt = path.extname(base);
+        if (baseExt && COMPOUND_SUFFIXES.has(baseExt.slice(1))) {
+            base = path.basename(base, baseExt);
+        }
+        // Next.js routing files are exempt
+        if (NEXT_ROUTING_FILES.has(base)) {
+            return {};
+        }
+        // .tsx components may be PascalCase (smart) or kebab-case (dumb)
+        if (ext === ".tsx") {
+            if (!(isPascalCase(base) || isKebabCase(base))) {
+                return report(context, filename, ext);
+            }
+            return {};
+        }
+        // Everything else must be kebab-case
+        if (!isKebabCase(base)) {
+            return report(context, filename, ext);
+        }
+        return {};
+    },
+};
+function report(context, filename, ext) {
+    return {
+        Program(node) {
+            const convention = ext === ".tsx"
+                ? "Component files must be PascalCase.tsx (smart) or kebab-case.tsx (dumb)."
+                : "Non-component files must use kebab-case.";
+            context.report({
+                node,
+                loc: { line: 1, column: 0 },
+                message: `Filename "${path.basename(filename)}" does not match pasika conventions. ${convention}`,
+            });
+        },
+    };
+}

package/docs/agent-conventions.md

@@ -13,6 +13,12 @@ Repo-wide engineering rules and commit hygiene for AI agents.
 - Never use `eslint-disable` directives. Fix issues properly.
 - Never commit with the `--no-verify` flag.
 
+## Browser Verification
+
+- Use `agent-browser` to verify browser behavior when a task requires it.
+- Before using `agent-browser`, run `agent-browser upgrade`.
+- Run `agent-browser --help` for available commands and `agent-browser <command> --help` for command-specific usage.
+
 ## Vulyk
 
 - Make Vulyk registry changes with Vulyk commands, not by editing generated files.

package/docs/code-organization-guide/code-organization-guide.md

@@ -2,64 +2,68 @@
 
 This guide covers how to organize code in the repository's `src/` tree — placement, extraction, and module conventions — so structure stays consistent across contributors and reviewers.
 
-For every JavaScript or TypeScript module covered by this guide, also follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md).
-
 ## How To Organize a Component
 
 Use this no matter whether you are adding a new component or extracting from existing code; the steps below apply in any case.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Pick the component's placement per the [Component Placement Rule](rules/component-placement-rule.md).
 3. Classify the component as smart or dumb per the [Smart vs Dumb Component Rule](rules/smart-vs-dumb-component-rule.md).
-4. Follow the [Native Prop Forwarding Rule](rules/native-prop-forwarding-rule.md) when a `src/shared/` component renders the same intrinsic root element in every rendered result, so its native prop contract remains available.
-5. Keep each component file to exactly one React component per the [No Mixed Concerns Rule](rules/no-mixed-concerns-rule.md).
-6. Extract interactive elements per the [Interactive Component Rule](rules/interactive-component-rule.md).
-7. Extract sole-state-owner blocks per the [Sole State Owner Rule](rules/sole-state-owner-rule.md).
-8. Extract repeated structures per the [Repeated Structure Rule](rules/repeated-structure-rule.md).
-9. Extract a group of elements when one clear component name describes it per the [Nameable Visual Concept Rule](rules/nameable-visual-concept-rule.md).
-10. For every component extracted in steps 6–9, repeat steps 2–5.
-11. Repeat steps 6–9 for an extracted component only when its JSX has an applicable trigger; stop when no new component is required.
-12. Nest a component when it gains exclusive children per the [Folder Nesting Rule](rules/folder-nesting-rule.md).
-13. Keep the component's JSX clean per the [JSX Hygiene Rule](rules/jsx-hygiene-rule.md).
+4. Keep each component file to exactly one React component per the [No Mixed Concerns Rule](rules/no-mixed-concerns-rule.md).
+5. Extract interactive elements per the [Interactive Component Rule](rules/interactive-component-rule.md).
+6. Extract sole-state-owner blocks per the [Sole State Owner Rule](rules/sole-state-owner-rule.md).
+7. Extract repeated structures per the [Repeated Structure Rule](rules/repeated-structure-rule.md).
+8. Extract a group of elements when one clear component name describes it per the [Nameable Visual Concept Rule](rules/nameable-visual-concept-rule.md).
+9. For every component extracted in steps 5–8, repeat steps 2–4.
+10. Repeat steps 5–8 for an extracted component only when one of those extraction conditions applies to its JSX; stop when no new component is required.
+11. Nest a component when it gains exclusive children per the [Folder Nesting Rule](rules/folder-nesting-rule.md).
+12. Keep the component's JSX clean per the [JSX Hygiene Rule](rules/jsx-hygiene-rule.md).
+13. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so every component module has predictable exports and import paths.
 
 ## How To Organize a Type or Schema
 
 Use this when adding or moving a type or schema.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Follow the [Types and Schemas Rule](rules/types-and-schemas-rule.md).
+3. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so the type or schema module has predictable exports and import paths.
 
 ## How To Organize a Constant
 
 Use this when adding or moving a constant.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Follow the [Constants Rule](rules/constants-rule.md).
+3. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so the constant module has predictable exports and import paths.
 
 ## How To Organize a Utility
 
 Use this when adding, extracting, or moving a pure function.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Follow the [Utilities Rule](rules/utilities-rule.md).
+3. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so the utility module has predictable exports and import paths.
 
 ## How To Organize Configuration
 
-Use this when adding or moving an application configuration object.
+Use this when adding or moving an application configuration module.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Follow the [Configuration Rule](rules/configuration-rule.md).
+3. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so the configuration module has predictable exports and import paths.
 
 ## How To Organize a Custom Hook
 
 Use this when extracting or moving a custom hook.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Follow the [Hook Extraction Rule](rules/hook-extraction-rule.md).
+3. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so the hook module has predictable exports and import paths.
 
 ## How To Organize a Locale String
 
 Use this when adding or moving user-facing text.
 
-1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to identify where the item belongs in `src/`.
 2. Follow the [Locales Rule](rules/locales-rule.md).
+3. Follow the [Exports and Imports Rule](rules/exports-and-imports-rule.md) so the locale module has predictable exports and import paths.

package/docs/code-organization-guide/references/application-architecture-reference.md

@@ -4,25 +4,72 @@ Use this reference to look up the canonical shape of the repository's `src/` tre
 
 ## Layer Model
 
-This section describes the repository's four layers, root support scope, and dependency direction. Use it to decide where a component or support file belongs and which layers it can import from.
+This section describes the repository's five layers and their dependency direction. Use it to decide where a component or support file belongs and which layers it can import from.
 
-| Layer or scope | Path                      | Permitted contents                                                                                                                                                                     | Imports from                         |
+| Layer          | Path                      | Permitted contents                                                                                                                                                                     | Imports from                         |
 | -------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `app`          | `src/app/`                | Next.js App Router framework-convention files and assets, plus styles required by routing files                                                                                        | compositions, features, shared, root |
+| `app`          | `src/app/`                | [Next.js App Router routing files](https://nextjs.org/docs/app/getting-started/project-structure#routing-files), [metadata assets](https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions), and [styles required by routing files](https://nextjs.org/docs/app/getting-started/css) | compositions, features, shared, root |
 | `compositions` | `src/compositions/`       | Components and support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`)                                                                                                  | compositions, features, shared, root |
 | `features`     | `src/features/<feature>/` | Components and support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`). `src/features/` itself holds feature folders only — never components or support folders         | same feature, shared, root           |
 | `shared`       | `src/shared/`             | Components and support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`)                                                                                                  | shared, root                         |
-| `root`         | `src/`                    | App-wide support files (`hooks/`, `types/`, `schemas/`, `constants/`, `utils/`), `locales/`, and `config/`                                                                             | root support folders; a configuration module may also import files in its own `src/config/<config-name>/` directory |
-
-Root support folders are `hooks/`, `types/`, `schemas/`, `constants/`, `utils/`, `config/`, and `locales/`.
+| `root`         | `src/`                    | App-wide support folders: `hooks/`, `types/`, `schemas/`, `constants/`, `utils/`, `config/`, and `locales/`                                                                          | root |
 
 ## Closest Common Folder (CCF)
 
-The CCF is the deepest eligible folder that contains every consumer of an item.
+The CCF determines the placement of components, hooks, types, schemas, constants, and utilities. It is the closest folder shared by the files under `src/` that use the item.
+
+```text
+src/features/payments/payment-card.tsx
+src/features/payments/payment-history.tsx
+└─ both import StatusBadge
+
+CCF: src/features/payments/
+Location: src/features/payments/status-badge.tsx
+```
+
+For components, imports from `src/app/` and configuration modules do not affect the CCF. A component used by `src/app/` and a feature therefore stays with the feature.
+
+```text
+src/app/products/page.tsx                ─┐
+src/features/products/product-card.tsx   ─┴─ imports ProductPrice
 
-- Eligible folders are a nested component directory, a feature folder, a configuration-object directory, `src/features/`, `src/compositions/`, `src/shared/`, and `src/`.
-- Support folders and `src/app/` do not determine the CCF. A consumer in a support folder counts at its enclosing eligible component, feature, composition, shared, configuration-object, or root scope. A Next.js route-file consumer counts at `src/` unless a rule explicitly excludes it. `src/features/` is a non-placeable CCF boundary; the relevant placement rule maps it to a destination.
-- A consumer is a module under `src/` that uses the item. For initial placement only, include the origin module that contains the item before extraction; omit it after extraction. Apply a rule's import exclusions before calculating the CCF, then use it for placement unless that rule states otherwise.
+CCF and location: src/features/products/product-price.tsx
+```
+
+A component with no consumers outside `src/app/` or configuration modules stays in the feature it represents or supports. When no existing feature applies, it creates a feature folder.
+
+```text
+src/app/search/page.tsx  → SearchForm  → src/features/search/search-form.tsx
+
+src/app/account/page.tsx ─┐
+src/app/orders/page.tsx  ─┴→ AccountNav → src/features/account/account-nav.tsx
+```
+
+When a component has consumers both inside and outside `src/compositions/`, only the consumers outside `src/compositions/` count. When all consumers are in `src/compositions/`, that folder counts.
+
+```text
+src/compositions/checkout.tsx             ─┐
+src/features/payments/payment-summary.tsx ─┴→ Total → src/features/payments/total.tsx
+
+src/compositions/checkout.tsx ─┐
+src/compositions/receipt.tsx  ─┴→ Total → src/compositions/total.tsx
+```
+
+A component stays at a nested component folder, feature folder, `src/compositions/`, or `src/shared/`. A CCF of `src/features/` places it in `src/shared/`.
+
+```text
+src/features/payments/payment-card.tsx ─┐
+src/features/orders/order-card.tsx     ─┴→ StatusBadge → src/shared/status-badge.tsx
+```
+
+For a support file imported by a file under `src/app/`, use the matching root support folder, such as `src/hooks/` or `src/utils/`. Otherwise, the CCF passes through a support folder to its parent folder, and the file lives in the matching support folder directly below that parent.
+
+```text
+src/app/products/page.tsx                    → useSearch    → src/hooks/use-search.ts
+src/features/payments/hooks/use-payment.ts   → formatAmount → src/features/payments/utils/format-amount.ts
+src/features/payments/payment-card.tsx       ─┐
+src/features/orders/order-card.tsx           ─┴→ formatDate → src/utils/format-date.ts
+```
 
 ## Application Structure
 
@@ -30,10 +77,7 @@ This tree shows the canonical directory layout and naming conventions for files
 
 ```
 src/
-├── app/                                 # Next.js framework-convention files, assets, and route styles
-│   ├── globals.css                        # Global stylesheet imported by the root layout
-│   ├── layout.tsx                         # Root layout
-│   └── <route>/                           # Next.js App Router routing files
+├── app/                                   # Next.js framework-convention files, assets, and route styles
 ├── compositions/                          # Components stay flat siblings by default
 │   ├── <ComponentA>.tsx                   # Smart component (PascalCase-named)
 │   ├── <component-b>.tsx                  # Dumb component (kebab-case-named)
@@ -94,13 +138,11 @@ src/
 ├── schemas/                               # App-wide validation schemas
 ├── constants/                             # App-wide constants
 ├── utils/                                 # App-wide pure functions
-├── config/                                # Configuration objects that centralize application behavior
-│   └── <config-name>/                     # One folder per configuration object
-│       ├── index.ts                       # Config object
-│       ├── hooks/                         # Config-only custom hooks
+├── config/                                # Configuration modules that centralize application behavior
+│   └── <config-name>/                     # One folder per configuration module
+│       ├── index.ts                       # Configuration-module entry point
 │       ├── types/                         # Config-only TypeScript types
 │       ├── schemas/                       # Config-only validation schemas
-│       ├── constants/                     # Config-only constants
 │       └── utils/                         # Config-only pure functions
 └── locales/                               # App-wide locale strings
     └── index.ts                           # Single locale-registration file

package/docs/code-organization-guide/rules/component-placement-rule.md

@@ -2,28 +2,12 @@
 
 Without clear placement, it is hard to tell where a component belongs and reuse can create tangled dependencies. This rule gives each component a specific place in the application structure.
 
-- A routing UI file is a Next.js App Router UI file, excluding request handlers and metadata files. A Next.js `layout.tsx` routing UI file MAY render the layout required by its route segment and `children`. Any other routing UI file MAY import root support modules and directly render one feature component, one composition, or one shared component, but MUST NOT own state, callbacks, effects, or page layout.
-- A routing UI file other than `layout.tsx` that needs state, callbacks, effects, or page layout MUST delegate that work to a component in `src/compositions/`.
-- Any other component that imports from two or more feature folders MUST live in `src/compositions/` and is, by definition, a composition.
-- A component whose only consumers are routing files and that does not import from two or more feature folders MUST live in the feature folder whose behavior it implements. A component implements a feature when it reads that feature's data or exposes that feature's actions. If it implements no feature and only one routing file imports it, it MUST introduce a new feature folder for that route; if routing files for two or more routes import it, it MUST live in `src/shared/`. This rule does not apply to Next.js routing files themselves.
-- A component with at least one consumer other than a routing file MUST live in the closest common folder (CCF) of its non-routing consumers.
-- A new component with no consumers and fewer than two feature-folder imports MUST start in the existing feature folder it belongs to, or in a new feature folder when it introduces a new feature. A new component with no feature-specific behavior or data MAY start in `src/shared/` only when it imports no feature folders; otherwise it starts in the feature it imports from.
-- Imports from routing files in `src/app/` MUST NOT count as component consumers or affect CCF calculation.
-- Imports from configuration modules MUST NOT count as component consumers or affect CCF calculation.
-- When a component is imported both inside and outside `src/compositions/`, its CCF MUST be calculated only from imports outside `src/compositions/`.
-- When a component is imported only in `src/compositions/`, its CCF MUST be calculated from those imports.
-- When a component’s CCF is `src/features/`, it MUST live in `src/shared/`.
-- When a component’s CCF is `src/`, it MUST live in `src/shared/`.
-- When a component’s CCF is a nested component directory, it MUST start flat in that directory unless the Folder Nesting Rule requires nesting.
-- When a component’s CCF is a feature folder, `src/compositions/`, or `src/shared/`, it MUST start flat in that folder unless the Folder Nesting Rule requires nesting.
+- A component that imports from two or more feature folders MUST live in `src/compositions/` and is, by definition, a composition.
+- A component with no consumers outside `src/app/` or configuration modules, and that does not import from two or more feature folders, MUST live in the feature folder it represents or supports. If no existing feature applies, it MUST introduce a new feature folder.
+- A component with at least one consumer outside `src/app/` and configuration modules MUST live in its CCF, calculated without imports from `src/app/` or configuration modules.
+- When calculating a component's CCF, consumers under `src/compositions/` MUST count only when no consumer is outside `src/compositions/`.
+- A component whose CCF is `src/features/` MUST live in `src/shared/`.
 - `src/app/` MUST contain [Next.js App Router framework-convention files and assets](https://nextjs.org/docs/app/getting-started/project-structure#routing-files), plus styles required by routing files, but MUST NOT contain ordinary components or support folders.
-- A JavaScript or TypeScript module under `src/app/` MUST NOT import modules under `src/` except from `src/compositions/`, `src/features/`, `src/shared/`, and root support folders.
-- A JavaScript or TypeScript module under `src/compositions/` MUST NOT import modules under `src/` except from `src/compositions/`, feature folders, `src/shared/`, and root support folders.
-- A JavaScript or TypeScript module in a feature folder MUST NOT import modules under `src/` except from the same feature folder, `src/shared/`, and root support folders.
-- A JavaScript or TypeScript module under `src/shared/` MUST NOT import modules under `src/` except from `src/shared/` and root support folders.
-- A JavaScript or TypeScript module in a root support folder MUST NOT import modules under `src/` except from root support folders. Any module under `src/config/<config-name>/` MAY also import files under that same configuration-object directory.
-- ESLint MUST enforce these import restrictions for JavaScript and TypeScript modules under `src/`.
-
 ## Incorrect — Cross-Feature Component Duplicated
 
 ```text
@@ -82,9 +66,9 @@ src/app/contact/
 └── page.tsx
 ```
 
-Why: the route folder contains ordinary component structure even though `src/app/` is reserved for framework routing files.
+Why: the route folder contains ordinary component structure even though `src/app/` is reserved for framework-convention files, assets, and styles.
 
-## Correct — Thin Route Imports a Page Composition
+## Correct — `src/app/` Imports a Page Composition
 
 ```text
 src/
@@ -107,7 +91,7 @@ import { locales } from "@/locales";
 
 export function ContactPageContent(): React.JSX.Element {
   return (
-    <main data-testid="contact-page-content">
+    <main>
       <header>
         <h1>{locales.contactPageTitle}</h1>
         <p>{locales.contactPageDescription}</p>
@@ -132,4 +116,4 @@ export default function Page(): React.JSX.Element {
 }
 ```
 
-Why: the routing file remains thin while the page composition provides the contact page layout and combines components from two feature folders.
+Why: `src/app/` contains the routing file while the composition provides the contact page layout and combines components from two feature folders.

package/docs/code-organization-guide/rules/configuration-rule.md

@@ -1,13 +1,13 @@
 # Configuration Rule
 
-Configuration objects centralize values that control application behavior. This rule keeps each object and the files that only support it together in `src/config/`.
+Configuration modules centralize values that control application behavior. This rule keeps each module and the files that only support it together in `src/config/`.
 
-- A configuration object is an app-wide object that selects or parameterizes application behavior. Feature options and domain values are not configuration objects.
-- All configuration objects MUST live in `src/config/`.
-- A configuration object MUST use `src/config/<config-name>/index.ts`.
-- A configuration support file is a hook, type, schema, constant, or utility used only to implement one configuration object; config-only extraction applies even with one consumer.
-- A configuration support file MUST live in its matching dedicated folder under `src/config/<config-name>/`.
-- A configuration support file remains in that configuration-object directory while every consumer is in that directory; it MUST move to its matching root support folder at the root CCF when any consumer is outside it.
+- A configuration module is an app-wide module that selects or parameterizes application behavior.
+- All configuration modules MUST live in `src/config/`.
+- A configuration module MUST be one `src/config/<config-name>/` folder with `index.ts` as its entry point.
+- A type, schema, or utility used only to implement one configuration module MUST be extracted even with one consumer.
+- An extracted configuration type, schema, or utility MUST live in its matching dedicated folder under `src/config/<config-name>/`.
+- An extracted configuration type, schema, or utility MUST move to its matching root support folder when a consumer outside its configuration module imports it.
 
 ## Incorrect — Supporting Schema Outside Its Config Folder
 
@@ -20,7 +20,7 @@ src/config/
 
 Why: the schema sits outside the `home-feed/` configuration folder.
 
-## Correct — Configuration Object with Its Supporting Schema
+## Correct — Configuration Module with Its Supporting Schema
 
 ```text
 src/config/
@@ -39,4 +39,4 @@ export const homeFeedConfig = homeFeedConfigSchema.parse({
 });
 ```
 
-Why: the configuration object and its supporting schema are grouped in the same configuration folder.
+Why: the configuration module and its supporting schema are grouped in the same configuration folder.

package/docs/code-organization-guide/rules/constants-rule.md

@@ -1,16 +1,13 @@
 # Constants Rule
 
-Duplicated constants are hard to keep in sync, while extracting every single-use value creates unnecessary files. This rule keeps reused constants in one module and leaves single-use values close to their consumer.
+Duplicated constants are hard to keep in sync, while extracting every single-use value creates unnecessary files. This rule keeps reused constants in one file and leaves single-use values close to their consumer.
 
-- A constant is an exported or reused fixed domain value; local literals and implementation values are not constants for this rule. A configuration object is not a constant for this rule.
-- Except for a constant used only to implement one configuration object, a constant MUST stay in the file that uses it until another file imports it.
-- A constant used only to implement one configuration object MUST live in that object's `constants/` folder.
+- A value MUST remain in its declaring component or file until another file imports it independently; it MUST then be extracted as a constant.
 - Extracted constants MUST live in a `constants/` folder at the closest common folder (CCF) of their consumers.
-- A `constants/index.ts` MAY define its exports directly.
-- Consumers MUST import extracted constants through the `constants/index.ts` at their scope.
-- Constants that are used together MAY be grouped in a file with a kebab-case name and named-re-exported from `constants/index.ts`.
-- When a `constants/` folder uses grouped files, its `index.ts` MUST only named-re-export those files.
+- Consumers MUST import an extracted constant through the `index.ts` in that constant's `constants/` folder.
+- A `constants/` folder MUST either define its constants directly in `index.ts` or group related constants in kebab-case files that `index.ts` named-re-exports.
 - When a constant's CCF is `src/features/`, it MUST move to `src/constants/`.
+- A constant MAY live in `src/config/<module>/` instead of a `constants/` folder when a developer determines that it configures application behavior and is best understood alongside the configuration that parameterizes it, even when consumers exist outside the config module.
 
 ## Incorrect — Constant Imported Without `constants/index.ts`
 

package/docs/code-organization-guide/rules/exports-and-imports-rule.md

@@ -1,12 +1,15 @@
 # Exports and Imports Rule
 
-Without consistent export and import styles, it is harder to tell what a file contains and how other files should import from it. This rule gives each file type a predictable export style and keeps import paths consistent.
-
-- Static JavaScript and TypeScript modules under `src/` MUST use named exports unless a framework or third-party package requires a different export style for a specific file.
-- Static imports under `src/` MUST use relative paths for the same folder, a direct subfolder, or one folder up.
-- Static imports under `src/` MUST use the `@/*` alias for anything beyond one folder up.
-- ESLint MUST enforce this rule's export and static import restrictions under `src/`.
-
+Without consistent exports, import paths, and layer boundaries, it is harder to tell what a file contains and which files may depend on it. This rule gives each file a predictable export style and keeps imports consistent with the application structure.
+
+- A file that exports values MUST use named exports unless a framework or third-party package requires a different export style for that file.
+- Imports MUST use relative paths for the same folder, a direct subfolder, or one folder up.
+- Imports MUST use the `@/*` alias for anything beyond one folder up.
+- A file under `src/compositions/` MUST NOT import from `src/app/`.
+- A file in a feature folder MUST NOT import from another feature folder, `src/compositions/`, or `src/app/`.
+- A file under `src/shared/` MUST NOT import from `src/app/`, `src/compositions/`, or a feature folder.
+- A file in the `root` layer MUST NOT import from `src/app/`, `src/compositions/`, a feature folder, or `src/shared/`.
+- A configuration module MUST import only from root support folders and its own files.
 ## Incorrect — Single-Export Utility Uses a Default Export
 
 ```ts

package/docs/code-organization-guide/rules/folder-nesting-rule.md

@@ -2,8 +2,7 @@
 
 Without nesting, exclusive children can look reusable and their relationship to the parent is easy to miss in review. This rule groups them with their parent and keeps them out of the folder's public API.
 
-- An exclusive child component is imported only by its parent component or descendants in the parent's folder. A flat component MUST be nested in a folder with the same name when it gains one or more exclusive child components.
-- A child that gains a consumer outside its parent's folder MUST move according to the Component Placement Rule, including that rule's CCF consumer exclusions.
+- An exclusive child component is imported only by its parent component. A component MUST stay flat until it has one or more exclusive child components, then MUST be nested in a folder with the same name.
 - A component MUST NOT be nested only because it has support files.
 - A nested component's support files MUST live in its folder.
 - The nested folder's `index.ts` MUST named-re-export the nested component and MUST NOT re-export its exclusive children.

package/docs/code-organization-guide/rules/hook-extraction-rule.md

@@ -3,22 +3,21 @@
 Keeping every hook inline makes components bloated, while extracting every hook adds indirection without benefit. This rule defines concrete reuse and imperative-complexity triggers for extraction.
 
 - A custom hook MUST be extracted to its own file when two or more consumers use it.
-- A custom hook used only to implement one configuration object MUST live in that object's `hooks/` folder.
 - A custom hook with exactly one consumer MUST be extracted when it contains two or more imperative categories and can be described as one coherent behavior.
 - An extracted custom hook MUST live in a `hooks/` folder at the closest common folder (CCF) of its consumers.
 - When a custom hook's CCF is `src/features/`, it MUST move to `src/hooks/`.
 - The imperative categories MUST be subscriptions, external I/O and persistence, DOM manipulation, or resource lifecycle.
-- One operation MAY count in only one imperative category; use its primary purpose when categories overlap.
+- Each operation MUST count toward only one imperative category.
 - Subscriptions MUST include event listeners and registration or cleanup APIs such as `on()` and `off()`.
 - External I/O and persistence MUST include network requests, asynchronous reads or writes, and browser storage.
 - DOM manipulation MUST include imperative APIs such as `focus()`, `classList`, observers, or imperative rendering.
 - Resource lifecycle MUST include setup and teardown APIs such as `load()`, `destroy()`, or `dispose()`.
-- A custom hook with one consumer that does not meet the two-category threshold MUST stay inline in its consumer module, unless it is used only to implement one configuration object.
+- A custom hook with one consumer that does not meet the two-category threshold MUST stay inline in its consumer file.
 
 ## Incorrect — Two Imperative Categories Left Inline
 
 ```tsx
-// src/features/player/Player.tsx
+// src/features/player/player.tsx
 export function Player({ src }: PlayerProps): React.JSX.Element {
   useEffect(() => {
     player.on("play", handlePlay);
@@ -58,7 +57,7 @@ export function usePlayerSetup(src: string): void {
 ```
 
 ```tsx
-// src/features/player/Player.tsx
+// src/features/player/player.tsx
 import { usePlayerSetup } from "./hooks/use-player-setup";
 
 export function Player({ src }: PlayerProps): React.JSX.Element {

package/docs/code-organization-guide/rules/interactive-component-rule.md

@@ -2,7 +2,7 @@
 
 Large component files need a clear way to decide what to extract first. This rule treats interactive elements as meaningful component boundaries instead of extracting arbitrary layout elements.
 
-- An [interactive HTML element](https://html.spec.whatwg.org/multipage/dom.html#interactive-content) MUST be extracted to a component with a descriptive name unless it is the top-level native element returned by the component that renders it in every rendered result.
+- An [interactive HTML element](https://html.spec.whatwg.org/multipage/dom.html#interactive-content) MUST be extracted to a component with a descriptive name.
 
 ## Incorrect — Interactive Element Kept Inline
 
@@ -18,8 +18,8 @@ export function HeaderSection({
   searchPlaceholder: string;
 }): React.JSX.Element {
   return (
-    <header className="flex items-center justify-between px-6 py-4">
-      <h1 className="text-2xl">{locales.layout.headerTitle}</h1>
+    <header>
+      <h1>{locales.layout.headerTitle}</h1>
 
       <button onClick={onMenuClick} aria-label={locales.layout.openMenu}>
         <Icon name="menu" />
@@ -71,23 +71,20 @@ export function SearchField(props: SearchFieldProps): React.JSX.Element {
 
 import { MenuButton } from "./menu-button";
 import { SearchField } from "./search-field";
-import { cn } from "@/utils/cn";
 import { locales } from "@/locales";
 
-type HeaderSectionProps = React.ComponentProps<"header"> & {
+type HeaderSectionProps = {
   onMenuClick: () => void;
   searchPlaceholder: string;
 };
 
 export function HeaderSection({
-  className,
   onMenuClick,
   searchPlaceholder,
-  ...props
 }: HeaderSectionProps): React.JSX.Element {
   return (
-    <header {...props} className={cn("flex items-center justify-between px-6 py-4", className)}>
-      <h1 className="text-2xl">{locales.layout.headerTitle}</h1>
+    <header>
+      <h1>{locales.layout.headerTitle}</h1>
 
       <MenuButton onClick={onMenuClick} aria-label={locales.layout.openMenu} />
 
@@ -97,4 +94,4 @@ export function HeaderSection({
 }
 ```
 
-Why: each interactive element now has its own descriptive component and forwards native props, leaving `HeaderSection` to compose them.
+Why: each interactive element now has its own descriptive component, leaving `HeaderSection` to compose them.

package/docs/code-organization-guide/rules/jsx-hygiene-rule.md

@@ -3,7 +3,7 @@
 JSX should show the component's structure, not its calculations. This rule moves complex expressions before `return` while keeping simple JSX readable.
 
 - Arithmetic, chained built-in method calls, calls to functions declared outside the component, nested ternaries, and conditions containing two or more logical operators MUST be extracted before `return`, including in JSX attributes.
-- An inline expression MAY contain one condition with at most one logical operator, one ternary, or one built-in method call. `cn()` is an explicit exception to the external-function-call restriction. Calls inside an event-handler callback are not JSX expressions.
+- An inline expression MAY contain one condition with up to one logical operator, one ternary, or one built-in method call. `cn()` MAY be called inline. An event handler MAY make one call inline.
 
 ## Incorrect — Computation in JSX
 
@@ -40,7 +40,6 @@ const total = calculateTotal(items);
 const canShowAdmin = isLoggedIn && hasPermission && isOwner && featureEnabled;
 const publishDate = new Date(post.publishedAt).toLocaleDateString();
 const scorePercent = Math.round(score * 100);
-const daysAgoLabel = locales.daysAgo;
 
 let statusView = <Content />;
 if (isLoading) {
@@ -51,7 +50,7 @@ if (isLoading) {
 
 return (
   <div>
-    <span>{daysSinceUpdate} {daysAgoLabel}</span>
+    <span>{daysSinceUpdate} {locales.daysAgo}</span>
     <ul>{activeItems.map(renderItem)}</ul>
     <p>
       {updatedLabel} — {total}