# CLAUDE.md

## 0. Project specifics

**Only ever write changes in this folder (travel-blog-intotheeast/) or its subfolders.**

### Folder explanation

- **./**: Grav CMS dev environment for intotheeast travel blog
- **scripts/**: Server install and maintenance scripts
- **user/**: Site content, config, pages, and theme (standalone git repo — do not modify from here)

### Environment

**Never read `.env`** — it contains sensitive credentials. You may pass it to commands (e.g. `docker compose`, `make`) but never read its contents directly. Ask the user if you need environment-specific information.

### Remote operations

Always use `make` commands for anything on the production server (`make remote-install-plugins`, `make remote-clean`, etc.) — never SSH directly since credentials live in `.env`. If a remote operation isn't covered by an existing `make` command, either ask the user to run it manually or suggest adding a new `make` command if it seems reusable.

### Content sync

- `make content-push` — commit and push `user/` to Gitea (triggers production pull via webhook)
- `make content-pull` — pull latest from Gitea to local
- `plugins.txt` is manually maintained — installing a plugin via Admin does NOT update it

### User repo gitignore

Only these folders are tracked in the `user/` Git repo: `pages/`, `config/`, `accounts/`, `themes/`. The `plugins/` and `data/` folders are excluded.

## 1. Local development setup

### First-time setup after cloning

`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once after cloning:

```bash
mkdir -p user/plugins user/data
```

Then run `make setup` (starts Docker + installs plugins).

### After make install-plugins: fix cache permissions

If the site returns a 500 error after plugin installation, the cache/logs/tmp directories may have wrong ownership (gpm runs as root inside the container). Fix with:

```bash
docker exec intotheeast_grav chown -R abc:users /app/www/public/cache /app/www/public/logs /app/www/public/tmp
```

### Language URL prefix

If Grav redirects to `/en/...` URLs, ensure `user/config/system.yaml` contains:

```yaml
languages:
  supported: [en]
  include_default_lang: false
```

Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites.