@utilarium/dreadcabinet 0.0.16-dev.0

package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-32-36-513Z.md

@@ -0,0 +1,55 @@
+# Agentic Workflow - Self-Reflection Report
+
+Generated: 2026-01-08T12:32:36.514Z
+
+## Execution Summary
+
+- **Iterations**: 1
+- **Tool Calls**: 0
+- **Unique Tools**: 0
+
+## Tool Effectiveness Analysis
+
+*No tools were executed during this run.*
+
+## Recommendations for Improvement
+
+*No specific recommendations at this time. Execution appears optimal.*
+
+## Detailed Execution Timeline
+
+*No tool execution timeline available.*
+## Conversation History
+
+<details>
+<summary>Click to expand full agentic interaction</summary>
+
+```json
+[
+  {
+    "role": "system",
+    "content": "You are a professional software engineer writing commit messages for your team.\n\n## Available Tools\n\n### Understanding\n\n**get_file_history** _(cheap)_\nGet git commit history for one or more files to understand their evolution and past changes\n\nParameters:\n- `filePaths` (required): Array of file paths to get history for\n- `limit`: Maximum number of commits to return (default: 10)\n- `format`: Output format: \"summary\" for brief or \"detailed\" for full messages\n\n**When to use:** Get git commit history for one or more files to understand their evolution and past changes\n\n**Examples:**\n- Check if file has recent refactoring: `get_file_history({\"filePaths\":[\"src/auth.ts\"],\"limit\":5})`\n- Understand evolution of multiple related files: `get_file_history({\"filePaths\":[\"src/user.ts\",\"src/auth.ts\"],\"limit\":10,\"format\":\"detailed\"})`\n\n---\n\n**get_file_content** _(moderate)_\nGet the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\nParameters:\n- `filePath` (required): Path to the file\n- `includeLineNumbers`: Include line numbers in output (default: false)\n\n**When to use:** Get the complete current content of a file to understand context around changes. Returns a message if the file does not exist (e.g., if it was deleted).\n\n**Examples:**\n- See full class definition for modified method: `get_file_content({\"filePath\":\"src/services/auth.ts\",\"includeLineNumbers\":true})`\n- Check imports and structure: `get_file_content({\"filePath\":\"src/utils/helpers.ts\"})`\n\n---\n\n**get_related_tests** _(cheap)_\nFind test files related to production files to understand what the code is supposed to do\n\nParameters:\n- `filePaths` (required): Production file paths\n\n**When to use:** Find test files related to production files to understand what the code is supposed to do\n\n**Examples:**\n- Find tests for modified service: `get_related_tests({\"filePaths\":[\"src/services/auth.ts\"]})`\n\n---\n\n**analyze_diff_section** _(cheap)_\nGet expanded context around specific lines in a file to better understand changes\n\nParameters:\n- `filePath` (required): File containing the section to analyze\n- `startLine` (required): Starting line number\n- `endLine` (required): Ending line number\n- `contextLines`: Number of additional context lines to show before and after (default: 10)\n\n**When to use:** Get expanded context around specific lines in a file to better understand changes\n\n**Examples:**\n- See context around confusing change: `analyze_diff_section({\"filePath\":\"src/auth.ts\",\"startLine\":45,\"endLine\":52,\"contextLines\":15})`\n\n---\n\n**get_recent_commits** _(cheap)_\nGet recent commits that modified the same files to understand recent work in this area\n\nParameters:\n- `filePaths` (required): Files to check for recent commits\n- `since`: Time period to look back (e.g., \"1 week ago\", \"2 days ago\")\n- `limit`: Maximum number of commits to return (default: 5)\n\n**When to use:** Get recent commits that modified the same files to understand recent work in this area\n\n**Examples:**\n- Check for duplicate commit messages: `get_recent_commits({\"filePaths\":[\"src/auth.ts\"],\"since\":\"1 week ago\",\"limit\":5})`\n\n---\n\n### Analysis\n\n**search_codebase** _(moderate)_\nSearch for code patterns, function names, or text across the codebase using git grep\n\nParameters:\n- `query` (required): Search pattern (can be plain text or regex)\n- `fileTypes`: Limit search to specific file extensions (e.g., [\"ts\", \"js\"])\n- `contextLines`: Number of context lines to show around matches (default: 2)\n\n**When to use:** Search for code patterns, function names, or text across the codebase using git grep\n\n**Examples:**\n- Find all uses of a renamed function: `search_codebase({\"query\":\"oldFunctionName\",\"fileTypes\":[\"ts\",\"tsx\"]})`\n- Check if pattern exists elsewhere: `search_codebase({\"query\":\"pattern.*string\",\"contextLines\":3})`\n\n---\n\n**get_file_dependencies** _(moderate)_\nFind which files import or depend on the changed files to assess change impact\n\nParameters:\n- `filePaths` (required): Files to analyze dependencies for\n\n**When to use:** Find which files import or depend on the changed files to assess change impact\n\n**Examples:**\n- Check impact of util function change: `get_file_dependencies({\"filePaths\":[\"src/utils/format.ts\"]})`\n\n---\n\n### Organization\n\n**group_files_by_concern** _(cheap)_\nAnalyze changed files and suggest logical groupings that might represent separate commits\n\nParameters:\n- `filePaths` (required): All changed files to analyze\n\n**When to use:** Analyze changed files and suggest logical groupings that might represent separate commits\n\n**Examples:**\n- Check if multiple unrelated changes should be split: `group_files_by_concern({\"filePaths\":[\"src/auth.ts\",\"README.md\",\"tests/auth.test.ts\",\"package.json\"]})`\n\n---\n\n\n\n## Your Task\n\nWrite a commit message that clearly explains what changed and why. Your message should help teammates understand the changes without needing to read the diff.\n\nThink about:\n- What problem does this solve?\n- How do the changes work together?\n- What should reviewers focus on?\n- Are there any important implications?\n\nUse the available tools to investigate the changes. The more you understand, the better your message will be.\n\n**Important**: If additional context is provided (from context files or other sources), use your judgment:\n- If the context is relevant to these specific changes, incorporate it\n- If the context describes unrelated changes or other packages, ignore it\n- Don't force connections between unrelated information\n- Focus on accurately describing what actually changed in this commit\n\n## Investigation Approach\n\nUse tools based on what you need to know:\n- group_files_by_concern - understand how files relate\n- get_file_content - see full context when diffs are unclear\n- get_file_history - understand how code evolved\n- get_file_dependencies - assess impact of changes\n- get_recent_commits - avoid duplicate messages\n- get_related_tests - understand behavior changes\n- search_codebase - find usage patterns\n\n## Writing Style\n\nWrite naturally and directly:\n- Use plain language, not corporate speak\n- Be specific and concrete\n- Avoid buzzwords and jargon\n- No emojis or excessive punctuation\n- No phrases like \"this commit\" or \"this PR\"\n- No meta-commentary about the commit itself\n\nFollow conventional commit format when appropriate (feat:, fix:, refactor:, docs:, test:, chore:), but prioritize clarity over formality.\n\n## Output Format\n\nWhen ready, format your response as:\n\nCOMMIT_MESSAGE:\n[Your commit message here]\n\nIf changes should be split into multiple commits:\n\nSUGGESTED_SPLITS:\nSplit 1:\nFiles: [list of files]\nRationale: [why these belong together]\nMessage: [commit message for this split]\n\nSplit 2:\n...\n\nOutput only the commit message and splits. No conversational remarks or follow-up offers."
+  },
+  {
+    "role": "user",
+    "content": "I have staged changes that need a commit message.\n\nChanged files (13):\n  - .github/workflows/deploy-docs.yml\n  - .github/workflows/test.yml\n  - README.md\n  - docs/public/contributing.md\n  - docs/public/faq.md\n  - docs/src/App.tsx\n  - guide/architecture.md\n  - guide/configuration.md\n  - guide/development.md\n  - guide/index.md\n  - guide/usage.md\n  - package-lock.json\n  - package.json\n\nDiff:\ndiff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml\nindex d7a8d33..00b0ba3 100644\n--- a/.github/workflows/deploy-docs.yml\n+++ b/.github/workflows/deploy-docs.yml\n@@ -30,14 +30,11 @@ jobs:\n         with:\n           node-version: 22\n           \n-      - name: Setup pnpm\n-        uses: pnpm/action-setup@v4\n-        \n       - name: Install dependencies\n-        run: pnpm install --frozen-lockfile --strict-peer-dependencies\n+        run: npm ci\n         \n       - name: Build library\n-        run: pnpm run build\n+        run: npm run build\n         \n       - name: Setup Pages\n         uses: actions/configure-pages@v5\n@@ -46,13 +43,13 @@ jobs:\n         run: |\n           # Change to docs directory and install dependencies\n           cd docs\n-          pnpm install --frozen-lockfile\n+          npm ci\n           \n           # Copy README.md to public directory so it can be fetched\n           cp ../README.md public/\n           \n           # Build the Vite documentation site\n-          pnpm run build\n+          npm run build\n         \n       - name: Upload artifact\n         uses: actions/upload-pages-artifact@v3\ndiff --git a/.github/workflows/test.yml b/.github/workflows/test.yml\nindex 1b1c8b4..7e1cb64 100644\n--- a/.github/workflows/test.yml\n+++ b/.github/workflows/test.yml\n@@ -18,11 +18,10 @@ jobs:\n       - uses: actions/setup-node@v4\n         with:\n           node-version: 22\n-      - uses: pnpm/action-setup@v4\n-      - run: pnpm install --frozen-lockfile --strict-peer-dependencies\n-      - run: pnpm run lint\n-      - run: pnpm run build\n-      - run: pnpm test\n+      - run: npm ci\n+      - run: npm run lint\n+      - run: npm run build\n+      - run: npm test\n       - uses: codecov/codecov-action@v5\n         with:\n           slug: theunwalked/dreadcabinet\ndiff --git a/README.md b/README.md\nindex 931ab1d..9ed542d 100644\n--- a/README.md\n+++ b/README.md\n@@ -24,9 +24,6 @@ npm install @theunwalked/dreadcabinet\n ```bash\n # yarn\n yarn add @theunwalked/dreadcabinet\n-\n-# pnpm\n-pnpm add @theunwalked/dreadcabinet\n ```\n \n ## Quick Start\n@@ -79,19 +76,19 @@ my-app \\\n \n For complete documentation, including detailed configuration options, advanced usage examples, and integration guides, visit:\n \n-**[📖 DreadCabinet Documentation](https://semicolonambulance.github.io/dreadcabinet/)**\n+**[📖 DreadCabinet Documentation](https://utilarium.github.io/dreadcabinet/)**\n \n ### Quick Links\n \n-- [Getting Started Guide](https://semicolonambulance.github.io/dreadcabinet/#getting-started)\n-- [CLI Options Reference](https://semicolonambulance.github.io/dreadcabinet/#cli-options)\n-- [Configuration Files](https://semicolonambulance.github.io/dreadcabinet/#configuration-files)\n-- [Advanced Usage](https://semicolonambulance.github.io/dreadcabinet/#advanced-usage)\n-- [API Reference](https://semicolonambulance.github.io/dreadcabinet/#api-reference)\n+- [Getting Started Guide](https://utilarium.github.io/dreadcabinet/#getting-started)\n+- [CLI Options Reference](https://utilarium.github.io/dreadcabinet/#cli-options)\n+- [Configuration Files](https://utilarium.github.io/dreadcabinet/#configuration-files)\n+- [Advanced Usage](https://utilarium.github.io/dreadcabinet/#advanced-usage)\n+- [API Reference](https://utilarium.github.io/dreadcabinet/#api-reference)\n \n ## Contributing\n \n-We welcome contributions! Please see our [Contributing Guide](https://semicolonambulance.github.io/dreadcabinet/#contributing) for details.\n+We welcome contributions! Please see our [Contributing Guide](https://utilarium.github.io/dreadcabinet/#contributing) for details.\n \n ## License\n \ndiff --git a/docs/public/contributing.md b/docs/public/contributing.md\nindex a73a913..52112ab 100644\n--- a/docs/public/contributing.md\n+++ b/docs/public/contributing.md\n@@ -14,7 +14,7 @@ We welcome contributions to DreadCabinet! This guide will help you get started w\n \n 1. **Fork and clone the repository**:\n    ```bash\n-   git clone https://github.com/tobrien/dreadcabinet.git\n+   git clone https://github.com/utilarium/dreadcabinet.git\n    cd dreadcabinet\n    ```\n \ndiff --git a/docs/public/faq.md b/docs/public/faq.md\nindex 8305fce..c52a15b 100644\n--- a/docs/public/faq.md\n+++ b/docs/public/faq.md\n@@ -278,7 +278,7 @@ Check these common issues:\n \n ### How do I report bugs or request features?\n \n-1. Check the [GitHub issues](https://github.com/tobrien/dreadcabinet/issues) for existing reports\n+1. Check the [GitHub issues](https://github.com/utilarium/dreadcabinet/issues) for existing reports\n 2. Create a new issue with:\n    - Clear description of the problem or feature request\n    - Code examples demonstrating the issue\ndiff --git a/docs/src/App.tsx b/docs/src/App.tsx\nindex d2aed8a..36817d3 100644\n--- a/docs/src/App.tsx\n+++ b/docs/src/App.tsx\n@@ -137,7 +137,7 @@ function App() {\n                     </div>\n                     <p className=\"subtitle\">Organize Your Digital Chaos</p>\n                     <div className=\"header-links\">\n-                        <a href=\"https://github.com/tobrien/dreadcabinet\" target=\"_blank\" rel=\"noopener noreferrer\">\n+                        <a href=\"https://github.com/utilarium/dreadcabinet\" target=\"_blank\" rel=\"noopener noreferrer\">\n                             GitHub\n                         </a>\n                         <a href=\"https://www.npmjs.com/package/@theunwalked/dreadcabinet\" target=\"_blank\" rel=\"noopener noreferrer\">\ndiff --git a/guide/architecture.md b/guide/architecture.md\nnew file mode 100644\nindex 0000000..38cb2e1\n--- /dev/null\n+++ b/guide/architecture.md\n@@ -0,0 +1,60 @@\n+# Architecture\n+\n+**Purpose**: High-level overview of the internal design of `dreadcabinet`.\n+\n+## Module Structure\n+\n+The project is organized into distinct logical modules:\n+\n+*   **`src/dreadcabinet.ts`**: Main entry point. Exports the `create` factory, types, schemas, and constants.\n+*   **`src/configure.ts`**: Handles Commander.js integration and CLI option configuration based on enabled features.\n+*   **`src/read.ts`**: Reads CLI arguments and converts them to partial configuration.\n+*   **`src/defaults.ts`**: Applies default values to partial configuration based on enabled features.\n+*   **`src/validate.ts`**: Validates final configuration against allowed options using Zod.\n+*   **`src/operate.ts`**: Creates the Operator interface for file processing.\n+*   **`src/output.ts`**: Constructs output directory paths and filenames based on dates and structure.\n+*   **`src/input/`**:\n+    *   **`input.ts`**: Factory for input processing.\n+    *   **`process.ts`**: Core file iteration logic with concurrency support.\n+    *   **`structured.ts`**: Handles structured input (date-organized directories).\n+    *   **`unstructured.ts`**: Handles flat/recursive input directories.\n+*   **`src/util/`**:\n+    *   **`dates.ts`**: Date formatting and timezone handling using dayjs.\n+    *   **`storage.ts`**: Abstracted filesystem operations.\n+*   **`src/error/`**: Custom error types (`ArgumentError`).\n+*   **`src/constants.ts`**: Default values, date formats, and allowed options.\n+*   **`src/logger.ts`**: Logger wrapper for consistent logging interface.\n+\n+## Data Flow\n+\n+1.  **Initialization**: User calls `create()` with defaults, allowed options, and features.\n+2.  **Configuration**: `configure()` adds CLI flags to Commander based on enabled features.\n+3.  **Read Phase**: `read()` extracts values from CLI arguments.\n+4.  **Defaults Phase**: `applyDefaults()` fills in missing values from defaults.\n+5.  **Validation Phase**: `validate()` checks config against allowed values.\n+6.  **Operation Phase**: `operate()` creates an Operator with:\n+    *   `process(callback)`: Iterates over input files, calling callback for each.\n+    *   `constructFilename()`: Generates output filenames.\n+    *   `constructOutputDirectory()`: Creates date-based directory paths.\n+\n+## Key Types\n+\n+```typescript\n+// Filesystem structure options\n+type FilesystemStructure = 'none' | 'year' | 'month' | 'day';\n+\n+// Filename components\n+type FilenameOption = 'date' | 'time' | 'subject';\n+\n+// Feature flags control which CLI options are added\n+type Feature = 'input' | 'output' | 'structured-output' | 'structured-input' | 'extensions';\n+```\n+\n+## Design Decisions\n+\n+*   **Feature Flags**: CLI options are conditionally added based on `features` array. This allows building focused tools without exposing irrelevant options.\n+*   **Non-Destructive**: The library only reads from input and writes to output. Original files are never modified or deleted.\n+*   **Timezone-Aware**: All date operations go through `dayjs` with timezone support for consistent cross-timezone behavior.\n+*   **Callback Pattern**: The `process()` method uses a callback pattern, giving consumers full control over what happens to each file.\n+*   **Testability**: The `storage` module abstracts filesystem calls for easy mocking.\n+\ndiff --git a/guide/configuration.md b/guide/configuration.md\nnew file mode 100644\nindex 0000000..3680b16\n--- /dev/null\n+++ b/guide/configuration.md\n@@ -0,0 +1,132 @@\n+# Configuration Reference\n+\n+**Purpose**: Detailed guide on configuring `dreadcabinet` instances and understanding available options.\n+\n+## Instance Configuration (`create`)\n+\n+The `create` function accepts an options object that controls behavior:\n+\n+### Options\n+\n+| Option | Type | Required | Description |\n+| :--- | :--- | :--- | :--- |\n+| `defaults` | `DefaultOptions` | No | Default values for configuration. |\n+| `allowed` | `AllowedOptions` | No | Restrict valid values for options. |\n+| `features` | `Feature[]` | No | Array of enabled features. |\n+| `addDefaults` | `boolean` | No | Whether to add defaults to CLI help text. |\n+| `logger` | `Logger` | No | Custom logger implementation. |\n+\n+### Default Options\n+\n+```typescript\n+interface DefaultOptions {\n+  timezone?: string;              // Default: 'Etc/UTC'\n+  recursive?: boolean;            // Default: false\n+  inputDirectory?: string;        // Default: './'\n+  inputStructure?: FilesystemStructure;    // Default: 'month'\n+  inputFilenameOptions?: FilenameOption[]; // Default: ['date', 'subject']\n+  outputDirectory?: string;       // Default: './'\n+  outputStructure?: FilesystemStructure;   // Default: 'month'\n+  outputFilenameOptions?: FilenameOption[];// Default: ['date', 'subject']\n+  extensions?: string[];          // Default: ['md']\n+  startDate?: string;             // Optional date filter\n+  endDate?: string;               // Optional date filter\n+  limit?: number;                 // Limit files processed\n+  concurrency?: number;           // Default: 1\n+}\n+```\n+\n+### Allowed Options\n+\n+Restrict which values users can specify:\n+\n+```typescript\n+interface AllowedOptions {\n+  inputStructures?: FilesystemStructure[];   // Default: ['none', 'year', 'month', 'day']\n+  inputFilenameOptions?: FilenameOption[];   // Default: ['date', 'time', 'subject']\n+  outputStructures?: FilesystemStructure[];  // Default: ['none', 'year', 'month', 'day']\n+  outputFilenameOptions?: FilenameOption[];  // Default: ['date', 'time', 'subject']\n+  extensions?: string[];                      // Default: ['md', 'txt']\n+}\n+```\n+\n+## Features\n+\n+Features control which CLI options are exposed:\n+\n+| Feature | CLI Options Added |\n+| :--- | :--- |\n+| `input` | `-r/--recursive`, `-i/--input-directory`, `--limit`, `--concurrency` |\n+| `output` | `-o/--output-directory` |\n+| `structured-output` | `--output-structure`, `--output-filename-options` |\n+| `structured-input` | `--input-structure`, `--input-filename-options`, `--start`, `--end` |\n+| `extensions` | `--extensions` |\n+\n+Default features: `['output', 'structured-output', 'input', 'extensions']`\n+\n+## Filesystem Structures\n+\n+Controls how files are organized into directories:\n+\n+| Structure | Directory Pattern | Example |\n+| :--- | :--- | :--- |\n+| `none` | Flat | `./output/` |\n+| `year` | By year | `./output/2025/` |\n+| `month` | By year/month | `./output/2025/1/` |\n+| `day` | By year/month/day | `./output/2025/1/15/` |\n+\n+## Filename Options\n+\n+Controls components included in generated filenames:\n+\n+| Option | Description | Example Component |\n+| :--- | :--- | :--- |\n+| `date` | Include date (format depends on structure) | `1-15` (if month structure) |\n+| `time` | Include time (HHmm format) | `1430` |\n+| `subject` | Include sanitized subject | `meeting_notes` |\n+\n+Example filename with `['date', 'time', 'subject']`: `1-15-1430-abc123-md-meeting_notes`\n+\n+## Example Configurations\n+\n+### Simple File Organizer\n+\n+```typescript\n+const instance = DreadCabinet.create({\n+  defaults: {\n+    inputDirectory: './inbox',\n+    outputDirectory: './archive',\n+    outputStructure: 'month',\n+    extensions: ['md', 'txt'],\n+  },\n+  features: ['input', 'output', 'structured-output', 'extensions']\n+});\n+```\n+\n+### High-Performance Batch Processor\n+\n+```typescript\n+const instance = DreadCabinet.create({\n+  defaults: {\n+    concurrency: 10,\n+    recursive: true,\n+    extensions: ['jpg', 'png', 'gif'],\n+  },\n+  features: ['input', 'output', 'structured-output', 'extensions']\n+});\n+```\n+\n+### Date-Range Filter\n+\n+```typescript\n+const instance = DreadCabinet.create({\n+  defaults: {\n+    inputStructure: 'day',\n+    outputStructure: 'month',\n+  },\n+  features: ['input', 'output', 'structured-input', 'structured-output']\n+});\n+\n+// Then use --start and --end flags to filter\n+```\n+\ndiff --git a/guide/development.md b/guide/development.md\nnew file mode 100644\nindex 0000000..2e00676\n--- /dev/null\n+++ b/guide/development.md\n@@ -0,0 +1,110 @@\n+# Development Guide\n+\n+**Purpose**: Instructions for contributing to and developing `dreadcabinet`.\n+\n+## Setup\n+\n+1.  **Clone Repository**: `git clone https://github.com/utilarium/dreadcabinet.git`\n+2.  **Install Dependencies**: `npm install`\n+3.  **Build**: `npm run build`\n+\n+## Testing\n+\n+We use **Vitest** for testing.\n+\n+*   **Run All Tests**: `npm test`\n+*   **Unit Tests Only**: `npm run test:coverage`\n+*   **README Doc Tests**: `npm run test:readme` (requires build first)\n+\n+### Testing Strategy\n+\n+*   **Unit Tests**: Located in `tests/`. We aim for high coverage.\n+    *   `tests/input/`: Tests for input processing (structured/unstructured).\n+    *   `tests/util/`: Tests for utilities (dates, storage).\n+    *   `tests/error/`: Tests for custom error classes.\n+*   **Doc Tests**: README code examples are tested via `doccident` to ensure they stay accurate.\n+*   **Mocking**: We use `vi.mock` for filesystem operations to avoid side effects.\n+\n+### Running Tests\n+\n+```bash\n+# Full test suite (requires build)\n+npm run precommit\n+\n+# Just unit tests\n+npm run test:coverage\n+\n+# Watch mode during development\n+npx vitest\n+```\n+\n+## Linting & Formatting\n+\n+*   **Lint**: `npm run lint`\n+*   **Fix**: `npm run lint:fix`\n+\n+We use ESLint with strict TypeScript rules.\n+\n+## Build\n+\n+```bash\n+npm run build\n+```\n+\n+This runs lint, TypeScript type checking, and Vite build to produce:\n+- `dist/dreadcabinet.js` (ESM)\n+- `dist/dreadcabinet.cjs` (CommonJS)\n+- `dist/dreadcabinet.d.ts` (TypeScript declarations)\n+\n+## Project Structure\n+\n+```\n+src/\n+├── dreadcabinet.ts      # Main entry, types, factory\n+├── configure.ts         # CLI option setup\n+├── read.ts              # CLI args parsing\n+├── defaults.ts          # Default value application\n+├── validate.ts          # Config validation\n+├── operate.ts           # Operator factory\n+├── output.ts            # Output path/filename generation\n+├── constants.ts         # Defaults and allowed values\n+├── logger.ts            # Logger wrapper\n+├── input/\n+│   ├── input.ts         # Input factory\n+│   ├── process.ts       # File iteration\n+│   ├── structured.ts    # Date-organized input\n+│   └── unstructured.ts  # Flat/recursive input\n+├── util/\n+│   ├── dates.ts         # Date/timezone utilities\n+│   └── storage.ts       # Filesystem abstraction\n+└── error/\n+    └── ArgumentError.ts # Custom error types\n+```\n+\n+## Adding Features\n+\n+1.  **Feature Flag**: Add to `Feature` type in `dreadcabinet.ts`.\n+2.  **CLI Options**: Add to `configure.ts` with feature check.\n+3.  **Read**: Update `read.ts` to handle new arguments.\n+4.  **Defaults**: Update `defaults.ts` for new default values.\n+5.  **Validation**: Update `validate.ts` if new validation needed.\n+6.  **Constants**: Add defaults to `constants.ts`.\n+7.  **Tests**: Write tests for all new functionality.\n+8.  **Documentation**: Update `guide/` and README.\n+\n+## Release Process\n+\n+1.  Update version in `package.json`.\n+2.  Run `npm run precommit` (build + all tests).\n+3.  Commit and push to `working` branch.\n+4.  Create PR to `main`.\n+5.  After merge, create GitHub release to trigger npm publish.\n+\n+## Code Style\n+\n+*   **TypeScript**: Strict mode enabled.\n+*   **Exports**: Prefer named exports over default exports.\n+*   **Async**: Use async/await consistently.\n+*   **Errors**: Use custom error classes for specific error types.\n+*   **Logging**: Use the logger interface, never `console.log` directly in library code.\n+\ndiff --git a/guide/index.md b/guide/index.md\nnew file mode 100644\nindex 0000000..70d1faa\n--- /dev/null\n+++ b/guide/index.md\n@@ -0,0 +1,62 @@\n+# AI Agent Guide: dreadcabinet\n+\n+**Role**: You are an AI assistant tasked with understanding, integrating, or extending `dreadcabinet` file organization capabilities in applications.\n+\n+**Goal**: Provide a comprehensive understanding of `dreadcabinet`'s capabilities, architecture, and usage patterns to facilitate correct implementation and extension.\n+\n+## Core Capabilities\n+\n+`dreadcabinet` is a file organization library for TypeScript/Node.js applications. It processes files from input directories and organizes them into structured output directories based on dates and metadata.\n+\n+*   **Date-Based Organization**: Place files into folders by year, month, or day (or flat structure).\n+*   **Flexible Filename Generation**: Include date, time, and subject in generated filenames.\n+*   **Timezone Support**: Convert timestamps to specific timezones for consistent naming.\n+*   **Concurrent Processing**: Process multiple files in parallel for improved performance.\n+*   **Extension Filtering**: Restrict processing to specific file types.\n+*   **Non-Destructive**: Original files remain untouched; only copies are created.\n+\n+## Quick Start Context\n+\n+When analyzing or generating code using `dreadcabinet`, keep these patterns in mind:\n+\n+1.  **Create Instance**: Use `create()` with defaults and feature flags.\n+2.  **Integrate CLI**: Use `.configure(program)` to bind to Commander.js.\n+3.  **Read & Validate**: Use `.read()`, `.applyDefaults()`, and `.validate()`.\n+4.  **Process Files**: Use the operator's `.process()` callback pattern.\n+\n+```typescript\n+import { Command } from 'commander';\n+import * as DreadCabinet from '@theunwalked/dreadcabinet';\n+\n+const instance = DreadCabinet.create({\n+  defaults: {\n+    timezone: 'America/New_York',\n+    extensions: ['md', 'txt'],\n+    outputStructure: 'month',\n+    outputDirectory: './organized',\n+  }\n+});\n+\n+const program = new Command();\n+await instance.configure(program);\n+program.parse();\n+\n+const config = await instance.read(program.opts());\n+const finalConfig = instance.applyDefaults(config);\n+await instance.validate(finalConfig);\n+\n+const operator = await instance.operate(finalConfig);\n+await operator.process(async (file) => {\n+  // Your file processing logic\n+});\n+```\n+\n+## Documentation Structure\n+\n+This guide directory contains specialized documentation for different aspects of the system:\n+\n+*   [Configuration](./configuration.md): Deep dive into configuration options, features, and defaults.\n+*   [Usage Patterns](./usage.md): Common patterns for CLI integration and file processing.\n+*   [Architecture](./architecture.md): Internal design, module structure, and data flow.\n+*   [Development](./development.md): Guide for contributing to `dreadcabinet` itself.\n+\ndiff --git a/guide/usage.md b/guide/usage.md\nnew file mode 100644\nindex 0000000..aea54f9\n--- /dev/null\n+++ b/guide/usage.md\n@@ -0,0 +1,166 @@\n+# Usage Patterns\n+\n+**Purpose**: Common patterns for integrating `dreadcabinet` into applications.\n+\n+## CLI Integration (Commander.js)\n+\n+`dreadcabinet` is designed to work seamlessly with `commander`.\n+\n+```typescript\n+import { Command } from 'commander';\n+import * as DreadCabinet from '@theunwalked/dreadcabinet';\n+\n+// 1. Create instance with your defaults\n+const manager = DreadCabinet.create({\n+  defaults: {\n+    timezone: 'America/New_York',\n+    outputStructure: 'month',\n+  }\n+});\n+\n+// 2. Setup Commander\n+const program = new Command();\n+program.name('my-organizer').version('1.0.0');\n+\n+// 3. Configure (adds CLI options based on features)\n+await manager.configure(program);\n+\n+// 4. Parse CLI args\n+program.parse();\n+const options = program.opts();\n+\n+// 5. Read, apply defaults, validate\n+const config = await manager.read(options);\n+const finalConfig = manager.applyDefaults(config);\n+await manager.validate(finalConfig);\n+\n+// 6. Process files\n+const operator = await manager.operate(finalConfig);\n+await operator.process(async (file) => {\n+  console.log(`Processing: ${file}`);\n+});\n+```\n+\n+## File Processing Patterns\n+\n+### Basic File Copy\n+\n+```typescript\n+import fs from 'fs/promises';\n+import path from 'path';\n+\n+await operator.process(async (file) => {\n+  const createDate = new Date(); // Or extract from file metadata\n+  const hash = crypto.randomBytes(4).toString('hex');\n+  const ext = path.extname(file).slice(1);\n+  \n+  const outputDir = await operator.constructOutputDirectory(createDate);\n+  const filename = await operator.constructFilename(createDate, ext, hash, {\n+    subject: path.basename(file, path.extname(file))\n+  });\n+  \n+  const outputPath = path.join(outputDir, `${filename}.${ext}`);\n+  await fs.copyFile(file, outputPath);\n+});\n+```\n+\n+### With Transformation\n+\n+```typescript\n+await operator.process(async (file) => {\n+  // Read and transform content\n+  const content = await fs.readFile(file, 'utf-8');\n+  const transformed = processContent(content);\n+  \n+  // Generate output location\n+  const createDate = extractDateFromContent(content);\n+  const outputDir = await operator.constructOutputDirectory(createDate);\n+  const filename = await operator.constructFilename(createDate, 'md', hash);\n+  \n+  // Write transformed content\n+  await fs.writeFile(path.join(outputDir, `${filename}.md`), transformed);\n+});\n+```\n+\n+### With Date Range Filtering\n+\n+When using `structured-input` feature, filter files by date:\n+\n+```typescript\n+await operator.process(\n+  async (file, date) => {\n+    console.log(`File: ${file}, Date: ${date}`);\n+  },\n+  {\n+    start: new Date('2025-01-01'),\n+    end: new Date('2025-01-31')\n+  }\n+);\n+```\n+\n+### Concurrent Processing\n+\n+Set concurrency for parallel processing:\n+\n+```typescript\n+const instance = DreadCabinet.create({\n+  defaults: {\n+    concurrency: 5, // Process 5 files simultaneously\n+  }\n+});\n+```\n+\n+Or via CLI: `--concurrency 5`\n+\n+## Custom Logger\n+\n+Provide your own logger for integration with existing logging systems:\n+\n+```typescript\n+import winston from 'winston';\n+\n+const winstonLogger = winston.createLogger({ /* ... */ });\n+\n+const instance = DreadCabinet.create({\n+  logger: {\n+    debug: (msg, ...args) => winstonLogger.debug(msg, ...args),\n+    info: (msg, ...args) => winstonLogger.info(msg, ...args),\n+    warn: (msg, ...args) => winstonLogger.warn(msg, ...args),\n+    error: (msg, ...args) => winstonLogger.error(msg, ...args),\n+    verbose: (msg, ...args) => winstonLogger.verbose(msg, ...args),\n+    silly: (msg, ...args) => winstonLogger.silly(msg, ...args),\n+  }\n+});\n+```\n+\n+Or set it after creation:\n+\n+```typescript\n+instance.setLogger(myLogger);\n+```\n+\n+## Restricting Options\n+\n+Limit what users can specify via CLI:\n+\n+```typescript\n+const instance = DreadCabinet.create({\n+  allowed: {\n+    extensions: ['md'],  // Only markdown files\n+    outputStructures: ['month', 'day'],  // No 'none' or 'year'\n+  }\n+});\n+```\n+\n+Validation will fail if users try to use disallowed values.\n+\n+## Hiding Defaults in Help\n+\n+By default, CLI help shows default values. To hide them (useful for dynamic defaults):\n+\n+```typescript\n+const instance = DreadCabinet.create({\n+  addDefaults: false,  // Defaults shown as \"(default: value)\" in description\n+});\n+```\n+\ndiff --git a/package.json b/package.json\nindex c320827..bdd5750 100644\n--- a/package.json\n+++ b/package.json\n@@ -7,8 +7,9 @@\n     \"type\": \"module\",\n     \"repository\": {\n         \"type\": \"git\",\n-        \"url\": \"git+https://github.com/tobrien/dreadcabinet.git\"\n+        \"url\": \"git+https://github.com/utilarium/dreadcabinet.git\"\n     },\n+    \"homepage\": \"https://utilarium.github.io/dreadcabinet/\",\n     \"exports\": {\n         \".\": {\n             \"types\": \"./dist/dreadcabinet.d.ts\",\n@@ -21,11 +22,12 @@\n         \"start\": \"dist/main.js\",\n         \"dev\": \"vite build --watch\",\n         \"watch\": \"npm run dev\",\n-        \"test\": \"npm run test:readme && npm run test:coverage\",\n+        \"test\": \"npm run test:coverage && npm run test:readme\",\n         \"test:coverage\": \"vitest run --coverage\",\n         \"test:readme\": \"doccident -c .markdown-doctest-setup.mjs README.md\",\n         \"lint\": \"eslint . --ext .ts\",\n         \"lint:fix\": \"eslint . --ext .ts --fix\",\n+        \"precommit\": \"npm run build && npm run test\",\n         \"clean\": \"rm -rf dist\",\n         \"prepublishOnly\": \"npm run clean && npm run build\"\n     },\n@@ -48,7 +50,7 @@\n         \"@babel/plugin-transform-modules-commonjs\": \"^7.27.1\",\n         \"@babel/plugin-transform-typescript\": \"^7.28.0\",\n         \"@babel/preset-typescript\": \"^7.27.1\",\n-        \"@doccident/doccident\": \"^0.0.1\",\n+        \"@doccident/doccident\": \"^0.0.7\",\n         \"@eslint/eslintrc\": \"^3.3.1\",\n         \"@eslint/js\": \"^9.30.1\",\n         \"@rollup/plugin-replace\": \"^6.0.2\",\n\n\nRecent commit history for context:\ncommit efae4042901387794b550dc151ef3d61bfa8eaa7\nAuthor: Tim O'Brien <tobrien@discursive.com>\nDate:   Wed Jan 7 20:21:54 2026 -0800\n\n    SUGGESTED_SPLITS:\n    Split 1:\n    Files: [.github/workflows/dependency-review.yml, .github/workflows/test.yml, .github/workflows/npm-publish.yml, .github/workflows/pnpm-publish.yml]\n    Rationale: CI/CD behavior changes (new security check, test trigger changes, and switching the release publish workflow to npm) are reviewable together and independent of docs/metadata updates.\n    Message: |\n      ci: add dependency review and publish releases via npm\n    \n      - Add dependency-review workflow with PR summary comments\n      - Run test workflow on pull requests to main/working (instead of push)\n      - Replace pnpm-based publish workflow with npm publish using npm ci and NPM_TOKEN\n    \n    Split 2:\n    Files: [package.json, pnpm-lock.yaml, docs/pnpm-lock.yaml, pnpm-workspace.yaml]\n    Rationale: Package manager/config changes (scripts/overrides/workspace + lockfile updates) should be reviewed as a cohesive “tooling” change.\n    Message: |\n      chore: prefer npm scripts and drop pnpm workspace config\n    \n      - Switch build/test/watch/prepublish scripts from pnpm to npm\n      - Move wrap-ansi override to top-level overrides\n      - Remove pnpm-workspace.yaml\n      - Update pnpm lockfiles to match dependency resolution\n    \n    Split 3:\n    Files: [LICENSE, README.md, docs/public/contributing.md, docs/public/faq.md, docs/src/App.tsx]\n    Rationale: Ownership/branding and documentation link updates are user-facing but don’t affect runtime/CI behavior; easier to review separately.\n    Message: |\n      docs: update repo links and attribution to tobrien\n    \n      - Update GitHub URLs across docs/site from SemicolonAmbulance to tobrien\n      - Update contributing guide to use npm commands\n      - Update LICENSE/README and docs footer attribution\n    \n    Split 4:\n    Files: [.DS_Store, src/.DS_Store, tests/.DS_Store]\n    Rationale: Accidental OS-generated binaries shouldn’t ship; keep noise out of functional commits.\n    Message: |\n      chore: remove accidentally committed .DS_Store files\n\ncommit 591887a67d0cc1e6845c8b4a07a990c23788efb3\nAuthor: SemicolonAmbulance <SemicolonAmbulance@proton.me>\nDate:   Thu Jul 10 08:17:14 2025 -0700\n\n    0.0.10\n    \n     (#37)\n    \n    * Add empty pnpm-workspace.yaml to initialize workspace support and enable pnpm to treat the repository as a monorepo root.\n    \n    * Remove moment-timezone and related timezone dependencies; provide static IANA timezone list and use dayjs exclusively for timezone support\n    \n    Removes the moment-timezone dependency along with associated packages (luxon, winston, js-yaml and their types) from the codebase and updates `.npmignore` to exclude additional config and docs files from npm package distribution. Introduces a static list of IANA timezone names directly in `src/util/dates.ts` to replace runtime timezone name queries, and updates the `validTimezones()` function to return this static array using only dayjs for all timezone-related operations. This simplifies dependencies, reduces bundle size, and eliminates dynamic timezone database requirements while maintaining support for timezone-aware date manipulation.\n    \n    * Bump dependencies in package.json: update packageManager to pnpm@10.13.1, upgrade zod to 4.0.2, @swc/core to 1.12.11, @theunwalked/cardigantime to 0.0.16, @types/node to 24.0.12, @typescript-eslint/eslint-plugin and parser to 8.36.0, and vite to 7.0.4. These updates address bug fixes, compatibility improvements, and ensure alignment with the latest ecosystem standards.\n    \n    * No staged changes detected; commit aborted.\n    \n    * 0.0.10\n\ncommit 468c3f60c6455ea49870121bc04df0f36ad49a21\nAuthor: SemicolonAmbulance <SemicolonAmbulance@proton.me>\nDate:   Thu Jul 3 07:32:19 2025 -0700\n\n    0.0.9\n    \n     (#33)\n    \n    * Removes the empty pnpm-workspace.yaml file from the project root, eliminating unused workspace configuration and restoring default pnpm behavior for package management.\n    \n    * 0.0.9\n\n\nAnalyze these changes and write a clear commit message. Consider:\n- What problem does this solve?\n- How do the changes work together?\n- Should this be one commit or multiple?\n\nIf context information is provided, use it only if relevant to these specific changes.\nDon't force connections that don't exist - if context doesn't apply to this package,\nsimply ignore it and focus on the actual changes.\n\nInvestigate as needed to write an accurate, helpful message."
+  },
+  {
+    "role": "assistant",
+    "content": "COMMIT_MESSAGE:\nchore: standardize on npm in CI and refresh docs/metadata for utilarium\n\n- Switch GitHub Actions (tests + docs deploy) from pnpm to `npm ci`/`npm run` to match the npm lockfile workflow\n- Update package metadata (repository/homepage) and documentation links to the `utilarium/dreadcabinet` URLs\n- Add `precommit` script and reorder `test` to run coverage before README doctests; bump `@doccident/doccident` and update lockfile\n- Add `guide/` docs (architecture/configuration/usage/development) to document internal structure and common integration patterns"
+  }
+]
+```
+
+</details>
+
+## Generated Commit Message
+
+```
+chore: standardize on npm in CI and refresh docs/metadata for utilarium
+
+- Switch GitHub Actions (tests + docs deploy) from pnpm to `npm ci`/`npm run` to match the npm lockfile workflow
+- Update package metadata (repository/homepage) and documentation links to the `utilarium/dreadcabinet` URLs
+- Add `precommit` script and reorder `test` to run coverage before README doctests; bump `@doccident/doccident` and update lockfile
+- Add `guide/` docs (architecture/configuration/usage/development) to document internal structure and common integration patterns
+```