# Claude Code — project conventions for StoryGen AI

This is a Laravel 11 app deployed **directly to cPanel from GitHub**. The
deploy target serves the **repository root as the web-accessible root** —
not a `public/` subdirectory. Every change Claude proposes must keep the
project ready for that direct GitHub-to-cPanel deployment.

## Project structure rules

- The repository root is the web root. cPanel's document root points at
  the repo root, not at any subdirectory.
- **Do not use a `public/` deployment layout.** Files Laravel would
  normally serve from `public/` live at the repository root.
- Web-accessible assets (CSS, JavaScript, images, fonts, etc.) go
  **directly at the repository root** or in root-level asset directories
  such as `css/`, `js/`, `images/`, `fonts/`. **Never** under `public/`.
- Keep the standard Laravel application directories — `app/`,
  `bootstrap/`, `config/`, `database/`, `resources/`, `routes/`,
  `storage/`, `vendor/` — in place. Do not move them.
- The root `.htaccess` MUST deny direct browser access to those Laravel
  application directories and to sensitive files (`.env`, `composer.json`,
  `composer.lock`, `artisan`, `phpunit.xml`, etc.). Anything inside
  `app/`, `bootstrap/`, `config/`, `database/`, `resources/`, `routes/`,
  `storage/`, `tests/`, or `vendor/` must return 403 if hit directly.

## Entrypoint rule

The root `index.php` is the front controller. It uses **root-based
paths**, not the default Laravel `public/index.php` paths:

```php
require __DIR__.'/vendor/autoload.php';

$app = require_once __DIR__.'/bootstrap/app.php';
```

Do not introduce `__DIR__.'/../...'` requires — they are wrong for this
project's layout.

## Working preferences

- **No local-only Laravel workflows.** Don't assume `php artisan` will be
  run on a developer machine before deploy. Don't optimize for a local
  dev experience.
- Prefer changes that can be **pushed directly to GitHub and tested on
  cPanel**. The deploy is `git pull` → `composer install` → exercise the
  app via the browser.
- Don't require any hand-run artisan command unless absolutely necessary.
  When unavoidable (e.g. `php artisan migrate` for a schema change),
  document it in the commit message, but make sure the change still
  applies cleanly via the standard cPanel git deploy flow.
- The `composer install` step automatically runs
  `php artisan view:clear` (wired in `composer.json`'s
  `post-autoload-dump` hook), so any Blade view change is picked up
  on the next deploy without manual intervention.
- For browser-cached assets like `css/app.css`, the layout already
  appends a `?v=<filemtime>` cache-buster, so updates flow to clients
  without hard-refresh requirements.

## File-path helpers

- For a path **inside the repository on disk**, use `base_path('foo')`.
  This resolves to `<repo-root>/foo`.
- Avoid `public_path('foo')` for new code. With our layout it would
  resolve to `<repo-root>/public/foo`, which is the wrong directory.
  Keep using `asset('css/...')` for browser URLs — that helper is
  unaffected because it generates `APP_URL + path` and the URL paths
  did not change.

## Things that already work the right way

- `routes/web.php` registers everything as relative routes; they map
  cleanly when served from the repo root.
- `config/filesystems.php` only uses `storage_path('app/...')` for
  disk roots, so storage paths are independent of the public/ layout.
- `composer.json`'s `post-autoload-dump` runs `view:clear`, so each
  deploy refreshes Blade cache automatically.

## When in doubt

If a change you're about to make would put a new file under `public/`,
add a `__DIR__.'/../'` to a path, or assume the developer will run an
artisan command from a local machine — stop and reconsider. None of
those fit this deployment.
