pasika 0.1.0 → 0.1.4

package/README.md

@@ -1,35 +1,31 @@
 # pasika
 
-Reusable base assets for Claude Code setups.
+Reusable agent setup package, starting with Claude.
 
-`pasika` stores portable Claude base config assets that individual repos can copy from or adapt.
+`pasika` stores portable agent setup assets that individual repos can apply or adapt. Today it focuses on Claude, with room for Codex and other agent-specific setup flows later.
 
 ## Scope
 
 This repo intentionally starts narrow:
 
-- Claude only for v1
-- reusable base config only
+- Claude first for v1
+- reusable agent setup assets only
 - shared docs at the repo root
-- no project-specific rules, workflows, or business logic
+- no project-specific workflows or business logic
 
 ## Layout
 
 ```text
 claude/
+  settings.base.json
+  hooks/
+    status-line/
+      index.js
+    notification.sh
+    protect-files.sh
   scripts/
     render-settings.ts
-  .claude/
-    settings.base.json
-    hooks/
-      status-line/
-        index.js
-      notification.sh
-      protect-files.sh
 docs/
-  common/
-    overview.md
-    merge-behavior.md
   claude/
     hooks.md
 scripts/
@@ -43,21 +39,22 @@ CLAUDE.md
 
 ## What belongs here
 
-- portable hook scripts
+- portable setup scripts
 - base settings templates
 - shared docs and generated `CLAUDE.md`
 - shared naming and layout conventions
+- reusable source-organization lint rules
 
 ## What stays in project repos
 
-- final `.claude` folders
-- project-specific skills, rules, agents, and prompts
+- final agent config folders in project repos
+- project-specific rules, agents, and prompts
 - repository-specific plugin choices
 - scripts that depend on a specific app, CI setup, or codebase
 
 ## CLI
 
-The main entry point is:
+The current entry point is:
 
 ```bash
 npx pasika claude
@@ -100,13 +97,22 @@ So the recommended pattern is:
 4. point hook commands at `./node_modules/pasika/claude/...`
 5. keep project-specific plugin, skill, and rule decisions in the project repo
 
-## Merge Behavior
+`npx pasika claude` also copies the packaged Claude hooks docs into `.claude/hooks/` in the target repo.
 
-By default, `pasika` merges its Claude base into an existing `.claude/settings.json`.
+## ESLint Pasika Ruleset
 
-That means:
+Pasika packages its source-organization rules separately from its own Node and TypeScript lint configuration. A consumer composes the exported ruleset with Zirka and enables any framework-specific Zirka blocks it needs.
 
-- it updates the portable base pieces shipped by `pasika`
-- it preserves unrelated project-specific settings such as extra hooks, plugin config, and custom permissions
+```ts
+// eslint.config.ts
+import { pasikaConfig } from "pasika/eslint";
+import { RuleSeverity, styleguide } from "zirka";
 
-Use `--force` only when you want to replace the existing file with the `pasika` base output.
+const { eslintConfig } = styleguide({
+  next: RuleSeverity.Error,
+  node: RuleSeverity.Error,
+  typescript: RuleSeverity.Error,
+});
+
+export default [...((await eslintConfig) ?? []), pasikaConfig];
+```

package/claude/hooks/.vulyk

@@ -0,0 +1,3 @@
+🍯 AGENTS.md
+🍯 CLAUDE.md
+🍯 claude-hooks.md

package/claude/hooks/AGENTS.md

@@ -0,0 +1,3 @@
+# Claude Hooks
+Shared Claude hooks shipped by pasika.
+Full documentation: docs/claude/hooks.md

package/claude/hooks/claude-hooks.md

@@ -0,0 +1,30 @@
+# Claude Hooks
+
+`pasika` ships the reusable shared Claude hooks.
+
+## `status-line/index.js`
+
+Displays a two-line status view with:
+
+- model name
+- current folder
+- git branch when available
+- used context percentage as a 10-segment bar
+- session cost
+- session duration
+
+## `notification.sh`
+
+Sends a desktop notification when Claude needs attention.
+
+- macOS: `terminal-notifier` with click-to-focus VS Code behavior, falls back to `osascript`
+- Linux: `notify-send`
+- Windows: PowerShell message box
+
+## `protect-files.sh`
+
+Blocks edits to:
+
+- `.env` files
+- `package-lock.json`
+- files inside `.git/`

package/claude/scripts/render-settings.ts

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -107,9 +107,9 @@ const mergeClaudeSettings = (
   baseSettings: ClaudeSettings,
   packagePath: string,
 ): ClaudeSettings => {
-  const notificationCommand = `${packagePath}/.claude/hooks/notification.sh`;
-  const protectFilesCommand = `${packagePath}/.claude/hooks/protect-files.sh`;
-  const statusLineCommand = `node ${packagePath}/.claude/hooks/status-line/index.js`;
+  const notificationCommand = `${packagePath}/hooks/notification.sh`;
+  const protectFilesCommand = `${packagePath}/hooks/protect-files.sh`;
+  const statusLineCommand = `node ${packagePath}/hooks/status-line/index.js`;
 
   return {
     ...existingSettings,
@@ -136,18 +136,18 @@ const mergeClaudeSettings = (
 };
 
 export const renderClaude = async (targetDir: string, force: boolean, packageRoot: string): Promise<string[]> => {
-  const templatePath = path.join(packageRoot, "claude/.claude/settings.base.json");
+  const templatePath = path.join(packageRoot, "claude/settings.base.json");
   const baseSettings = await readClaudeSettings(templatePath);
   const packagePath = "./node_modules/pasika/claude";
   const notificationEntries = upsertHookMatcherEntry(
     baseSettings.hooks.Notification,
     "",
-    `${packagePath}/.claude/hooks/notification.sh`,
+    `${packagePath}/hooks/notification.sh`,
   );
   const preToolUseEntries = upsertHookMatcherEntry(
     baseSettings.hooks.PreToolUse,
     "Edit|Write",
-    `${packagePath}/.claude/hooks/protect-files.sh`,
+    `${packagePath}/hooks/protect-files.sh`,
   );
   const settings: ClaudeSettings = {
     ...baseSettings,
@@ -159,14 +159,16 @@ export const renderClaude = async (targetDir: string, force: boolean, packageRoo
     statusLine: {
       ...baseSettings.statusLine,
       type: "command",
-      command: `node ${packagePath}/.claude/hooks/status-line/index.js`,
+      command: `node ${packagePath}/hooks/status-line/index.js`,
     },
   };
 
   const outputDir = path.join(targetDir, ".claude");
   const outputPath = path.join(outputDir, "settings.json");
+  const hooksOutputDir = path.join(outputDir, "hooks");
 
   await mkdir(outputDir, { recursive: true });
+  await mkdir(hooksOutputDir, { recursive: true });
 
   const finalSettings =
     !force && (await fileExists(outputPath))
@@ -175,7 +177,21 @@ export const renderClaude = async (targetDir: string, force: boolean, packageRoo
 
   await writeFile(outputPath, `${JSON.stringify(finalSettings, null, 2)}\n`, "utf8");
 
-  return [outputPath];
+  const outputs = [outputPath];
+  const hookDocFiles = ["AGENTS.md", "CLAUDE.md"] as const;
+
+  for (const fileName of hookDocFiles) {
+    const sourcePath = path.join(packageRoot, "claude/hooks", fileName);
+    if (!(await fileExists(sourcePath))) {
+      continue;
+    }
+
+    const destinationPath = path.join(hooksOutputDir, fileName);
+    await copyFile(sourcePath, destinationPath);
+    outputs.push(destinationPath);
+  }
+
+  return outputs;
 };
 
 const isDirectRun = process.argv[1] ? path.resolve(process.argv[1]) === __filename : false;

package/dist/claude/scripts/render-settings.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { constants } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -52,9 +52,9 @@ const upsertHookMatcherEntry = (entries, matcher, command) => {
     return nextEntries;
 };
 const mergeClaudeSettings = (existingSettings, baseSettings, packagePath) => {
-    const notificationCommand = `${packagePath}/.claude/hooks/notification.sh`;
-    const protectFilesCommand = `${packagePath}/.claude/hooks/protect-files.sh`;
-    const statusLineCommand = `node ${packagePath}/.claude/hooks/status-line/index.js`;
+    const notificationCommand = `${packagePath}/hooks/notification.sh`;
+    const protectFilesCommand = `${packagePath}/hooks/protect-files.sh`;
+    const statusLineCommand = `node ${packagePath}/hooks/status-line/index.js`;
     return {
         ...existingSettings,
         $schema: baseSettings.$schema ?? existingSettings.$schema,
@@ -79,11 +79,11 @@ const mergeClaudeSettings = (existingSettings, baseSettings, packagePath) => {
     };
 };
 export const renderClaude = async (targetDir, force, packageRoot) => {
-    const templatePath = path.join(packageRoot, "claude/.claude/settings.base.json");
+    const templatePath = path.join(packageRoot, "claude/settings.base.json");
     const baseSettings = await readClaudeSettings(templatePath);
     const packagePath = "./node_modules/pasika/claude";
-    const notificationEntries = upsertHookMatcherEntry(baseSettings.hooks.Notification, "", `${packagePath}/.claude/hooks/notification.sh`);
-    const preToolUseEntries = upsertHookMatcherEntry(baseSettings.hooks.PreToolUse, "Edit|Write", `${packagePath}/.claude/hooks/protect-files.sh`);
+    const notificationEntries = upsertHookMatcherEntry(baseSettings.hooks.Notification, "", `${packagePath}/hooks/notification.sh`);
+    const preToolUseEntries = upsertHookMatcherEntry(baseSettings.hooks.PreToolUse, "Edit|Write", `${packagePath}/hooks/protect-files.sh`);
     const settings = {
         ...baseSettings,
         hooks: {
@@ -94,17 +94,30 @@ export const renderClaude = async (targetDir, force, packageRoot) => {
         statusLine: {
             ...baseSettings.statusLine,
             type: "command",
-            command: `node ${packagePath}/.claude/hooks/status-line/index.js`,
+            command: `node ${packagePath}/hooks/status-line/index.js`,
         },
     };
     const outputDir = path.join(targetDir, ".claude");
     const outputPath = path.join(outputDir, "settings.json");
+    const hooksOutputDir = path.join(outputDir, "hooks");
     await mkdir(outputDir, { recursive: true });
+    await mkdir(hooksOutputDir, { recursive: true });
     const finalSettings = !force && (await fileExists(outputPath))
         ? mergeClaudeSettings(await readClaudeSettings(outputPath), settings, packagePath)
         : settings;
     await writeFile(outputPath, `${JSON.stringify(finalSettings, null, 2)}\n`, "utf8");
-    return [outputPath];
+    const outputs = [outputPath];
+    const hookDocFiles = ["AGENTS.md", "CLAUDE.md"];
+    for (const fileName of hookDocFiles) {
+        const sourcePath = path.join(packageRoot, "claude/hooks", fileName);
+        if (!(await fileExists(sourcePath))) {
+            continue;
+        }
+        const destinationPath = path.join(hooksOutputDir, fileName);
+        await copyFile(sourcePath, destinationPath);
+        outputs.push(destinationPath);
+    }
+    return outputs;
 };
 const isDirectRun = process.argv[1] ? path.resolve(process.argv[1]) === __filename : false;
 if (isDirectRun) {

package/dist/eslint/pasika/index.d.ts

@@ -0,0 +1,2 @@
+import type { Linter } from "eslint";
+export declare const pasikaConfig: Linter.Config;

package/dist/eslint/pasika/index.js

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

package/dist/eslint/pasika/rules/organization-imports.d.ts

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

package/dist/eslint/pasika/rules/organization-imports.js

@@ -0,0 +1,124 @@
+import path from "node:path";
+const sourceRoot = path.resolve("src");
+const rootSupportFolders = new Set(["config", "constants", "hooks", "locales", "schemas", "types", "utils"]);
+const moduleExtensions = new Set([".cjs", ".cts", ".js", ".jsx", ".mjs", ".mts", ".ts", ".tsx"]);
+const styleExtensions = new Set([".css", ".less", ".sass", ".scss"]);
+function resolveSourceImport(filename, importPath) {
+    if (importPath.startsWith("@/")) {
+        return path.resolve(sourceRoot, importPath.slice(2));
+    }
+    if (importPath.startsWith(".")) {
+        return path.resolve(path.dirname(filename), importPath);
+    }
+    return undefined;
+}
+function sourceSegments(absolutePath) {
+    const relativePath = path.relative(sourceRoot, absolutePath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        return undefined;
+    }
+    return relativePath.split(path.sep);
+}
+function isNearbyImport(filename, resolvedPath) {
+    const relativePath = path.relative(path.dirname(filename), resolvedPath);
+    const segments = relativePath.split(path.sep).filter((segment) => segment !== ".");
+    const parentTraversals = segments.filter((segment) => segment === "..").length;
+    const nonParentSegments = segments.length - parentTraversals;
+    return (parentTraversals === 0 && nonParentSegments <= 2) || (parentTraversals === 1 && nonParentSegments <= 1);
+}
+export const organizationImportsRule = {
+    meta: {
+        schema: [],
+        type: "problem",
+    },
+    create(context) {
+        const filename = context.filename;
+        if (!filename) {
+            return {};
+        }
+        function reportImport(source) {
+            if (typeof source.value !== "string") {
+                return;
+            }
+            const importPath = source.value;
+            const resolvedPath = resolveSourceImport(filename, importPath);
+            if (!resolvedPath) {
+                return;
+            }
+            const importer = sourceSegments(filename);
+            const imported = sourceSegments(resolvedPath);
+            if (!importer || !imported || importer.length === 0 || imported.length === 0) {
+                return;
+            }
+            if (isNearbyImport(filename, resolvedPath) && importPath.startsWith("@/")) {
+                context.report({
+                    node: source,
+                    message: "Use a relative path for imports in the same folder, a descendant, or one folder up.",
+                });
+            }
+            if (!isNearbyImport(filename, resolvedPath) && importPath.startsWith(".")) {
+                context.report({
+                    node: source,
+                    message: "Use the @/* alias for imports beyond one folder up.",
+                });
+            }
+            const [importerLayer = "", importerFeature] = importer;
+            const [importedLayer = "", importedFeature] = imported;
+            const extension = path.extname(importPath);
+            const isCodeModule = !extension || moduleExtensions.has(extension);
+            const isAppLocalStyleImport = importerLayer === "app" && importedLayer === "app" && styleExtensions.has(extension);
+            const importedIsRootSupport = rootSupportFolders.has(importedLayer);
+            const importedIsSameConfig = importerLayer === "config" && importedLayer === "config" && importer[1] === imported[1];
+            const isAllowed = (!isCodeModule && importerLayer === "app" && isAppLocalStyleImport) ||
+                (isCodeModule &&
+                    importerLayer === "app" &&
+                    (importedLayer === "compositions" ||
+                        importedLayer === "features" ||
+                        importedLayer === "shared" ||
+                        importedIsRootSupport)) ||
+                (isCodeModule &&
+                    importerLayer === "compositions" &&
+                    (importedLayer === "compositions" ||
+                        importedLayer === "features" ||
+                        importedLayer === "shared" ||
+                        importedIsRootSupport)) ||
+                (isCodeModule &&
+                    importerLayer === "features" &&
+                    ((importedLayer === "features" && importerFeature === importedFeature) ||
+                        importedLayer === "shared" ||
+                        importedIsRootSupport)) ||
+                (isCodeModule && importerLayer === "shared" && (importedLayer === "shared" || importedIsRootSupport)) ||
+                (isCodeModule &&
+                    rootSupportFolders.has(importerLayer) &&
+                    importedIsRootSupport &&
+                    (importerLayer !== "config" || importedLayer !== "config" || importedIsSameConfig));
+            if (!isAllowed) {
+                context.report({
+                    node: source,
+                    message: "This import violates the src layer boundary.",
+                });
+            }
+        }
+        return {
+            ImportDeclaration(node) {
+                reportImport(node.source);
+            },
+            ExportAllDeclaration(node) {
+                reportImport(node.source);
+            },
+            ExportNamedDeclaration(node) {
+                if (node.source) {
+                    reportImport(node.source);
+                }
+            },
+            ImportExpression(node) {
+                reportImport(node.source);
+            },
+            CallExpression(node) {
+                if (node.callee.type === "Identifier" && node.callee.name === "require" && node.arguments[0]) {
+                    reportImport(node.arguments[0]);
+                }
+            },
+        };
+    },
+};

package/docs/agent-conventions.md

@@ -0,0 +1,21 @@
+# Agent Conventions
+
+Repo-wide engineering rules and commit hygiene for AI agents.
+
+## Data Contracts
+
+- Use Zod schemas for runtime validation; prioritize them over ad hoc type guards.
+- Prefer strict-by-default data contracts. Make fields required unless real runtime evidence shows they must be nullable or optional.
+- Do not preserve backward compatibility by default. Prefer simplifying and updating all in-repo call sites unless the user explicitly asks for compatibility.
+
+## Code Quality
+
+- Never use `eslint-disable` directives. Fix issues properly.
+- Never commit with the `--no-verify` flag.
+
+## Vulyk
+
+- Make Vulyk registry changes with Vulyk commands, not by editing generated files.
+- Treat `AGENTS.md`, `docs/external`, `.agents/skills`, and `.vulyk` as generated output.
+- Use ephemeral commands such as `npx vulyk@latest ...`.
+- Do not add Vulyk to `package.json` only to run the CLI.

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

@@ -0,0 +1,65 @@
+# Code Organization Guide
+
+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.
+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).
+
+## 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.
+2. Follow the [Types and Schemas Rule](rules/types-and-schemas-rule.md).
+
+## 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.
+2. Follow the [Constants Rule](rules/constants-rule.md).
+
+## 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.
+2. Follow the [Utilities Rule](rules/utilities-rule.md).
+
+## How To Organize Configuration
+
+Use this when adding or moving an application configuration object.
+
+1. Read the [Application Architecture Reference](references/application-architecture-reference.md) to choose the right layer and scope.
+2. Follow the [Configuration Rule](rules/configuration-rule.md).
+
+## 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.
+2. Follow the [Hook Extraction Rule](rules/hook-extraction-rule.md).
+
+## 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.
+2. Follow the [Locales Rule](rules/locales-rule.md).

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

@@ -0,0 +1,107 @@
+# Application Architecture Reference
+
+Use this reference to look up the canonical shape of the repository's `src/` tree and its Layer Model.
+
+## 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.
+
+| Layer or scope | 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 |
+| `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/`.
+
+## Closest Common Folder (CCF)
+
+The CCF is the deepest eligible folder that contains every consumer of an item.
+
+- 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.
+
+## Application Structure
+
+This tree shows the canonical directory layout and naming conventions for files and folders inside `src/`. It is included so readers can verify their structure matches the project standard at a glance.
+
+```
+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
+├── compositions/                          # Components stay flat siblings by default
+│   ├── <ComponentA>.tsx                   # Smart component (PascalCase-named)
+│   ├── <component-b>.tsx                  # Dumb component (kebab-case-named)
+│   ├── <component-part>.tsx               # Dumb component — shared by A and B, so it stays flat too
+│   ├── <NestedComponent>/                 # Smart (PascalCase-named) — or kebab-case-named for dumb; nested only once it gains exclusive children
+│   │   ├── index.ts                       # Named-re-exports only the nested parent
+│   │   ├── <NestedComponent>.tsx          # Smart (PascalCase-named) — or kebab-case-named for dumb
+│   │   ├── <nested-part>.tsx              # Exclusive child — not in index.ts
+│   │   ├── hooks/                         # Nested-scoped support folders
+│   │   ├── types/
+│   │   ├── schemas/
+│   │   ├── constants/
+│   │   └── utils/
+│   ├── hooks/                             # Composition-scoped custom hooks
+│   ├── types/                             # Composition-scoped TypeScript types
+│   ├── schemas/                           # Composition-scoped validation schemas
+│   ├── constants/                         # Composition-scoped constants
+│   └── utils/                             # Composition-scoped pure functions
+├── features/                              # Feature folders only — no components, no support folders here
+│   └── <feature>/                         # One folder per feature — a feature can hold several components
+│       ├── <ComponentA>.tsx               # Smart component (PascalCase-named)
+│       ├── <component-b>.tsx              # Dumb component (kebab-case-named)
+│       ├── <component-part>.tsx           # Dumb component — shared by A and B, so it stays flat too
+│       ├── <NestedComponent>/             # Smart (PascalCase-named) — or kebab-case-named for dumb; nested only once it gains exclusive children
+│       │   ├── index.ts                   # Named-re-exports only the nested parent
+│       │   ├── <NestedComponent>.tsx      # Smart (PascalCase-named) — or kebab-case-named for dumb
+│       │   ├── <nested-part>.tsx          # Exclusive child — not in index.ts
+│       │   ├── hooks/                     # Nested-scoped support folders
+│       │   ├── types/
+│       │   ├── schemas/
+│       │   ├── constants/
+│       │   └── utils/
+│       ├── hooks/                         # Feature-scoped custom hooks
+│       ├── types/                         # Feature-scoped TypeScript types
+│       ├── schemas/                       # Feature-scoped validation schemas
+│       ├── constants/                     # Feature-scoped constants
+│       └── utils/                         # Feature-scoped pure functions
+├── shared/                                # Components stay flat siblings by default
+│   ├── <ComponentA>.tsx                   # Smart component (PascalCase-named)
+│   ├── <component-b>.tsx                  # Dumb component (kebab-case-named)
+│   ├── <component-part>.tsx               # Dumb component — shared by A and B, so it stays flat too
+│   ├── <NestedComponent>/                 # Smart (PascalCase-named) — or kebab-case-named for dumb; nested only once it gains exclusive children
+│   │   ├── index.ts                       # Named-re-exports only the nested parent
+│   │   ├── <NestedComponent>.tsx          # Smart (PascalCase-named) — or kebab-case-named for dumb
+│   │   ├── <nested-part>.tsx              # Exclusive child — not in index.ts
+│   │   ├── hooks/                         # Nested-scoped support folders
+│   │   ├── types/
+│   │   ├── schemas/
+│   │   ├── constants/
+│   │   └── utils/
+│   ├── hooks/                             # Shared-scoped custom hooks
+│   ├── types/                             # Shared-scoped TypeScript types
+│   ├── schemas/                           # Shared-scoped validation schemas
+│   ├── constants/                         # Shared-scoped constants
+│   └── utils/                             # Shared-scoped pure functions
+├── hooks/                                 # App-wide custom hooks
+├── types/                                 # App-wide TypeScript types
+├── 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
+│       ├── 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
+```