# Claude Code Instructions

## Hard limits:
   - Do not scan the whole codebase.
   - First inspect only files that are directly relevant.
   - Keep changes minimal.
   - Do not run full test suite unless needed.
   - Use Sonnet unless I ask for Opus-level architecture.
   - Give a short plan before editing.
   - After editing, summarize changed files and next command to test.

## Development Workflow

Follow these steps for every feature addition or task:

1. **Implement the feature or task** as requested.

2. **Protect existing and new customers** — every change must be safe for both audiences:

   - **Existing customers (already installed):** If the change touches database tables, config keys, settings, file storage, or any persisted data structure, write a migration so their data is automatically carried forward. Never assume an existing installation is in a "clean" state — it may have years of data that must keep working.
   - **New customers (fresh install):** Ensure the change does not break a clean installation. Seeders, default config values, and migration order must all work from scratch without manual steps.
   - **When in doubt, write a migration.** Even for small structural changes (adding a column, renaming a setting key, changing a default value), a migration is cheaper than a broken upgrade.

3. **Update documentation** — add or update the relevant documentation for the feature or change (changelog, inline docs, README, or any docs/ files that describe the affected area).

   > **Docs repo:** Documentation lives at `F:\html\ChargePanda-docs` (GitHub: `https://github.com/ChargePanda/docs`). It is a standalone VitePress project — `cd F:\html\ChargePanda-docs && npm run dev` to preview. Do **not** add a `docs/` folder to this repo.

   > **Changelog dates:** Never write a real date in `changelog.md`. New entries must use `TBD` as the release date (e.g. `## v1.x.x — TBD`). Dates are filled in by the team at release time.

   > **Changelog tone:** Write for non-technical end users — store owners and customers, not developers. Describe what changed from the user's perspective (what they can now do, or what was broken and is now fixed). Never mention code, variable names, error messages, file paths, or implementation details.

---

## Styling Conventions

### Admin Panel (backend views — `resources/views/admin/` and module `admin/` views)

The admin panel uses Bootstrap 5 with a **heavily customised utility layer**. Do NOT use `btn-outline-*` variants — they render with invisible text against the custom background. Use solid button variants only.

**Buttons:**
```html
<button class="btn btn-primary">Primary action</button>
<button class="btn btn-secondary btn-sm">Secondary / back / cancel</button>
<button class="btn btn-success btn-sm">Confirm / activate</button>
<button class="btn btn-danger btn-sm">Delete / destructive</button>
<button class="btn btn-warning btn-sm">Deactivate / caution</button>
<button class="btn btn-info btn-sm">Filter / search</button>
<button class="btn btn-link">Inline link action</button>
<!-- NEVER use btn-outline-* — invisible text in the custom theme -->
```

**Badges (Bootstrap 5 syntax — always `bg-*`, never `badge-*`):**
```html
<span class="badge bg-success">Active</span>
<span class="badge bg-secondary">Inactive</span>
<span class="badge bg-danger">Error</span>
<span class="badge bg-warning text-dark">Warning</span>  <!-- text-dark required on warning -->
<span class="badge bg-info">Info</span>
<span class="badge bg-primary">Primary</span>
<!-- NEVER use badge-success, badge-secondary etc. — that is Bootstrap 4 syntax -->
```

**Card / panel container:**
```html
<div class="bgc-white bd bdrs-3 p-20 mB-20">
    <!-- content -->
</div>
```

**Spacing utilities** (custom, not Bootstrap):
- Margin: `mB-20`, `mT-10`, `mR-5`, `mL-5`, `mY-20`
- Padding: `p-20`, `pY-40`, `pX-20`, `pT-10`, `pB-10`

**Text colour utilities** (custom):
- `c-grey-900` — headings / primary text
- `c-grey-600` — secondary / muted text
- `c-blue-500`, `c-green-500`, `c-red-500`, `c-orange-500` — accent colours

**Flexbox helpers** (custom):
- `peers` — flex container, `peer` — flex child
- `ai-c` — align-items: center

**Icons:** Themify Icons (`ti-*`) — e.g. `ti-pencil`, `ti-trash`, `ti-check`, `ti-arrow-left`

---

### Frontend / Account pages (Tailwind theme — `resources/themes/tailwind/` and module `account/` views)

The frontend uses **Tailwind CSS v4** with a custom design token layer. Always follow these patterns when writing account-facing views.

**Layout wrapper** (every account page):
```html
@extends('theme::layouts.app', ['title' => $title])
@section('content')
<main class="flex-grow w-full max-w-[1440px] mx-auto px-6 lg:px-10 py-10">
    <div class="flex flex-col lg:flex-row gap-10">
        @include('theme::partials.account.nav')
        <section class="flex-grow">
            <!-- content -->
        </section>
    </div>
</main>
@endsection
```

**Page header:**
```html
<div class="mb-8">
    <h1 class="text-2xl font-bold text-text-main dark:text-white">Title</h1>
    <p class="text-text-muted dark:text-gray-400 mt-1">Subtitle</p>
</div>
```

**Card (section container):**
```html
<section class="bg-white dark:bg-surface-dark border border-border-light dark:border-border-dark rounded-2xl shadow-sm overflow-hidden">
    <div class="p-6 border-b border-border-light dark:border-border-dark">
        <h2 class="text-lg font-bold text-text-main dark:text-white">Section title</h2>
    </div>
    <div class="p-6 space-y-5">
        <!-- content -->
    </div>
</section>
```

**Buttons:**
```html
<!-- Primary -->
<button class="flex items-center gap-2 px-5 py-2.5 bg-primary hover:bg-primary-dark text-white rounded-xl font-semibold text-sm transition-all shadow-sm shadow-primary/20">
    <span class="material-symbols-outlined text-[18px]">add</span> Label
</button>
<!-- Secondary / outline -->
<button class="flex items-center gap-2 px-4 py-2.5 border border-gray-200 dark:border-gray-700 text-text-main dark:text-white rounded-xl font-medium text-sm hover:bg-gray-50 dark:hover:bg-gray-800 transition-colors">
    Label
</button>
<!-- Danger icon button -->
<button class="size-7 flex items-center justify-center text-text-muted hover:text-red-500 rounded-lg hover:bg-red-50 dark:hover:bg-red-900/20 transition-colors">
    <span class="material-symbols-outlined text-[16px]">delete</span>
</button>
```

**Form inputs:**
```html
<div class="space-y-1.5">
    <label class="block text-xs font-bold text-text-muted uppercase tracking-wider" for="field_id">Label</label>
    <input type="text" id="field_id" name="field"
           class="w-full px-4 py-2.5 bg-gray-50 dark:bg-background-dark border border-gray-200 dark:border-gray-700 rounded-xl text-sm focus:outline-none focus:ring-2 focus:ring-primary/10 focus:border-primary transition-all" />
    <!-- Validation error -->
    <p class="text-[11px] text-red-500">{{ $message }}</p>
    <!-- Help text -->
    <p class="text-xs text-text-muted dark:text-gray-500">Help text here.</p>
</div>
```

**Status / tag badges:**
```html
<!-- Green -->
<span class="px-2 py-0.5 bg-green-50 dark:bg-green-900/20 text-green-600 dark:text-green-400 text-[11px] font-bold rounded uppercase tracking-wider">Active</span>
<!-- Red -->
<span class="px-2 py-0.5 bg-red-50 dark:bg-red-900/20 text-red-600 dark:text-red-400 text-[11px] font-bold rounded uppercase tracking-wider">Failed</span>
<!-- Amber -->
<span class="px-2 py-0.5 bg-amber-50 dark:bg-amber-900/20 text-amber-600 dark:text-amber-400 text-[11px] font-bold rounded uppercase tracking-wider">Pending</span>
<!-- Gray / neutral -->
<span class="px-2 py-0.5 bg-gray-100 dark:bg-gray-800 text-gray-600 dark:text-gray-400 text-[11px] font-bold rounded uppercase tracking-wider">Inactive</span>
```

**Alert / flash messages:**
```html
<!-- Error -->
<div class="px-4 py-3 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-xl text-sm text-red-600 dark:text-red-400">
    Message here.
</div>
<!-- Success -->
<div class="px-4 py-3 bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-800 rounded-xl text-sm text-green-600 dark:text-green-400">
    Message here.
</div>
```

**Icons:** Material Symbols Outlined — `<span class="material-symbols-outlined text-[20px]">icon_name</span>`
- Common sizes: `text-[14px]` (xs), `text-[18px]` (sm), `text-[20px]` (base), `text-[24px]` (lg), `text-[64px]` (empty-state hero)
- Do **not** use `ti-*` (Themify) or `fa-*` (Font Awesome) in frontend views — those are admin-panel only

**Empty state:**
```html
<div class="bg-white dark:bg-surface-dark border border-border-light dark:border-border-dark rounded-2xl shadow-sm p-12 text-center">
    <span class="material-symbols-outlined text-[64px] text-gray-300 dark:text-gray-700 mb-4">icon_name</span>
    <h3 class="text-lg font-bold text-text-main dark:text-white mb-2">Nothing here yet</h3>
    <p class="text-text-muted dark:text-gray-400">Descriptive message.</p>
</div>
```

**Custom design tokens** (defined in Tailwind config):
- `text-text-main` / `dark:text-white` — primary text
- `text-text-muted` / `dark:text-gray-400` — secondary text
- `bg-surface-dark` — dark mode card background
- `border-border-light` / `dark:border-border-dark` — card borders
- `bg-primary`, `hover:bg-primary-dark` — brand colour
- `shadow-soft`, `shadow-soft-hover` — custom soft shadows