@aladac/hu 0.1.0-a1

package/doc/claude-code/directory-structure.md

@@ -0,0 +1,246 @@
+---
+source: https://idsc2025.substack.com/p/the-complete-technical-guide-to-claude
+additional_sources:
+  - https://code.claude.com/docs/en/memory
+  - https://www.vincentschmalbach.com/migrate-claude-code-sessions-to-a-new-computer/
+fetched: 2026-01-13
+---
+
+# Claude Code Directory Structure
+
+The `~/.claude/` directory contains all local state, configuration, and data for Claude Code.
+
+## Directory Overview
+
+```
+~/.claude/
+├── CLAUDE.md              # User memory/instructions (global)
+├── settings.json          # Global configuration
+├── settings.local.json    # Local overrides (not synced)
+├── history.jsonl          # Session index (metadata only)
+│
+├── projects/              # Conversation transcripts by project
+│   └── -Users-chi-myproject/
+│       └── {session-uuid}.jsonl
+│
+├── commands/              # Custom slash commands
+│   └── mycommand.md
+│
+├── plans/                 # Saved implementation plans
+│   └── {adjective}-{verb}-{noun}.md
+│
+├── plugins/               # Installed plugins
+│   └── installed_plugins.json
+│
+├── todos/                 # Todo lists per session
+│   └── {session-uuid}.json
+│
+├── cache/                 # Cached data (changelog, etc.)
+├── debug/                 # Debug logs per session
+├── documents/             # Global document store
+├── file-history/          # File edit history per session
+├── paste-cache/           # Clipboard paste cache
+├── session-env/           # Persisted env vars per session
+├── shell-snapshots/       # Shell environment snapshots
+├── statsig/               # Feature flags cache
+└── telemetry/             # Usage telemetry
+```
+
+## Key Directories
+
+### projects/
+
+**Purpose**: Stores all conversation transcripts.
+
+**Path encoding**: `/Users/chi/myproject` → `-Users-chi-myproject`
+
+**Format**: JSONL (one JSON object per line)
+
+```jsonl
+{"type":"summary","summary":"Topic description","leafUuid":"..."}
+{"type":"user","message":{"role":"user","content":"..."},"uuid":"...","parentUuid":"..."}
+{"type":"assistant","message":{"role":"assistant","content":[...]},"uuid":"...","parentUuid":"..."}
+```
+
+**Key fields**:
+- `uuid` / `parentUuid`: Thread linking
+- `sessionId`: Session identifier
+- `cwd`: Working directory at time of message
+- `isSidechain`: Parallel thread flag
+- `costUSD` / `durationMs`: Performance metrics
+
+### todos/
+
+**Purpose**: Per-session todo lists.
+
+**Naming**: `{session-uuid}.json` or `{session-uuid}-agent-{agent-uuid}.json`
+
+**Format**:
+```json
+[
+  {"content": "Task description", "status": "pending|in_progress|completed", "activeForm": "..."}
+]
+```
+
+### file-history/
+
+**Purpose**: Stores file versions for undo/diff.
+
+**Structure**: `{session-uuid}/{filename}` with version history.
+
+### session-env/
+
+**Purpose**: Environment variables persisted via `SessionStart` hooks.
+
+**Usage**: Write to `$CLAUDE_ENV_FILE` in hooks to persist env vars.
+
+### shell-snapshots/
+
+**Purpose**: Captures shell environment (functions, aliases) for command execution.
+
+**Format**: Executable shell scripts that recreate the environment.
+
+### plans/
+
+**Purpose**: Saved implementation plans from plan mode.
+
+**Naming**: `{adjective}-{verb}-{noun}.md` (e.g., `crispy-crafting-pnueli.md`)
+
+### statsig/
+
+**Purpose**: Feature flag cache and evaluation state.
+
+**Files**:
+- `statsig.cached.evaluations.*` - Cached feature flags
+- `statsig.stable_id.*` - Persistent user ID
+- `statsig.session_id.*` - Current session tracking
+
+### debug/
+
+**Purpose**: Debug logs per session.
+
+**Naming**: `{session-uuid}.txt`
+
+## Configuration Files
+
+### settings.json
+
+Global settings applied to all projects.
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash", "Read", "Write"],
+    "deny": []
+  },
+  "hooks": { ... },
+  "enabledPlugins": { ... }
+}
+```
+
+### settings.local.json
+
+Local overrides (not committed to version control).
+
+```json
+{
+  "enableAllProjectMcpServers": false
+}
+```
+
+## Session Data Format
+
+### JSONL Message Types
+
+**Summary** (session start):
+```json
+{"type": "summary", "summary": "Topic", "leafUuid": "last-msg-uuid"}
+```
+
+**User message**:
+```json
+{
+  "type": "user",
+  "userType": "external",
+  "message": {"role": "user", "content": "..."},
+  "uuid": "...",
+  "parentUuid": "...",
+  "timestamp": "2026-01-13T20:00:00.000Z",
+  "cwd": "/working/directory",
+  "sessionId": "...",
+  "version": "1.0.24"
+}
+```
+
+**Assistant message**:
+```json
+{
+  "type": "assistant",
+  "message": {
+    "id": "msg_01XYZ...",
+    "role": "assistant",
+    "model": "claude-sonnet-4-20250514",
+    "content": [...],
+    "usage": {
+      "input_tokens": 1234,
+      "output_tokens": 567,
+      "cache_creation_input_tokens": 890,
+      "cache_read_input_tokens": 2345
+    }
+  },
+  "costUSD": 0.01234,
+  "durationMs": 5678,
+  "uuid": "...",
+  "parentUuid": "..."
+}
+```
+
+**Tool use** (in assistant content):
+```json
+{
+  "type": "tool_use",
+  "id": "toolu_01ABC...",
+  "name": "Read",
+  "input": {"file_path": "/path/to/file"}
+}
+```
+
+## Storage Stats
+
+Typical sizes:
+- **projects/**: 85% of storage (conversation transcripts)
+- **node_modules/**: 12% (local dependencies, if present)
+- **todos/**: 2% (task management)
+- **config/cache**: <1%
+
+## Backup Strategies
+
+```bash
+# Conversation data only
+rsync -av ~/.claude/projects/ backup/claude-conversations/
+
+# Full backup excluding cache
+rsync -av --exclude='node_modules' --exclude='statsig' \
+  ~/.claude/ backup/claude-full/
+
+# Configuration only
+tar -czf claude-config.tar.gz \
+  ~/.claude/settings*.json \
+  ~/.claude/CLAUDE.md \
+  ~/.claude/commands/
+```
+
+## Session Cleanup
+
+Sessions older than 30 days are auto-deleted. Override with:
+```json
+{
+  "cleanupPeriodDays": 365
+}
+```
+
+## Path Encoding
+
+Project paths are encoded by replacing `/` with `-`:
+- `/Users/chi/project` → `-Users-chi-project`
+- When moving projects, manually rename the corresponding directory in `projects/`

package/doc/claude-code/hooks.md

@@ -0,0 +1,348 @@
+---
+source: https://code.claude.com/docs/en/hooks
+additional_sources:
+  - https://code.claude.com/docs/en/hooks-guide
+fetched: 2026-01-13
+---
+
+# Claude Code Hooks
+
+Hooks are user-defined shell commands that execute at various points in Claude Code's lifecycle. They provide deterministic control over behavior.
+
+## Configuration
+
+Hooks are configured in settings files:
+
+- `~/.claude/settings.json` - User settings (global)
+- `.claude/settings.json` - Project settings
+- `.claude/settings.local.json` - Local project settings (not committed)
+
+### Structure
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolPattern",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command-here",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Fields:**
+- `matcher`: Pattern to match tool names (regex supported: `Edit|Write`, `Notebook.*`, `*` for all)
+- `type`: `"command"` for bash or `"prompt"` for LLM-based evaluation
+- `command`: Bash command to execute
+- `timeout`: Optional, seconds before canceling
+
+## Hook Events
+
+| Event | Matcher | Description |
+|-------|---------|-------------|
+| `PreToolUse` | Yes | Before tool execution (can block) |
+| `PostToolUse` | Yes | After tool completion |
+| `PermissionRequest` | Yes | When permission dialog shown |
+| `UserPromptSubmit` | No | Before Claude processes user input |
+| `Notification` | Yes | When notifications sent |
+| `Stop` | No | When Claude finishes responding |
+| `SubagentStop` | No | When subagent finishes |
+| `PreCompact` | Yes | Before compact operation |
+| `SessionStart` | Yes | Session start/resume |
+| `SessionEnd` | No | Session ends |
+
+### Notification Matchers
+
+- `permission_prompt` - Permission requests
+- `idle_prompt` - Claude waiting for input
+- `auth_success` - Authentication success
+- `elicitation_dialog` - MCP tool elicitation
+
+### SessionStart Matchers
+
+- `startup` - Fresh start
+- `resume` - From `--resume`, `--continue`, `/resume`
+- `clear` - From `/clear`
+- `compact` - Auto or manual compact
+
+### PreCompact Matchers
+
+- `manual` - From `/compact`
+- `auto` - Auto-compact
+
+## Environment Variables
+
+- `$CLAUDE_PROJECT_DIR` - Project root directory
+- `$CLAUDE_ENV_FILE` - (SessionStart only) File to persist env vars
+- `${CLAUDE_PLUGIN_ROOT}` - Plugin directory (for plugins)
+
+## Hook Input (stdin JSON)
+
+Common fields in all hooks:
+
+```json
+{
+  "session_id": "abc123",
+  "transcript_path": "/path/to/transcript.jsonl",
+  "cwd": "/current/directory",
+  "permission_mode": "default",
+  "hook_event_name": "PreToolUse"
+}
+```
+
+### PreToolUse Input
+
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "ls -la",
+    "description": "List files"
+  },
+  "tool_use_id": "toolu_01ABC123"
+}
+```
+
+### UserPromptSubmit Input
+
+```json
+{
+  "prompt": "Write a function..."
+}
+```
+
+### Stop/SubagentStop Input
+
+```json
+{
+  "stop_hook_active": true
+}
+```
+
+## Hook Output
+
+### Exit Codes
+
+- **0**: Success. stdout shown in verbose mode
+- **2**: Blocking error. stderr shown to Claude
+- **Other**: Non-blocking error. stderr shown to user
+
+### JSON Output (exit 0)
+
+```json
+{
+  "continue": true,
+  "stopReason": "string",
+  "suppressOutput": true,
+  "systemMessage": "string"
+}
+```
+
+### PreToolUse Decision Control
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow|deny|ask",
+    "permissionDecisionReason": "reason",
+    "updatedInput": { "field": "new value" }
+  }
+}
+```
+
+### PostToolUse Decision Control
+
+```json
+{
+  "decision": "block",
+  "reason": "Explanation",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Info for Claude"
+  }
+}
+```
+
+### UserPromptSubmit Control
+
+```json
+{
+  "decision": "block",
+  "reason": "Explanation",
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Context to add"
+  }
+}
+```
+
+### Stop/SubagentStop Control
+
+```json
+{
+  "decision": "block",
+  "reason": "Must continue because..."
+}
+```
+
+### SessionStart Control
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "Context to load"
+  }
+}
+```
+
+## Examples
+
+### Log All Bash Commands
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Auto-Format on Edit
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Block Main Branch Edits
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo 'Cannot edit on main' >&2; exit 2; }"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Load Context on Session Start
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cat ~/.claude/context.txt"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Persist Environment Variables
+
+```bash
+#!/bin/bash
+# In SessionStart hook
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE"
+fi
+exit 0
+```
+
+## Prompt-Based Hooks
+
+Use `type: "prompt"` for LLM-evaluated decisions (Stop, SubagentStop):
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Evaluate if Claude should stop: $ARGUMENTS",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Response schema:
+```json
+{
+  "ok": true,
+  "reason": "Explanation (required when ok=false)"
+}
+```
+
+## Hooks in Skills/Commands
+
+Define hooks in frontmatter (scoped to component lifecycle):
+
+```yaml
+---
+name: secure-ops
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/check.sh"
+          once: true
+---
+```
+
+`once: true` runs the hook only once per session.

package/doc/claude-code/overview.md

@@ -0,0 +1,109 @@
+---
+source: https://code.claude.com/docs/en/overview
+fetched: 2026-01-13
+---
+
+# Claude Code Overview
+
+Claude Code is Anthropic's agentic coding tool that lives in your terminal and helps developers turn ideas into code faster. It works within your existing workflow and development environment.
+
+## What Claude Code Does
+
+- **Build features from descriptions**: Write features in plain English. Claude Code makes a plan, writes the code, and ensures it works.
+- **Debug and fix issues**: Describe bugs or paste error messages. Claude Code analyzes your codebase, identifies problems, and implements fixes.
+- **Navigate any codebase**: Ask questions about your team's codebase and get thoughtful answers. Claude Code maintains awareness of your entire project structure, can find up-to-date information from the web, and can pull from external data sources (Google Drive, Figma, Slack) via MCP.
+- **Automate tedious tasks**: Fix lint issues, resolve merge conflicts, write release notes—all from a single command. Run from your developer machines or automatically in CI.
+
+## Why Developers Love Claude Code
+
+- **Works in your terminal**: Not another chat window or IDE. Meets you where you already work with the tools you already love.
+- **Takes action**: Directly edit files, run commands, create commits. With MCP, read design docs from Google Drive, update Jira tickets, or use custom tooling.
+- **Unix philosophy**: Composable and scriptable:
+  ```bash
+  tail -f app.log | claude -p "Slack me if you see any anomalies appear in this log stream"
+  claude -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"
+  ```
+- **Enterprise-ready**: Use the Claude API or host on AWS/GCP with enterprise-grade security, privacy, and compliance. Supports Amazon Bedrock, Google Vertex AI, and Microsoft Foundry.
+
+## Installation
+
+### Prerequisites
+A Claude subscription (Pro, Max, Teams, or Enterprise) or Claude Console account.
+
+### macOS/Linux/WSL
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+```
+
+### Windows PowerShell
+```powershell
+irm https://claude.ai/install.ps1 | iex
+```
+
+### Windows CMD
+```cmd
+curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
+```
+
+### Homebrew
+```bash
+brew install --cask claude-code
+```
+
+### WinGet
+```powershell
+winget install Anthropic.ClaudeCode
+```
+
+### NPM (requires Node.js 18+)
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+## Quick Start
+
+```bash
+cd your-project
+claude
+```
+
+You'll be prompted to log in on first use. Claude Code automatically keeps itself up to date.
+
+## Platform Support
+
+- **Terminal**: Native CLI experience
+- **Web**: Claude Code on the web
+- **Desktop**: Claude desktop app
+- **IDEs**: VS Code, JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.)
+- **Chrome**: Browser extension (beta)
+- **CI/CD**: GitHub Actions, GitLab CI/CD integration
+- **Team Tools**: Slack integration, GitHub @claude mentions
+
+## Key Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| Codebase awareness | Full project structure understanding |
+| File operations | Read, write, edit files directly |
+| Command execution | Run shell commands and scripts |
+| Git workflows | Commits, branches, PRs, merge conflicts |
+| MCP integration | Connect to external data sources and tools |
+| Custom commands | Slash commands for repeated workflows |
+| Plugins | Extend with custom agents, hooks, and skills |
+
+## Language Support
+
+Supports 12+ languages including English, French, German, Italian, Japanese, Spanish, Korean, Chinese, Russian, Indonesian, and Portuguese (Brazil).
+
+## Resources
+
+- [Official Documentation](https://code.claude.com/docs/en/overview)
+- [Quickstart Guide](https://code.claude.com/docs/en/quickstart) (5 minutes)
+- [Common Workflows](https://code.claude.com/docs/en/common-workflows)
+- [Troubleshooting](https://code.claude.com/docs/en/troubleshooting)
+- [IDE Setup](https://code.claude.com/docs/en/vs-code)
+- [Security Documentation](https://code.claude.com/docs/en/security)
+- [Data Usage & Privacy](https://code.claude.com/docs/en/data-usage)
+- [GitHub Repository](https://github.com/anthropics/claude-code)
+- [Claude Developers Discord](https://anthropic.com/discord)
+- [Report Issues](https://github.com/anthropics/claude-code/issues)