pasika 0.1.1 → 0.1.6

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,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/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,27 @@
+# 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.
+
+## 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.
+- 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,69 @@
+# 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.
+
+## 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 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. 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 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 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 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 module.
+
+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 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 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.