shiplog 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0f17beb628a8bf038407c3a1b0e5caa404db7f51eba9472dbf507df7da84431
+  data.tar.gz: da38c5e1bc625bcae2ed31ef037db2440bc94a612760c11cc842cb91b02cdf28
+SHA512:
+  metadata.gz: 588b5d5e87c63b828d0a75ef4aa01591efec6c94a954622d3ad2e36a6cf88deeb46ae72b19b0f865828606f147dfcdb2b6d30f34ce75741acc23543f9a853d15
+  data.tar.gz: d6a7f52d6df8768e5586a47bbded5e5b867dfaac2ec07e85fd0ac86b37b0a8e4a275db62f7893a1ea8b0f607027924cc50bb4925ff2efb41c9b10e4158bd1a95

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-10-26)
+
+Initial release.
+
+- Public roadmap and changelog engine (`Shiplog::Engine`) and a separate admin engine (`Shiplog::Admin::Engine`) with a drafts inbox, entry editing, a roadmap board with drag and drop, and sync status.
+- GitHub GraphQL sync across several repositories, a signed webhook endpoint (`issues`, `pull_request`, `sub_issues`), and scheduled jobs (`Shiplog::SyncJob`, `Shiplog::ScanChangesJob`).
+- Roadmap columns derived from GitHub state (open PR or assignee, milestone or `soon` label), with admins able to pin a card to a column.
+- Changelog drafts for shipped features (from the issue form's Problem / Before / After) and for small merged PRs and commits, skipping bots, internal conventional-commit types and excluded labels.
+- Host-supplied LLM rewriter. Nothing is public until approved, and approved text is never silently replaced.
+- Styling: `config.classes` (per-element classes next to stable `shiplog-*` BEM classes), `config.stylesheet`, and a bundled stylesheet in `@layer shiplog` with `--shiplog-*` variables. Public views are split into overridable partials.
+- Rendering inside host layouts: `public_parent_controller` / `public_layout`, `admin_parent_controller` / `admin_layout` / `admin_chrome` / `admin_flash`, and unknown `*_path` / `*_url` helpers forwarded to `main_app`.
+- Admin access fails closed (`config.authorize_admin` defaults to deny).
+- `rails generate shiplog:install` (with `--tailwind`) and a `shiplog-feature.yml` issue form.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Trackberry
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,410 @@
+# Shiplog
+
+A mountable Rails engine that turns your GitHub issues, pull requests and commits into a public roadmap and changelog written for customers, not developers. An LLM that you supply drafts the plain-language text. Nothing is public until an admin approves it.
+
+- **Roadmap**: issues labelled `public` appear in three columns (In progress, Coming soon, Later) once approved.
+- **Changelog**: shipped features and small changes, grouped by month.
+- **Admin**: drafts inbox, entry editing, a drag-and-drop roadmap board and a sync status page.
+
+## Requirements
+
+- Ruby 4.0 or newer
+- Rails 8.1.4 or newer (< 9)
+- PostgreSQL (tables use `jsonb`)
+- A job backend for Active Job (GoodJob, Solid Queue, ...)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "shiplog"
+```
+
+```sh
+bundle install
+bin/rails generate shiplog:install
+bin/rails db:migrate
+```
+
+The generator:
+
+- creates `config/initializers/shiplog.rb` with every setting, commented;
+- adds the public mount (and a commented admin mount) to `config/routes.rb`;
+- runs `shiplog:install:migrations` (all tables are prefixed `shiplog_`);
+- copies the issue form to `.github/ISSUE_TEMPLATE/shiplog-feature.yml`. It has Problem / Before / After fields and applies the `public` label.
+
+With `--tailwind` the initializer also sets `config.stylesheet = false` and a `config.classes` hash of Tailwind classes, and the generator adds the `@source` line to `app/assets/tailwind/application.css`. See [Styling](#styling).
+
+## Mounting
+
+Shiplog ships two engines so that the admin can sit behind your own authentication while the public pages and the GitHub webhook stay open (the same approach as GoodJob):
+
+```ruby
+# config/routes.rb
+mount Shiplog::Engine => "/"   # /roadmap, /changelog, /shiplog/github/webhook, engine assets
+
+authenticate :user, ->(user) { user.admin? } do   # Devise shown; use whatever fits your app
+  mount Shiplog::Admin::Engine => "/admin/shiplog"
+end
+```
+
+The generator writes the admin mount as a comment because authentication differs between apps. Uncomment it once it is wrapped in a constraint.
+
+`config.authorize_admin` is checked by the admin controllers and a falsy result returns 403. It is fail-closed: the default denies everyone, so a mount that is not configured is never open. The generated initializer sets `config.authorize_admin = ->(controller) { true }` because the route constraint around the mount does the authentication. If you do not wrap the mount in a constraint, replace it with a real check (for example `controller.current_user&.admin?`).
+
+The public paths come from `config.roadmap_path` and `config.changelog_path`, read when routes are drawn.
+
+### Customising the admin layout
+
+By default the admin uses its own layout (`layouts/shiplog/admin`) and its own CSS and JS, served by the engine (and aware of your CSP nonce). To change it, create the same file in your app, which takes precedence over the engine's:
+
+```erb
+<%# app/views/layouts/shiplog/admin.html.erb %>
+```
+
+To render the admin inside your own admin layout instead, see [Rendering inside your layouts](#rendering-inside-your-layouts).
+
+For smaller tweaks override a partial instead:
+
+- `app/views/shiplog/admin/_custom_head.html.erb`: rendered inside `<head>` of the engine layout (extra stylesheets, favicon, ...).
+- `app/views/shiplog/admin/_nav.html.erb`: the navigation bar (a compact sub-nav when a host layout is used).
+- `app/views/shiplog/admin/_assets.html.erb`: links `admin.css`; every admin page renders it, so it works in any layout.
+
+Engine views use the engine's route helpers, so inside a host layout or partial rendered by a Shiplog controller your own routes are available as `main_app.` helpers, or directly (see [host route helpers](#host-route-helpers)).
+
+### Public pages
+
+The public controllers inherit from `config.public_parent_controller` and render with `config.public_layout`.
+
+## Configuration
+
+All settings live in `config/initializers/shiplog.rb`:
+
+| Key | Default | Description |
+|---|---|---|
+| `repositories` | `[]` | GitHub repositories to sync, as `"owner/name"`. Sub-issues may cross repositories of the same owner. |
+| `github_token` | `nil` | A String, or a callable evaluated on every GitHub request. |
+| `webhook_secret` | `nil` | Secret of the GitHub webhook. While blank, the webhook endpoint answers 503. |
+| `public_label` | `"public"` | Only issues with this label reach the roadmap. |
+| `soon_labels` | `["soon"]` | Labels that put an issue in "Coming soon". A milestone does the same. |
+| `excluded_labels` | `["internal", "dependencies", "refactor", "chore"]` | Pull requests with one of these labels never become changelog entries. |
+| `excluded_authors` | `[/\[bot\]\z/]` | Patterns (matched with `===`) for authors whose pull requests and commits are skipped. |
+| `commit_types` | `["feat", "fix", "perf"]` | Conventional-commit types eligible for the changelog. Commits need one of these types; pull requests whose title has a different type (`ci:`, `chore(deps):`, ...) are skipped, untyped titles are kept. |
+| `rewriter` | `nil` | Callable that rewrites text with an LLM. See [The rewriter](#the-rewriter). |
+| `product_name` | `nil` | Your product's name, used in the prompts. |
+| `audience` | `nil` | Who your customers are, used in the prompts. |
+| `tone` | `"Friendly, concise, no jargon. Address the customer as 'you'."` | Writing style used in the prompts. |
+| `prompt_builder` | `nil` | Optional `->(kind:, context:) { String }` replacing the built-in prompts. `kind` is `"roadmap"`, `"feature"` or `"change"`. |
+| `public_parent_controller` | `"ActionController::Base"` | Parent class of the public controllers. Read once when they load, so set it in the initializer; assigning it after the controllers loaded raises `ArgumentError`. |
+| `public_layout` | `"shiplog/application"` | Layout of the public pages. |
+| `admin_parent_controller` | `"ActionController::Base"` | Parent class of the admin controllers. Read once when they load, so set it in the initializer; assigning it after the controllers loaded raises `ArgumentError`. |
+| `admin_layout` | `"shiplog/admin"` | Layout of the admin pages. |
+| `admin_chrome` | `:standalone` | `:standalone` wraps the admin in Shiplog's own page chrome (nav bar, flash, background). `:hosted` is for an `admin_layout` of your own: Shiplog renders only a compact sub-nav inside your content. Anything else raises `ArgumentError`. The layout name is never inspected. |
+| `admin_flash` | `true` | In `:hosted` mode, render Shiplog's flash messages inside the admin content. Set to `false` if your layout already shows the flash. Standalone always shows it. |
+| `stylesheet` | `true` | Include the bundled `shiplog.css` in the public pages. Set to `false` when you style them yourself. |
+| `classes` | `{}` | Extra classes per element, added to the stable `shiplog-*` classes. See [Styling](#styling). |
+| `authorize_admin` | `->(controller) { false }` | Admin check; return false for a 403. Denies everyone until set; the generated initializer opens it, relying on your route constraint. |
+| `current_admin` | `->(controller) { controller.try(:current_user)&.try(:email) }` | Stored as the approver of an entry. |
+| `roadmap_path` | `"roadmap"` | Path of the public roadmap. |
+| `changelog_path` | `"changelog"` | Path of the public changelog. |
+
+Example:
+
+```ruby
+Shiplog.configure do |config|
+  config.repositories   = %w[acme/app acme/app-ios]
+  config.github_token   = -> { Rails.application.credentials.dig(:github, :shiplog_token) }
+  config.webhook_secret = Rails.application.credentials.dig(:github, :shiplog_webhook_secret)
+  config.product_name   = "Acme"
+  config.audience       = "small business owners who invoice customers"
+  config.rewriter       = ->(prompt) { RubyLLM.chat.ask(prompt).content }
+end
+```
+
+## GitHub token
+
+Shiplog talks to the GitHub GraphQL API. Provide either:
+
+- a **fine-grained personal access token** with access to the configured repositories and read-only permissions for **Issues**, **Pull requests**, **Contents** and **Metadata**; or
+- a **GitHub App installation token** with the same permissions. Because `github_token` accepts a callable, you can mint a fresh token on each call:
+
+```ruby
+config.github_token = -> { MyApp::GithubApp.installation_token }
+```
+
+## Webhook setup
+
+Webhooks keep Shiplog fresh between scheduled syncs. In each repository (or at organisation level) add a webhook:
+
+- **Payload URL**: `https://your-app.example.com/shiplog/github/webhook` (prefix it if you mounted `Shiplog::Engine` below `/`)
+- **Content type**: `application/json`
+- **Secret**: the value of `config.webhook_secret`
+- **Events**: *Issues*, *Pull requests* and *Sub-issues*
+
+Requests are verified with `X-Hub-Signature-256`; an invalid signature returns 401. Each `X-GitHub-Delivery` id is recorded, so redeliveries are harmless. Valid events enqueue a `Shiplog::RefreshJob` that refetches the current state of the issue or pull request and respond 202. `ping` answers 200 and other events are ignored. Recent deliveries are listed on the admin Sync page.
+
+## Scheduling
+
+Webhooks can be missed, so schedule two jobs:
+
+- `Shiplog::SyncJob`: reconciles issues and pull requests and creates missing drafts. Every 30 minutes is a good start. The first run backfills everything.
+- `Shiplog::ScanChangesJob`: looks at default-branch commits without a pull request, then drafts small changes. Run it weekly.
+
+GoodJob (`config/initializers/good_job.rb` or `config/application.rb`):
+
+```ruby
+config.good_job.enable_cron = true
+config.good_job.cron = {
+  shiplog_sync: { cron: "*/30 * * * *", class: "Shiplog::SyncJob" },
+  shiplog_scan_changes: { cron: "0 6 * * 1", class: "Shiplog::ScanChangesJob" }
+}
+```
+
+Solid Queue (`config/recurring.yml`):
+
+```yaml
+production:
+  shiplog_sync:
+    class: Shiplog::SyncJob
+    schedule: every 30 minutes
+  shiplog_scan_changes:
+    class: Shiplog::ScanChangesJob
+    schedule: every monday at 6am
+```
+
+You can also trigger a sync from the admin Sync page. Rewriting always runs in `Shiplog::RewriteEntryJob`, never in a request.
+
+## The rewriter
+
+`config.rewriter` is a callable that receives the prompt (a String) and returns a String containing a JSON object:
+
+```json
+{"title": "...", "body": "...", "customer_facing": true}
+```
+
+Shiplog extracts the first valid JSON object from the reply, so models that wrap it in prose or code fences still work. `customer_facing: false` means the model thinks the change is irrelevant for customers; such small changes are stored as discarded and can be restored by an admin. If no rewriter is configured, the reply can't be parsed or the call raises, the entry keeps the original GitHub text and the error is shown in the admin, where you can edit the text or regenerate.
+
+With [RubyLLM](https://rubyllm.com):
+
+```ruby
+config.rewriter = ->(prompt) { RubyLLM.chat.ask(prompt).content }
+```
+
+With the Anthropic SDK:
+
+```ruby
+client = Anthropic::Client.new
+config.rewriter = lambda do |prompt|
+  message = client.messages.create(model: "claude-sonnet-5-5", max_tokens: 1024, messages: [ { role: "user", content: prompt } ])
+  message.content.first.text
+end
+```
+
+## How items reach the roadmap
+
+- An issue is *public* when it has `config.public_label`.
+- A public, open issue whose parent is not itself public is a roadmap item. Public children of a public parent are folded into the parent.
+- A roadmap item is drafted, rewritten and visible on `/roadmap` only after an admin approves it. It leaves the roadmap when it is closed.
+- The column is the first match of:
+  1. the column an admin pinned it to;
+  2. **In progress**: the issue or one of its sub-issues has an open linked pull request, or the issue has assignees;
+  3. **Coming soon**: it has a milestone or a label from `soon_labels`;
+  4. **Later**.
+- Within a column cards are ordered by their board position, then by last GitHub update. Dragging a card on the admin board pins it to the target column and stores the order. "Unpin" returns it to the automatic column. Without JavaScript, each card has a column select and a Move button.
+
+## How changelog entries are produced
+
+- **Features**: a public top-level issue closed as completed that has at least one merged linked pull request on itself or a sub-issue. The issue form sections (`### Problem`, `### Before`, `### After`), sub-issue titles and linked pull request titles are given to the rewriter. Only issues closed in the last 90 days are drafted, so a first sync doesn't flood the inbox. The release date is the newest merge date.
+- **Small changes**: the weekly scan looks at pull requests merged, and stored commits made, since the last scan (seven days on the first run). Commits are only considered when they are on the default branch and have no pull request, and their conventional-commit type (`feat:`, `fix(scope):`, ...) must be in `commit_types`. Pull requests are skipped when their title carries a type outside `commit_types`; untyped titles are left for the rewriter to judge. Bot authors are recorded as `name[bot]`, so the default `excluded_authors` pattern matches them.
+- **Exclusions**: pull requests with an excluded label or an excluded author, commits from excluded authors, pull requests that belong to a feature's issue tree (the feature entry covers them), and anything that already has an entry.
+
+## Approval workflow
+
+Every entry starts as a **draft**. In the admin inbox you can edit the text, regenerate it, approve it or discard it. Only approved entries are public. Discarded entries are never proposed again but can be restored. If the GitHub text changes after a draft was written, the entry is flagged "GitHub text changed since this draft" and can be regenerated, and approved text is never replaced silently.
+
+Approved changelog entries do not react to later GitHub changes (a reverted pull request, a removed label): discard them by hand in the admin. A roadmap issue that is re-labelled or reopened shows its previously approved text again, and the inbox flags it as "GitHub text changed". Issues deleted or transferred on GitHub are closed locally (state reason `deleted`), which removes them from the roadmap; their entries are kept.
+
+Drafts whose rewrite job was lost (no result and no error after an hour) are queued again by the next sync, and the admin marks them "Not rewritten yet" until then.
+
+## Styling
+
+The public pages ship plain semantic HTML with stable [BEM](https://getbem.com) classes (`shiplog-card`, `shiplog-entry__title`, ...) and a small, framework-free stylesheet. Pick the level that fits your app; the same views work in all of them.
+
+### 1. CSS variables
+
+The bundled stylesheet is driven by variables you can set on `:root`, `body` or `.shiplog-page`. Inside your own layout it inherits your text colour and draws cards and borders as translucent mixes of that colour (`color-mix` against `currentColor`), so it works on light and dark hosts without any setting. Only Shiplog's own layout (`.shiplog-layout`), which paints the page background, switches to dark colours with `prefers-color-scheme`.
+
+| Variable | Meaning |
+|---|---|
+| `--shiplog-fg` | Text colour |
+| `--shiplog-muted` | Secondary text |
+| `--shiplog-bg` | Page background (only painted by the engine's own layout) |
+| `--shiplog-card` | Card and entry background |
+| `--shiplog-border` | Borders and dividers |
+| `--shiplog-accent` | Links, feature marker, pill, hover |
+| `--shiplog-radius` | Corner radius (default `0.5rem`) |
+| `--shiplog-font` | Font family |
+| `--shiplog-space` | Base spacing unit (default `1rem`) |
+
+```css
+:root { --shiplog-accent: #7c3aed; --shiplog-radius: 0.75rem; }
+```
+
+### 2. Override the BEM classes
+
+All rules live in `@layer shiplog`, so any unlayered CSS in your app wins without extra specificity:
+
+```css
+.shiplog-card { border-radius: 0; }
+.shiplog-entry--feature { border-left-width: 8px; }
+```
+
+If your own CSS is layered too, declare the order up front, for example `@layer shiplog, app;`.
+
+### 3. `config.classes` (Tailwind and other utility frameworks)
+
+`config.classes` maps a key to the classes added to that element, next to its BEM class. Set `config.stylesheet = false` to drop the bundled CSS:
+
+```ruby
+Shiplog.configure do |config|
+  config.stylesheet = false
+  config.classes = {
+    columns: "grid gap-6 md:grid-cols-3",
+    card: "rounded-lg border border-gray-200 bg-white p-3 dark:border-gray-800 dark:bg-gray-900"
+  }
+end
+```
+
+With Tailwind v4, the class names live in a Ruby file, so tell Tailwind to scan it. In `app/assets/tailwind/application.css`:
+
+```css
+@import "tailwindcss";
+@source "../../../config/initializers/shiplog.rb";
+```
+
+(The path is relative to the stylesheet: `app/assets/tailwind/` up three levels is the app root.) `bin/rails generate shiplog:install --tailwind` writes both for you, with neutral gray/indigo classes covering every key.
+
+If you keep the bundled stylesheet (`stylesheet: true`) next to Tailwind v4 utilities, declare the layer order before the import so utilities win over Shiplog's rules:
+
+```css
+@layer theme, base, shiplog, components, utilities;
+@import "tailwindcss";
+@source "../../../config/initializers/shiplog.rb";
+```
+
+Without it, `shiplog` is first seen when `shiplog.css` loads, which can put it after `utilities` in the cascade order (a layer's position is fixed by its first mention), and then `.shiplog-card { border-radius: ... }` would beat a `rounded-lg` utility. Declaring the order first pins `shiplog` below `components` and `utilities`.
+
+| Key | BEM class | Element |
+|---|---|---|
+| `page` | `shiplog-page` (+ `--roadmap` / `--changelog`) | Page wrapper |
+| `page_header` | `shiplog-page__header` | Header with title and lede |
+| `page_title` | `shiplog-page__title` | `h1` |
+| `page_lede` | `shiplog-page__lede` | Intro paragraph |
+| `columns` | `shiplog-columns` | Roadmap column grid |
+| `column` | `shiplog-column` (+ `--in-progress` / `--coming-soon` / `--later`) | One roadmap column |
+| `column_header` | `shiplog-column__header` | Column heading block |
+| `column_title` | `shiplog-column__title` | Column `h2` |
+| `column_count` | `shiplog-column__count` | Number of items |
+| `column_description` | `shiplog-column__description` | One-line description |
+| `column_empty` | `shiplog-column__empty` | Empty column notice |
+| `cards` | `shiplog-cards` | List of roadmap cards |
+| `card` | `shiplog-card` | Roadmap card |
+| `card_title` | `shiplog-card__title` | Card `h3` |
+| `card_body` | `shiplog-card__body` | Card text |
+| `months` | `shiplog-months` | Changelog months wrapper |
+| `month` | `shiplog-month` | One month section |
+| `month_title` | `shiplog-month__title` | Month `h2` |
+| `entries` | `shiplog-entries` | List of entries |
+| `entry` | `shiplog-entry` (+ `--feature` / `--change`) | Changelog entry |
+| `entry_feature` | `shiplog-entry--feature` | Also applied to feature entries |
+| `entry_category` | `shiplog-entry__category` | "New" / "Improved" pill |
+| `entry_title` | `shiplog-entry__title` | Entry `h3` |
+| `entry_body` | `shiplog-entry__body` | Entry text |
+| `entry_date` | `shiplog-entry__date` | `time` element |
+| `pagination` | `shiplog-pagination` | Pagination `nav` |
+| `pagination_link` | `shiplog-pagination__link` (+ `--newer` / `--older`) | Newer/older links |
+| `empty` | `shiplog-empty` | "Nothing here yet" notice |
+
+Values may be strings or arrays. The list is `Shiplog::Classes::KEYS`; assigning `config.classes` raises `ArgumentError` (listing the valid keys) for any other key, in every environment. String keys are accepted and normalised to symbols, and the hash is stored frozen. Texts come from I18n (`shiplog.roadmap.title`, `shiplog.roadmap.lede`, `shiplog.changelog.*`, `shiplog.categories.feature` / `change`, `shiplog.date_format` (default `%-d %B %Y`, used for entry dates), `shiplog.columns.<column>_description`), so override them in your locale files.
+
+### 4. Override the partials
+
+Copy any view from the engine's `app/views/shiplog/` into your app with the same path and edit it. Each partial documents its locals in a comment on its first lines:
+
+- `shiplog/_page.html.erb`, `shiplog/_page_header.html.erb`, `shiplog/_pagination.html.erb`, `shiplog/_empty.html.erb`
+- `shiplog/roadmaps/_column.html.erb`, `shiplog/roadmaps/_card.html.erb`
+- `shiplog/changelogs/_month.html.erb`, `shiplog/changelogs/_entry.html.erb`
+
+`shiplog/_page.html.erb` is what links the stylesheet (so it also works in layouts you don't control); keep that line if you copy it and still want the bundled CSS.
+
+The admin has its own stylesheet, scoped under `.shiplog-admin` and also in `@layer shiplog`. Its variables (`--shiplog-admin-fg`, `-muted`, `-bg`, `-surface`, `-border`, `-accent`) can be set on `:root` or `.shiplog-admin`. The admin follows the same rule: dark colours only in the standalone chrome, inherited colours when `admin_chrome` is `:hosted`.
+
+## Rendering inside your layouts
+
+- **Public pages**: set `config.public_parent_controller` (default `ActionController::Base`; read once when the controller loads, so use the initializer) and `config.public_layout` (default `"shiplog/application"`). The public controllers run under the parent's `before_action`s, so pick one that lets visitors through.
+- **Admin**: set `config.admin_parent_controller` (same rule), `config.admin_layout` and `config.admin_chrome = :hosted`. Each admin page links its own `admin.css` (and `board.js` on the board) and wraps itself in `<div class="shiplog-admin">`, so nothing depends on your layout's `<head>`. In `:hosted` mode Shiplog adds a small Drafts / Roadmap board / Sync sub-nav inside the content and shows its flash messages there too (set `config.admin_flash = false` if your layout renders the flash itself). The board reads the CSRF token from `meta[name=csrf-token]` and falls back to a `data-csrf-token` attribute, so your layout does not need `csrf_meta_tags` for drag and drop.
+- `config.authorize_admin` and the route constraint still apply.
+
+### Host route helpers
+
+A layout rendered by a Shiplog controller runs in the engine's isolated routing context. Shiplog's controllers include `Shiplog::HostRoutesHelper`, which forwards any `*_path` / `*_url` helper the engine does not define to `main_app`, so `root_path`, `about_path` or `new_user_session_path` work in your layout as they do elsewhere. Helpers the engine defines win: in the public engine `roadmap_path` is Shiplog's, and in the admin engine `root_path` is the admin root, so use `main_app.root_path` there when you mean your own.
+
+### Example: Trackberry-style setup
+
+```ruby
+# config/routes.rb
+mount Shiplog::Engine => "/"                       # /roadmap and /changelog next to the app's own pages
+authenticate :user, ->(user) { user.admin? } do
+  mount Shiplog::Admin::Engine => "/admin/shiplog"
+end
+
+# config/initializers/shiplog.rb
+Shiplog.configure do |config|
+  config.public_parent_controller = "ApplicationController"
+  config.public_layout            = "application"
+  config.admin_parent_controller  = "Admin::BaseController"
+  config.admin_layout             = "admin"
+  config.admin_chrome             = :hosted
+  config.stylesheet               = false
+  config.classes                  = { columns: "grid gap-6 md:grid-cols-3", card: "rounded-lg border p-3" } # see the generator for all keys
+end
+```
+
+The host layouts keep using their own helpers (`root_path`, `current_user`, ...) and Tailwind compiles the classes through the `@source` line.
+
+## Hosting notes
+
+- Set `public_parent_controller` and `admin_parent_controller` in an initializer (`config/initializers/shiplog.rb`). They are read once, when the engine's controller classes load, so changing them later has no effect.
+- The public pages send an ETag covering the data, locale, gem version, `config.classes` and `config.stylesheet`. If your host layout shows per-user content, declare `etag { current_user&.id }` in the parent controller (`config.public_parent_controller`); Rails ETags are inherited, so cached responses are not shared between users.
+
+## Running the tests
+
+```sh
+bin/rails db:create db:schema:load   # once, creates shiplog_test on local PostgreSQL
+bin/rails test
+bin/rails test test/system           # the roadmap board in headless Chrome
+bin/rubocop
+```
+
+The system tests need Chrome; Selenium fetches a matching chromedriver. The database is configured in `test/dummy/config/database.yml`; set `PGHOST`, `PGUSER` and `PGPASSWORD` if your PostgreSQL needs them.
+
+Tests that call the real GitHub API are skipped by default. To run them:
+
+```sh
+SHIPLOG_LIVE_GITHUB=1 GITHUB_TOKEN=... SHIPLOG_LIVE_REPO=owner/name bin/rails test test/live
+```
+
+`SHIPLOG_LIVE_REPO` defaults to `Trackberry/shiplog`.
+
+## License
+
+Released under the [MIT License](MIT-LICENSE).
+
+## Releasing
+
+Releases are published by `.github/workflows/release.yml` through RubyGems trusted publishing; there is no API key and no manual `gem push`.
+
+1. Open a pull request that bumps `lib/shiplog/version.rb` and adds a `## x.y.z (date)` entry to `CHANGELOG.md`.
+2. Merge it. The workflow reruns the tests, refuses a version that is already on RubyGems, publishes the gem, tags `vx.y.z` and creates the GitHub release with that changelog entry as its notes.
+
+The workflow can also be started by hand (Actions → Release → Run workflow), for the first release or to retry one that failed for an unrelated reason.

data/app/controllers/shiplog/admin/application_controller.rb

@@ -0,0 +1,37 @@
+module Shiplog
+  module Admin
+    # Parent controller of the admin. The parent class is resolved when this file loads, so
+    # `config.admin_parent_controller` must be set in an initializer (config/initializers/shiplog.rb).
+    class ApplicationController < Shiplog.config.admin_parent_controller.constantize
+      protect_from_forgery with: :exception
+
+      helper Shiplog::FrontendHelper
+      helper Shiplog::HostRoutesHelper
+      helper Shiplog::ApplicationHelper
+      helper Shiplog::Admin::EntriesHelper
+      helper_method :current_admin_name, :shiplog_admin_hosted?
+      layout -> { Shiplog.config.admin_layout }
+
+      before_action :authorize_admin
+
+      rescue_from Shiplog::Entry::InvalidTransition do
+        redirect_to edit_entry_path(params[:entry_id]), alert: t("shiplog.admin.entries.invalid_transition")
+      end
+
+      private
+
+      def authorize_admin
+        head :forbidden unless Shiplog.config.authorize_admin.call(self)
+      end
+
+      # True when the admin renders inside a host layout (config.admin_chrome = :hosted).
+      def shiplog_admin_hosted?
+        Shiplog.config.admin_chrome == :hosted
+      end
+
+      def current_admin_name
+        Shiplog.config.current_admin.call(self)
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/boards_controller.rb

@@ -0,0 +1,60 @@
+module Shiplog
+  module Admin
+    class BoardsController < ApplicationController
+      def show
+        @columns = Roadmap.new(published_only: false).columns
+        ActiveRecord::Associations::Preloader.new(records: @columns.values.flatten.map(&:issue), associations: :repository).call
+      end
+
+      def update
+        if request.format.json?
+          update_json
+        else
+          update_form
+        end
+      end
+
+      private
+
+      def update_json
+        ids = params[:issue_ids]
+        return render_json_error("issue_ids required") unless ids.is_a?(Array) && ids.any?
+
+        BoardArrangement.new(column: params[:column], moved_id: params[:moved_id], issue_ids: ids).save!
+        render json: { card: render_card(params[:moved_id].to_i) }
+      rescue ArgumentError, ActiveRecord::RecordInvalid, ActiveRecord::RecordNotFound => error
+        render_json_error(error.message)
+      end
+
+      def update_form
+        issue = Issue.find(params[:issue_id])
+        if params[:unpin].present?
+          BoardArrangement.unpin!(issue)
+        else
+          move_to_end(issue, params[:column].to_s)
+        end
+        redirect_to board_path, notice: t("shiplog.admin.board.updated")
+      rescue ArgumentError, ActiveRecord::RecordInvalid, ActiveRecord::RecordNotFound => error
+        redirect_to board_path, alert: error.message
+      end
+
+      def move_to_end(issue, column)
+        raise ArgumentError, "Unknown column: #{column.inspect}" unless Issue::COLUMNS.include?(column)
+
+        ids = Roadmap.new(published_only: false).columns.fetch(column).map { |item| item.issue.id } - [ issue.id ]
+        BoardArrangement.new(column:, moved_id: issue.id, issue_ids: ids + [ issue.id ]).save!
+      end
+
+      # The same partial as a full page load, so the badges, select and Unpin
+      # button the script swaps in can't drift from what a reload would show.
+      def render_card(issue_id)
+        item = Roadmap.new(published_only: false).items.find { |candidate| candidate.issue.id == issue_id }
+        render_to_string(partial: "shiplog/admin/boards/card", formats: :html, locals: { item: })
+      end
+
+      def render_json_error(message)
+        render json: { error: message }, status: :unprocessable_content
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/approvals_controller.rb

@@ -0,0 +1,15 @@
+module Shiplog
+  module Admin
+    module Entries
+      class ApprovalsController < ApplicationController
+        def create
+          entry = Entry.find(params[:entry_id])
+          entry.approve!(by: current_admin_name)
+          redirect_to root_path, notice: t("shiplog.admin.entries.approved")
+        rescue ActiveRecord::RecordInvalid => error
+          redirect_to edit_entry_path(entry), alert: error.record.errors.full_messages.to_sentence
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/discards_controller.rb

@@ -0,0 +1,25 @@
+module Shiplog
+  module Admin
+    module Entries
+      class DiscardsController < ApplicationController
+        before_action :set_entry
+
+        def create
+          @entry.discard!(reason: params[:reason].to_s.strip.presence)
+          redirect_to root_path, notice: t("shiplog.admin.entries.discarded")
+        end
+
+        def destroy
+          @entry.restore!
+          redirect_to root_path, notice: t("shiplog.admin.entries.restored")
+        end
+
+        private
+
+        def set_entry
+          @entry = Entry.find(params[:entry_id])
+        end
+      end
+    end
+  end
+end

data/app/controllers/shiplog/admin/entries/rewrites_controller.rb

@@ -0,0 +1,13 @@
+module Shiplog
+  module Admin
+    module Entries
+      class RewritesController < ApplicationController
+        def create
+          entry = Entry.find(params[:entry_id])
+          RewriteEntryJob.perform_later(entry.id, force: true)
+          redirect_to edit_entry_path(entry), notice: t("shiplog.admin.entries.rewrite_queued")
+        end
+      end
+    end
+  end
+end