@aladac/hu 0.1.0-a1

package/commands/replicate.md

@@ -0,0 +1,303 @@
+Diagnose a reported issue and identify code areas to investigate.
+
+Arguments: $ARGUMENTS
+
+## Phase 1: Parse the Issue
+
+Extract from the user's description:
+- **Environment**: URL, event slug, environment (dev/staging/prod)
+- **Issue**: What's broken (pricing mismatch, availability wrong, display error)
+- **Steps to Reproduce**: User actions that trigger the issue
+- **Expected vs Actual**: What should happen vs what happens
+- **Specific values**: Package IDs, hotel IDs, guest counts, prices mentioned
+
+If details are missing, ask for clarification.
+
+## Phase 2: Generate TEST.md
+
+Create `./TEST.md` with diagnostic commands using the jam CLI tool.
+
+**Template:**
+```markdown
+# Test Plan: [Issue Title]
+
+## Issue Summary
+[One paragraph from user's description]
+
+## Test Parameters
+- Event: {slug}
+- Package ID: {id}
+- Hotel IDs: {ids}
+- Guest counts to test: {n1, n2, ...}
+
+## Diagnostic Commands
+
+### 1. Landing Page Data
+jam landing {event} --json | jq '.data.packages[] | select(.id == {pkg}) | {name, min_prices_by_occupancy}'
+
+### 2. Hotel Search (for each guest count)
+jam hotel-search -e {event} -p {pkg} -t {n} --json | jq '.data[] | {hotel_id, name, booking_source, min_price_per_person}' | head -20
+
+### 3. Specific Hotel Details
+jam hotel-details -e {event} -p {pkg} -h {hotel} -t {n} --json | jq '.data.rooms[] | {room_id, room_name, min_price, min_price_with_mandatory_fees}'
+
+### 4. Pricing Confirmation
+jam pricing -e {event} -p {pkg} -h {hotel} -t {n} --json | jq '.data.room | {price, mandatory_fees_total}'
+
+### 5. Full Flow with Validation
+jam run -e {event} -p {pkg} -t {n} --validate-prices -v
+
+## Expected vs Actual
+| Metric | Expected | Actual | Source |
+|--------|----------|--------|--------|
+| Package card price (N guests) | $X | $Y | landing.min_prices_by_occupancy |
+| Hotel page min price | $X | $Y | hotel-search min |
+```
+
+Tell the user: **"Run the commands in TEST.md and paste the results here, or I can run them if you prefer."**
+
+## Phase 3: Analyze Results
+
+When user provides output:
+
+1. **Compare values** - Find discrepancies between expected and actual
+2. **Identify pattern** - Match to known issue types (see Reference below)
+3. **Update FINDINGS.md** with:
+   - Data tables showing expected vs actual
+   - Root cause hypothesis
+   - Verification commands
+
+## Phase 4: Output Code to Investigate
+
+Based on findings, output specific file paths:
+
+```markdown
+## Investigation Summary
+
+**Issue:** [One line description]
+**Root Cause Hypothesis:** [What's likely causing this]
+
+**Files to Check (in priority order):**
+1. `app/path/to/file.rb:method_name` - [Why]
+2. `app/path/to/file.rb` - [Why]
+
+**Cache/DB to Verify:**
+- Redis key: `{key_pattern}`
+- SQL: `SELECT ... FROM packages WHERE id = {id}`
+
+**Next Steps:**
+1. [Specific action]
+2. [Specific action]
+```
+
+---
+
+# Reference: System Architecture
+
+```
+User Browser (fuseignited-landing)
+    ↓ API calls
+fuseignited-cms (Rails + Grape API)
+    ↓ inventory requests
+fuse-hotel (Python FastAPI)
+    ↓ provider calls
+External Providers (Hotelbeds, Priceline, etc.)
+```
+
+## Booking Flow Stages
+
+| Stage | Frontend Route | CMS Endpoint | JAM Command |
+|-------|----------------|--------------|-------------|
+| 1. Landing | `/events/{slug}` | GET /api/v1/landing/{slug} | `jam landing {slug} --json` |
+| 2. Tickets | `/booking/tickets` | (landing data) | `jam tickets -e {slug}` |
+| 3. Hotel Search | `/booking/hotels` | GET /api/v1/hotels/search | `jam hotel-search -e {slug} -p {pkg} -t {n}` |
+| 4. Availability | Hotel list | GET /api/v1/prices/hotel-availability | `jam hotel-availability -e {slug} -h {hotel} -t {n}` |
+| 5. Room Select | Room modal | GET /api/v1/hotels/hotel-details | `jam hotel-details -e {slug} -h {hotel} -t {n}` |
+| 6. Pricing | Room select | GET /api/v1/prices/pricing-confirmation | `jam pricing -e {slug} -h {hotel} -t {n}` |
+| 7. Addons | `/booking/add-ons` | GET /events/{slug}/{pkg}/addons | `jam packages {pkg} addons` |
+| 8. Calculate | `/booking/order-details` | POST /api/v1/prices/calculate-order | `jam calculate -e {slug} -h {hotel} -t {n}` |
+| 9. Insurance | `/booking/review-and-pay` | POST /api/v1/insurance/quote | `jam insurance -e {slug} --total {amount}` |
+| 10. Booking | Checkout | POST /api/v1/booking | `jam book -e {slug} -h {hotel} --booking` |
+
+## Key Data Structures
+
+### min_prices_by_occupancy (Package Card Pricing)
+Location: `.data.packages[].min_prices_by_occupancy` (array indexed by occupancy-1)
+```json
+{"occupancy": 3, "price_on_offer": 211.13, "mandatory_fees_total": 0, "booking_source": "external"}
+```
+**Code:** `app/serializers/api/package_serializer.rb`, `app/services/pricing/*`
+**Cache:** Redis key `package_array_hash_min_prices_{package_id}`
+
+### Hotel Search Response
+```json
+{"hotel_id": 3777, "name": "Dev test hotel", "booking_source": "internal", "min_price_per_person": 99.54, "sold_out": false}
+```
+**Code:** `app/controllers/api/v1/hotels.rb`, `app/services/inventory_services/hotels/*`
+
+### Room Pricing Response
+```json
+{"room_id": 123, "min_price": 260.00, "min_price_with_mandatory_fees": 290.00, "mandatory_fees_total": 30.00}
+```
+**Code:** `app/controllers/api/v1/prices.rb`, `app/services/inventory_services/hotels/availability_service.rb`
+
+## Issue Type → Code Location
+
+| Issue Type | Primary Files to Check |
+|------------|------------------------|
+| Package min price wrong | `app/serializers/api/package_serializer.rb`, `app/services/pricing/*` |
+| Landing page data | `app/controllers/api/v1/landing.rb`, `app/serializers/api/landing_serializer.rb` |
+| Hotel search/filter | `app/controllers/api/v1/hotels.rb` |
+| Hotel availability | `app/services/inventory_services/hotels/availability_service.rb` |
+| Price calculation | `app/controllers/api/v1/prices.rb` |
+| External inventory | `app/services/inventory_services/hotels/gateway_v3.rb` |
+| Caching/stale data | Redis keys, `Rails.cache` calls in services |
+| Fees/resort fees | `app/services/inventory_services/hotels/*` fee handling |
+
+## Common Issue Patterns
+
+### Package Card ≠ Hotel Page Price
+**Symptom:** Package card shows $211, hotel page shows $31
+**Root Cause:** `min_prices_by_occupancy` cached/stale data
+```bash
+jam landing {event} --json | jq '.data.packages[] | select(.id == {pkg}) | .min_prices_by_occupancy'
+jam hotel-search -e {event} -p {pkg} -t {n} --json | jq '.data | sort_by(.min_price_per_person) | .[0]'
+```
+**Check:** `app/serializers/api/package_serializer.rb`, Redis cache staleness, cache invalidation triggers
+
+### Internal Hotels Not Considered
+**Symptom:** Cheapest internal hotel not reflected in min price
+```bash
+jam hotel-search -e {event} -p {pkg} -t {n} --json | jq '.data[] | {hotel_id, name, booking_source, min_price_per_person}'
+```
+**Check:** `app/services/inventory_services/hotels/*` filtering logic
+
+### External Hotel Stale/No Rooms
+**Symptom:** External hotel in cached price has no availability
+```bash
+jam hotel-details -e {event} -h {hotel} -t {n} --json
+jam inventory availability -h {hotel_id}
+```
+**Check:** `InventoryServices::Hotels::GatewayV3`, fuse-hotel caching
+
+### Mandatory Fees Missing
+**Symptom:** Price doesn't include resort fees
+```bash
+jam pricing -e {event} -h {hotel} -t {n} --json | jq '.data.room | {price, mandatory_fees_total}'
+```
+**Check:** `app/services/inventory_services/hotels/availability_service.rb`
+
+## Investigation Methodology
+
+1. **Compare cached vs live data** - Is `min_prices_by_occupancy` stale?
+2. **Check by occupancy** - Does behavior change at different guest counts?
+3. **Internal vs external** - Are both hotel types being considered?
+4. **Mandatory fees** - Are fees included consistently?
+5. **Cache invalidation** - What triggers a refresh?
+
+### Key Questions to Answer
+- Where is `min_prices_by_occupancy` calculated?
+- When is it refreshed? On-demand or cached?
+- Does it query all hotels or a subset?
+- Are hotels with no availability excluded?
+
+---
+
+# JAM CLI Reference
+
+## Installation
+```bash
+pip install -e /Users/chi/Projects/jam
+jam init  # Creates ~/.config/jam/settings.json
+```
+
+## Environments
+| Flag | URL |
+|------|-----|
+| `--local` | http://localhost:3000 |
+| `-E dev` (default) | https://cms.dev.jampack.com |
+| `-E prod` | https://api.jampack.com |
+
+## Core Commands
+
+### Full Booking Flow
+```bash
+jam run -e <event-slug>                    # Stop at order summary
+jam run -e <event-slug> --booking          # Create actual booking
+jam run -e <event-slug> --validate-prices  # Check price consistency
+jam run -e <event-slug> --compare-inventory # Compare CMS vs inventory API
+jam run -e <event-slug> --save             # Save request/response JSON
+jam run -e <event-slug> -p 1024 -h 2200    # Specific package/hotel
+jam test-all -e <event-slug>               # Test all combinations
+```
+
+### Events & Landing
+```bash
+jam events                        # List all test events
+jam landing <slug>                # Landing page data
+jam landing <slug> --json         # Raw JSON output
+jam packages -e <event>           # List packages
+jam packages <id> tickets         # Package ticket details
+jam packages <id> addons          # Package addons
+jam tickets -e <event>            # List ticket types
+```
+
+### Hotels
+```bash
+jam hotels -e <event> -p <package>         # List available hotels
+jam hotel-search -e <event> -p <pkg> -t <n> # Search with params
+jam hotel-availability -e <event> -h <id>  # Check availability
+jam hotel-details -e <event> -h <id> -t <n> # Room details
+jam validate-hotels -e <event>             # Test all hotels
+```
+
+### Pricing & Calculation
+```bash
+jam pricing -e <event> -h <hotel-id> -t <n>
+jam calculate -e <event> -h <hotel-id> -t <n>
+jam calculate -e <event> --no-hotel        # Ticket-only
+```
+
+### Inventory (Direct API to fuse-hotel)
+```bash
+jam inventory availability -h <hotel-id>
+jam inventory availability --hotel-ids 2200,2306
+jam inventory check-rate -h <hotel-id> -r <room-type-id> -k <rate-key>
+```
+
+### Authentication
+```bash
+jam auth                          # Get JWT token
+jam auth -e <event> -p <password> # Password-protected event
+```
+
+## Common Options
+| Option | Description |
+|--------|-------------|
+| `-e, --event` | Event slug |
+| `-E, --env` | Environment (local, dev, prod) |
+| `-p, --package-id` | Package ID |
+| `-h, --hotel-id` | Hotel ID |
+| `-t, --travellers` | Number of travellers |
+| `--json` | Raw JSON output |
+| `-v, --verbose` | Debug output |
+
+## Test Events
+| Slug | Type | Notes |
+|------|------|-------|
+| `single-page-checkout-test-event` | flexible | General testing |
+| `flexible-tickets-and-hotel-testing` | flexible | Internal hotel testing |
+| `sep-flexible-event` | flexible | Default event |
+| `e2e-jampack-mandatory-fees-dev` | regular | Fee testing |
+
+---
+
+# Related Codebases
+
+| Path | Purpose |
+|------|---------|
+| `/Users/chi/Projects/fuseignited-cms` | Main CMS/API |
+| `/Users/chi/Projects/jam` | Testing CLI |
+| `/Users/chi/Projects/fuse-hotel` | Hotel inventory service |
+| `/Users/chi/Projects/fuseignited-landing` | Frontend |
+| `/Users/chi/Projects/fuse-config` | Backoffice (JamForge) |

package/doc/README.md

@@ -0,0 +1,35 @@
+# Documentation
+
+Reference documentation fetched from the web.
+
+```
+doc/
+├── README.md
+└── claude-code/
+    ├── overview.md           # Overview, installation, quick start
+    ├── capabilities.md       # CLI commands, flags, agents
+    ├── plugins.md            # Plugin creation, structure, marketplace
+    ├── hooks.md              # Hook events, configuration, examples
+    ├── directory-structure.md # ~/.claude directory layout, formats
+    └── sdk-protocols.md      # Agent SDK, MCP, ACP protocols
+```
+
+## Claude Code
+
+| Document | Description |
+|----------|-------------|
+| [Overview](claude-code/overview.md) | What Claude Code does, installation, platform support |
+| [Capabilities](claude-code/capabilities.md) | CLI reference, flags, custom subagents |
+| [Plugins](claude-code/plugins.md) | Creating, installing, and publishing plugins |
+| [Hooks](claude-code/hooks.md) | Hook events, settings configuration, examples |
+| [Directory Structure](claude-code/directory-structure.md) | ~/.claude layout, session formats, backup strategies |
+| [SDK & Protocols](claude-code/sdk-protocols.md) | Agent SDK, MCP, ACP - the underlying protocols |
+
+## Adding Documentation
+
+Use the `/docs:get` command:
+
+```bash
+/docs:get "topic name"           # Saves to ./doc/topic-name.md
+/docs:get "topic name" category  # Saves to ./doc/category/topic-name.md
+```

package/doc/claude-code/capabilities.md

@@ -0,0 +1,202 @@
+---
+source: https://code.claude.com/docs/en/cli-reference
+fetched: 2026-01-13
+---
+
+# Claude Code Capabilities
+
+Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows—all through natural language commands.
+
+## Installation
+
+```bash
+# MacOS/Linux
+curl -fsSL https://claude.ai/install.sh | bash
+
+# Homebrew (MacOS)
+brew install --cask claude-code
+
+# Windows
+irm https://claude.ai/install.ps1 | iex
+
+# NPM (requires Node.js 18+)
+npm install -g @anthropic-ai/claude-code
+```
+
+## CLI Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `claude` | Start interactive REPL | `claude` |
+| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |
+| `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` |
+| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` |
+| `claude -c` | Continue most recent conversation | `claude -c` |
+| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` |
+| `claude -r "<session>" "query"` | Resume session by ID or name | `claude -r "auth-refactor" "Finish this PR"` |
+| `claude update` | Update to latest version | `claude update` |
+| `claude mcp` | Configure MCP servers | See MCP documentation |
+
+## Core Capabilities
+
+### Terminal & IDE Integration
+- Works in terminal, VS Code, Cursor, and other IDEs
+- Run multiple instances in parallel on different parts of your codebase
+- Tag @claude on GitHub for PR reviews and issue assistance
+
+### Codebase Understanding
+- Contextual awareness of your project structure
+- Explain complex code and architecture
+- Search and navigate large codebases
+
+### Task Execution
+- Execute routine coding tasks
+- Handle git workflows through natural language
+- Automate common development workflows
+
+## CLI Flags <!-- updated: 2026-01-13 -->
+
+### Core Execution
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--print`, `-p` | Print response without interactive mode | `claude -p "query"` |
+| `--continue`, `-c` | Load most recent conversation | `claude --continue` |
+| `--resume`, `-r` | Resume specific session by ID or name | `claude --resume auth-refactor` |
+| `--session-id` | Use specific session ID (valid UUID) | `claude --session-id "550e8400-..."` |
+| `--fork-session` | Create new session instead of reusing original | `claude --resume abc123 --fork-session` |
+
+### Model & Agent Configuration
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--model` | Set model (`sonnet`, `opus`, or full name) | `claude --model opus` |
+| `--agent` | Specify agent for current session (overrides `agent` setting) | `claude --agent my-custom-agent` |
+| `--agents` | Define custom subagents via JSON | See agents section below |
+| `--fallback-model` | Fallback model when overloaded (print mode) | `claude -p --fallback-model sonnet "query"` |
+| `--betas` | Beta headers for API requests (API key users only) | `claude --betas interleaved-thinking` |
+
+### System Prompt Customization
+
+| Flag | Description | Mode |
+|------|-------------|------|
+| `--system-prompt` | Replace entire default prompt | Interactive + Print |
+| `--system-prompt-file` | Replace with file contents | Print only |
+| `--append-system-prompt` | Append to default prompt (recommended) | Interactive + Print |
+
+```bash
+# Replace entire system prompt
+claude --system-prompt "You are a Python expert"
+
+# Load from file
+claude -p --system-prompt-file ./prompts/review.txt "Review this PR"
+
+# Append to default (recommended)
+claude --append-system-prompt "Always use TypeScript"
+```
+
+**Note:** `--system-prompt` and `--system-prompt-file` are mutually exclusive. For most use cases, `--append-system-prompt` is recommended as it preserves Claude Code's built-in capabilities.
+
+### Tool & Permission Management
+
+| Flag | Description |
+|------|-------------|
+| `--tools` | Restrict which built-in tools Claude can use (`""` for none, `"default"` for all, or specific tools like `"Bash,Edit,Read"`) |
+| `--allowedTools` | Tools that execute without prompting |
+| `--disallowedTools` | Tools removed from context |
+| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) |
+| `--permission-mode` | Begin in specified permission mode |
+| `--permission-prompt-tool` | MCP tool to handle permission prompts in non-interactive mode |
+
+### Directory & File Configuration
+
+| Flag | Description |
+|------|-------------|
+| `--add-dir` | Add additional working directories (validates each path) |
+| `--settings` | Path to settings JSON file or JSON string |
+| `--setting-sources` | Comma-separated list: `user`, `project`, `local` |
+| `--plugin-dir` | Load plugins from directories (repeatable) |
+
+### MCP Configuration
+
+| Flag | Description |
+|------|-------------|
+| `--mcp-config` | Load MCP servers from JSON files or strings (space-separated) |
+| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignore all others |
+
+### Input/Output Formatting
+
+| Flag | Description | Options |
+|------|-------------|---------|
+| `--output-format` | Output format for print mode | `text`, `json`, `stream-json` |
+| `--input-format` | Input format for print mode | `text`, `stream-json` |
+| `--json-schema` | Get validated JSON output matching schema | Print mode only |
+| `--include-partial-messages` | Include partial streaming events | Requires `--print` and `--output-format=stream-json` |
+
+### Advanced Options
+
+| Flag | Description |
+|------|-------------|
+| `--max-turns` | Limit agentic turns (print mode). Exits with error when reached |
+| `--chrome` | Enable Chrome browser integration for web automation |
+| `--no-chrome` | Disable Chrome browser integration |
+| `--ide` | Auto-connect to IDE on startup if exactly one valid IDE available |
+| `--debug` | Enable debug mode with optional category filtering (e.g., `"api,hooks"`) |
+| `--verbose` | Enable verbose logging, shows full turn-by-turn output |
+| `--version`, `-v` | Output version number |
+
+## Custom Subagents
+
+Define custom agents with the `--agents` flag:
+
+```bash
+claude --agents '{
+  "code-reviewer": {
+    "description": "Expert code reviewer. Use proactively after code changes.",
+    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  },
+  "debugger": {
+    "description": "Debugging specialist for errors and test failures.",
+    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
+  }
+}'
+```
+
+### Agent Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | When the subagent should be invoked |
+| `prompt` | Yes | System prompt for the subagent |
+| `tools` | No | Specific tools (inherits all if omitted) |
+| `model` | No | Model: `sonnet`, `opus`, or `haiku` |
+
+## Extensibility
+
+### Hooks
+Shell commands that execute at lifecycle points:
+- **PreToolUse**: Before tool execution
+- **PostToolUse**: After tool completion
+- **Notification**: When Claude sends notifications
+- **Stop**: When Claude finishes responding
+
+### MCP (Model Context Protocol)
+Claude Code functions as both MCP server and client. Connect to MCP servers via `.mcp.json` for team-wide tool access.
+
+### Custom Commands
+Store prompt templates in `.claude/commands/` as Markdown files. Access via `/` slash commands.
+
+### Plugins
+Install plugins from the marketplace for extended functionality.
+
+## Resources
+
+- [Official Documentation](https://code.claude.com/docs/en/overview)
+- [Chrome Extension](https://code.claude.com/docs/en/chrome)
+- [Interactive Mode](https://code.claude.com/docs/en/interactive-mode)
+- [Slash Commands](https://code.claude.com/docs/en/slash-commands)
+- [Settings](https://code.claude.com/docs/en/settings)
+- [SDK Documentation](https://docs.claude.com/en/docs/agent-sdk)
+- [GitHub Repository](https://github.com/anthropics/claude-code)