Implement academy analytics, billing, and web stories updates

docs/academy-billing-production.md

@@ -0,0 +1,105 @@
+# Academy Billing Production Rollout
+
+Last updated: 2026-05-19
+
+This note covers the remaining non-code steps required to move Academy Stripe billing from implemented-in-app to production-ready.
+
+## Readiness Check
+
+Run the local readiness command before enabling the rollout flag:
+
+```bash
+php artisan academy:billing-health
+php artisan academy:billing-health --json
+php artisan academy:billing-health --strict
+```
+
+What it checks:
+- Stripe publishable key, secret key, and webhook secret are configured and not placeholder values
+- Academy billing price IDs are present for all configured plans
+- Cashier webhook and Academy billing routes are registered
+- Billing tables and Cashier user columns exist locally
+- Moderation Academy billing overview route is available
+
+`--strict` exits non-zero when blocking issues are found, which makes it suitable for CI or pre-deploy checks.
+
+## Environment Variables
+
+The following values must be set with real production values before enabling Academy billing:
+
+```dotenv
+SKINBASE_ACADEMY_ENABLED=true
+ACADEMY_BILLING_ENABLED=true
+ACADEMY_STRIPE_SUBSCRIPTION_NAME=academy
+
+STRIPE_KEY=pk_live_...
+STRIPE_SECRET=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+CASHIER_CURRENCY=eur
+CASHIER_CURRENCY_LOCALE=sl_SI
+
+ACADEMY_CREATOR_MONTHLY_PRICE_ID=price_...
+ACADEMY_PRO_MONTHLY_PRICE_ID=price_...
+```
+
+Do not enable `ACADEMY_BILLING_ENABLED=true` until the webhook endpoint and Billing Portal are configured in Stripe.
+
+## Stripe Dashboard Steps
+
+Create these products:
+- Skinbase Academy Creator
+- Skinbase Academy Pro
+
+Create these recurring prices:
+- `creator_monthly`
+- `pro_monthly`
+
+Configure the production webhook endpoint:
+- URL: `https://skinbase.org/stripe/webhook`
+- Signing secret: copy into `STRIPE_WEBHOOK_SECRET`
+
+Recommended subscribed events:
+- `checkout.session.completed`
+- `customer.subscription.created`
+- `customer.subscription.updated`
+- `customer.subscription.deleted`
+- `customer.updated`
+- `customer.deleted`
+- `payment_method.automatically_updated`
+- `invoice.payment_succeeded`
+- `invoice.payment_failed`
+- `invoice.payment_action_required`
+
+Configure Stripe Billing Portal:
+- Allow payment method updates
+- Allow plan changes
+- Allow cancellation
+- Allow invoice history access
+
+## Deployment Sequence
+
+1. Deploy code and migrations.
+2. Populate production env with live Stripe values and production price IDs.
+3. Run `php artisan academy:billing-health --strict` on the target environment.
+4. Confirm the webhook endpoint is reachable and signature verification is active.
+5. Test a full Stripe test-mode or low-risk live transaction.
+6. Verify the subscription appears in local Cashier tables and Academy access updates from synced state.
+7. Verify `/moderation/academy/billing` shows the expected audit event and subscription counts.
+8. Enable `ACADEMY_BILLING_ENABLED=true` only after the prior checks pass.
+
+## Smoke Test Checklist
+
+After rollout:
+- Guest can view Academy pricing
+- Guest cannot start checkout
+- Verified user can start checkout
+- Success page does not grant access by itself
+- Webhook sync creates or updates the local subscription rows
+- Creator plan unlocks creator content but not pro content
+- Pro plan unlocks creator and pro content
+- Billing Portal opens and returns to `/academy/billing`
+- Canceling a subscription keeps access during grace period and removes it after end
+
+## Operational Note
+
+The moderation billing overview at `/moderation/academy/billing` is visibility-only. It is not a manual entitlement system and should not be used to bypass Stripe billing state.

docs/cli-reference.md

@@ -1,6 +1,6 @@
 # Skinbase26 CLI Reference
 
-Last updated: 2026-04-25
+Last updated: 2026-05-19
 
 This document lists the repository-specific command-line entry points in Skinbase26.
 
@@ -20,14 +20,14 @@ Examples below are representative. For the full option list of any Artisan comma
 | Entry point | Why it is used | Example |
 | --- | --- | --- |
 | `php artisan` | Main Laravel CLI for all custom app commands listed below | `php artisan list --raw` |
-| `bash sync.sh` | Main production deploy wrapper; delegates to the production deploy script | `bash sync.sh` |
+| `bash sync.sh` | Main production deploy wrapper; delegates to the safe release-based production deploy script | `bash sync.sh` |
 | `bash sync_dev.sh` | Push the development environment to the configured remote dev host | `bash sync_dev.sh` |
 
 ## Maintained Standalone Scripts
 
 | Script | Why it is used | Example |
 | --- | --- | --- |
-| `scripts/deploy-production.sh` | Full production deployment workflow using retained release directories and a server-side current-release switch | `bash scripts/deploy-production.sh --mode=normal` |
+| `scripts/deploy-production.sh` | Safe production deployment wrapper that resolves to the retained-release deploy workflow with a server-side current-release switch | `bash scripts/deploy-production.sh --mode=normal` |
 | `scripts/rollback-production.sh` | Switch the active production release to a previously retained server-side deployment | `bash scripts/rollback-production.sh --previous` |
 | `scripts/push-db-to-prod.sh` | Push the local database to production with remote backup controls | `bash scripts/push-db-to-prod.sh --force` |
 | `scripts/render-nova-card.cjs` | Render a Nova card screenshot through Playwright | `node scripts/render-nova-card.cjs --url=https://example.test/card --out=tmp/card.png` |
@@ -57,6 +57,14 @@ Examples below are representative. For the full option list of any Artisan comma
 | `ai-biography:review-queue` | List AI biography records that need manual review | `php artisan ai-biography:review-queue --needs-review --limit=25` |
 | `ai-biography:validate` | Revalidate stored AI biographies against the current rules | `php artisan ai-biography:validate --limit=100 --dry-run` |
 
+### Academy
+
+| Command | Why it is used | Example |
+| --- | --- | --- |
+| `academy:analytics-health` | Inspect Academy analytics collection health, rollup freshness, and privacy safeguards | `php artisan academy:analytics-health --json` |
+| `academy:billing-health` | Check Academy Stripe billing rollout readiness, including Stripe secrets, price IDs, Cashier routes, and billing tables | `php artisan academy:billing-health --strict` |
+| `academy:courses:sync-foundations` | Create or update the default AI-Assisted Digital Art Foundations Academy course | `php artisan academy:courses:sync-foundations` |
+
 ### Artworks
 
 | Command | Why it is used | Example |

docs/deployment.md

@@ -10,6 +10,8 @@ Run the existing entrypoint:
 bash sync.sh
 ```
 
+`bash sync.sh` delegates to the safe production deploy wrapper, which stages each deploy into a versioned release directory and switches traffic by updating the server-side `current` symlink.
+
 If you launch `bash sync.sh` from WSL against this Windows checkout, the script will automatically run the frontend build with `npm.cmd` on Windows so Rollup/Vite use the correct optional native package set.
 
 This will: