document-engine

name	document-engine
type	atomic
license	MIT
description	Use when documenting Rails engines — show the minimum working install path first (gem add→bundle→install generator→mount in routes), document ALL configuration options with defaults (required vs optional), state host model/auth assumptions explicitly, keep examples copyable, satisfy minimum install path + config options + host assumptions before optional sections, validate against CHECKLIST.md with at least one copyable code example per section before finalizing. Generates README templates, installation guides, configuration docs, mount instructions, extension API docs, and migration notes. Trigger words: engine README, installation guide, configuration docs, mount instructions, migration notes, host integration examples.
metadata	{"version":"1.0.0","user-invocable":"true"}

Document Engine

Use this skill when writing or maintaining documentation for Rails engines.

Core Process & Constraints

Step	Section	Focus
1	Installation	gem add, bundle, run install generator — show minimum working path first
2	Host Assumptions	Explicitly state any host model, job backend, or auth integration assumptions
3	Configuration	All options with defaults, required vs optional
4	Mounting	Explicit mount MyEngine::Engine, at: '/path' in routes — show once only
5	Usage	Copyable code for typical workflows
6	Migrations	Install generator, one-time setup, upgrade-impacting changes

Hard gate: All generated documentation MUST satisfy steps 1, 2, and 3 above before proceeding to optional sections.

README snippet (install + mount):

## Installation

Add to your Gemfile:

    gem 'my_engine'

Run:

    bundle install
    rails generate my_engine:install

This creates `config/initializers/my_engine.rb`. Mount the engine in `config/routes.rb`:

    mount MyEngine::Engine, at: '/admin'

Configuration section:

## Configuration

In `config/initializers/my_engine.rb`:

    MyEngine.configure do |config|
      config.user_class = "User"       # required: host model for current user
      config.widget_count = 10         # optional, default 10
    end

Extended Resources

See CHECKLIST.md for the full recommended README shape and documentation gap checklist. Critical gaps tracked there: installation steps, all config options with defaults, explicit mount path, migration timing, host model/auth assumptions.

• assets/configuration.md — detailed config option catalog with type info, validation rules, and all supported defaults
• assets/examples.md — realistic end-to-end usage examples covering common host-app integration workflows
• assets/installation.md — step-by-step install and generator reference including post-install setup tasks

Output Style

1. Keep sections short and task-oriented.
2. Validate against CHECKLIST.md: a checklist item passes when the docs contain a corresponding section with at least one copyable code example or explicit prose statement; it fails when absent, incomplete, or lacking a concrete example. Fix each failing item, then re-run from the top. Do not finalize until all critical items pass.
3. Section Delineation: Explicitly label mandatory "Hard-Gate" sections (Installation, Configuration, Host Assumptions) and "Optional" sections (Extension Points, Usage Examples).
4. Upgrade Notes: Include at least one copyable code example in any Upgrade Notes section.
5. Language — Must be in English unless explicitly requested otherwise.

Common pitfalls to avoid:

• Duplicate mount MyEngine::Engine ... across multiple sections — show it only once in the primary installation/mounting section.
• Syntax errors in Ruby/Rails code examples — double-check route mounting and authentication blocks (e.g., authenticate :user, ->(u) { u.admin? } do).

Integration

Skill	When to chain
create-engine	Host-app contract, structure, extension points to document
create-engine-installer	Install generators, setup steps to document
release-engine	Changelog, upgrade notes, version documentation
generate-api-collection	When documenting or adding API endpoints (keep Postman collection in sync)