# paper-signal

Adopt this skill: https://proskills.md/skills/other/jiahuiqu17-paper-signal-skills-paper-signal

Page: https://proskills.md/skills/other/jiahuiqu17-paper-signal-skills-paper-signal
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/paper-signal/SKILL.md
size: 8016
upstream: https://github.com/jiahuiqu17/paper-signal/blob/main/skills/paper-signal/SKILL.md

````text
---
name: paper-signal
description: >-
  Plan, art-direct, generate, edit, and quality-check tactile minimal-zine bitmap imagery from almost any subject: landscapes, portraits, objects, products, architecture, interiors, existing photographs, moods, article ideas, cultural essays, data, reviews, and social-media card series. Use for 小红书图片, Instagram carousels, poetic posters, editorial covers, photo restyling, visual essays, evidence-aware explainers, or any request for aged paper, photocopy, risograph, letterpress, sparse type, and restrained single-ink character. Routes the subject before choosing composition, preserves identity and factual content when editing, saves reproducible prompts, invokes the runtime-native image generator, and audits the real raster output. Do not use for glossy commercial ads, deterministic UI/vector assets, or exact diagram rendering.
---

# Paper Signal

Turn a subject or source into a complete visual production: understand it, choose a subject-aware minimal-zine composition, save the final prompt, render the bitmap, and judge the actual image rather than the intention.

## Route the job

1. Read `manifest.yaml`.
2. Read every file listed under `always_load`.
3. Select one delivery route:
   - `single-card` — one poster, cover, landscape treatment, portrait, object plate, or concept image.
   - `restyle-existing` — one or more supplied images are edit targets.
   - `new-series` — a social carousel, visual essay, story sequence, or evidence-led card set.
4. Select one subject route from `references/subject-routing.md` before choosing a layout.
5. Read only the route-specific and on-demand references needed for the job.
6. State the detected delivery route, subject route, and intended deliverables in one short user-facing line before production.

Default to `single-card` for a theme, sentence, scene, person, place, object, or one supplied photo. Default to `new-series` only when the user asks for several images or supplies content that clearly needs a sequence. Use `restyle-existing` when preservation of an existing image is the primary goal.

## Non-negotiable contract

- Preserve the subject before styling it. A landscape must still feel spatial, a portrait must retain identity, and a product or object must keep its defining form.
- Preserve factual and semantic invariants when editing. Never invent or silently alter text, numbers, labels, identity, architecture, product features, or scene-defining details.
- Use `minimal-zine-standard` as a material kernel, not a universal template. Choose an adaptive composition mode; do not force every subject into one tiny central data cluster.
- Build texture from one plausible reproduction process. Do not simulate quality by piling random scratches, tape, coffee stains, and generic grunge onto a clean design.
- Use real language or intentional abstraction. Never add faux Japanese/Korean characters, fake archival codes, fake coordinates, or meaningless pseudo-text to manufacture atmosphere.
- Keep public source labels hidden by default while retaining provenance internally when facts or licensed material are involved.
- Separate truth, interpretation, and voice. Never invent a rating, quote, review consensus, first-hand experience, or source.
- Save the exact final prompt to `prompts/NN-{role}-{slug}.md` before generation.
- Use a runtime-native raster image tool. In Codex, use the built-in `imagegen` skill/tool; do not substitute SVG, HTML, canvas, or programmatic poster rendering.
- Never repair generated text by painting over the bitmap. Reduce text, correct the prompt, and regenerate to a versioned output.
- Preserve user files and generated candidates. Never overwrite an existing artifact without a versioned sibling or timestamped backup.

## Production workflow

### 1. Resolve the brief

Extract the intended use, subject, mood, audience, output count, aspect ratio, exact visible text, edit invariants, reference-image roles, and any factual or rights constraints.

Use these defaults when the request leaves them open:

- delivery route: `single-card`
- subject route: infer from `references/subject-routing.md`
- aspect ratio: preserve the edit target; otherwise `3:4` for social cards and `3:5` for standalone posters
- visible text: one short phrase or none
- public source labels: hidden
- preset: `minimal-zine-standard`
- anchor hue: derive from the subject; cobalt is the fallback

Load the first available preference file, if present:

1. `.paper-signal/PREFERENCES.md`
2. `${XDG_CONFIG_HOME:-$HOME/.config}/paper-signal/PREFERENCES.md`

When a file exists, read `references/preferences.md` and apply its contract. Preferences refine the brief but never override the current request.

### 2. Inspect and classify inputs

For each image, label it `edit-target`, `style-reference`, `content-reference`, or `series-anchor`. Inspect local images with `view_image` before editing or using them for detailed art direction.

For an existing photo, record the subject, crop, horizon or pose, identity, light, key colors, text, and protected details. For a new image, extract one imageable core rather than illustrating every idea.

### 3. Choose subject and composition modes

Read `references/subject-routing.md`, then apply `references/visual-language.md` and select a preset from `references/presets.md`.

Choose one composition mode that serves the subject:

- `airy-fragment`
- `photo-window`
- `panorama-strip`
- `dual-frame`
- `specimen-plate`
- `portrait-archive`
- `type-object`

Lock paper family, reproduction process, type character, anchor hue, and texture intensity. Let image scale, crop, and negative space adapt to the selected mode.

### 4. Add editorial structure only when needed

For a series, read `references/content-architecture.md` and plan the swipe rhythm before styling. For facts, reviews, data, rankings, or source documents, create `evidence.json` using `references/evidence-ledger.md`. For personal sharing or recommendation copy, apply `references/human-voice.md`.

Do not make a single landscape, portrait, object, or mood poster carry a social-card evidence workflow it does not need.

### 5. Create a reproducible project

For a project that needs an artifact trail, run:

```bash
python scripts/init_project.py <topic-slug> --path <parent-directory> --cards <count> \
  --subject <subject-route> --composition <composition-mode>
```

Use a 2-5 word lowercase kebab-case slug. Create a versioned sibling when the directory exists. Follow `references/project-schema.md`.

### 6. Compile and save prompts

Read `references/prompt-compiler.md`. Save only the compact final image prompt that will reach the raster model. Use four paragraphs:

1. canvas, paper field, adaptive image geometry, and protected crop/safe zones
2. subject, spatial or identity invariants, and one physical image treatment
3. exact sparse text, type behaviour, anchor hue/form, and valid print defects
4. emotional temperature, flat-material finish, and targeted hard avoids

When editing, repeat the preservation clause in every prompt. Keep text short enough for image generation.

### 7. Confirm once, then render

Before rendering, show the route, subject route, composition mode, preset, hue, output count, edit invariants, and output directory. Ask for confirmation unless the user explicitly requested direct generation or default execution.

Then:

1. Generate a single image without an unnecessary series reference.
2. For a series, accept card 1 as the material anchor before generating later cards.
3. Generate each distinct image with a distinct call; use the accepted anchor as a style reference when supported.
4. Keep batches to four or fewer calls.
5. Inspect every result at full size and thumbnail size.
6. Retry a failed image once with one targeted correction.
7. Copy selected project-bound outputs into `outputs/` with stable filenames.

### 8. Audit and deliver

Apply `references/quality-contract.md`, then run the proje
````

## File: README.md
upstream: https://github.com/jiahuiqu17/paper-signal/blob/main/README.md

````text
# Paper Signal Studio

**Turn photos, ideas, and research into beautiful editorial visuals with Codex or Claude Code.**

<table>
  <tr>
    <td width="50%"><a href="examples/edinburgh-field-studies/outputs/01-study-old-town-after-rain.png"><img src="assets/gallery/01-study-old-town-after-rain.webp" alt="Old Town after rain, cyanotype panorama" /></a></td>
    <td width="50%"><a href="examples/edinburgh-field-studies/outputs/02-study-arthurs-seat-low-cloud.png"><img src="assets/gallery/02-study-arthurs-seat-low-cloud.webp" alt="Arthur's Seat in low cloud, dual frame" /></a></td>
  </tr>
  <tr>
    <td width="50%"><a href="examples/edinburgh-field-studies/outputs/03-study-leith-last-light.png"><img src="assets/gallery/03-study-leith-last-light.webp" alt="Leith at last light, vermilion photo window" /></a></td>
    <td width="50%"><a href="examples/edinburgh-field-studies/outputs/04-study-stone-light-close.png"><img src="assets/gallery/04-study-stone-light-close.webp" alt="Edinburgh stone and light, specimen plate" /></a></td>
  </tr>
</table>

Made with one shared paper-and-ink system and four compositions chosen for the subject. Click any image for the full result.

## Quick start

```bash
npx skills add jiahuiqu17/paper-signal
```

**Codex Desktop: end-to-end verified · Claude Code: Skill-compatible · Agent Skills · MIT**

Then open a fresh task and ask:

```text
Use $paper-signal-art-director to restyle this photo as a tactile minimal-zine
poster. Preserve the subject, save the final prompt, and inspect the bitmap.
```

Works as a standard Skill in Codex, Claude Code, and other compatible clients. Final image generation depends on the image tools available in your host; see the [verified support levels](#installation-and-compatibility).

[![validate](https://github.com/jiahuiqu17/paper-signal/actions/workflows/validate.yml/badge.svg)](https://github.com/jiahuiqu17/paper-signal/actions/workflows/validate.yml)
[![release](https://img.shields.io/github/v/release/jiahuiqu17/paper-signal?display_name=tag)](https://github.com/jiahuiqu17/paper-signal/releases)
[![license](https://img.shields.io/github/license/jiahuiqu17/paper-signal)](LICENSE)

[简体中文](README.zh-CN.md) · [See how it works](#why-it-is-more-than-a-style-prompt) · [Compatibility](docs/compatibility.md) · [Contributing](.github/CONTRIBUTING.md)

## Why it is more than a style prompt

The simple promise is better-looking editorial imagery. Underneath, Paper Signal protects the things a style prompt often loses:

- **the subject** — identity, architecture, object shape, crop, and exact values;
- **the visual logic** — composition follows the content instead of one template;
- **the craft** — paper, ink, halftone, type, and colour behave as one physical system;
- **the result** — the real bitmap is inspected, corrected, and saved with its prompt.

Paper Signal keeps the whole production chain inspectable:

```text
brief → protect the subject → route subject and composition → art direction
      → save the exact prompt → native raster generation → inspect the bitmap
      → targeted correction → validated project
```

For factual posts it can also keep an evidence record and write natural caption copy. For a single photograph or idea, it stays compact and focuses on the image.

## What makes it different

| Capability | Paper Signal approach |
|---|---|
| Subject integrity | Identity, horizon, silhouette, architecture, crop, and exact values are blocking constraints |
| Composition | Seven adaptive modes selected after the subject route, not one template for every topic |
| Material craft | One physical reproduction process explains grain, dot gain, ink spread, registration, and edge behaviour |
| Colour | One meaningful chromatic signal; no palette contamination for decoration's sake |
| Reproducibility | Every selected image keeps its brief, manifest, final prompt, output, and QA record |
| Social series | Sequence, caption, evidence, and per-card routing are available without burdening a single poster |
| Quality control | Automated structure checks plus full-size and phone-thumbnail visual review |

See [`docs/comparison.md`](docs/comparison.md) for a respectful scope comparison with GC Minimal Zine Poster, `baoyu-xhs-images`, Anthropic Canvas Design, and one-off prompts.

## Before / after: style without losing the subject

The four Edinburgh images remain the finished-work hero. The compact block below tests a different claim: whether a print transfer can change the material reading without replacing the person or object. Each pair shows a repository-generated fictional edit target followed by the selected Paper Signal result.

<table>
  <tr>
    <th colspan="2">Portrait · identity preservation</th>
  </tr>
  <tr>
    <td width="50%"><a href="examples/portrait-carbon-study/refs/source-portrait.png"><img src="assets/proofs/portrait-reference.webp" alt="Fictional portrait edit target" /></a><br /><sub>Before · edit target</sub></td>
    <td width="50%"><a href="examples/portrait-carbon-study/outputs/01-poster-portrait-carbon-study.png"><img src="assets/proofs/portrait-result.webp" alt="Portrait Carbon Paper Signal result" /></a><br /><sub>After · Paper Signal</sub></td>
  </tr>
  <tr>
    <th colspan="2">Object · geometry and wear preservation</th>
  </tr>
  <tr>
    <td width="50%"><a href="examples/object-specimen-study/refs/source-moka-pot.png"><img src="assets/proofs/object-reference.webp" alt="Moka pot edit target" /></a><br /><sub>Before · edit target</sub></td>
    <td width="50%"><a href="examples/object-specimen-study/outputs/01-poster-object-specimen-study.png"><img src="assets/proofs/object-result.webp" alt="Object Specimen Paper Signal result" /></a><br /><sub>After · Paper Signal</sub></td>
  </tr>
</table>

The full [`portrait`](examples/portrait-carbon-study/) and [`object`](examples/object-specimen-study/) cases include the source-generation prompt, edit target, preservation record, exact transfer prompt, manifest, selected bitmap, asset hashes, and observation-based QA. The README loads only 600 × 800 WebP previews; click any image for the full PNG.

## Installation and compatibility

### Choose a host

The Quick Start command is interactive. To target a host explicitly:

```bash
npx skills add jiahuiqu17/paper-signal --agent codex
npx skills add jiahuiqu17/paper-signal --agent claude-code
```

Select the full `paper-signal` entry point or one of the three specialist skills. The repository also contains a Codex plugin manifest at `.codex-plugin/plugin.json`.

| Host | Skill loading | Complete bitmap workflow |
|---|---|---|
| Codex Desktop | Verified | End-to-end reference runtime with image inspection and built-in ImageGen |
| Codex CLI | Verified discovery and repository tooling | Depends on the image tools configured for that session |
| Claude Code | Agent Skills-compatible; installable with the community installer | Requires an image-inspection and image-generation tool; not yet end-to-end verified here |
| Cursor and other compatible agents | Installer- and host-dependent | Depends on the host capabilities; prompt-only fallback remains available |

The short compatibility line near the top means the Skill format loads on those hosts—not that every host exposes the same image tools. Format compatibility, tool availability, and tested rendering are separate levels. See the maintained [`compatibility matrix`](docs/compatibility.md).

### Install an immutable release

Each tagged release includes a deterministic skills-only ZIP and `SHA256SUMS`. It omits the large visual examples while retaining the four skills, schemas, license, and essential documentation.

```bash
gh release download --repo jiahuiqu17/paper-signal \
  --pattern "paper-signal-skills-*.zip" --pattern SHA256SUMS
shasum -a 256 -c SHA256SUMS
unzip paper-signal-skills-v*.zip
npx skills add ./paper-signal-v*
```

### Local Codex development

Clone the repository, then link the skill folders into Codex:

```bash
````
