mirror of
https://github.com/bitsocialnet/5chan.git
synced 2026-08-03 07:41:04 +02:00
fix(ai skills): correct stale branch names, rg flags, and commit scope rules
Fixes deslop diffing against nonexistent main, an invalid rg --type tsx flag in fix-merge-conflicts, a Codex-specific phrase leaking into the Claude/Cursor inspect-elements description, and aligns commit-format with the required-scope convention the commit skill and git history already use. Rewrites the readme skill from 764 lines of Rails-specific guidance to a lean version matching this Vite/Capacitor/Electron repo.
This commit is contained in:
Tommaso Casaburi
@@ -9,12 +9,12 @@ description: Formats GitHub commit messages following Conventional Commits style
|
||||
|
||||
Title only — raw markdown:
|
||||
```
|
||||
> **Commit title:** `type: short description here`
|
||||
> **Commit title:** `type(scope): short description here`
|
||||
```
|
||||
|
||||
Title with description — raw markdown:
|
||||
```
|
||||
> **Commit title:** `type: short description here`
|
||||
> **Commit title:** `type(scope): short description here`
|
||||
>
|
||||
> Description sentence one. Description sentence two with `codeRef()` references.
|
||||
```
|
||||
@@ -25,31 +25,38 @@ Title with description — raw markdown:
|
||||
2. Title goes after `**Commit title:**` wrapped in exactly ONE backtick pair
|
||||
3. NEVER put backticks inside the title — the whole title is one code span, no nesting
|
||||
4. Description uses backticks for code references — title does NOT
|
||||
5. Conventional Commits types: `fix:`, `feat:`, `perf:`, `refactor:`, `docs:`, `chore:`
|
||||
6. Use `perf:` for performance optimizations (not `fix:`)
|
||||
5. Conventional Commits types: `fix`, `feat`, `perf`, `refactor`, `docs`, `chore`
|
||||
6. Always include a scope — a short, human-readable area name (e.g. `reply modal`, `mod queue`), matching how this repo actually commits (see the `commit` skill)
|
||||
7. Use `perf` for performance optimizations (not `fix`)
|
||||
7. Description: 2-3 sentences about the solution, no bullet points, only if title isn't enough
|
||||
|
||||
## Wrong vs Right
|
||||
|
||||
❌ WRONG — missing backticks around title:
|
||||
```
|
||||
> **Commit title:** refactor: rename from /queue to /modqueue
|
||||
> **Commit title:** refactor(mod queue): rename from /queue to /modqueue
|
||||
```
|
||||
|
||||
❌ WRONG — backticks around individual words instead of whole title:
|
||||
```
|
||||
> **Commit title:** refactor: rename from `/queue` to `/modqueue`
|
||||
> **Commit title:** refactor(mod queue): rename from `/queue` to `/modqueue`
|
||||
```
|
||||
|
||||
✅ CORRECT — entire title in one backtick pair, no backticks inside:
|
||||
❌ WRONG — missing scope:
|
||||
```
|
||||
> **Commit title:** `refactor: rename from /queue to /modqueue`
|
||||
```
|
||||
|
||||
✅ CORRECT — entire title in one backtick pair, no backticks inside, scope present:
|
||||
```
|
||||
> **Commit title:** `refactor(mod queue): rename from /queue to /modqueue`
|
||||
```
|
||||
|
||||
## Self-check
|
||||
|
||||
Before outputting, verify:
|
||||
- [ ] Lines start with `>`
|
||||
- [ ] Title is wrapped in exactly one backtick pair: `` `like this` ``
|
||||
- [ ] Title has the form `type(scope): description`
|
||||
- [ ] No backticks inside the title text
|
||||
- [ ] Code references in description (not title) use backticks
|
||||
|
||||
@@ -6,19 +6,19 @@ disable-model-invocation: true
|
||||
|
||||
# Remove AI Code Slop
|
||||
|
||||
Scan the diff against main and remove AI-generated slop introduced in this branch.
|
||||
Scan the diff against master and remove AI-generated slop introduced in this branch.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Get the diff**
|
||||
|
||||
```bash
|
||||
git diff main...HEAD
|
||||
git diff master...HEAD
|
||||
```
|
||||
|
||||
If there are also uncommitted changes, include them:
|
||||
```bash
|
||||
git diff main
|
||||
git diff master
|
||||
```
|
||||
|
||||
2. **Scan each changed file** for the slop categories below
|
||||
|
||||
@@ -56,7 +56,7 @@ If `package.json` was modified, run `corepack yarn install` first.
|
||||
### 4. Verify no remaining markers
|
||||
|
||||
```bash
|
||||
rg '<<<<<<<|=======|>>>>>>>' --type ts --type tsx --type json
|
||||
rg '<<<<<<<|=======|>>>>>>>' --type ts --type json
|
||||
```
|
||||
|
||||
If any markers remain, go back and resolve them.
|
||||
@@ -65,7 +65,7 @@ If any markers remain, go back and resolve them.
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "chore: resolve merge conflicts"
|
||||
git commit -m "chore(merge): resolve merge conflicts"
|
||||
```
|
||||
|
||||
## Operational Guidance
|
||||
@@ -79,5 +79,5 @@ git commit -m "chore: resolve merge conflicts"
|
||||
|
||||
- Clean working tree with all conflicts resolved
|
||||
- Passing `corepack yarn build && corepack yarn lint && corepack yarn type-check`
|
||||
- One local commit: `chore: resolve merge conflicts`
|
||||
- One local commit: `chore(merge): resolve merge conflicts`
|
||||
- Brief summary of files touched and notable resolution choices
|
||||
|
||||
@@ -32,7 +32,7 @@ Batch 3 (parallel): [tasks that depend on batch 2]
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Max 4 concurrent subagents (tool limitation)
|
||||
- Max 4 concurrent subagents, to bound machine load and coordination overhead
|
||||
- Tasks touching the same file(s) go in the same subagent or sequential batches — never parallel
|
||||
- Small related tasks can be grouped into one subagent to reduce overhead
|
||||
- Large independent tasks get their own subagent
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: inspect-elements
|
||||
description: Resolve on-screen 5chan DOM elements to React source files, line numbers, component names, and ownership stacks using the app's dev-only element-source helpers and playwright-cli. Use when Codex needs to inspect a page element, map a snapshot ref to source code, confirm which component rendered a node, or follow up after $profile-browsing finds a rerender hotspot and needs file-level attribution.
|
||||
description: Resolve on-screen 5chan DOM elements to React source files, line numbers, component names, and ownership stacks using the app's dev-only element-source helpers and playwright-cli. Use when an agent needs to inspect a page element, map a snapshot ref to source code, confirm which component rendered a node, or follow up after $profile-browsing finds a rerender hotspot and needs file-level attribution.
|
||||
---
|
||||
|
||||
# Inspect Elements
|
||||
|
||||
+40
-737
@@ -1,764 +1,67 @@
|
||||
---
|
||||
name: readme
|
||||
description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment.
|
||||
description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. Produces thorough, verified documentation covering local setup, architecture, and distribution.
|
||||
---
|
||||
|
||||
# README Generator
|
||||
|
||||
You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.
|
||||
You are an expert technical writer. Write (or update) a README.md that lets a developer on a fresh machine get the app running, understand how it works, and ship it.
|
||||
|
||||
## The Three Purposes of a README
|
||||
|
||||
1. **Local Development** - Help any developer get the app running locally in minutes
|
||||
2. **Understanding the System** - Explain in great detail how the app works
|
||||
3. **Production Deployment** - Cover everything needed to deploy and maintain in production
|
||||
|
||||
---
|
||||
2. **Understanding the System** - Explain how the app is put together and why
|
||||
3. **Distribution** - Cover how the project is built, released, and deployed
|
||||
|
||||
## Before Writing
|
||||
|
||||
### Step 1: Deep Codebase Exploration
|
||||
**If a README.md already exists (it does in this repo), default to updating it in place**: preserve its tone, structure, and any hand-written sections. Only restructure wholesale if the user asks for a rewrite.
|
||||
|
||||
Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:
|
||||
### Step 1: Explore the codebase — never document from memory
|
||||
|
||||
**Project Structure**
|
||||
- Read the root directory structure
|
||||
- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
|
||||
- Find the main entry point(s)
|
||||
- Map out the directory organization
|
||||
Every claim in the README must be verifiable in the repo. Check:
|
||||
|
||||
**Configuration Files**
|
||||
- .env.example, .env.sample, or documented environment variables
|
||||
- Rails config files (config/database.yml, config/application.rb, config/environments/)
|
||||
- Credentials setup (config/credentials.yml.enc, config/master.key)
|
||||
- Docker files (Dockerfile, docker-compose.yml)
|
||||
- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)
|
||||
- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)
|
||||
- **Manifest and scripts**: `package.json` (name, scripts, engines, packageManager), lockfile, `.nvmrc`
|
||||
- **Entry points and build**: `index.html`, `vite.config.js`, `src/` layout, `tsconfig.json`
|
||||
- **Platform targets**: `capacitor.config.ts` + `android/` (mobile), `electron/` + `forge.config.js` (desktop), `vercel.json` (web hosting), `fastlane/` (store releases)
|
||||
- **CI/CD**: `.github/workflows/`
|
||||
- **Repo docs that already answer questions**: `AGENTS.md`, `DESIGN.md`, `PRODUCT.md`, `CHANGELOG.md`, `docs/`
|
||||
- **Helper scripts**: `scripts/` — document the ones a contributor actually needs
|
||||
|
||||
**Database**
|
||||
- db/schema.rb or db/structure.sql
|
||||
- Migrations in db/migrate/
|
||||
- Seeds in db/seeds.rb
|
||||
- Database type from config/database.yml
|
||||
For this repo specifically: it is a Yarn 4 (Corepack) + Vite + React 19 SPA that also ships as an Android app (Capacitor) and desktop app (Electron Forge). Package-manager commands in the README must use `yarn`, never `npm`.
|
||||
|
||||
**Key Dependencies**
|
||||
- Gemfile and Gemfile.lock for Ruby gems
|
||||
- package.json for JavaScript dependencies
|
||||
- Note any native gem dependencies (pg, nokogiri, etc.)
|
||||
### Step 2: Ask only if critical
|
||||
|
||||
**Scripts and Commands**
|
||||
- bin/ scripts (bin/dev, bin/setup, bin/ci)
|
||||
- Procfile or Procfile.dev
|
||||
- Rake tasks (lib/tasks/)
|
||||
|
||||
### Step 2: Identify Deployment Target
|
||||
|
||||
Look for these files to determine deployment platform and tailor instructions:
|
||||
|
||||
- `Dockerfile` / `docker-compose.yml` → Docker-based deployment
|
||||
- `vercel.json` / `.vercel/` → Vercel
|
||||
- `netlify.toml` → Netlify
|
||||
- `fly.toml` → Fly.io
|
||||
- `railway.json` / `railway.toml` → Railway
|
||||
- `render.yaml` → Render
|
||||
- `app.yaml` → Google App Engine
|
||||
- `Procfile` → Heroku or Heroku-like platforms
|
||||
- `.ebextensions/` → AWS Elastic Beanstalk
|
||||
- `serverless.yml` → Serverless Framework
|
||||
- `terraform/` / `*.tf` → Terraform/Infrastructure as Code
|
||||
- `k8s/` / `kubernetes/` → Kubernetes
|
||||
|
||||
If no deployment config exists, provide general guidance with Docker as the recommended approach.
|
||||
|
||||
### Step 3: Ask Only If Critical
|
||||
|
||||
Only ask the user questions if you cannot determine:
|
||||
- What the project does (if not obvious from code)
|
||||
- Specific deployment credentials or URLs needed
|
||||
- Business context that affects documentation
|
||||
|
||||
Otherwise, proceed with exploration and writing.
|
||||
|
||||
---
|
||||
If something can be discovered from the repo, discover it. Ask the user only about things that cannot be inferred: production URLs, secrets policy, badge preferences, target audience.
|
||||
|
||||
## README Structure
|
||||
|
||||
Write the README with these sections in order:
|
||||
|
||||
### 1. Project Title and Overview
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief description of what the project does and who it's for. 2-3 sentences max.
|
||||
|
||||
## Key Features
|
||||
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
```
|
||||
|
||||
### 2. Tech Stack
|
||||
|
||||
List all major technologies:
|
||||
|
||||
```markdown
|
||||
## Tech Stack
|
||||
|
||||
- **Language**: Ruby 3.3+
|
||||
- **Framework**: Rails 7.2+
|
||||
- **Frontend**: Inertia.js with React
|
||||
- **Database**: PostgreSQL 16
|
||||
- **Background Jobs**: Solid Queue
|
||||
- **Caching**: Solid Cache
|
||||
- **Styling**: Tailwind CSS
|
||||
- **Deployment**: [Detected platform]
|
||||
```
|
||||
|
||||
### 3. Prerequisites
|
||||
|
||||
What must be installed before starting:
|
||||
|
||||
```markdown
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20 or higher
|
||||
- PostgreSQL 15 or higher (or Docker)
|
||||
- pnpm (recommended) or npm
|
||||
- A Google Cloud project for OAuth (optional for development)
|
||||
```
|
||||
|
||||
### 4. Getting Started
|
||||
|
||||
The complete local development guide:
|
||||
|
||||
```markdown
|
||||
## Getting Started
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
\`\`\`bash
|
||||
git clone https://github.com/user/repo.git
|
||||
cd repo
|
||||
\`\`\`
|
||||
|
||||
### 2. Install Ruby Dependencies
|
||||
|
||||
Ensure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):
|
||||
|
||||
\`\`\`bash
|
||||
bundle install
|
||||
\`\`\`
|
||||
|
||||
### 3. Install JavaScript Dependencies
|
||||
|
||||
\`\`\`bash
|
||||
corepack yarn install
|
||||
\`\`\`
|
||||
|
||||
### 4. Environment Setup
|
||||
|
||||
Copy the example environment file:
|
||||
|
||||
\`\`\`bash
|
||||
cp .env.example .env
|
||||
\`\`\`
|
||||
|
||||
Configure the following variables:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
|
||||
| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
|
||||
| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
|
||||
|
||||
### 5. Database Setup
|
||||
|
||||
Start PostgreSQL (if using Docker):
|
||||
|
||||
\`\`\`bash
|
||||
docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
|
||||
\`\`\`
|
||||
|
||||
Create and set up the database:
|
||||
|
||||
\`\`\`bash
|
||||
bin/rails db:setup
|
||||
\`\`\`
|
||||
|
||||
This runs `db:create`, `db:schema:load`, and `db:seed`.
|
||||
|
||||
For existing databases, run migrations:
|
||||
|
||||
\`\`\`bash
|
||||
bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### 6. Start Development Server
|
||||
|
||||
Using Foreman/Overmind (recommended, runs Rails + Vite):
|
||||
|
||||
\`\`\`bash
|
||||
bin/dev
|
||||
\`\`\`
|
||||
|
||||
Or manually:
|
||||
|
||||
\`\`\`bash
|
||||
# Terminal 1: Rails server
|
||||
bin/rails server
|
||||
|
||||
# Terminal 2: Vite dev server (for Inertia/React)
|
||||
bin/vite dev
|
||||
\`\`\`
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||
```
|
||||
|
||||
Include every step. Assume the reader is setting up on a fresh machine.
|
||||
|
||||
### 5. Architecture Overview
|
||||
|
||||
This is where you go absurdly deep:
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
\`\`\`
|
||||
├── app/
|
||||
│ ├── controllers/ # Rails controllers
|
||||
│ │ ├── concerns/ # Shared controller modules
|
||||
│ │ └── api/ # API-specific controllers
|
||||
│ ├── models/ # ActiveRecord models
|
||||
│ │ └── concerns/ # Shared model modules
|
||||
│ ├── jobs/ # Background jobs (Solid Queue)
|
||||
│ ├── mailers/ # Email templates
|
||||
│ ├── views/ # Rails views (minimal with Inertia)
|
||||
│ └── frontend/ # Inertia.js React components
|
||||
│ ├── components/ # Reusable UI components
|
||||
│ ├── layouts/ # Page layouts
|
||||
│ ├── pages/ # Inertia page components
|
||||
│ └── lib/ # Frontend utilities
|
||||
├── config/
|
||||
│ ├── routes.rb # Route definitions
|
||||
│ ├── database.yml # Database configuration
|
||||
│ └── initializers/ # App initializers
|
||||
├── db/
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ ├── schema.rb # Current schema
|
||||
│ └── seeds.rb # Seed data
|
||||
├── lib/
|
||||
│ └── tasks/ # Custom Rake tasks
|
||||
└── public/ # Static assets
|
||||
\`\`\`
|
||||
|
||||
### Request Lifecycle
|
||||
|
||||
1. Request hits Rails router (`config/routes.rb`)
|
||||
2. Middleware stack processes request (authentication, sessions, etc.)
|
||||
3. Controller action executes
|
||||
4. Models interact with PostgreSQL via ActiveRecord
|
||||
5. Inertia renders React component with props
|
||||
6. Response sent to browser
|
||||
|
||||
### Data Flow
|
||||
|
||||
\`\`\`
|
||||
User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
|
||||
↓
|
||||
React Props ← Inertia Response ←
|
||||
\`\`\`
|
||||
|
||||
### Key Components
|
||||
|
||||
**Authentication**
|
||||
- Devise/Rodauth for user authentication
|
||||
- Session-based auth with encrypted cookies
|
||||
- `authenticate_user!` before_action for protected routes
|
||||
|
||||
**Inertia.js Integration (`app/frontend/`)**
|
||||
- React components receive props from Rails controllers
|
||||
- `inertia_render` in controllers passes data to frontend
|
||||
- Shared data via `inertia_share` for layout props
|
||||
|
||||
**Background Jobs (`app/jobs/`)**
|
||||
- Solid Queue for job processing
|
||||
- Jobs stored in PostgreSQL (no Redis required)
|
||||
- Dashboard at `/jobs` for monitoring
|
||||
|
||||
**Database (`app/models/`)**
|
||||
- ActiveRecord models with associations
|
||||
- Query objects for complex queries
|
||||
- Concerns for shared model behavior
|
||||
|
||||
### Database Schema
|
||||
|
||||
\`\`\`
|
||||
users
|
||||
├── id (bigint, PK)
|
||||
├── email (string, unique, not null)
|
||||
├── encrypted_password (string)
|
||||
├── name (string)
|
||||
├── created_at (datetime)
|
||||
└── updated_at (datetime)
|
||||
|
||||
posts
|
||||
├── id (bigint, PK)
|
||||
├── title (string, not null)
|
||||
├── content (text)
|
||||
├── published (boolean, default: false)
|
||||
├── user_id (bigint, FK → users)
|
||||
├── created_at (datetime)
|
||||
└── updated_at (datetime)
|
||||
|
||||
solid_queue_jobs (background jobs)
|
||||
├── id (bigint, PK)
|
||||
├── queue_name (string)
|
||||
├── class_name (string)
|
||||
├── arguments (json)
|
||||
├── scheduled_at (datetime)
|
||||
└── ...
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 6. Environment Variables
|
||||
|
||||
Complete reference for all env vars:
|
||||
|
||||
```markdown
|
||||
## Environment Variables
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Description | How to Get |
|
||||
|----------|-------------|------------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
|
||||
| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
|
||||
|
||||
### Optional
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
|
||||
| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
|
||||
| `RAILS_MAX_THREADS` | Puma thread count | `5` |
|
||||
| `WEB_CONCURRENCY` | Puma worker count | `2` |
|
||||
| `SMTP_ADDRESS` | Mail server hostname | - |
|
||||
| `SMTP_PORT` | Mail server port | `587` |
|
||||
|
||||
### Rails Credentials
|
||||
|
||||
Sensitive values should be stored in Rails encrypted credentials:
|
||||
|
||||
\`\`\`bash
|
||||
# Edit credentials (opens in $EDITOR)
|
||||
bin/rails credentials:edit
|
||||
|
||||
# Or for environment-specific credentials
|
||||
RAILS_ENV=production bin/rails credentials:edit
|
||||
\`\`\`
|
||||
|
||||
Credentials file structure:
|
||||
\`\`\`yaml
|
||||
secret_key_base: xxx
|
||||
stripe:
|
||||
public_key: pk_xxx
|
||||
secret_key: sk_xxx
|
||||
google:
|
||||
client_id: xxx
|
||||
client_secret: xxx
|
||||
\`\`\`
|
||||
|
||||
Access in code: `Rails.application.credentials.stripe[:secret_key]`
|
||||
|
||||
### Environment-Specific
|
||||
|
||||
**Development**
|
||||
\`\`\`
|
||||
DATABASE_URL=postgresql://localhost/myapp_development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
\`\`\`
|
||||
|
||||
**Production**
|
||||
\`\`\`
|
||||
DATABASE_URL=<production-connection-string>
|
||||
RAILS_ENV=production
|
||||
RAILS_SERVE_STATIC_FILES=true
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 7. Available Scripts
|
||||
|
||||
```markdown
|
||||
## Available Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bin/dev` | Start development server (Rails + Vite via Foreman) |
|
||||
| `bin/rails server` | Start Rails server only |
|
||||
| `bin/vite dev` | Start Vite dev server only |
|
||||
| `bin/rails console` | Open Rails console (IRB with app loaded) |
|
||||
| `bin/rails db:migrate` | Run pending database migrations |
|
||||
| `bin/rails db:rollback` | Rollback last migration |
|
||||
| `bin/rails db:seed` | Run database seeds |
|
||||
| `bin/rails db:reset` | Drop, create, migrate, and seed database |
|
||||
| `bin/rails routes` | List all routes |
|
||||
| `bin/rails test` | Run test suite (Minitest) |
|
||||
| `bundle exec rspec` | Run test suite (RSpec, if used) |
|
||||
| `bin/rails assets:precompile` | Compile assets for production |
|
||||
| `bin/rubocop` | Run Ruby linter |
|
||||
| `yarn lint` | Run JavaScript/TypeScript linter |
|
||||
```
|
||||
|
||||
### 8. Testing
|
||||
|
||||
```markdown
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
\`\`\`bash
|
||||
# Run all tests (Minitest)
|
||||
bin/rails test
|
||||
|
||||
# Run all tests (RSpec, if used)
|
||||
bundle exec rspec
|
||||
|
||||
# Run specific test file
|
||||
bin/rails test test/models/user_test.rb
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
|
||||
# Run tests matching a pattern
|
||||
bin/rails test -n /creates_user/
|
||||
bundle exec rspec -e "creates user"
|
||||
|
||||
# Run system tests (browser tests)
|
||||
bin/rails test:system
|
||||
|
||||
# Run with coverage (SimpleCov)
|
||||
COVERAGE=true bin/rails test
|
||||
\`\`\`
|
||||
|
||||
### Test Structure
|
||||
|
||||
\`\`\`
|
||||
test/ # Minitest structure
|
||||
├── controllers/ # Controller tests
|
||||
├── models/ # Model unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── system/ # System/browser tests
|
||||
├── fixtures/ # Test data
|
||||
└── test_helper.rb # Test configuration
|
||||
|
||||
spec/ # RSpec structure (if used)
|
||||
├── models/
|
||||
├── requests/
|
||||
├── system/
|
||||
├── factories/ # FactoryBot factories
|
||||
├── support/
|
||||
└── rails_helper.rb
|
||||
\`\`\`
|
||||
|
||||
### Writing Tests
|
||||
|
||||
**Minitest example:**
|
||||
\`\`\`ruby
|
||||
require "test_helper"
|
||||
|
||||
class UserTest < ActiveSupport::TestCase
|
||||
test "creates user with valid attributes" do
|
||||
user = User.new(email: "test@example.com", name: "Test User")
|
||||
assert user.valid?
|
||||
end
|
||||
|
||||
test "requires email" do
|
||||
user = User.new(name: "Test User")
|
||||
assert_not user.valid?
|
||||
assert_includes user.errors[:email], "can't be blank"
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
**RSpec example:**
|
||||
\`\`\`ruby
|
||||
require "rails_helper"
|
||||
|
||||
RSpec.describe User, type: :model do
|
||||
describe "validations" do
|
||||
it "is valid with valid attributes" do
|
||||
user = build(:user)
|
||||
expect(user).to be_valid
|
||||
end
|
||||
|
||||
it "requires an email" do
|
||||
user = build(:user, email: nil)
|
||||
expect(user).not_to be_valid
|
||||
expect(user.errors[:email]).to include("can't be blank")
|
||||
end
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
### Frontend Testing
|
||||
|
||||
For Inertia/React components:
|
||||
|
||||
\`\`\`bash
|
||||
yarn test
|
||||
\`\`\`
|
||||
|
||||
\`\`\`typescript
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import { Dashboard } from './Dashboard'
|
||||
|
||||
describe('Dashboard', () => {
|
||||
it('renders user name', () => {
|
||||
render(<Dashboard user={{ name: 'Josh' }} />)
|
||||
expect(screen.getByText('Josh')).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 9. Deployment
|
||||
|
||||
Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal/, etc.):
|
||||
|
||||
```markdown
|
||||
## Deployment
|
||||
|
||||
### Kamal (Recommended for Rails)
|
||||
|
||||
If using Kamal for deployment:
|
||||
|
||||
\`\`\`bash
|
||||
# Setup Kamal (first time)
|
||||
kamal setup
|
||||
|
||||
# Deploy
|
||||
kamal deploy
|
||||
|
||||
# Rollback to previous version
|
||||
kamal rollback
|
||||
|
||||
# View logs
|
||||
kamal app logs
|
||||
|
||||
# Run console on production
|
||||
kamal app exec --interactive 'bin/rails console'
|
||||
\`\`\`
|
||||
|
||||
Configuration lives in `config/deploy.yml`.
|
||||
|
||||
### Docker
|
||||
|
||||
Build and run:
|
||||
|
||||
\`\`\`bash
|
||||
# Build image
|
||||
docker build -t myapp .
|
||||
|
||||
# Run with environment variables
|
||||
docker run -p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://... \
|
||||
-e SECRET_KEY_BASE=... \
|
||||
-e RAILS_ENV=production \
|
||||
myapp
|
||||
\`\`\`
|
||||
|
||||
### Heroku
|
||||
|
||||
\`\`\`bash
|
||||
# Create app
|
||||
heroku create myapp
|
||||
|
||||
# Add PostgreSQL
|
||||
heroku addons:create heroku-postgresql:mini
|
||||
|
||||
# Set environment variables
|
||||
heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
|
||||
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
|
||||
|
||||
# Deploy
|
||||
git push heroku main
|
||||
|
||||
# Run migrations
|
||||
heroku run bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Fly.io
|
||||
|
||||
\`\`\`bash
|
||||
# Launch (first time)
|
||||
fly launch
|
||||
|
||||
# Deploy
|
||||
fly deploy
|
||||
|
||||
# Run migrations
|
||||
fly ssh console -C "bin/rails db:migrate"
|
||||
|
||||
# Open console
|
||||
fly ssh console -C "bin/rails console"
|
||||
\`\`\`
|
||||
|
||||
### Render
|
||||
|
||||
If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
|
||||
|
||||
Manual setup:
|
||||
1. Create new Web Service
|
||||
2. Connect GitHub repository
|
||||
3. Set build command: `bundle install && bin/rails assets:precompile`
|
||||
4. Set start command: `bin/rails server`
|
||||
5. Add environment variables in dashboard
|
||||
|
||||
### Manual/VPS Deployment
|
||||
|
||||
\`\`\`bash
|
||||
# On the server:
|
||||
|
||||
# Pull latest code
|
||||
git pull origin main
|
||||
|
||||
# Install dependencies
|
||||
bundle install --deployment
|
||||
|
||||
# Compile assets
|
||||
RAILS_ENV=production bin/rails assets:precompile
|
||||
|
||||
# Run migrations
|
||||
RAILS_ENV=production bin/rails db:migrate
|
||||
|
||||
# Restart application server (e.g., Puma via systemd)
|
||||
sudo systemctl restart myapp
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 10. Troubleshooting
|
||||
|
||||
```markdown
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
**Error:** `could not connect to server: Connection refused`
|
||||
|
||||
**Solution:**
|
||||
1. Verify PostgreSQL is running: `pg_isready` or `docker ps`
|
||||
2. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
|
||||
3. Ensure database exists: `bin/rails db:create`
|
||||
|
||||
### Pending Migrations
|
||||
|
||||
**Error:** `Migrations are pending`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Asset Compilation Issues
|
||||
|
||||
**Error:** `The asset "application.css" is not present in the asset pipeline`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
# Clear and recompile assets
|
||||
bin/rails assets:clobber
|
||||
bin/rails assets:precompile
|
||||
\`\`\`
|
||||
|
||||
### Bundle Install Failures
|
||||
|
||||
**Error:** Native extension build failures
|
||||
|
||||
**Solution:**
|
||||
1. Ensure system dependencies are installed:
|
||||
\`\`\`bash
|
||||
# macOS
|
||||
brew install postgresql libpq
|
||||
|
||||
# Ubuntu
|
||||
sudo apt-get install libpq-dev
|
||||
\`\`\`
|
||||
2. Try again: `bundle install`
|
||||
|
||||
### Credentials Issues
|
||||
|
||||
**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`
|
||||
|
||||
**Solution:**
|
||||
The master key doesn't match the credentials file. Either:
|
||||
1. Get the correct `config/master.key` from another team member
|
||||
2. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`
|
||||
|
||||
### Vite/Inertia Issues
|
||||
|
||||
**Error:** `Vite Ruby - Build failed`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
# Clear Vite cache
|
||||
rm -rf node_modules/.vite
|
||||
|
||||
# Reinstall JS dependencies
|
||||
rm -rf node_modules && corepack yarn install
|
||||
\`\`\`
|
||||
|
||||
### Solid Queue Issues
|
||||
|
||||
**Error:** Jobs not processing
|
||||
|
||||
**Solution:**
|
||||
Ensure the queue worker is running:
|
||||
\`\`\`bash
|
||||
bin/jobs
|
||||
# or
|
||||
bin/rails solid_queue:start
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 11. Contributing (Optional)
|
||||
|
||||
Include if open source or team project.
|
||||
|
||||
### 12. License (Optional)
|
||||
|
||||
---
|
||||
Include the sections that apply; skip ones that don't. Suggested order:
|
||||
|
||||
1. **Title + one-paragraph overview** — what it is, who it's for, links to the live app/stores
|
||||
2. **Key features** — short bullet list, user-facing
|
||||
3. **Tech stack** — table of major dependencies with one-line roles
|
||||
4. **Prerequisites** — runtime versions (from `engines`/`.nvmrc`), `corepack enable`, platform SDKs only for the platform sections that need them
|
||||
5. **Getting started** — clone, `corepack yarn install`, `yarn start`, expected dev URL; every command copy-pasteable and tested
|
||||
6. **Architecture overview** — directory map with one-line descriptions, data flow, where state lives, how the P2P/backendless parts work (if applicable)
|
||||
7. **Configuration** — env vars/flags as a table (name, required?, default, purpose)
|
||||
8. **Available scripts** — table of the `package.json` scripts a contributor will actually use
|
||||
9. **Testing** — how to run unit/e2e tests, what CI runs
|
||||
10. **Building and releasing** — per-platform build commands (web, Android, Electron), release process pointers
|
||||
11. **Troubleshooting** — only real, observed failure modes with fixes; don't invent generic ones
|
||||
12. **Contributing / License** — link `AGENTS.md`/docs rather than duplicating policy
|
||||
|
||||
## Writing Principles
|
||||
|
||||
1. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.
|
||||
1. **Verify every command** — run it or confirm it exists in `package.json` before documenting it
|
||||
2. **Copy-pasteable code blocks** with language hints; show expected output where it helps
|
||||
3. **Explain the why**, not just the what
|
||||
4. **Assume a fresh machine** for setup sections
|
||||
5. **Tables for reference material** — env vars, scripts, options
|
||||
6. **Match the project's package manager** — `yarn` here; never write `npm install` for a Yarn repo
|
||||
7. **Table of contents** for READMEs over ~200 lines
|
||||
8. **Don't duplicate other repo docs** — link to `AGENTS.md`, `DESIGN.md`, `PRODUCT.md`, playbooks instead of restating them; duplicated policy drifts
|
||||
|
||||
2. **Use Code Blocks Liberally** - Every command should be copy-pasteable.
|
||||
## Output
|
||||
|
||||
3. **Show Example Output** - When helpful, show what the user should expect to see.
|
||||
|
||||
4. **Explain the Why** - Don't just say "run this command," explain what it does.
|
||||
|
||||
5. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.
|
||||
|
||||
6. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.
|
||||
|
||||
7. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.
|
||||
|
||||
8. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Generate a complete README.md file with:
|
||||
- Proper markdown formatting
|
||||
- Code blocks with language hints (```bash, ```typescript, etc.)
|
||||
- Tables where appropriate
|
||||
- Clear section hierarchy
|
||||
- Linked table of contents for long documents
|
||||
|
||||
Write the README directly to `README.md` in the project root.
|
||||
Write directly to `README.md` in the project root. After public-facing English content changes in this repo, run `yarn llms:generate` and commit any resulting `public/llms*.txt` changes (see AGENTS.md Task Router).
|
||||
|
||||
@@ -171,7 +171,6 @@ adb logcat -d -t 300 | tail -300
|
||||
| `android/app/src/androidTest/.../MediaUploadAutomationRunnerTest.java` | Fixture-based unit tests |
|
||||
| `android/app/src/androidTest/.../PostimagesLiveUploadTest.java` | Live integration test |
|
||||
| `android/app/src/main/assets/fixtures/` | HTML test fixtures |
|
||||
| `scripts/run-postimages-live-emulator-test.sh` | Reference emulator test script |
|
||||
|
||||
## Upload Automation Stages (for interpreting logcat)
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Based on https://react.dev/learn/you-might-not-need-an-effect
|
||||
|
||||
## Arguments
|
||||
|
||||
- **scope**: what to analyze (default: uncommitted changes). Examples: `diff to main`, `src/components/`, `whole codebase`
|
||||
- **scope**: what to analyze (default: uncommitted changes). Examples: `diff to master`, `src/components/`, `whole codebase`
|
||||
- **fix**: whether to apply fixes (default: `true`). Set to `false` to only propose changes.
|
||||
|
||||
## Workflow
|
||||
|
||||
@@ -9,12 +9,12 @@ description: Formats GitHub commit messages following Conventional Commits style
|
||||
|
||||
Title only — raw markdown:
|
||||
```
|
||||
> **Commit title:** `type: short description here`
|
||||
> **Commit title:** `type(scope): short description here`
|
||||
```
|
||||
|
||||
Title with description — raw markdown:
|
||||
```
|
||||
> **Commit title:** `type: short description here`
|
||||
> **Commit title:** `type(scope): short description here`
|
||||
>
|
||||
> Description sentence one. Description sentence two with `codeRef()` references.
|
||||
```
|
||||
@@ -25,31 +25,38 @@ Title with description — raw markdown:
|
||||
2. Title goes after `**Commit title:**` wrapped in exactly ONE backtick pair
|
||||
3. NEVER put backticks inside the title — the whole title is one code span, no nesting
|
||||
4. Description uses backticks for code references — title does NOT
|
||||
5. Conventional Commits types: `fix:`, `feat:`, `perf:`, `refactor:`, `docs:`, `chore:`
|
||||
6. Use `perf:` for performance optimizations (not `fix:`)
|
||||
5. Conventional Commits types: `fix`, `feat`, `perf`, `refactor`, `docs`, `chore`
|
||||
6. Always include a scope — a short, human-readable area name (e.g. `reply modal`, `mod queue`), matching how this repo actually commits (see the `commit` skill)
|
||||
7. Use `perf` for performance optimizations (not `fix`)
|
||||
7. Description: 2-3 sentences about the solution, no bullet points, only if title isn't enough
|
||||
|
||||
## Wrong vs Right
|
||||
|
||||
❌ WRONG — missing backticks around title:
|
||||
```
|
||||
> **Commit title:** refactor: rename from /queue to /modqueue
|
||||
> **Commit title:** refactor(mod queue): rename from /queue to /modqueue
|
||||
```
|
||||
|
||||
❌ WRONG — backticks around individual words instead of whole title:
|
||||
```
|
||||
> **Commit title:** refactor: rename from `/queue` to `/modqueue`
|
||||
> **Commit title:** refactor(mod queue): rename from `/queue` to `/modqueue`
|
||||
```
|
||||
|
||||
✅ CORRECT — entire title in one backtick pair, no backticks inside:
|
||||
❌ WRONG — missing scope:
|
||||
```
|
||||
> **Commit title:** `refactor: rename from /queue to /modqueue`
|
||||
```
|
||||
|
||||
✅ CORRECT — entire title in one backtick pair, no backticks inside, scope present:
|
||||
```
|
||||
> **Commit title:** `refactor(mod queue): rename from /queue to /modqueue`
|
||||
```
|
||||
|
||||
## Self-check
|
||||
|
||||
Before outputting, verify:
|
||||
- [ ] Lines start with `>`
|
||||
- [ ] Title is wrapped in exactly one backtick pair: `` `like this` ``
|
||||
- [ ] Title has the form `type(scope): description`
|
||||
- [ ] No backticks inside the title text
|
||||
- [ ] Code references in description (not title) use backticks
|
||||
|
||||
@@ -6,19 +6,19 @@ disable-model-invocation: true
|
||||
|
||||
# Remove AI Code Slop
|
||||
|
||||
Scan the diff against main and remove AI-generated slop introduced in this branch.
|
||||
Scan the diff against master and remove AI-generated slop introduced in this branch.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Get the diff**
|
||||
|
||||
```bash
|
||||
git diff main...HEAD
|
||||
git diff master...HEAD
|
||||
```
|
||||
|
||||
If there are also uncommitted changes, include them:
|
||||
```bash
|
||||
git diff main
|
||||
git diff master
|
||||
```
|
||||
|
||||
2. **Scan each changed file** for the slop categories below
|
||||
|
||||
@@ -56,7 +56,7 @@ If `package.json` was modified, run `corepack yarn install` first.
|
||||
### 4. Verify no remaining markers
|
||||
|
||||
```bash
|
||||
rg '<<<<<<<|=======|>>>>>>>' --type ts --type tsx --type json
|
||||
rg '<<<<<<<|=======|>>>>>>>' --type ts --type json
|
||||
```
|
||||
|
||||
If any markers remain, go back and resolve them.
|
||||
@@ -65,7 +65,7 @@ If any markers remain, go back and resolve them.
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "chore: resolve merge conflicts"
|
||||
git commit -m "chore(merge): resolve merge conflicts"
|
||||
```
|
||||
|
||||
## Operational Guidance
|
||||
@@ -79,5 +79,5 @@ git commit -m "chore: resolve merge conflicts"
|
||||
|
||||
- Clean working tree with all conflicts resolved
|
||||
- Passing `corepack yarn build && corepack yarn lint && corepack yarn type-check`
|
||||
- One local commit: `chore: resolve merge conflicts`
|
||||
- One local commit: `chore(merge): resolve merge conflicts`
|
||||
- Brief summary of files touched and notable resolution choices
|
||||
|
||||
@@ -32,7 +32,7 @@ Batch 3 (parallel): [tasks that depend on batch 2]
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Max 4 concurrent subagents (tool limitation)
|
||||
- Max 4 concurrent subagents, to bound machine load and coordination overhead
|
||||
- Tasks touching the same file(s) go in the same subagent or sequential batches — never parallel
|
||||
- Small related tasks can be grouped into one subagent to reduce overhead
|
||||
- Large independent tasks get their own subagent
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: inspect-elements
|
||||
description: Resolve on-screen 5chan DOM elements to React source files, line numbers, component names, and ownership stacks using the app's dev-only element-source helpers and playwright-cli. Use when Codex needs to inspect a page element, map a snapshot ref to source code, confirm which component rendered a node, or follow up after $profile-browsing finds a rerender hotspot and needs file-level attribution.
|
||||
description: Resolve on-screen 5chan DOM elements to React source files, line numbers, component names, and ownership stacks using the app's dev-only element-source helpers and playwright-cli. Use when an agent needs to inspect a page element, map a snapshot ref to source code, confirm which component rendered a node, or follow up after $profile-browsing finds a rerender hotspot and needs file-level attribution.
|
||||
---
|
||||
|
||||
# Inspect Elements
|
||||
|
||||
+40
-737
@@ -1,764 +1,67 @@
|
||||
---
|
||||
name: readme
|
||||
description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment.
|
||||
description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. Produces thorough, verified documentation covering local setup, architecture, and distribution.
|
||||
---
|
||||
|
||||
# README Generator
|
||||
|
||||
You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.
|
||||
You are an expert technical writer. Write (or update) a README.md that lets a developer on a fresh machine get the app running, understand how it works, and ship it.
|
||||
|
||||
## The Three Purposes of a README
|
||||
|
||||
1. **Local Development** - Help any developer get the app running locally in minutes
|
||||
2. **Understanding the System** - Explain in great detail how the app works
|
||||
3. **Production Deployment** - Cover everything needed to deploy and maintain in production
|
||||
|
||||
---
|
||||
2. **Understanding the System** - Explain how the app is put together and why
|
||||
3. **Distribution** - Cover how the project is built, released, and deployed
|
||||
|
||||
## Before Writing
|
||||
|
||||
### Step 1: Deep Codebase Exploration
|
||||
**If a README.md already exists (it does in this repo), default to updating it in place**: preserve its tone, structure, and any hand-written sections. Only restructure wholesale if the user asks for a rewrite.
|
||||
|
||||
Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:
|
||||
### Step 1: Explore the codebase — never document from memory
|
||||
|
||||
**Project Structure**
|
||||
- Read the root directory structure
|
||||
- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
|
||||
- Find the main entry point(s)
|
||||
- Map out the directory organization
|
||||
Every claim in the README must be verifiable in the repo. Check:
|
||||
|
||||
**Configuration Files**
|
||||
- .env.example, .env.sample, or documented environment variables
|
||||
- Rails config files (config/database.yml, config/application.rb, config/environments/)
|
||||
- Credentials setup (config/credentials.yml.enc, config/master.key)
|
||||
- Docker files (Dockerfile, docker-compose.yml)
|
||||
- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)
|
||||
- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)
|
||||
- **Manifest and scripts**: `package.json` (name, scripts, engines, packageManager), lockfile, `.nvmrc`
|
||||
- **Entry points and build**: `index.html`, `vite.config.js`, `src/` layout, `tsconfig.json`
|
||||
- **Platform targets**: `capacitor.config.ts` + `android/` (mobile), `electron/` + `forge.config.js` (desktop), `vercel.json` (web hosting), `fastlane/` (store releases)
|
||||
- **CI/CD**: `.github/workflows/`
|
||||
- **Repo docs that already answer questions**: `AGENTS.md`, `DESIGN.md`, `PRODUCT.md`, `CHANGELOG.md`, `docs/`
|
||||
- **Helper scripts**: `scripts/` — document the ones a contributor actually needs
|
||||
|
||||
**Database**
|
||||
- db/schema.rb or db/structure.sql
|
||||
- Migrations in db/migrate/
|
||||
- Seeds in db/seeds.rb
|
||||
- Database type from config/database.yml
|
||||
For this repo specifically: it is a Yarn 4 (Corepack) + Vite + React 19 SPA that also ships as an Android app (Capacitor) and desktop app (Electron Forge). Package-manager commands in the README must use `yarn`, never `npm`.
|
||||
|
||||
**Key Dependencies**
|
||||
- Gemfile and Gemfile.lock for Ruby gems
|
||||
- package.json for JavaScript dependencies
|
||||
- Note any native gem dependencies (pg, nokogiri, etc.)
|
||||
### Step 2: Ask only if critical
|
||||
|
||||
**Scripts and Commands**
|
||||
- bin/ scripts (bin/dev, bin/setup, bin/ci)
|
||||
- Procfile or Procfile.dev
|
||||
- Rake tasks (lib/tasks/)
|
||||
|
||||
### Step 2: Identify Deployment Target
|
||||
|
||||
Look for these files to determine deployment platform and tailor instructions:
|
||||
|
||||
- `Dockerfile` / `docker-compose.yml` → Docker-based deployment
|
||||
- `vercel.json` / `.vercel/` → Vercel
|
||||
- `netlify.toml` → Netlify
|
||||
- `fly.toml` → Fly.io
|
||||
- `railway.json` / `railway.toml` → Railway
|
||||
- `render.yaml` → Render
|
||||
- `app.yaml` → Google App Engine
|
||||
- `Procfile` → Heroku or Heroku-like platforms
|
||||
- `.ebextensions/` → AWS Elastic Beanstalk
|
||||
- `serverless.yml` → Serverless Framework
|
||||
- `terraform/` / `*.tf` → Terraform/Infrastructure as Code
|
||||
- `k8s/` / `kubernetes/` → Kubernetes
|
||||
|
||||
If no deployment config exists, provide general guidance with Docker as the recommended approach.
|
||||
|
||||
### Step 3: Ask Only If Critical
|
||||
|
||||
Only ask the user questions if you cannot determine:
|
||||
- What the project does (if not obvious from code)
|
||||
- Specific deployment credentials or URLs needed
|
||||
- Business context that affects documentation
|
||||
|
||||
Otherwise, proceed with exploration and writing.
|
||||
|
||||
---
|
||||
If something can be discovered from the repo, discover it. Ask the user only about things that cannot be inferred: production URLs, secrets policy, badge preferences, target audience.
|
||||
|
||||
## README Structure
|
||||
|
||||
Write the README with these sections in order:
|
||||
|
||||
### 1. Project Title and Overview
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief description of what the project does and who it's for. 2-3 sentences max.
|
||||
|
||||
## Key Features
|
||||
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
```
|
||||
|
||||
### 2. Tech Stack
|
||||
|
||||
List all major technologies:
|
||||
|
||||
```markdown
|
||||
## Tech Stack
|
||||
|
||||
- **Language**: Ruby 3.3+
|
||||
- **Framework**: Rails 7.2+
|
||||
- **Frontend**: Inertia.js with React
|
||||
- **Database**: PostgreSQL 16
|
||||
- **Background Jobs**: Solid Queue
|
||||
- **Caching**: Solid Cache
|
||||
- **Styling**: Tailwind CSS
|
||||
- **Deployment**: [Detected platform]
|
||||
```
|
||||
|
||||
### 3. Prerequisites
|
||||
|
||||
What must be installed before starting:
|
||||
|
||||
```markdown
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20 or higher
|
||||
- PostgreSQL 15 or higher (or Docker)
|
||||
- pnpm (recommended) or npm
|
||||
- A Google Cloud project for OAuth (optional for development)
|
||||
```
|
||||
|
||||
### 4. Getting Started
|
||||
|
||||
The complete local development guide:
|
||||
|
||||
```markdown
|
||||
## Getting Started
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
\`\`\`bash
|
||||
git clone https://github.com/user/repo.git
|
||||
cd repo
|
||||
\`\`\`
|
||||
|
||||
### 2. Install Ruby Dependencies
|
||||
|
||||
Ensure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):
|
||||
|
||||
\`\`\`bash
|
||||
bundle install
|
||||
\`\`\`
|
||||
|
||||
### 3. Install JavaScript Dependencies
|
||||
|
||||
\`\`\`bash
|
||||
corepack yarn install
|
||||
\`\`\`
|
||||
|
||||
### 4. Environment Setup
|
||||
|
||||
Copy the example environment file:
|
||||
|
||||
\`\`\`bash
|
||||
cp .env.example .env
|
||||
\`\`\`
|
||||
|
||||
Configure the following variables:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
|
||||
| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
|
||||
| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
|
||||
|
||||
### 5. Database Setup
|
||||
|
||||
Start PostgreSQL (if using Docker):
|
||||
|
||||
\`\`\`bash
|
||||
docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
|
||||
\`\`\`
|
||||
|
||||
Create and set up the database:
|
||||
|
||||
\`\`\`bash
|
||||
bin/rails db:setup
|
||||
\`\`\`
|
||||
|
||||
This runs `db:create`, `db:schema:load`, and `db:seed`.
|
||||
|
||||
For existing databases, run migrations:
|
||||
|
||||
\`\`\`bash
|
||||
bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### 6. Start Development Server
|
||||
|
||||
Using Foreman/Overmind (recommended, runs Rails + Vite):
|
||||
|
||||
\`\`\`bash
|
||||
bin/dev
|
||||
\`\`\`
|
||||
|
||||
Or manually:
|
||||
|
||||
\`\`\`bash
|
||||
# Terminal 1: Rails server
|
||||
bin/rails server
|
||||
|
||||
# Terminal 2: Vite dev server (for Inertia/React)
|
||||
bin/vite dev
|
||||
\`\`\`
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||
```
|
||||
|
||||
Include every step. Assume the reader is setting up on a fresh machine.
|
||||
|
||||
### 5. Architecture Overview
|
||||
|
||||
This is where you go absurdly deep:
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
\`\`\`
|
||||
├── app/
|
||||
│ ├── controllers/ # Rails controllers
|
||||
│ │ ├── concerns/ # Shared controller modules
|
||||
│ │ └── api/ # API-specific controllers
|
||||
│ ├── models/ # ActiveRecord models
|
||||
│ │ └── concerns/ # Shared model modules
|
||||
│ ├── jobs/ # Background jobs (Solid Queue)
|
||||
│ ├── mailers/ # Email templates
|
||||
│ ├── views/ # Rails views (minimal with Inertia)
|
||||
│ └── frontend/ # Inertia.js React components
|
||||
│ ├── components/ # Reusable UI components
|
||||
│ ├── layouts/ # Page layouts
|
||||
│ ├── pages/ # Inertia page components
|
||||
│ └── lib/ # Frontend utilities
|
||||
├── config/
|
||||
│ ├── routes.rb # Route definitions
|
||||
│ ├── database.yml # Database configuration
|
||||
│ └── initializers/ # App initializers
|
||||
├── db/
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ ├── schema.rb # Current schema
|
||||
│ └── seeds.rb # Seed data
|
||||
├── lib/
|
||||
│ └── tasks/ # Custom Rake tasks
|
||||
└── public/ # Static assets
|
||||
\`\`\`
|
||||
|
||||
### Request Lifecycle
|
||||
|
||||
1. Request hits Rails router (`config/routes.rb`)
|
||||
2. Middleware stack processes request (authentication, sessions, etc.)
|
||||
3. Controller action executes
|
||||
4. Models interact with PostgreSQL via ActiveRecord
|
||||
5. Inertia renders React component with props
|
||||
6. Response sent to browser
|
||||
|
||||
### Data Flow
|
||||
|
||||
\`\`\`
|
||||
User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
|
||||
↓
|
||||
React Props ← Inertia Response ←
|
||||
\`\`\`
|
||||
|
||||
### Key Components
|
||||
|
||||
**Authentication**
|
||||
- Devise/Rodauth for user authentication
|
||||
- Session-based auth with encrypted cookies
|
||||
- `authenticate_user!` before_action for protected routes
|
||||
|
||||
**Inertia.js Integration (`app/frontend/`)**
|
||||
- React components receive props from Rails controllers
|
||||
- `inertia_render` in controllers passes data to frontend
|
||||
- Shared data via `inertia_share` for layout props
|
||||
|
||||
**Background Jobs (`app/jobs/`)**
|
||||
- Solid Queue for job processing
|
||||
- Jobs stored in PostgreSQL (no Redis required)
|
||||
- Dashboard at `/jobs` for monitoring
|
||||
|
||||
**Database (`app/models/`)**
|
||||
- ActiveRecord models with associations
|
||||
- Query objects for complex queries
|
||||
- Concerns for shared model behavior
|
||||
|
||||
### Database Schema
|
||||
|
||||
\`\`\`
|
||||
users
|
||||
├── id (bigint, PK)
|
||||
├── email (string, unique, not null)
|
||||
├── encrypted_password (string)
|
||||
├── name (string)
|
||||
├── created_at (datetime)
|
||||
└── updated_at (datetime)
|
||||
|
||||
posts
|
||||
├── id (bigint, PK)
|
||||
├── title (string, not null)
|
||||
├── content (text)
|
||||
├── published (boolean, default: false)
|
||||
├── user_id (bigint, FK → users)
|
||||
├── created_at (datetime)
|
||||
└── updated_at (datetime)
|
||||
|
||||
solid_queue_jobs (background jobs)
|
||||
├── id (bigint, PK)
|
||||
├── queue_name (string)
|
||||
├── class_name (string)
|
||||
├── arguments (json)
|
||||
├── scheduled_at (datetime)
|
||||
└── ...
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 6. Environment Variables
|
||||
|
||||
Complete reference for all env vars:
|
||||
|
||||
```markdown
|
||||
## Environment Variables
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Description | How to Get |
|
||||
|----------|-------------|------------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
|
||||
| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
|
||||
|
||||
### Optional
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
|
||||
| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
|
||||
| `RAILS_MAX_THREADS` | Puma thread count | `5` |
|
||||
| `WEB_CONCURRENCY` | Puma worker count | `2` |
|
||||
| `SMTP_ADDRESS` | Mail server hostname | - |
|
||||
| `SMTP_PORT` | Mail server port | `587` |
|
||||
|
||||
### Rails Credentials
|
||||
|
||||
Sensitive values should be stored in Rails encrypted credentials:
|
||||
|
||||
\`\`\`bash
|
||||
# Edit credentials (opens in $EDITOR)
|
||||
bin/rails credentials:edit
|
||||
|
||||
# Or for environment-specific credentials
|
||||
RAILS_ENV=production bin/rails credentials:edit
|
||||
\`\`\`
|
||||
|
||||
Credentials file structure:
|
||||
\`\`\`yaml
|
||||
secret_key_base: xxx
|
||||
stripe:
|
||||
public_key: pk_xxx
|
||||
secret_key: sk_xxx
|
||||
google:
|
||||
client_id: xxx
|
||||
client_secret: xxx
|
||||
\`\`\`
|
||||
|
||||
Access in code: `Rails.application.credentials.stripe[:secret_key]`
|
||||
|
||||
### Environment-Specific
|
||||
|
||||
**Development**
|
||||
\`\`\`
|
||||
DATABASE_URL=postgresql://localhost/myapp_development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
\`\`\`
|
||||
|
||||
**Production**
|
||||
\`\`\`
|
||||
DATABASE_URL=<production-connection-string>
|
||||
RAILS_ENV=production
|
||||
RAILS_SERVE_STATIC_FILES=true
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 7. Available Scripts
|
||||
|
||||
```markdown
|
||||
## Available Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bin/dev` | Start development server (Rails + Vite via Foreman) |
|
||||
| `bin/rails server` | Start Rails server only |
|
||||
| `bin/vite dev` | Start Vite dev server only |
|
||||
| `bin/rails console` | Open Rails console (IRB with app loaded) |
|
||||
| `bin/rails db:migrate` | Run pending database migrations |
|
||||
| `bin/rails db:rollback` | Rollback last migration |
|
||||
| `bin/rails db:seed` | Run database seeds |
|
||||
| `bin/rails db:reset` | Drop, create, migrate, and seed database |
|
||||
| `bin/rails routes` | List all routes |
|
||||
| `bin/rails test` | Run test suite (Minitest) |
|
||||
| `bundle exec rspec` | Run test suite (RSpec, if used) |
|
||||
| `bin/rails assets:precompile` | Compile assets for production |
|
||||
| `bin/rubocop` | Run Ruby linter |
|
||||
| `yarn lint` | Run JavaScript/TypeScript linter |
|
||||
```
|
||||
|
||||
### 8. Testing
|
||||
|
||||
```markdown
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
\`\`\`bash
|
||||
# Run all tests (Minitest)
|
||||
bin/rails test
|
||||
|
||||
# Run all tests (RSpec, if used)
|
||||
bundle exec rspec
|
||||
|
||||
# Run specific test file
|
||||
bin/rails test test/models/user_test.rb
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
|
||||
# Run tests matching a pattern
|
||||
bin/rails test -n /creates_user/
|
||||
bundle exec rspec -e "creates user"
|
||||
|
||||
# Run system tests (browser tests)
|
||||
bin/rails test:system
|
||||
|
||||
# Run with coverage (SimpleCov)
|
||||
COVERAGE=true bin/rails test
|
||||
\`\`\`
|
||||
|
||||
### Test Structure
|
||||
|
||||
\`\`\`
|
||||
test/ # Minitest structure
|
||||
├── controllers/ # Controller tests
|
||||
├── models/ # Model unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── system/ # System/browser tests
|
||||
├── fixtures/ # Test data
|
||||
└── test_helper.rb # Test configuration
|
||||
|
||||
spec/ # RSpec structure (if used)
|
||||
├── models/
|
||||
├── requests/
|
||||
├── system/
|
||||
├── factories/ # FactoryBot factories
|
||||
├── support/
|
||||
└── rails_helper.rb
|
||||
\`\`\`
|
||||
|
||||
### Writing Tests
|
||||
|
||||
**Minitest example:**
|
||||
\`\`\`ruby
|
||||
require "test_helper"
|
||||
|
||||
class UserTest < ActiveSupport::TestCase
|
||||
test "creates user with valid attributes" do
|
||||
user = User.new(email: "test@example.com", name: "Test User")
|
||||
assert user.valid?
|
||||
end
|
||||
|
||||
test "requires email" do
|
||||
user = User.new(name: "Test User")
|
||||
assert_not user.valid?
|
||||
assert_includes user.errors[:email], "can't be blank"
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
**RSpec example:**
|
||||
\`\`\`ruby
|
||||
require "rails_helper"
|
||||
|
||||
RSpec.describe User, type: :model do
|
||||
describe "validations" do
|
||||
it "is valid with valid attributes" do
|
||||
user = build(:user)
|
||||
expect(user).to be_valid
|
||||
end
|
||||
|
||||
it "requires an email" do
|
||||
user = build(:user, email: nil)
|
||||
expect(user).not_to be_valid
|
||||
expect(user.errors[:email]).to include("can't be blank")
|
||||
end
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
### Frontend Testing
|
||||
|
||||
For Inertia/React components:
|
||||
|
||||
\`\`\`bash
|
||||
yarn test
|
||||
\`\`\`
|
||||
|
||||
\`\`\`typescript
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import { Dashboard } from './Dashboard'
|
||||
|
||||
describe('Dashboard', () => {
|
||||
it('renders user name', () => {
|
||||
render(<Dashboard user={{ name: 'Josh' }} />)
|
||||
expect(screen.getByText('Josh')).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 9. Deployment
|
||||
|
||||
Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal/, etc.):
|
||||
|
||||
```markdown
|
||||
## Deployment
|
||||
|
||||
### Kamal (Recommended for Rails)
|
||||
|
||||
If using Kamal for deployment:
|
||||
|
||||
\`\`\`bash
|
||||
# Setup Kamal (first time)
|
||||
kamal setup
|
||||
|
||||
# Deploy
|
||||
kamal deploy
|
||||
|
||||
# Rollback to previous version
|
||||
kamal rollback
|
||||
|
||||
# View logs
|
||||
kamal app logs
|
||||
|
||||
# Run console on production
|
||||
kamal app exec --interactive 'bin/rails console'
|
||||
\`\`\`
|
||||
|
||||
Configuration lives in `config/deploy.yml`.
|
||||
|
||||
### Docker
|
||||
|
||||
Build and run:
|
||||
|
||||
\`\`\`bash
|
||||
# Build image
|
||||
docker build -t myapp .
|
||||
|
||||
# Run with environment variables
|
||||
docker run -p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://... \
|
||||
-e SECRET_KEY_BASE=... \
|
||||
-e RAILS_ENV=production \
|
||||
myapp
|
||||
\`\`\`
|
||||
|
||||
### Heroku
|
||||
|
||||
\`\`\`bash
|
||||
# Create app
|
||||
heroku create myapp
|
||||
|
||||
# Add PostgreSQL
|
||||
heroku addons:create heroku-postgresql:mini
|
||||
|
||||
# Set environment variables
|
||||
heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
|
||||
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
|
||||
|
||||
# Deploy
|
||||
git push heroku main
|
||||
|
||||
# Run migrations
|
||||
heroku run bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Fly.io
|
||||
|
||||
\`\`\`bash
|
||||
# Launch (first time)
|
||||
fly launch
|
||||
|
||||
# Deploy
|
||||
fly deploy
|
||||
|
||||
# Run migrations
|
||||
fly ssh console -C "bin/rails db:migrate"
|
||||
|
||||
# Open console
|
||||
fly ssh console -C "bin/rails console"
|
||||
\`\`\`
|
||||
|
||||
### Render
|
||||
|
||||
If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
|
||||
|
||||
Manual setup:
|
||||
1. Create new Web Service
|
||||
2. Connect GitHub repository
|
||||
3. Set build command: `bundle install && bin/rails assets:precompile`
|
||||
4. Set start command: `bin/rails server`
|
||||
5. Add environment variables in dashboard
|
||||
|
||||
### Manual/VPS Deployment
|
||||
|
||||
\`\`\`bash
|
||||
# On the server:
|
||||
|
||||
# Pull latest code
|
||||
git pull origin main
|
||||
|
||||
# Install dependencies
|
||||
bundle install --deployment
|
||||
|
||||
# Compile assets
|
||||
RAILS_ENV=production bin/rails assets:precompile
|
||||
|
||||
# Run migrations
|
||||
RAILS_ENV=production bin/rails db:migrate
|
||||
|
||||
# Restart application server (e.g., Puma via systemd)
|
||||
sudo systemctl restart myapp
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 10. Troubleshooting
|
||||
|
||||
```markdown
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
**Error:** `could not connect to server: Connection refused`
|
||||
|
||||
**Solution:**
|
||||
1. Verify PostgreSQL is running: `pg_isready` or `docker ps`
|
||||
2. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
|
||||
3. Ensure database exists: `bin/rails db:create`
|
||||
|
||||
### Pending Migrations
|
||||
|
||||
**Error:** `Migrations are pending`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Asset Compilation Issues
|
||||
|
||||
**Error:** `The asset "application.css" is not present in the asset pipeline`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
# Clear and recompile assets
|
||||
bin/rails assets:clobber
|
||||
bin/rails assets:precompile
|
||||
\`\`\`
|
||||
|
||||
### Bundle Install Failures
|
||||
|
||||
**Error:** Native extension build failures
|
||||
|
||||
**Solution:**
|
||||
1. Ensure system dependencies are installed:
|
||||
\`\`\`bash
|
||||
# macOS
|
||||
brew install postgresql libpq
|
||||
|
||||
# Ubuntu
|
||||
sudo apt-get install libpq-dev
|
||||
\`\`\`
|
||||
2. Try again: `bundle install`
|
||||
|
||||
### Credentials Issues
|
||||
|
||||
**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`
|
||||
|
||||
**Solution:**
|
||||
The master key doesn't match the credentials file. Either:
|
||||
1. Get the correct `config/master.key` from another team member
|
||||
2. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`
|
||||
|
||||
### Vite/Inertia Issues
|
||||
|
||||
**Error:** `Vite Ruby - Build failed`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
# Clear Vite cache
|
||||
rm -rf node_modules/.vite
|
||||
|
||||
# Reinstall JS dependencies
|
||||
rm -rf node_modules && corepack yarn install
|
||||
\`\`\`
|
||||
|
||||
### Solid Queue Issues
|
||||
|
||||
**Error:** Jobs not processing
|
||||
|
||||
**Solution:**
|
||||
Ensure the queue worker is running:
|
||||
\`\`\`bash
|
||||
bin/jobs
|
||||
# or
|
||||
bin/rails solid_queue:start
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 11. Contributing (Optional)
|
||||
|
||||
Include if open source or team project.
|
||||
|
||||
### 12. License (Optional)
|
||||
|
||||
---
|
||||
Include the sections that apply; skip ones that don't. Suggested order:
|
||||
|
||||
1. **Title + one-paragraph overview** — what it is, who it's for, links to the live app/stores
|
||||
2. **Key features** — short bullet list, user-facing
|
||||
3. **Tech stack** — table of major dependencies with one-line roles
|
||||
4. **Prerequisites** — runtime versions (from `engines`/`.nvmrc`), `corepack enable`, platform SDKs only for the platform sections that need them
|
||||
5. **Getting started** — clone, `corepack yarn install`, `yarn start`, expected dev URL; every command copy-pasteable and tested
|
||||
6. **Architecture overview** — directory map with one-line descriptions, data flow, where state lives, how the P2P/backendless parts work (if applicable)
|
||||
7. **Configuration** — env vars/flags as a table (name, required?, default, purpose)
|
||||
8. **Available scripts** — table of the `package.json` scripts a contributor will actually use
|
||||
9. **Testing** — how to run unit/e2e tests, what CI runs
|
||||
10. **Building and releasing** — per-platform build commands (web, Android, Electron), release process pointers
|
||||
11. **Troubleshooting** — only real, observed failure modes with fixes; don't invent generic ones
|
||||
12. **Contributing / License** — link `AGENTS.md`/docs rather than duplicating policy
|
||||
|
||||
## Writing Principles
|
||||
|
||||
1. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.
|
||||
1. **Verify every command** — run it or confirm it exists in `package.json` before documenting it
|
||||
2. **Copy-pasteable code blocks** with language hints; show expected output where it helps
|
||||
3. **Explain the why**, not just the what
|
||||
4. **Assume a fresh machine** for setup sections
|
||||
5. **Tables for reference material** — env vars, scripts, options
|
||||
6. **Match the project's package manager** — `yarn` here; never write `npm install` for a Yarn repo
|
||||
7. **Table of contents** for READMEs over ~200 lines
|
||||
8. **Don't duplicate other repo docs** — link to `AGENTS.md`, `DESIGN.md`, `PRODUCT.md`, playbooks instead of restating them; duplicated policy drifts
|
||||
|
||||
2. **Use Code Blocks Liberally** - Every command should be copy-pasteable.
|
||||
## Output
|
||||
|
||||
3. **Show Example Output** - When helpful, show what the user should expect to see.
|
||||
|
||||
4. **Explain the Why** - Don't just say "run this command," explain what it does.
|
||||
|
||||
5. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.
|
||||
|
||||
6. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.
|
||||
|
||||
7. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.
|
||||
|
||||
8. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Generate a complete README.md file with:
|
||||
- Proper markdown formatting
|
||||
- Code blocks with language hints (```bash, ```typescript, etc.)
|
||||
- Tables where appropriate
|
||||
- Clear section hierarchy
|
||||
- Linked table of contents for long documents
|
||||
|
||||
Write the README directly to `README.md` in the project root.
|
||||
Write directly to `README.md` in the project root. After public-facing English content changes in this repo, run `yarn llms:generate` and commit any resulting `public/llms*.txt` changes (see AGENTS.md Task Router).
|
||||
|
||||
@@ -171,7 +171,6 @@ adb logcat -d -t 300 | tail -300
|
||||
| `android/app/src/androidTest/.../MediaUploadAutomationRunnerTest.java` | Fixture-based unit tests |
|
||||
| `android/app/src/androidTest/.../PostimagesLiveUploadTest.java` | Live integration test |
|
||||
| `android/app/src/main/assets/fixtures/` | HTML test fixtures |
|
||||
| `scripts/run-postimages-live-emulator-test.sh` | Reference emulator test script |
|
||||
|
||||
## Upload Automation Stages (for interpreting logcat)
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Based on https://react.dev/learn/you-might-not-need-an-effect
|
||||
|
||||
## Arguments
|
||||
|
||||
- **scope**: what to analyze (default: uncommitted changes). Examples: `diff to main`, `src/components/`, `whole codebase`
|
||||
- **scope**: what to analyze (default: uncommitted changes). Examples: `diff to master`, `src/components/`, `whole codebase`
|
||||
- **fix**: whether to apply fixes (default: `true`). Set to `false` to only propose changes.
|
||||
|
||||
## Workflow
|
||||
|
||||
@@ -9,12 +9,12 @@ description: Formats GitHub commit messages following Conventional Commits style
|
||||
|
||||
Title only — raw markdown:
|
||||
```
|
||||
> **Commit title:** `type: short description here`
|
||||
> **Commit title:** `type(scope): short description here`
|
||||
```
|
||||
|
||||
Title with description — raw markdown:
|
||||
```
|
||||
> **Commit title:** `type: short description here`
|
||||
> **Commit title:** `type(scope): short description here`
|
||||
>
|
||||
> Description sentence one. Description sentence two with `codeRef()` references.
|
||||
```
|
||||
@@ -25,31 +25,38 @@ Title with description — raw markdown:
|
||||
2. Title goes after `**Commit title:**` wrapped in exactly ONE backtick pair
|
||||
3. NEVER put backticks inside the title — the whole title is one code span, no nesting
|
||||
4. Description uses backticks for code references — title does NOT
|
||||
5. Conventional Commits types: `fix:`, `feat:`, `perf:`, `refactor:`, `docs:`, `chore:`
|
||||
6. Use `perf:` for performance optimizations (not `fix:`)
|
||||
5. Conventional Commits types: `fix`, `feat`, `perf`, `refactor`, `docs`, `chore`
|
||||
6. Always include a scope — a short, human-readable area name (e.g. `reply modal`, `mod queue`), matching how this repo actually commits (see the `commit` skill)
|
||||
7. Use `perf` for performance optimizations (not `fix`)
|
||||
7. Description: 2-3 sentences about the solution, no bullet points, only if title isn't enough
|
||||
|
||||
## Wrong vs Right
|
||||
|
||||
❌ WRONG — missing backticks around title:
|
||||
```
|
||||
> **Commit title:** refactor: rename from /queue to /modqueue
|
||||
> **Commit title:** refactor(mod queue): rename from /queue to /modqueue
|
||||
```
|
||||
|
||||
❌ WRONG — backticks around individual words instead of whole title:
|
||||
```
|
||||
> **Commit title:** refactor: rename from `/queue` to `/modqueue`
|
||||
> **Commit title:** refactor(mod queue): rename from `/queue` to `/modqueue`
|
||||
```
|
||||
|
||||
✅ CORRECT — entire title in one backtick pair, no backticks inside:
|
||||
❌ WRONG — missing scope:
|
||||
```
|
||||
> **Commit title:** `refactor: rename from /queue to /modqueue`
|
||||
```
|
||||
|
||||
✅ CORRECT — entire title in one backtick pair, no backticks inside, scope present:
|
||||
```
|
||||
> **Commit title:** `refactor(mod queue): rename from /queue to /modqueue`
|
||||
```
|
||||
|
||||
## Self-check
|
||||
|
||||
Before outputting, verify:
|
||||
- [ ] Lines start with `>`
|
||||
- [ ] Title is wrapped in exactly one backtick pair: `` `like this` ``
|
||||
- [ ] Title has the form `type(scope): description`
|
||||
- [ ] No backticks inside the title text
|
||||
- [ ] Code references in description (not title) use backticks
|
||||
|
||||
@@ -6,19 +6,19 @@ disable-model-invocation: true
|
||||
|
||||
# Remove AI Code Slop
|
||||
|
||||
Scan the diff against main and remove AI-generated slop introduced in this branch.
|
||||
Scan the diff against master and remove AI-generated slop introduced in this branch.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Get the diff**
|
||||
|
||||
```bash
|
||||
git diff main...HEAD
|
||||
git diff master...HEAD
|
||||
```
|
||||
|
||||
If there are also uncommitted changes, include them:
|
||||
```bash
|
||||
git diff main
|
||||
git diff master
|
||||
```
|
||||
|
||||
2. **Scan each changed file** for the slop categories below
|
||||
|
||||
@@ -56,7 +56,7 @@ If `package.json` was modified, run `corepack yarn install` first.
|
||||
### 4. Verify no remaining markers
|
||||
|
||||
```bash
|
||||
rg '<<<<<<<|=======|>>>>>>>' --type ts --type tsx --type json
|
||||
rg '<<<<<<<|=======|>>>>>>>' --type ts --type json
|
||||
```
|
||||
|
||||
If any markers remain, go back and resolve them.
|
||||
@@ -65,7 +65,7 @@ If any markers remain, go back and resolve them.
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "chore: resolve merge conflicts"
|
||||
git commit -m "chore(merge): resolve merge conflicts"
|
||||
```
|
||||
|
||||
## Operational Guidance
|
||||
@@ -79,5 +79,5 @@ git commit -m "chore: resolve merge conflicts"
|
||||
|
||||
- Clean working tree with all conflicts resolved
|
||||
- Passing `corepack yarn build && corepack yarn lint && corepack yarn type-check`
|
||||
- One local commit: `chore: resolve merge conflicts`
|
||||
- One local commit: `chore(merge): resolve merge conflicts`
|
||||
- Brief summary of files touched and notable resolution choices
|
||||
|
||||
@@ -32,7 +32,7 @@ Batch 3 (parallel): [tasks that depend on batch 2]
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Max 4 concurrent subagents (tool limitation)
|
||||
- Max 4 concurrent subagents, to bound machine load and coordination overhead
|
||||
- Tasks touching the same file(s) go in the same subagent or sequential batches — never parallel
|
||||
- Small related tasks can be grouped into one subagent to reduce overhead
|
||||
- Large independent tasks get their own subagent
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: inspect-elements
|
||||
description: Resolve on-screen 5chan DOM elements to React source files, line numbers, component names, and ownership stacks using the app's dev-only element-source helpers and playwright-cli. Use when Codex needs to inspect a page element, map a snapshot ref to source code, confirm which component rendered a node, or follow up after $profile-browsing finds a rerender hotspot and needs file-level attribution.
|
||||
description: Resolve on-screen 5chan DOM elements to React source files, line numbers, component names, and ownership stacks using the app's dev-only element-source helpers and playwright-cli. Use when an agent needs to inspect a page element, map a snapshot ref to source code, confirm which component rendered a node, or follow up after $profile-browsing finds a rerender hotspot and needs file-level attribution.
|
||||
---
|
||||
|
||||
# Inspect Elements
|
||||
|
||||
+40
-737
@@ -1,764 +1,67 @@
|
||||
---
|
||||
name: readme
|
||||
description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. This skill creates absurdly thorough documentation covering local setup, architecture, and deployment.
|
||||
description: When the user wants to create or update a README.md file for a project. Also use when the user says "write readme," "create readme," "document this project," "project documentation," or asks for help with README.md. Produces thorough, verified documentation covering local setup, architecture, and distribution.
|
||||
---
|
||||
|
||||
# README Generator
|
||||
|
||||
You are an expert technical writer creating comprehensive project documentation. Your goal is to write a README.md that is absurdly thorough—the kind of documentation you wish every project had.
|
||||
You are an expert technical writer. Write (or update) a README.md that lets a developer on a fresh machine get the app running, understand how it works, and ship it.
|
||||
|
||||
## The Three Purposes of a README
|
||||
|
||||
1. **Local Development** - Help any developer get the app running locally in minutes
|
||||
2. **Understanding the System** - Explain in great detail how the app works
|
||||
3. **Production Deployment** - Cover everything needed to deploy and maintain in production
|
||||
|
||||
---
|
||||
2. **Understanding the System** - Explain how the app is put together and why
|
||||
3. **Distribution** - Cover how the project is built, released, and deployed
|
||||
|
||||
## Before Writing
|
||||
|
||||
### Step 1: Deep Codebase Exploration
|
||||
**If a README.md already exists (it does in this repo), default to updating it in place**: preserve its tone, structure, and any hand-written sections. Only restructure wholesale if the user asks for a rewrite.
|
||||
|
||||
Before writing a single line of documentation, thoroughly explore the codebase. You MUST understand:
|
||||
### Step 1: Explore the codebase — never document from memory
|
||||
|
||||
**Project Structure**
|
||||
- Read the root directory structure
|
||||
- Identify the framework/language (Gemfile for Rails, package.json, go.mod, requirements.txt, etc.)
|
||||
- Find the main entry point(s)
|
||||
- Map out the directory organization
|
||||
Every claim in the README must be verifiable in the repo. Check:
|
||||
|
||||
**Configuration Files**
|
||||
- .env.example, .env.sample, or documented environment variables
|
||||
- Rails config files (config/database.yml, config/application.rb, config/environments/)
|
||||
- Credentials setup (config/credentials.yml.enc, config/master.key)
|
||||
- Docker files (Dockerfile, docker-compose.yml)
|
||||
- CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)
|
||||
- Deployment configs (config/deploy.yml for Kamal, fly.toml, render.yaml, Procfile, etc.)
|
||||
- **Manifest and scripts**: `package.json` (name, scripts, engines, packageManager), lockfile, `.nvmrc`
|
||||
- **Entry points and build**: `index.html`, `vite.config.js`, `src/` layout, `tsconfig.json`
|
||||
- **Platform targets**: `capacitor.config.ts` + `android/` (mobile), `electron/` + `forge.config.js` (desktop), `vercel.json` (web hosting), `fastlane/` (store releases)
|
||||
- **CI/CD**: `.github/workflows/`
|
||||
- **Repo docs that already answer questions**: `AGENTS.md`, `DESIGN.md`, `PRODUCT.md`, `CHANGELOG.md`, `docs/`
|
||||
- **Helper scripts**: `scripts/` — document the ones a contributor actually needs
|
||||
|
||||
**Database**
|
||||
- db/schema.rb or db/structure.sql
|
||||
- Migrations in db/migrate/
|
||||
- Seeds in db/seeds.rb
|
||||
- Database type from config/database.yml
|
||||
For this repo specifically: it is a Yarn 4 (Corepack) + Vite + React 19 SPA that also ships as an Android app (Capacitor) and desktop app (Electron Forge). Package-manager commands in the README must use `yarn`, never `npm`.
|
||||
|
||||
**Key Dependencies**
|
||||
- Gemfile and Gemfile.lock for Ruby gems
|
||||
- package.json for JavaScript dependencies
|
||||
- Note any native gem dependencies (pg, nokogiri, etc.)
|
||||
### Step 2: Ask only if critical
|
||||
|
||||
**Scripts and Commands**
|
||||
- bin/ scripts (bin/dev, bin/setup, bin/ci)
|
||||
- Procfile or Procfile.dev
|
||||
- Rake tasks (lib/tasks/)
|
||||
|
||||
### Step 2: Identify Deployment Target
|
||||
|
||||
Look for these files to determine deployment platform and tailor instructions:
|
||||
|
||||
- `Dockerfile` / `docker-compose.yml` → Docker-based deployment
|
||||
- `vercel.json` / `.vercel/` → Vercel
|
||||
- `netlify.toml` → Netlify
|
||||
- `fly.toml` → Fly.io
|
||||
- `railway.json` / `railway.toml` → Railway
|
||||
- `render.yaml` → Render
|
||||
- `app.yaml` → Google App Engine
|
||||
- `Procfile` → Heroku or Heroku-like platforms
|
||||
- `.ebextensions/` → AWS Elastic Beanstalk
|
||||
- `serverless.yml` → Serverless Framework
|
||||
- `terraform/` / `*.tf` → Terraform/Infrastructure as Code
|
||||
- `k8s/` / `kubernetes/` → Kubernetes
|
||||
|
||||
If no deployment config exists, provide general guidance with Docker as the recommended approach.
|
||||
|
||||
### Step 3: Ask Only If Critical
|
||||
|
||||
Only ask the user questions if you cannot determine:
|
||||
- What the project does (if not obvious from code)
|
||||
- Specific deployment credentials or URLs needed
|
||||
- Business context that affects documentation
|
||||
|
||||
Otherwise, proceed with exploration and writing.
|
||||
|
||||
---
|
||||
If something can be discovered from the repo, discover it. Ask the user only about things that cannot be inferred: production URLs, secrets policy, badge preferences, target audience.
|
||||
|
||||
## README Structure
|
||||
|
||||
Write the README with these sections in order:
|
||||
|
||||
### 1. Project Title and Overview
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief description of what the project does and who it's for. 2-3 sentences max.
|
||||
|
||||
## Key Features
|
||||
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
- Feature 3
|
||||
```
|
||||
|
||||
### 2. Tech Stack
|
||||
|
||||
List all major technologies:
|
||||
|
||||
```markdown
|
||||
## Tech Stack
|
||||
|
||||
- **Language**: Ruby 3.3+
|
||||
- **Framework**: Rails 7.2+
|
||||
- **Frontend**: Inertia.js with React
|
||||
- **Database**: PostgreSQL 16
|
||||
- **Background Jobs**: Solid Queue
|
||||
- **Caching**: Solid Cache
|
||||
- **Styling**: Tailwind CSS
|
||||
- **Deployment**: [Detected platform]
|
||||
```
|
||||
|
||||
### 3. Prerequisites
|
||||
|
||||
What must be installed before starting:
|
||||
|
||||
```markdown
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20 or higher
|
||||
- PostgreSQL 15 or higher (or Docker)
|
||||
- pnpm (recommended) or npm
|
||||
- A Google Cloud project for OAuth (optional for development)
|
||||
```
|
||||
|
||||
### 4. Getting Started
|
||||
|
||||
The complete local development guide:
|
||||
|
||||
```markdown
|
||||
## Getting Started
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
\`\`\`bash
|
||||
git clone https://github.com/user/repo.git
|
||||
cd repo
|
||||
\`\`\`
|
||||
|
||||
### 2. Install Ruby Dependencies
|
||||
|
||||
Ensure you have Ruby 3.3+ installed (via rbenv, asdf, or mise):
|
||||
|
||||
\`\`\`bash
|
||||
bundle install
|
||||
\`\`\`
|
||||
|
||||
### 3. Install JavaScript Dependencies
|
||||
|
||||
\`\`\`bash
|
||||
corepack yarn install
|
||||
\`\`\`
|
||||
|
||||
### 4. Environment Setup
|
||||
|
||||
Copy the example environment file:
|
||||
|
||||
\`\`\`bash
|
||||
cp .env.example .env
|
||||
\`\`\`
|
||||
|
||||
Configure the following variables:
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost/myapp_development` |
|
||||
| `REDIS_URL` | Redis connection (if used) | `redis://localhost:6379/0` |
|
||||
| `SECRET_KEY_BASE` | Rails secret key | `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | For credentials encryption | Check `config/master.key` |
|
||||
|
||||
### 5. Database Setup
|
||||
|
||||
Start PostgreSQL (if using Docker):
|
||||
|
||||
\`\`\`bash
|
||||
docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
|
||||
\`\`\`
|
||||
|
||||
Create and set up the database:
|
||||
|
||||
\`\`\`bash
|
||||
bin/rails db:setup
|
||||
\`\`\`
|
||||
|
||||
This runs `db:create`, `db:schema:load`, and `db:seed`.
|
||||
|
||||
For existing databases, run migrations:
|
||||
|
||||
\`\`\`bash
|
||||
bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### 6. Start Development Server
|
||||
|
||||
Using Foreman/Overmind (recommended, runs Rails + Vite):
|
||||
|
||||
\`\`\`bash
|
||||
bin/dev
|
||||
\`\`\`
|
||||
|
||||
Or manually:
|
||||
|
||||
\`\`\`bash
|
||||
# Terminal 1: Rails server
|
||||
bin/rails server
|
||||
|
||||
# Terminal 2: Vite dev server (for Inertia/React)
|
||||
bin/vite dev
|
||||
\`\`\`
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||
```
|
||||
|
||||
Include every step. Assume the reader is setting up on a fresh machine.
|
||||
|
||||
### 5. Architecture Overview
|
||||
|
||||
This is where you go absurdly deep:
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
\`\`\`
|
||||
├── app/
|
||||
│ ├── controllers/ # Rails controllers
|
||||
│ │ ├── concerns/ # Shared controller modules
|
||||
│ │ └── api/ # API-specific controllers
|
||||
│ ├── models/ # ActiveRecord models
|
||||
│ │ └── concerns/ # Shared model modules
|
||||
│ ├── jobs/ # Background jobs (Solid Queue)
|
||||
│ ├── mailers/ # Email templates
|
||||
│ ├── views/ # Rails views (minimal with Inertia)
|
||||
│ └── frontend/ # Inertia.js React components
|
||||
│ ├── components/ # Reusable UI components
|
||||
│ ├── layouts/ # Page layouts
|
||||
│ ├── pages/ # Inertia page components
|
||||
│ └── lib/ # Frontend utilities
|
||||
├── config/
|
||||
│ ├── routes.rb # Route definitions
|
||||
│ ├── database.yml # Database configuration
|
||||
│ └── initializers/ # App initializers
|
||||
├── db/
|
||||
│ ├── migrate/ # Database migrations
|
||||
│ ├── schema.rb # Current schema
|
||||
│ └── seeds.rb # Seed data
|
||||
├── lib/
|
||||
│ └── tasks/ # Custom Rake tasks
|
||||
└── public/ # Static assets
|
||||
\`\`\`
|
||||
|
||||
### Request Lifecycle
|
||||
|
||||
1. Request hits Rails router (`config/routes.rb`)
|
||||
2. Middleware stack processes request (authentication, sessions, etc.)
|
||||
3. Controller action executes
|
||||
4. Models interact with PostgreSQL via ActiveRecord
|
||||
5. Inertia renders React component with props
|
||||
6. Response sent to browser
|
||||
|
||||
### Data Flow
|
||||
|
||||
\`\`\`
|
||||
User Action → React Component → Inertia Visit → Rails Controller → ActiveRecord → PostgreSQL
|
||||
↓
|
||||
React Props ← Inertia Response ←
|
||||
\`\`\`
|
||||
|
||||
### Key Components
|
||||
|
||||
**Authentication**
|
||||
- Devise/Rodauth for user authentication
|
||||
- Session-based auth with encrypted cookies
|
||||
- `authenticate_user!` before_action for protected routes
|
||||
|
||||
**Inertia.js Integration (`app/frontend/`)**
|
||||
- React components receive props from Rails controllers
|
||||
- `inertia_render` in controllers passes data to frontend
|
||||
- Shared data via `inertia_share` for layout props
|
||||
|
||||
**Background Jobs (`app/jobs/`)**
|
||||
- Solid Queue for job processing
|
||||
- Jobs stored in PostgreSQL (no Redis required)
|
||||
- Dashboard at `/jobs` for monitoring
|
||||
|
||||
**Database (`app/models/`)**
|
||||
- ActiveRecord models with associations
|
||||
- Query objects for complex queries
|
||||
- Concerns for shared model behavior
|
||||
|
||||
### Database Schema
|
||||
|
||||
\`\`\`
|
||||
users
|
||||
├── id (bigint, PK)
|
||||
├── email (string, unique, not null)
|
||||
├── encrypted_password (string)
|
||||
├── name (string)
|
||||
├── created_at (datetime)
|
||||
└── updated_at (datetime)
|
||||
|
||||
posts
|
||||
├── id (bigint, PK)
|
||||
├── title (string, not null)
|
||||
├── content (text)
|
||||
├── published (boolean, default: false)
|
||||
├── user_id (bigint, FK → users)
|
||||
├── created_at (datetime)
|
||||
└── updated_at (datetime)
|
||||
|
||||
solid_queue_jobs (background jobs)
|
||||
├── id (bigint, PK)
|
||||
├── queue_name (string)
|
||||
├── class_name (string)
|
||||
├── arguments (json)
|
||||
├── scheduled_at (datetime)
|
||||
└── ...
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 6. Environment Variables
|
||||
|
||||
Complete reference for all env vars:
|
||||
|
||||
```markdown
|
||||
## Environment Variables
|
||||
|
||||
### Required
|
||||
|
||||
| Variable | Description | How to Get |
|
||||
|----------|-------------|------------|
|
||||
| `DATABASE_URL` | PostgreSQL connection string | Your database provider |
|
||||
| `SECRET_KEY_BASE` | Rails secret for sessions/cookies | Run `bin/rails secret` |
|
||||
| `RAILS_MASTER_KEY` | Decrypts credentials file | Check `config/master.key` (not in git) |
|
||||
|
||||
### Optional
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `REDIS_URL` | Redis connection string (for caching/ActionCable) | - |
|
||||
| `RAILS_LOG_LEVEL` | Logging verbosity | `debug` (dev), `info` (prod) |
|
||||
| `RAILS_MAX_THREADS` | Puma thread count | `5` |
|
||||
| `WEB_CONCURRENCY` | Puma worker count | `2` |
|
||||
| `SMTP_ADDRESS` | Mail server hostname | - |
|
||||
| `SMTP_PORT` | Mail server port | `587` |
|
||||
|
||||
### Rails Credentials
|
||||
|
||||
Sensitive values should be stored in Rails encrypted credentials:
|
||||
|
||||
\`\`\`bash
|
||||
# Edit credentials (opens in $EDITOR)
|
||||
bin/rails credentials:edit
|
||||
|
||||
# Or for environment-specific credentials
|
||||
RAILS_ENV=production bin/rails credentials:edit
|
||||
\`\`\`
|
||||
|
||||
Credentials file structure:
|
||||
\`\`\`yaml
|
||||
secret_key_base: xxx
|
||||
stripe:
|
||||
public_key: pk_xxx
|
||||
secret_key: sk_xxx
|
||||
google:
|
||||
client_id: xxx
|
||||
client_secret: xxx
|
||||
\`\`\`
|
||||
|
||||
Access in code: `Rails.application.credentials.stripe[:secret_key]`
|
||||
|
||||
### Environment-Specific
|
||||
|
||||
**Development**
|
||||
\`\`\`
|
||||
DATABASE_URL=postgresql://localhost/myapp_development
|
||||
REDIS_URL=redis://localhost:6379/0
|
||||
\`\`\`
|
||||
|
||||
**Production**
|
||||
\`\`\`
|
||||
DATABASE_URL=<production-connection-string>
|
||||
RAILS_ENV=production
|
||||
RAILS_SERVE_STATIC_FILES=true
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 7. Available Scripts
|
||||
|
||||
```markdown
|
||||
## Available Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bin/dev` | Start development server (Rails + Vite via Foreman) |
|
||||
| `bin/rails server` | Start Rails server only |
|
||||
| `bin/vite dev` | Start Vite dev server only |
|
||||
| `bin/rails console` | Open Rails console (IRB with app loaded) |
|
||||
| `bin/rails db:migrate` | Run pending database migrations |
|
||||
| `bin/rails db:rollback` | Rollback last migration |
|
||||
| `bin/rails db:seed` | Run database seeds |
|
||||
| `bin/rails db:reset` | Drop, create, migrate, and seed database |
|
||||
| `bin/rails routes` | List all routes |
|
||||
| `bin/rails test` | Run test suite (Minitest) |
|
||||
| `bundle exec rspec` | Run test suite (RSpec, if used) |
|
||||
| `bin/rails assets:precompile` | Compile assets for production |
|
||||
| `bin/rubocop` | Run Ruby linter |
|
||||
| `yarn lint` | Run JavaScript/TypeScript linter |
|
||||
```
|
||||
|
||||
### 8. Testing
|
||||
|
||||
```markdown
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
\`\`\`bash
|
||||
# Run all tests (Minitest)
|
||||
bin/rails test
|
||||
|
||||
# Run all tests (RSpec, if used)
|
||||
bundle exec rspec
|
||||
|
||||
# Run specific test file
|
||||
bin/rails test test/models/user_test.rb
|
||||
bundle exec rspec spec/models/user_spec.rb
|
||||
|
||||
# Run tests matching a pattern
|
||||
bin/rails test -n /creates_user/
|
||||
bundle exec rspec -e "creates user"
|
||||
|
||||
# Run system tests (browser tests)
|
||||
bin/rails test:system
|
||||
|
||||
# Run with coverage (SimpleCov)
|
||||
COVERAGE=true bin/rails test
|
||||
\`\`\`
|
||||
|
||||
### Test Structure
|
||||
|
||||
\`\`\`
|
||||
test/ # Minitest structure
|
||||
├── controllers/ # Controller tests
|
||||
├── models/ # Model unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── system/ # System/browser tests
|
||||
├── fixtures/ # Test data
|
||||
└── test_helper.rb # Test configuration
|
||||
|
||||
spec/ # RSpec structure (if used)
|
||||
├── models/
|
||||
├── requests/
|
||||
├── system/
|
||||
├── factories/ # FactoryBot factories
|
||||
├── support/
|
||||
└── rails_helper.rb
|
||||
\`\`\`
|
||||
|
||||
### Writing Tests
|
||||
|
||||
**Minitest example:**
|
||||
\`\`\`ruby
|
||||
require "test_helper"
|
||||
|
||||
class UserTest < ActiveSupport::TestCase
|
||||
test "creates user with valid attributes" do
|
||||
user = User.new(email: "test@example.com", name: "Test User")
|
||||
assert user.valid?
|
||||
end
|
||||
|
||||
test "requires email" do
|
||||
user = User.new(name: "Test User")
|
||||
assert_not user.valid?
|
||||
assert_includes user.errors[:email], "can't be blank"
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
**RSpec example:**
|
||||
\`\`\`ruby
|
||||
require "rails_helper"
|
||||
|
||||
RSpec.describe User, type: :model do
|
||||
describe "validations" do
|
||||
it "is valid with valid attributes" do
|
||||
user = build(:user)
|
||||
expect(user).to be_valid
|
||||
end
|
||||
|
||||
it "requires an email" do
|
||||
user = build(:user, email: nil)
|
||||
expect(user).not_to be_valid
|
||||
expect(user.errors[:email]).to include("can't be blank")
|
||||
end
|
||||
end
|
||||
end
|
||||
\`\`\`
|
||||
|
||||
### Frontend Testing
|
||||
|
||||
For Inertia/React components:
|
||||
|
||||
\`\`\`bash
|
||||
yarn test
|
||||
\`\`\`
|
||||
|
||||
\`\`\`typescript
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import { Dashboard } from './Dashboard'
|
||||
|
||||
describe('Dashboard', () => {
|
||||
it('renders user name', () => {
|
||||
render(<Dashboard user={{ name: 'Josh' }} />)
|
||||
expect(screen.getByText('Josh')).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 9. Deployment
|
||||
|
||||
Tailor this to detected platform (look for Dockerfile, fly.toml, render.yaml, kamal/, etc.):
|
||||
|
||||
```markdown
|
||||
## Deployment
|
||||
|
||||
### Kamal (Recommended for Rails)
|
||||
|
||||
If using Kamal for deployment:
|
||||
|
||||
\`\`\`bash
|
||||
# Setup Kamal (first time)
|
||||
kamal setup
|
||||
|
||||
# Deploy
|
||||
kamal deploy
|
||||
|
||||
# Rollback to previous version
|
||||
kamal rollback
|
||||
|
||||
# View logs
|
||||
kamal app logs
|
||||
|
||||
# Run console on production
|
||||
kamal app exec --interactive 'bin/rails console'
|
||||
\`\`\`
|
||||
|
||||
Configuration lives in `config/deploy.yml`.
|
||||
|
||||
### Docker
|
||||
|
||||
Build and run:
|
||||
|
||||
\`\`\`bash
|
||||
# Build image
|
||||
docker build -t myapp .
|
||||
|
||||
# Run with environment variables
|
||||
docker run -p 3000:3000 \
|
||||
-e DATABASE_URL=postgresql://... \
|
||||
-e SECRET_KEY_BASE=... \
|
||||
-e RAILS_ENV=production \
|
||||
myapp
|
||||
\`\`\`
|
||||
|
||||
### Heroku
|
||||
|
||||
\`\`\`bash
|
||||
# Create app
|
||||
heroku create myapp
|
||||
|
||||
# Add PostgreSQL
|
||||
heroku addons:create heroku-postgresql:mini
|
||||
|
||||
# Set environment variables
|
||||
heroku config:set SECRET_KEY_BASE=$(bin/rails secret)
|
||||
heroku config:set RAILS_MASTER_KEY=$(cat config/master.key)
|
||||
|
||||
# Deploy
|
||||
git push heroku main
|
||||
|
||||
# Run migrations
|
||||
heroku run bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Fly.io
|
||||
|
||||
\`\`\`bash
|
||||
# Launch (first time)
|
||||
fly launch
|
||||
|
||||
# Deploy
|
||||
fly deploy
|
||||
|
||||
# Run migrations
|
||||
fly ssh console -C "bin/rails db:migrate"
|
||||
|
||||
# Open console
|
||||
fly ssh console -C "bin/rails console"
|
||||
\`\`\`
|
||||
|
||||
### Render
|
||||
|
||||
If `render.yaml` exists, connect your repo to Render and it will auto-deploy.
|
||||
|
||||
Manual setup:
|
||||
1. Create new Web Service
|
||||
2. Connect GitHub repository
|
||||
3. Set build command: `bundle install && bin/rails assets:precompile`
|
||||
4. Set start command: `bin/rails server`
|
||||
5. Add environment variables in dashboard
|
||||
|
||||
### Manual/VPS Deployment
|
||||
|
||||
\`\`\`bash
|
||||
# On the server:
|
||||
|
||||
# Pull latest code
|
||||
git pull origin main
|
||||
|
||||
# Install dependencies
|
||||
bundle install --deployment
|
||||
|
||||
# Compile assets
|
||||
RAILS_ENV=production bin/rails assets:precompile
|
||||
|
||||
# Run migrations
|
||||
RAILS_ENV=production bin/rails db:migrate
|
||||
|
||||
# Restart application server (e.g., Puma via systemd)
|
||||
sudo systemctl restart myapp
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 10. Troubleshooting
|
||||
|
||||
```markdown
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Issues
|
||||
|
||||
**Error:** `could not connect to server: Connection refused`
|
||||
|
||||
**Solution:**
|
||||
1. Verify PostgreSQL is running: `pg_isready` or `docker ps`
|
||||
2. Check `DATABASE_URL` format: `postgresql://USER:PASSWORD@HOST:PORT/DATABASE`
|
||||
3. Ensure database exists: `bin/rails db:create`
|
||||
|
||||
### Pending Migrations
|
||||
|
||||
**Error:** `Migrations are pending`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
bin/rails db:migrate
|
||||
\`\`\`
|
||||
|
||||
### Asset Compilation Issues
|
||||
|
||||
**Error:** `The asset "application.css" is not present in the asset pipeline`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
# Clear and recompile assets
|
||||
bin/rails assets:clobber
|
||||
bin/rails assets:precompile
|
||||
\`\`\`
|
||||
|
||||
### Bundle Install Failures
|
||||
|
||||
**Error:** Native extension build failures
|
||||
|
||||
**Solution:**
|
||||
1. Ensure system dependencies are installed:
|
||||
\`\`\`bash
|
||||
# macOS
|
||||
brew install postgresql libpq
|
||||
|
||||
# Ubuntu
|
||||
sudo apt-get install libpq-dev
|
||||
\`\`\`
|
||||
2. Try again: `bundle install`
|
||||
|
||||
### Credentials Issues
|
||||
|
||||
**Error:** `ActiveSupport::MessageEncryptor::InvalidMessage`
|
||||
|
||||
**Solution:**
|
||||
The master key doesn't match the credentials file. Either:
|
||||
1. Get the correct `config/master.key` from another team member
|
||||
2. Or regenerate credentials: `rm config/credentials.yml.enc && bin/rails credentials:edit`
|
||||
|
||||
### Vite/Inertia Issues
|
||||
|
||||
**Error:** `Vite Ruby - Build failed`
|
||||
|
||||
**Solution:**
|
||||
\`\`\`bash
|
||||
# Clear Vite cache
|
||||
rm -rf node_modules/.vite
|
||||
|
||||
# Reinstall JS dependencies
|
||||
rm -rf node_modules && corepack yarn install
|
||||
\`\`\`
|
||||
|
||||
### Solid Queue Issues
|
||||
|
||||
**Error:** Jobs not processing
|
||||
|
||||
**Solution:**
|
||||
Ensure the queue worker is running:
|
||||
\`\`\`bash
|
||||
bin/jobs
|
||||
# or
|
||||
bin/rails solid_queue:start
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 11. Contributing (Optional)
|
||||
|
||||
Include if open source or team project.
|
||||
|
||||
### 12. License (Optional)
|
||||
|
||||
---
|
||||
Include the sections that apply; skip ones that don't. Suggested order:
|
||||
|
||||
1. **Title + one-paragraph overview** — what it is, who it's for, links to the live app/stores
|
||||
2. **Key features** — short bullet list, user-facing
|
||||
3. **Tech stack** — table of major dependencies with one-line roles
|
||||
4. **Prerequisites** — runtime versions (from `engines`/`.nvmrc`), `corepack enable`, platform SDKs only for the platform sections that need them
|
||||
5. **Getting started** — clone, `corepack yarn install`, `yarn start`, expected dev URL; every command copy-pasteable and tested
|
||||
6. **Architecture overview** — directory map with one-line descriptions, data flow, where state lives, how the P2P/backendless parts work (if applicable)
|
||||
7. **Configuration** — env vars/flags as a table (name, required?, default, purpose)
|
||||
8. **Available scripts** — table of the `package.json` scripts a contributor will actually use
|
||||
9. **Testing** — how to run unit/e2e tests, what CI runs
|
||||
10. **Building and releasing** — per-platform build commands (web, Android, Electron), release process pointers
|
||||
11. **Troubleshooting** — only real, observed failure modes with fixes; don't invent generic ones
|
||||
12. **Contributing / License** — link `AGENTS.md`/docs rather than duplicating policy
|
||||
|
||||
## Writing Principles
|
||||
|
||||
1. **Be Absurdly Thorough** - When in doubt, include it. More detail is always better.
|
||||
1. **Verify every command** — run it or confirm it exists in `package.json` before documenting it
|
||||
2. **Copy-pasteable code blocks** with language hints; show expected output where it helps
|
||||
3. **Explain the why**, not just the what
|
||||
4. **Assume a fresh machine** for setup sections
|
||||
5. **Tables for reference material** — env vars, scripts, options
|
||||
6. **Match the project's package manager** — `yarn` here; never write `npm install` for a Yarn repo
|
||||
7. **Table of contents** for READMEs over ~200 lines
|
||||
8. **Don't duplicate other repo docs** — link to `AGENTS.md`, `DESIGN.md`, `PRODUCT.md`, playbooks instead of restating them; duplicated policy drifts
|
||||
|
||||
2. **Use Code Blocks Liberally** - Every command should be copy-pasteable.
|
||||
## Output
|
||||
|
||||
3. **Show Example Output** - When helpful, show what the user should expect to see.
|
||||
|
||||
4. **Explain the Why** - Don't just say "run this command," explain what it does.
|
||||
|
||||
5. **Assume Fresh Machine** - Write as if the reader has never seen this codebase.
|
||||
|
||||
6. **Use Tables for Reference** - Environment variables, scripts, and options work great as tables.
|
||||
|
||||
7. **Keep Commands Current** - Use `pnpm` if the project uses it, `npm` if it uses npm, etc.
|
||||
|
||||
8. **Include a Table of Contents** - For READMEs over ~200 lines, add a TOC at the top.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
Generate a complete README.md file with:
|
||||
- Proper markdown formatting
|
||||
- Code blocks with language hints (```bash, ```typescript, etc.)
|
||||
- Tables where appropriate
|
||||
- Clear section hierarchy
|
||||
- Linked table of contents for long documents
|
||||
|
||||
Write the README directly to `README.md` in the project root.
|
||||
Write directly to `README.md` in the project root. After public-facing English content changes in this repo, run `yarn llms:generate` and commit any resulting `public/llms*.txt` changes (see AGENTS.md Task Router).
|
||||
|
||||
@@ -171,7 +171,6 @@ adb logcat -d -t 300 | tail -300
|
||||
| `android/app/src/androidTest/.../MediaUploadAutomationRunnerTest.java` | Fixture-based unit tests |
|
||||
| `android/app/src/androidTest/.../PostimagesLiveUploadTest.java` | Live integration test |
|
||||
| `android/app/src/main/assets/fixtures/` | HTML test fixtures |
|
||||
| `scripts/run-postimages-live-emulator-test.sh` | Reference emulator test script |
|
||||
|
||||
## Upload Automation Stages (for interpreting logcat)
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Based on https://react.dev/learn/you-might-not-need-an-effect
|
||||
|
||||
## Arguments
|
||||
|
||||
- **scope**: what to analyze (default: uncommitted changes). Examples: `diff to main`, `src/components/`, `whole codebase`
|
||||
- **scope**: what to analyze (default: uncommitted changes). Examples: `diff to master`, `src/components/`, `whole codebase`
|
||||
- **fix**: whether to apply fixes (default: `true`). Set to `false` to only propose changes.
|
||||
|
||||
## Workflow
|
||||
|
||||
Reference in New Issue
Block a user