@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/deploy/references/hetzner-setup.md

@@ -0,0 +1,67 @@
+# Hetzner VM Setup Guide
+
+First-time setup for deploying containerized applications to a Hetzner Cloud VM.
+
+## Primary Path: Terraform
+
+Always provision infrastructure via Terraform for reproducibility and cloud portability. See existing patterns:
+
+- `apps/web-platform/infra/` — CPX21 server, 20GB volume, HTTP/HTTPS firewall
+
+### Quick Start
+
+```bash
+cd apps/<app>/infra
+terraform init
+# Interactive shell: enter the token at the prompt (it stays off the argument list and out of shell history).
+# An agent or CI run has no terminal: export TF_VAR_hcloud_token from its secret store before this block (the guard keeps it).
+if [ -z "${TF_VAR_hcloud_token:-}" ]; then printf 'Hetzner API token: ' >&2; read -rs TF_VAR_hcloud_token && echo >&2 && export TF_VAR_hcloud_token; fi
+terraform apply -var='admin_ips=["<your-ip>/32"]'
+unset TF_VAR_hcloud_token
+```
+
+Terraform handles: server creation, SSH key upload, volume attachment, firewall rules, and cloud-init (Docker install, volume mount, container start, SSH hardening).
+
+### Post-Terraform Steps
+
+1. Create `.env` with app secrets
+2. SCP `.env` to `root@<server-ip>:/mnt/data/.env`
+3. Authenticate Docker with GHCR on the server (see below)
+4. Restart container: `ssh root@<ip> "docker restart <container>"`
+
+## Manual Steps (only when Terraform doesn't cover them)
+
+### Authenticate with GHCR
+
+Create a GitHub Personal Access Token (classic) with `read:packages` scope, then log in on the server:
+
+```bash
+echo "<ghcr-token>" | docker login ghcr.io -u <github-username> --password-stdin
+```
+
+Pipe the token via stdin — do not pass it as a command-line argument.
+
+### SSH Key Setup
+
+On the local machine, generate a deploy key and copy it to the server:
+
+```bash
+ssh-keygen -t ed25519 -f ~/.ssh/deploy_key -N ""
+ssh-copy-id -i ~/.ssh/deploy_key.pub root@<server-ip>
+```
+
+Verify passwordless access:
+
+```bash
+ssh -o BatchMode=yes -i ~/.ssh/deploy_key root@<server-ip> "echo OK"
+```
+
+### Health Endpoint
+
+Add a `/health` endpoint to the application that returns HTTP 200 when the service is ready. The deploy skill checks this endpoint after deployment.
+
+Set the `DEPLOY_HEALTH_URL` environment variable to enable automated health verification:
+
+```bash
+export DEPLOY_HEALTH_URL="http://<server-ip>:<app-port>/health"
+```

package/skills/deploy/scripts/deploy.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Required env vars (fail-fast with :? syntax)
+IMAGE="${DEPLOY_IMAGE:?Set DEPLOY_IMAGE env var}"
+HOST="${DEPLOY_HOST:?Set DEPLOY_HOST env var}"
+CONTAINER="${DEPLOY_CONTAINER:-$(basename "$IMAGE")}"
+DOCKERFILE="${DEPLOY_DOCKERFILE:-./Dockerfile}"
+TAG=$(git rev-parse --short HEAD)
+
+echo "=== Deploying $IMAGE:$TAG to $HOST ==="
+
+# Build and push
+echo "Building $IMAGE:$TAG ..."
+docker build -f "$DOCKERFILE" -t "$IMAGE:$TAG" -t "$IMAGE:latest" .
+echo "Pushing to GHCR ..."
+docker push "$IMAGE:$TAG"
+docker push "$IMAGE:latest"
+
+# Deploy via SSH: pull new image, stop old container, start new one
+echo "Deploying to $HOST ..."
+ssh "$HOST" "docker pull $IMAGE:$TAG \
+  && { docker stop $CONTAINER 2>/dev/null || true; } \
+  && { docker rm $CONTAINER 2>/dev/null || true; } \
+  && docker run -d --name $CONTAINER --restart unless-stopped $IMAGE:$TAG"
+
+# Health check (if URL provided)
+if [[ -n "${DEPLOY_HEALTH_URL:-}" ]]; then
+  echo "Checking health at $DEPLOY_HEALTH_URL ..."
+  for i in 1 2 3 4 5; do
+    curl -sf --max-time 5 "$DEPLOY_HEALTH_URL" > /dev/null 2>&1 && { echo "Health check passed"; break; }
+    [[ $i -eq 5 ]] && { echo "ERROR: Health check failed after 5 attempts" >&2; exit 1; }
+    sleep 3
+  done
+fi
+
+echo "Deployed $TAG to $HOST"

package/skills/deploy-docs/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: deploy-docs
+description: "This skill should be used when validating the documentation build and preparing for Cloudflare Pages deployment. It runs the Eleventy build, validates output, checks component counts, and provides deployment instructions."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Deploy Documentation Command
+
+Validate the documentation build and prepare it for Cloudflare Pages deployment.
+
+## Step 1: Build and Validate
+
+```bash
+# Install dependencies (if needed)
+npm ci --ignore-scripts
+
+# Run Eleventy build
+npx @11ty/eleventy
+
+# Verify build output
+test -f _site/index.html && echo "OK index.html"
+test -f "_site/pages/agents.html" && echo "OK agents.html"
+test -f "_site/pages/skills.html" && echo "OK skills.html"
+test -f "_site/pages/changelog.html" && echo "OK changelog.html"
+test -f "_site/pages/getting-started.html" && echo "OK getting-started.html"
+test -f _site/404.html && echo "OK 404.html"
+test -f _site/css/style.css && echo "OK style.css"
+test -f _site/CNAME && echo "OK CNAME"
+test -f _site/sitemap.xml && echo "OK sitemap.xml"
+```
+
+## Step 2: Verify Component Counts
+
+Use Grep to count occurrences of `component-card` in `_site/pages/agents.html` and `_site/pages/skills.html`.
+
+Then compare with source counts using Glob:
+
+- Agent files: count `.md` files (excluding README.md) under `plugins/soleur/agents/`
+- Skill files: count `SKILL.md` files under `plugins/soleur/skills/`
+
+Cards in the output must match source file counts exactly.
+
+## Step 3: Check for Uncommitted Changes
+
+```bash
+git status --porcelain plugins/soleur/docs/ eleventy.config.js package.json
+```
+
+If there are uncommitted changes, warn the user to commit first.
+
+## Step 4: Deployment
+
+Deployment is automated via `.github/workflows/deploy-docs.yml`:
+
+- **Trigger:** Push to `main` that changes docs, agents, skills, commands, plugin.json, or eleventy.config.js
+- **Manual:** Go to Actions > "Deploy Documentation to Cloudflare Pages" > "Run workflow"
+
+The workflow:
+
+1. Checks out the repo
+2. Installs Node.js 20 and npm dependencies
+3. Runs `npx @11ty/eleventy` to build
+4. Verifies all required files are present
+5. Stamps `_site/version.txt` with the commit SHA
+6. Deploys `_site/` to the `soleur-docs` Cloudflare Pages project with wrangler
+7. Fetches `version.txt` back and fails the job unless it matches the SHA just built
+
+## Step 5: Report Status
+
+Provide a summary:
+
+```
+## Deployment Readiness
+
+OK All HTML pages present
+OK CSS and fonts present
+OK Component counts match source
+OK CNAME and sitemap present
+
+### Next Steps
+- [ ] Commit any pending changes
+- [ ] Push to main branch
+- [ ] Verify deployment at https://soleur.ai/ (the live apex)
+
+> **The ADR-194 cutover is COMPLETE (2026-09-03).** `https://soleur.ai/` is
+> served by Cloudflare Pages and DOES advance with these deploys — verify at the
+> apex, not at `pages.dev`. Until PR4b this block said the opposite and sent the
+> operator to the `pages.dev` hostname; that was correct then and is misdirection
+> now. `soleur-docs.pages.dev` still resolves and is still a useful
+> origin-vs-edge discriminator, but it is not where a deploy is confirmed. See
+> `knowledge-base/engineering/operations/runbooks/cloudflare-pages-cutover.md`.
+```

package/skills/dhh-rails-style/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: dhh-rails-style
+description: "This skill should be used when writing Ruby and Rails code in DHH's 37signals style: REST purity, fat models, thin controllers, Current attributes, Hotwire patterns."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+<objective>
+Apply 37signals/DHH Rails conventions to Ruby and Rails code. This skill provides comprehensive domain expertise extracted from analyzing production 37signals codebases (Fizzy/Campfire) and DHH's code review patterns.
+</objective>
+
+<essential_principles>
+
+## Core Philosophy
+
+"The best code is the code you don't write. The second best is the code that's obviously correct."
+
+**Vanilla Rails is plenty:**
+
+- Rich domain models over service objects
+- CRUD controllers over custom actions
+- Concerns for horizontal code sharing
+- Records as state instead of boolean columns
+- Database-backed everything (no Redis)
+- Build solutions before reaching for gems
+
+**What they deliberately avoid:**
+
+- devise (custom ~150-line auth instead)
+- pundit/cancancan (simple role checks in models)
+- sidekiq (Solid Queue uses database)
+- redis (database for everything)
+- view_component (partials work fine)
+- GraphQL (REST with Turbo sufficient)
+- factory_bot (fixtures are simpler)
+- rspec (Minitest ships with Rails)
+- Tailwind (native CSS with layers)
+
+**Development Philosophy:**
+
+- Ship, Validate, Refine - prototype-quality code to production to learn
+- Fix root causes, not symptoms
+- Write-time operations over read-time computations
+- Database constraints over ActiveRecord validations
+</essential_principles>
+
+<intake>
+What are you working on?
+
+1. **Controllers** - REST mapping, concerns, Turbo responses, API patterns
+2. **Models** - Concerns, state records, callbacks, scopes, POROs
+3. **Views & Frontend** - Turbo, Stimulus, CSS, partials
+4. **Architecture** - Routing, multi-tenancy, authentication, jobs, caching
+5. **Testing** - Minitest, fixtures, integration tests
+6. **Gems & Dependencies** - What to use vs avoid
+7. **Code Review** - Review code against DHH style
+8. **General Guidance** - Philosophy and conventions
+
+**Specify a number or describe your task.**
+</intake>
+
+<routing>
+
+| Response | Reference to Read |
+|----------|-------------------|
+| 1, controller | [controllers.md](./references/controllers.md) |
+| 2, model | [models.md](./references/models.md) |
+| 3, view, frontend, turbo, stimulus, css | [frontend.md](./references/frontend.md) |
+| 4, architecture, routing, auth, job, cache | [architecture.md](./references/architecture.md) |
+| 5, test, testing, minitest, fixture | [testing.md](./references/testing.md) |
+| 6, gem, dependency, library | [gems.md](./references/gems.md) |
+| 7, review | Read all references, then review code |
+| 8, general task | Read relevant references based on context |
+
+**After reading relevant references, apply patterns to the user's code.**
+</routing>
+
+<quick_reference>
+
+## Naming Conventions
+
+**Verbs:** `card.close`, `card.gild`, `board.publish` (not `set_style` methods)
+
+**Predicates:** `card.closed?`, `card.golden?` (derived from presence of related record)
+
+**Concerns:** Adjectives describing capability (`Closeable`, `Publishable`, `Watchable`)
+
+**Controllers:** Nouns matching resources (`Cards::ClosuresController`)
+
+**Scopes:**
+
+- `chronologically`, `reverse_chronologically`, `alphabetically`, `latest`
+- `preloaded` (standard eager loading name)
+- `indexed_by`, `sorted_by` (parameterized)
+- `active`, `unassigned` (business terms, not SQL-ish)
+
+## REST Mapping
+
+Instead of custom actions, create new resources:
+
+```
+POST /cards/:id/close    → POST /cards/:id/closure
+DELETE /cards/:id/close  → DELETE /cards/:id/closure
+POST /cards/:id/archive  → POST /cards/:id/archival
+```
+
+## Ruby Syntax Preferences
+
+```ruby
+# Symbol arrays with spaces inside brackets
+before_action :set_message, only: %i[ show edit update destroy ]
+
+# Private method indentation
+  private
+    def set_message
+      @message = Message.find(params[:id])
+    end
+
+# Expression-less case for conditionals
+case
+when params[:before].present?
+  messages.page_before(params[:before])
+else
+  messages.last_page
+end
+
+# Bang methods for fail-fast
+@message = Message.create!(params)
+
+# Ternaries for simple conditionals
+@room.direct? ? @room.users : @message.mentionees
+```
+
+## Key Patterns
+
+**State as Records:**
+
+```ruby
+Card.joins(:closure)         # closed cards
+Card.where.missing(:closure) # open cards
+```
+
+**Current Attributes:**
+
+```ruby
+belongs_to :creator, default: -> { Current.user }
+```
+
+**Authorization on Models:**
+
+```ruby
+class User < ApplicationRecord
+  def can_administer?(message)
+    message.creator == self || admin?
+  end
+end
+```
+
+</quick_reference>
+
+<reference_index>
+
+## Domain Knowledge
+
+All detailed patterns in `references/`:
+
+| File | Topics |
+|------|--------|
+| [controllers.md](./references/controllers.md) | REST mapping, concerns, Turbo responses, API patterns, HTTP caching |
+| [models.md](./references/models.md) | Concerns, state records, callbacks, scopes, POROs, authorization, broadcasting |
+| [frontend.md](./references/frontend.md) | Turbo Streams, Stimulus controllers, CSS layers, OKLCH colors, partials |
+| [architecture.md](./references/architecture.md) | Routing, authentication, jobs, Current attributes, caching, database patterns |
+| [testing.md](./references/testing.md) | Minitest, fixtures, unit/integration/system tests, testing patterns |
+| [gems.md](./references/gems.md) | What they use vs avoid, decision framework, Gemfile examples |
+
+</reference_index>
+
+<success_criteria>
+Code follows DHH style when:
+
+- Controllers map to CRUD verbs on resources
+- Models use concerns for horizontal behavior
+- State is tracked via records, not booleans
+- No unnecessary service objects or abstractions
+- Database-backed solutions preferred over external services
+- Tests use Minitest with fixtures
+- Turbo/Stimulus for interactivity (no heavy JS frameworks)
+- Native CSS with modern features (layers, OKLCH, nesting)
+- Authorization logic lives on User model
+- Jobs are shallow wrappers calling model methods
+</success_criteria>
+
+<credits>
+Based on [The Unofficial 37signals/DHH Rails Style Guide](https://github.com/marckohlbrugge/unofficial-37signals-coding-style-guide) by [Marc Köhlbrugge](https://x.com/marckohlbrugge), generated through deep analysis of 265 pull requests from the Fizzy codebase.
+
+**Important Disclaimers:**
+
+- LLM-generated guide - may contain inaccuracies
+- Code examples from Fizzy are licensed under the O'Saasy License
+- Not affiliated with or endorsed by 37signals
+</credits>