docs: extract local setup guide from CLAUDE.md; add skill path overrides

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WPJztrVGbwic2xTG7G9fjM

CLAUDE.md

@@ -116,67 +116,11 @@ The custom plugin at `user/plugins/cache-on-save/` clears Grav's page-tree cache
 
 ## 2. Local development setup
 
-### First-time setup after cloning
+Full setup guide: [`docs/guides/local-setup.md`](docs/guides/local-setup.md)
 
-`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once after cloning:
+### Superpowers skill paths
 
-```bash
-mkdir -p user/plugins user/data
-```
+Specs: `docs/working/specs/YYYY-MM-DD-<topic>-design.md`
+Plans: `docs/working/plans/YYYY-MM-DD-<topic>.md`
 
-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 or after recreating the container,
-run `make fix-perms`. This creates uid 1000 in the container, chowns `/var/www/html` to 1000:1000,
-and reloads Apache. Always run `make setup` (not just `make start`) after `docker compose down && up`
-to ensure permissions are correct.
-
-### Grav 2.0 upgrade (local)
-
-Grav 2.0 is baked into the custom Docker image via `Dockerfile`. The base `getgrav/grav` image ships 1.7 — the `Dockerfile` downloads the 2.0-rc.10 bundle from GitHub and overwrites the core files at build time, so the image always contains 2.0.
-
-`make setup` = `build → start → install-plugins → fix-perms`. After any `docker compose down`, run `make setup` to get back to a fully working state. `docker compose restart` (soft restart) also preserves the image, so Grav 2.0 stays.
-
-To upgrade to a newer RC: update the URL in `Dockerfile` and run `make setup` — Docker rebuilds the image layer automatically.
-
-After upgrading, ensure these settings in `user/config/system.yaml`:
-```yaml
-accounts:
-  type: flex      # required for Admin2 API
-pages:
-  type: flex      # required for Admin2 pages API
-```
-
-And ensure the admin user account has `api.*` permissions (Admin2 uses a new permission namespace):
-```yaml
-# user/accounts/<username>.yaml
-access:
-  admin:
-    login: true
-    super: true
-  api:
-    super: true
-    access: true
-```
-
-**Disable the old `admin` plugin** once `admin2` is installed — both route to `/admin` and conflict:
-```bash
-# In user/plugins/admin/admin.yaml:
-enabled: false
-```
-
-**JWT secret:** Leave `jwt_secret: ''` in `user/plugins/api/api.yaml` — it works for local dev and production installs generate a secure secret automatically.
-
-### 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.
+The brainstorming and writing-plans skills default to `docs/superpowers/`; these lines override that default.

docs/guides/local-setup.md

@@ -0,0 +1,113 @@
+# Local Development Setup
+
+This guide covers setting up the dev environment from scratch after cloning the repo.
+
+---
+
+## First-time setup
+
+`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once:
+
+```bash
+mkdir -p user/plugins user/data
+```
+
+Then run:
+
+```bash
+make setup
+```
+
+`make setup` = `build → start → install-plugins → fix-perms`. This builds the Docker image (Grav 2.0 baked in), starts the container, installs all plugins from `plugins.txt`, and fixes file ownership.
+
+The dev server runs at **http://localhost:8081**.
+
+---
+
+## After any docker compose down
+
+Always run `make setup` — not just `make start` — to ensure permissions are correct.
+
+`docker compose restart` (soft restart) preserves the image and is fine for quick restarts. Only `make setup` is needed after `docker compose down`.
+
+---
+
+## Fix 500 errors after plugin install
+
+If the site returns a 500 error after plugin installation or after recreating the container:
+
+```bash
+make fix-perms
+```
+
+This creates uid 1000 in the container, chowns `/var/www/html` to 1000:1000, and reloads Apache.
+
+---
+
+## Upgrading to a newer Grav RC
+
+Grav 2.0 is baked into the custom Docker image via `Dockerfile`. The base `getgrav/grav` image ships 1.7 — the `Dockerfile` downloads the 2.0 RC bundle from GitHub and overwrites the core files at build time.
+
+To upgrade:
+1. Update the bundle URL in `Dockerfile`
+2. Run `make setup` — Docker rebuilds the image layer automatically
+
+---
+
+## Required system.yaml settings (Grav 2.0)
+
+After upgrading, verify these are set in `user/config/system.yaml`:
+
+```yaml
+accounts:
+  type: flex      # required for Admin2 API
+pages:
+  type: flex      # required for Admin2 pages API
+```
+
+---
+
+## Admin user API permissions
+
+The admin user account needs `api.*` permissions for Admin2. In `user/accounts/<username>.yaml`:
+
+```yaml
+access:
+  admin:
+    login: true
+    super: true
+  api:
+    super: true
+    access: true
+```
+
+---
+
+## Disable the old admin plugin
+
+Both `admin` and `admin2` route to `/admin` and conflict. After installing `admin2`, disable the old one:
+
+In `user/plugins/admin/admin.yaml`:
+```yaml
+enabled: false
+```
+
+---
+
+## JWT secret
+
+Leave `jwt_secret: ''` in `user/plugins/api/api.yaml`. It works for local dev; production installs generate a secure secret automatically during `make remote-install`.
+
+---
+
+## 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.