Shipseal

For your agent

You were never going to read all this.

Fair enough. Copy a prompt, paste it into Claude Code, Cursor, Copilot or whatever is typing for you today, and it will wire Shipseal into your repo properly. The prompts below tell it where the real docs are and which mistakes to avoid, so it checks instead of guessing.

Humans are also allowed here. The quick start takes about four minutes.

Set it up

paste into any agent
# Task
Add Shipseal to this repository so publishing a GitHub release automatically generates and
attaches social images.

# Context
Shipseal is an open source CLI and composite GitHub Action.
Docs: https://shipseal.dev  Machine readable: https://shipseal.dev/llms.txt
Package: shipseal on npm, Node 22+, MIT. Renders with Takumi, no browser and no image model.

# Steps
1. Run `npx shipseal@latest init --yes` at the repository root. It detects the brand
   (name, tagline, colours, logo, fonts) and writes .shipseal/brand.json and
   .shipseal/config.json. Commit both.
2. Open .shipseal/brand.json and check the colours. Any colour it could not detect is
   reported as a built-in default in the init output, so fix those by hand.
3. Add .github/workflows/shipseal.yml:

   name: Shipseal
   on:
     release:
       types: [published]
   permissions:
     contents: write
   jobs:
     visuals:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
           with:
             fetch-depth: 0
         - uses: akii09/shipseal@v0.0.6
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

4. Add .shipseal/output/ to .gitignore.
5. Verify locally with `npx shipseal@latest release --dry-run`, which prints the facts it
   collected without rendering anything.

# Constraints
- fetch-depth: 0 is required. Without full history and tags the release facts are incomplete.
- Do not invent values in brand.json. If a colour is not found in the project, leave the
  default in place and tell me which ones need my attention.
- Do not add an image generation dependency, and do not add a headless browser. Shipseal is
  deterministic on purpose.
- Do not edit files under .shipseal/output. They are generated.

# Done when
- .shipseal/brand.json and .shipseal/config.json exist and are committed.
- The workflow file exists with fetch-depth: 0 and contents: write.
- `npx shipseal@latest release --dry-run` prints facts with no error.
- You have told me every colour that fell back to a built-in default.

Something looks wrong

debugging
# Task
A Shipseal card came out wrong. Diagnose it from evidence, not from guesses.

# Gather evidence first, change nothing yet
1. Run `npx shipseal@latest doctor`. It checks Node, git, a shallow clone, brand.json,
   fonts, the logo and the renderer.
2. Run `npx shipseal@latest release --dry-run --json`. This prints every collected fact
   with its provenance and renders nothing.
3. Read .shipseal/output/<tag>/manifest.json. Every file, fact, computed value, warning and
   missing fact is listed there.

Read these before changing anything:
- A wrong number is a source problem, never a template problem. Find the fact in the
  manifest and check its `ref`.
- A "fit-warning" means text was shrunk or truncated. Shorten the copy rather than widening
  the template.
- A missing element is listed under `missing` with the fact that caused it.
- Wrong colours mean detection failed. The init output names every colour that fell back to
  a built-in default.

Facts an agent needs

The short version

Package
shipseal on npm, Node 22 or newer, MIT
Action
akii09/shipseal@v0.0.6, composite, needs fetch-depth: 0
Commands
init, release, milestone, bench, doctor
Config
.shipseal/brand.json and .shipseal/config.json
Output
.shipseal/output/<event-id>/ plus manifest.json
Rendering
Takumi. No headless browser, no image model

Machine readable: llms.txt, which agents that support it read instead of scraping this page. An MCP server is not available yet, so point your agent at these prompts for now.

If your repo has an AGENTS.md

Drop this in

## Release visuals

This repo uses Shipseal (https://shipseal.dev) to generate release images.

- Brand config lives in .shipseal/brand.json. Edit it rather than hard-coding colours.
- Never put a number on a card by hand. Numbers come from sources with provenance and
  land in manifest.json.
- After changing a template or the brand, run `npx shipseal@latest release --dry-run`
  and read the facts before rendering.
- .shipseal/output/ is generated. Do not commit it.