.agent/skills/astro/SKILL.md

@@ -266,7 +266,7 @@ Keep hostname routing and nginx server_name policy in the `nginx` skill and setu
 ### sharp has no pre-built binary for FreeBSD
 
 `sharp` is an optional Astro image optimization library. It tries to build from
-source on FreeBSD, which fails because `node-addon-api` is not bundled.
+source on FreeBSD, which requires `node-addon-api` to be bundled.
 
 **Symptoms:**
 

.agent/skills/docs-deployment/SKILL.md

@@ -270,7 +270,7 @@ echo "*-DRAFT.md" >> /home/clawdie/clawdie-ai/docs/.docignore
 
 ### Instant Rollback
 
-If new version is broken:
+If the new version needs rollback:
 
 ```bash
 # Find previous working version
@@ -299,7 +299,7 @@ ls -l /usr/local/www/docs.clawdie.si/{en,de,fr,es}-current
 # Sync logs (watch real-time)
 tail -f /var/log/clawdie-docs-sync.log
 
-# Check for broken symlinks
+# Verify symlinks
 find /usr/local/www/docs.clawdie.si -maxdepth 1 -type l ! -exec test -d {} \; -print
 # Should be empty
 ```

.agent/skills/nginx/SKILL.md

@@ -299,7 +299,7 @@ Store credentials in `/home/clawdie/clawdie-ai/.env`. Never in skill files.
 ## Safe defaults
 
 - Always run `nginx -t` before reloading
-- Never reload nginx with a broken config
+- Reload nginx only with a valid config
 - Back up vhost configs before modifying
 - Keep CSS in shared files, not inline (except index.html which is self-contained)
 - Test changes locally before pushing to production
@@ -348,7 +348,7 @@ Do not proceed until the authoritative NS returns the correct IP.
 
 **Hiccup #1: nginx refuses to start when the SSL cert file doesn't exist.**
 The vhost references `ssl_certificate` and `ssl_certificate_key` — if those
-files are absent, `nginx -t` fails and you can't even start the HTTP server for
+files are missing, `nginx -t` reports an error and the HTTP server cannot start for
 ACME validation. Fix: create a **temporary self-signed cert** first:
 
 ```sh
@@ -620,13 +620,13 @@ curl -sI https://docs.clawdie.si/architecture/colibri/ | head -5
 
 ## Troubleshooting
 
-### nginx won't start
+### nginx status check
 
 - Check config: `nginx -t`
 - Check logs: `tail /var/log/nginx/error.log`
 - Check port conflicts: `sockstat -l | grep :80`
 
-### nginx config test fails: "cannot load certificate — BIO_new_file() failed"
+### SSL certificate file missing — "cannot load certificate"
 
 This means the `ssl_certificate` path in a vhost references a file that doesn't
 exist yet. **Do not remove the SSL block** — create a placeholder cert first:
@@ -645,7 +645,7 @@ HTTPS site" for the full flow.
 
 ### ACME challenge returns 404 or 301
 
-Two common causes:
+Two things to check:
 
 1. **The `location /.well-known/acme-challenge/` block is AFTER the
    `location / { return 301 https://... }` redirect.** Nginx matches locations

.agent/skills/setup/SKILL.md

@@ -7,7 +7,7 @@ description: Run initial Clawdie setup on FreeBSD 15 + Lumina desktop. Use when
 
 Run setup steps automatically. Only pause when user action is required (channel authentication, configuration choices). Steps emit structured status blocks to stdout. Verbose logs go to `logs/setup.log`.
 
-**Principle:** When something is broken or missing, fix it. Don't tell the user to go fix it themselves unless it genuinely requires their manual action (e.g. authenticating a channel, pasting a secret token). If a dependency is missing, install it. If a service won't start, diagnose and repair. Ask the user for permission when needed, then do the work.
+**Principle:** When something needs repair, handle it. Don't tell the user to go fix it themselves unless it genuinely requires their manual action (e.g. authenticating a channel, pasting a secret token). If a dependency is missing, install it. If a service needs diagnosis, investigate and resolve. Ask the user for permission when needed, then do the work.
 
 **UX Note:** Use `AskUserQuestion` for all user-facing questions.
 
@@ -52,7 +52,7 @@ Run `bash setup.sh` and parse the status block.
   ```
   After installing, re-run `bash setup.sh`.
 - If DEPS_OK=false → Read `logs/setup.log`. Delete `node_modules` and re-run `bash setup.sh`.
-- If NATIVE_OK=false → `pg` native bindings failed to load. Install build tools:
+- If NATIVE_OK=false → `pg` native bindings need build tools:
   ```bash
   sudo pkg install -y gmake gcc python311
   ```
@@ -147,14 +147,14 @@ Run `npx tsx setup/index.ts --step service` and parse the status block.
 
 - Read `logs/setup.log` for the error.
 - Check: `sudo service clawdie status`
-- Common causes: missing `.env`, Node.js path wrong, build not run yet.
+- What to check: missing `.env`, Node.js path incorrect, build not yet run.
 - Run `npm run build` first, then retry the service step.
 
 ## 8. Verify
 
 Run `npx tsx setup/index.ts --step verify` and parse the status block.
 
-**If STATUS=failed, fix each:**
+**If STATUS=failed, resolve each:**
 
 - SERVICE=stopped → `npm run build`, then `sudo service clawdie start`
 - SERVICE=not_found → re-run step 7

.agent/skills/update/SKILL.md

@@ -7,7 +7,7 @@ description: 'Update Clawdie from upstream or apply local changes safely with ZF
 
 Pull upstream changes and merge them with the current installation, using ZFS snapshots for rollback safety. The update skill always takes a snapshot before applying changes so rollback is instant via `zfs rollback`.
 
-**Principle:** Handle everything automatically. Only pause for user confirmation before applying changes, or when merge conflicts need human judgment. Never leave the system in a broken state — if the update fails, roll back to the snapshot.
+**Principle:** Handle everything automatically. Only pause for user confirmation before applying changes, or when merge conflicts need human judgment. Always leave the system in a consistent state — if the update encounters an issue, roll back to the snapshot.
 
 **UX Note:** Use `AskUserQuestion` for all user-facing questions.
 
@@ -210,7 +210,7 @@ npm run build
 npm test
 ```
 
-**If tests fail:** Show which tests failed. Try to diagnose and fix. If unfixable, warn user and offer rollback.
+**If tests don't pass:** Show which tests need attention. Try to diagnose and resolve. If not immediately resolvable, inform the user and offer rollback.
 
 ### Type check
 
@@ -301,7 +301,7 @@ sudo zfs snapshot zroot/clawdie-runtime/jails/cms@v${NEW_VERSION}-$(./scripts/da
 
 **Build fails after update:** Check if dependencies changed. Run `npm install` to pick up new packages. Check for breaking TypeScript changes.
 
-**Service won't start after update:** Check `logs/clawdie.error.log`. If unfixable, roll back the affected service jail snapshot under `zroot/clawdie-runtime/jails/`.
+**Service needs attention after update:** Check `logs/clawdie.error.log`. If not immediately resolvable, roll back the affected service jail snapshot under `zroot/clawdie-runtime/jails/`.
 
 **ZFS snapshot missing:** If the pre-update snapshot wasn't taken (manual setup without ZFS), fall back to `git reset --hard HEAD~1` but this is less safe. Always prefer ZFS rollback.