@lovehlmmm/primekit 1.0.0

package/skills/shader/references/glsl-shapes-sdf-circles-rectangles-polar-distance-fields.md

@@ -0,0 +1,106 @@
+# Shapes in GLSL
+
+Drawing shapes using Signed Distance Fields (SDF) and distance calculations.
+
+## Distance Fields Concept
+
+SDF returns distance from any point to shape edge:
+- **Negative**: Inside shape
+- **Zero**: On edge
+- **Positive**: Outside shape
+
+## Circle
+
+```glsl
+// Basic circle
+float circle(vec2 st, vec2 center, float radius) {
+    float d = distance(st, center);
+    return 1.0 - step(radius, d);
+}
+
+// Smooth edge circle
+float circleSDF(vec2 st, vec2 center, float radius) {
+    return length(st - center) - radius;
+}
+
+// Usage
+float d = circleSDF(st, vec2(0.5), 0.3);
+vec3 color = vec3(1.0 - smoothstep(0.0, 0.01, d));
+```
+
+## Rectangle
+
+```glsl
+// Basic rectangle
+float rect(vec2 st, vec2 pos, vec2 size) {
+    vec2 bl = step(pos, st);
+    vec2 tr = step(1.0 - pos - size, 1.0 - st);
+    return bl.x * bl.y * tr.x * tr.y;
+}
+
+// Rectangle SDF
+float rectSDF(vec2 st, vec2 center, vec2 size) {
+    vec2 d = abs(st - center) - size * 0.5;
+    return length(max(d, 0.0)) + min(max(d.x, d.y), 0.0);
+}
+
+// Rounded rectangle SDF
+float roundedRectSDF(vec2 st, vec2 center, vec2 size, float radius) {
+    vec2 d = abs(st - center) - size * 0.5 + radius;
+    return length(max(d, 0.0)) + min(max(d.x, d.y), 0.0) - radius;
+}
+```
+
+## Line
+
+```glsl
+// Line segment SDF
+float lineSDF(vec2 p, vec2 a, vec2 b) {
+    vec2 pa = p - a;
+    vec2 ba = b - a;
+    float h = clamp(dot(pa, ba) / dot(ba, ba), 0.0, 1.0);
+    return length(pa - ba * h);
+}
+
+// Draw line with thickness
+float line(vec2 st, vec2 a, vec2 b, float thickness) {
+    float d = lineSDF(st, a, b);
+    return 1.0 - smoothstep(0.0, thickness, d);
+}
+```
+
+## Shape Outlines
+
+```glsl
+// Outline only
+float outline(float d, float thickness) {
+    return 1.0 - smoothstep(0.0, thickness, abs(d));
+}
+
+// Fill with outline
+vec3 fillWithOutline(float d, vec3 fill, vec3 stroke, float thick) {
+    float fillMask = 1.0 - smoothstep(0.0, 0.01, d);
+    float edge = 1.0 - smoothstep(0.0, thick, abs(d));
+    return mix(fill * fillMask, stroke, edge * (1.0 - fillMask));
+}
+```
+
+## 2D Transformations
+
+```glsl
+// Rotate point around center
+vec2 rotate(vec2 st, vec2 center, float angle) {
+    st -= center;
+    float c = cos(angle);
+    float s = sin(angle);
+    st = mat2(c, -s, s, c) * st;
+    return st + center;
+}
+
+// Scale from center
+vec2 scale(vec2 st, vec2 center, vec2 s) {
+    return (st - center) / s + center;
+}
+```
+
+See also: `glsl-shapes-polygon-star-polar-sdf-combinations.md`

package/skills/shader/references/glsl-shaping-functions-step-smoothstep-curves-interpolation.md

@@ -0,0 +1,141 @@
+# Shaping Functions
+
+Control value interpolation for smooth transitions and effects.
+
+## Core Functions
+
+### step(edge, x)
+Hard threshold - returns 0.0 if x < edge, else 1.0.
+
+```glsl
+float y = step(0.5, st.x);  // Black left, white right
+```
+
+### smoothstep(edge0, edge1, x)
+Smooth Hermite interpolation between edges.
+
+```glsl
+float y = smoothstep(0.2, 0.8, st.x);  // Gradual transition
+```
+
+Internally: `t = clamp((x-edge0)/(edge1-edge0), 0.0, 1.0); return t*t*(3.0-2.0*t);`
+
+### mix(a, b, t)
+Linear interpolation: `a*(1-t) + b*t`
+
+```glsl
+vec3 color = mix(colorA, colorB, st.x);  // Gradient
+```
+
+## Power Functions
+
+```glsl
+float y = pow(st.x, 5.0);     // Exponential curve
+float y = sqrt(st.x);         // Square root
+float y = exp(st.x);          // Natural exponential
+float y = log(st.x);          // Natural logarithm
+```
+
+Exponent controls curve shape:
+- `pow(x, n)` where n > 1: Slow start, fast end
+- `pow(x, n)` where n < 1: Fast start, slow end
+
+## Trigonometric Functions
+
+```glsl
+float y = sin(st.x * PI);           // Wave (0 to 1 to 0)
+float y = cos(st.x * TWO_PI);       // Full cycle
+float y = sin(st.x * 10.0 + u_time); // Animated wave
+```
+
+Normalize sin/cos from [-1,1] to [0,1]:
+```glsl
+float y = sin(x) * 0.5 + 0.5;
+```
+
+## Fractional & Modulo
+
+```glsl
+float y = fract(st.x * 5.0);  // Sawtooth wave (0 to 1 repeating)
+float y = mod(st.x, 0.2);     // Modulo, repeats every 0.2
+float y = floor(st.x * 5.0);  // Integer part (0,1,2,3,4...)
+float y = ceil(st.x * 5.0);   // Round up
+```
+
+## Absolute & Sign
+
+```glsl
+float y = abs(st.x - 0.5);    // V-shape centered at 0.5
+float y = sign(st.x - 0.5);   // -1.0, 0.0, or 1.0
+```
+
+## Clamping
+
+```glsl
+float y = clamp(x, 0.0, 1.0);         // Constrain range
+float y = min(a, b);                   // Smaller value
+float y = max(a, b);                   // Larger value
+```
+
+## Custom Shaping Curves
+
+### Polynomial smoothstep (quintic)
+```glsl
+float smootherStep(float x) {
+    return x * x * x * (x * (x * 6.0 - 15.0) + 10.0);
+}
+```
+
+### Exponential impulse
+```glsl
+float impulse(float k, float x) {
+    float h = k * x;
+    return h * exp(1.0 - h);
+}
+```
+
+### Parabola
+```glsl
+float parabola(float x, float k) {
+    return pow(4.0 * x * (1.0 - x), k);
+}
+```
+
+### Cubic pulse
+```glsl
+float cubicPulse(float c, float w, float x) {
+    x = abs(x - c);
+    if (x > w) return 0.0;
+    x /= w;
+    return 1.0 - x * x * (3.0 - 2.0 * x);
+}
+```
+
+## Combining Functions
+
+Create band with two smoothsteps:
+```glsl
+float y = smoothstep(0.2, 0.4, st.x) - smoothstep(0.6, 0.8, st.x);
+```
+
+Smooth edges on shapes:
+```glsl
+float edge = 0.01;
+float circle = smoothstep(radius + edge, radius - edge, dist);
+```
+
+## Animation Patterns
+
+```glsl
+// Oscillate 0-1
+float t = sin(u_time) * 0.5 + 0.5;
+
+// Sawtooth
+float t = fract(u_time);
+
+// Triangle wave
+float t = abs(fract(u_time) * 2.0 - 1.0);
+
+// Ping-pong
+float t = abs(mod(u_time, 2.0) - 1.0);
+```

package/skills/ship/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: pk:ship
+description: "Ship a completed branch through tests, review, commit, push, and PR creation. Supports official/beta aliases, Kongming advice, and optional reviewed merge with CI convergence."
+user-invocable: true
+when_to_use: "Invoke when a completed branch needs PR shipping workflow."
+category: dev-tools
+keywords: [ship, PR, merge, push, release, advice, kongming, review-pr]
+argument-hint: "[official|stable|main|beta|dev|next] [--both] [--advice] [--merge] [--skip-tests] [--skip-review] [--skip-journal] [--skip-docs] [--social] [--yes-post] [--yes-post-private] [--dry-run]"
+license: MIT
+metadata:
+  author: primekit
+  version: "2.3.0"
+---
+
+# Ship: Unified Ship Pipeline
+
+Single command to ship a feature branch. Fully automated — only stops for test failures, critical review issues, or major version bumps.
+
+**Inspired by:** gstack `/ship` by Garry Tan. Adapted for framework-agnostic, multi-language support.
+
+## Arguments
+
+| Flag | Effect |
+|------|--------|
+| `official`, `stable`, `main` | Normalize to `official`; ship to the detected default branch (main/master). Full pipeline with docs + journal |
+| `beta`, `dev`, `next` | Normalize to `beta`; ship to the detected development branch (dev/beta/develop). Lighter pipeline, skip docs update |
+| (none) | Auto-detect: if base branch is main/master → official, else → beta |
+| `--both` | Dual-target ship: beta stage first, then a gated stable stage (see Dual-target ship). Supersedes a positional mode token |
+| `--advice` | MUST run the ship-to-PR path under advisory-only `kongming` supervision |
+| `--merge` | After PR creation, activate `pk:review-pr <PR> --fix --reply --merge`; append `--advice` when both flags are present |
+| `--skip-tests` | Skip test step (use when tests already passed) |
+| `--skip-review` | Skip pre-landing review step |
+| `--skip-journal` | Skip journal writing step (also honors `journal.auto=false` config preference) |
+| `--skip-docs` | Skip docs update step |
+| `--social` | Opt-in: after the PR is created, compose a build-in-public journal draft and publish it to social channels (see "Build-in-public publishing" below). Off by default — never fires on a plain `/pk:ship`. |
+| `--yes-post` | Required alongside `--social` to actually publish. Without it, the social step runs in dry-run mode: renders and prints the per-channel posts, makes no API call, exits 0. |
+| `--yes-post-private` | Required alongside `--social --yes-post` when the repo is private — an explicit second opt-in for posting about non-public work. |
+| `--dry-run` | Show what would happen without executing |
+
+## Ship Mode Detection
+
+```
+Normalize one positional mode token before side effects:
+  - official | stable | main → official
+  - beta | dev | next        → beta
+  - multiple or unknown tokens, including unknown `--flags` → stop and ask; never guess
+If mode = "official" → target = main/master (auto-detect default branch)
+If mode = "beta"     → target = dev/beta/develop (auto-detect dev branch)
+If no mode token      → infer from current branch naming:
+  - feature/* hotfix/* bugfix/* → official (target main)
+  - dev/* beta/* experiment/*  → beta (target dev/beta)
+  - unclear                    → ask_user capability
+```
+
+Aliases select a canonical mode; they do not force a literal branch name.
+
+## Dual-target ship (`--both`)
+
+When `--both` is present, ship to both targets in sequence — the beta pipeline
+first, then a gated stable stage. `--both` supersedes a positional mode token;
+if one is also given, warn once and continue in dual-target mode. It composes
+with `--advice`, `--merge`, and the skip flags. With `--dry-run`, it simulates
+the beta stage only and reports the stable stage as not-simulated.
+
+Load `references/dual-stage-workflow.md` for the stage sequencing, the stable
+stage gate (beta PR exists; with `--merge`, beta CI green first), the
+promotion-convention path with its unrelated-work stop, and the completion
+contract. The stable stage never force-pushes, never bypasses branch
+protection, and never merges a promotion PR that sweeps unrelated work without
+asking.
+
+## Advisory supervision (`--advice`)
+
+When `--advice` is present, MUST spawn `kongming` to supervise the local
+ship-to-PR path. Load `../primekit-brainstorm/references/advisory-supervision.md`
+for supervisor identity, host detection, and model routing (Claude
+subscription → Fable 5; Codex → `gpt-5.6-sol` + high effort; Cursor →
+`claude-fable-5-high`). Kongming returns counsel, never code; the main agent
+remains responsible for every decision, edit, and gate.
+
+Mandatory normal-path checkpoints:
+
+- **After pre-flight, before mutation** — pass the resolved canonical mode,
+  detected target, branch/diff summary, constraints, and ask for a go/no-go plus
+  the highest risk to watch.
+- **After tests and local review, before versioning/commit/push/PR writes** —
+  pass test evidence, findings and fixes, intended PR scope, and ask whether the
+  evidence supports proceeding.
+- **When stuck or before a high-stakes decision** — pass approaches tried, the
+  exact blocker or irreversible choice, and ask for a legitimate next step.
+
+Empty/error counsel is recorded as a non-fatal advisory failure; authoritative
+ship gates still decide whether to proceed. If `--advice` is present and no
+delegation call occurs, the workflow is incomplete.
+
+When `--merge` is also present, forward `--advice` to `pk:review-pr`. That skill
+exclusively owns PR-level advisory checkpoints, review/fix/reply, merge
+readiness, and post-merge CI. Do not duplicate those steps here.
+
+`--advice` never bypasses tests, review blockers, branch protection, security
+policy, or the downstream merge-readiness gate.
+
+## When to Stop (blocking)
+
+- On target branch already → abort
+- Merge conflicts that can't be auto-resolved → stop, show conflicts
+- Test failures → stop, show failures
+- Critical review issues → ask_user capability per issue
+- Major/minor version bump needed → ask_user capability
+
+## When NOT to Stop
+
+- Uncommitted changes → always include them
+- Patch version bump → auto-decide
+- Changelog content → auto-generate
+- Commit message → auto-compose
+- No version file → skip version step silently
+- No changelog → skip changelog step silently
+
+## Pipeline
+
+```
+Step 1:  Pre-flight      → Branch check, mode detection, status, diff analysis
+Step 2:  Link Issues      → Find/create related GitHub issues
+Step 3:  Merge target     → Fetch + merge origin/<target-branch>
+Step 4:  Run tests        → Auto-detect test runner, run, check results
+Step 5:  Review           → Two-pass checklist review (critical + informational)
+Step 6:  Version bump     → Auto-detect version file, bump patch/minor
+Step 7:  Changelog        → Auto-generate from commits + diff
+Step 8:  Journal          → Write technical journal via /pk:journal (see the shared "Journal step — opt-out" contract: --skip-journal flag or journal.auto config skips)
+Step 9:  Docs update      → Update project docs via /pk:docs update (official only)
+Step 9b: Finalize plan    → primekit plan update --status completed (plan-backed; foreground, staged by Step 10)
+Step 10: Commit           → Conventional commit with version/changelog
+Step 11: Push             → git push -u origin <branch>
+Step 12: Create PR        → gh pr create with structured body + linked issues
+Step 12b: Link plan↔PR    → primekit plan update --linked-pr <n> (plan-backed; no close until merge)
+Step 13: Review + merge   → if --merge: pk:review-pr <PR> --fix --reply --merge [--advice]
+Step 14: Social publish   → if --social: after Step 13 terminal-green when merging; otherwise after the existing green-PR-check gate
+```
+
+**Detailed steps:** Load `references/ship-workflow.md`
+**Auto-detection:** Load `references/auto-detect.md`
+**PR template:** Load `references/pr-template.md`
+**Writing language:** Load `kits/core/skills/primekit-review-pr/references/writing-language.md`
+**PR body contract:** Load `kits/core/skills/primekit-review-pr/references/pr-body-contract.md`
+
+## Writing language + PR body (#1195)
+
+Before Step 12, resolve language with
+`WL_BIN=.claude/hooks/lib/writing-language.cjs
+test -f "$WL_BIN" || WL_BIN=kits/core/hooks/lib/writing-language.cjs
+node "$WL_BIN" --json` and author the PR body in
+that language. Titles stay English conventional commits. The body must include
+the seven evidence sections (plus Linked Issues / Ship Mode). Prefer honest
+`None` / `Not run` / `Unavailable` over invented narrative.
+
+## Build-in-public publishing (`--social`)
+
+Opt-in only — without `--social`, primekit-ship behavior is byte-identical to
+today. When passed, after Step 12b and any requested Step 13 review/merge,
+Step 14 composes
+a build-in-public journal draft from the PR/issue/plan context (`Why this?`
+/ `What changed` / `The tricky bit` / `What's next` / an optional thanks),
+persists it via `primekit journal create` (so every social post traces back to a
+durable journal entry), then publishes to the channels tagged
+`groups.build_in_public` in `.primekit/journal.yaml` (falling back to all
+configured channels if that group isn't defined).
+
+Guardrails (never bypassed by any flag):
+- **CI must be green.** If the PR's checks are failing, the step refuses to
+  post and explains why — the ship itself still completed.
+- **`--skip-journal` skips the whole social step**, not just the journal
+  write — a social post always requires its journal record.
+  `journal.auto = false` does **not** suppress this step: `--social` is an
+  explicit user choice, distinct from the automatic per-ship journal (Step 8).
+- **Collaborator-only signal.** Only PR review comments from
+  `COLLABORATOR`/`MEMBER`/`OWNER` associations feed the draft's "The tricky
+  bit" section — outside commenters are never quoted into a public post.
+- **Dry-run by default.** Without `--yes-post`, the step renders every
+  channel's post and stops — no API call. Re-run with `--social --yes-post`
+  to actually publish.
+- **Private-repo confirmation.** If the repository is private, `--social
+  --yes-post` alone still refuses; add `--yes-post-private` too.
+
+Full step-by-step commands: `references/release-and-social-workflow.md` (Step 14).
+
+## Token Efficiency Rules
+
+- Steps 4 (tests) and 5 (review): delegate to `tester` and `code-reviewer` subagents — don't inline
+- Steps 8 (journal) and 9 (docs): run in **background** — don't block pipeline
+- Step 2 (issues): use single `gh` command batch — avoid multiple API calls
+- Skip steps early via flags to save tokens on unnecessary work
+- Beta mode auto-skips: docs update (Step 9)
+- Capture step outputs inline — don't re-read files already in context
+
+## Quick Start
+
+User says `/pk:ship` → run full pipeline → output PR URL.
+User says `/pk:ship beta` → ship to dev branch with lighter pipeline.
+User says `/pk:ship official` → ship to main with full docs + journal.
+User says `/pk:ship stable` or `/pk:ship main` → normalize to official mode.
+User says `/pk:ship dev` or `/pk:ship next` → normalize to beta mode.
+User says `/pk:ship beta --advice --merge` → supervised ship, then reviewed merge and CI convergence.
+User says `/pk:ship --both --merge` → beta PR, reviewed beta merge to green, then the gated stable stage.
+
+## Output Format
+
+```
+✓ Pre-flight: branch feature/foo, 5 commits, +200/-50 lines (mode: official)
+✓ Issues: linked #42, created #43
+✓ Merged: origin/main (up to date)
+✓ Tests: 42 passed, 0 failed
+✓ Review: 0 critical, 2 informational
+✓ Version: 1.2.3 → 1.2.4
+✓ Changelog: updated
+✓ Journal: written (background) / skipped (opt-out via --skip-journal or journal.auto)
+✓ Docs: updated (background)
+✓ Committed: feat(auth): add OAuth2 login flow
+✓ Pushed: origin/feature/foo
+✓ PR: https://github.com/org/repo/pull/123 (linked: #42, #43)
+✓ Advice: 2 checkpoints completed / failed with reason / not requested
+✓ Review: Approve / blocked(reason) / not requested
+✓ Merge: merged / blocked(reason) / not requested
+✓ CI: green / red / pending / n/a
+```
+
+## Important Rules
+
+- **Never skip tests** (unless `--skip-tests`). If tests fail, stop.
+- **Never force push.** Regular `git push` only.
+- **Never ask for confirmation** except for critical review issues and major/minor version bumps.
+- **Auto-detect everything.** Test runner, version file, changelog format, target branch — detect from project files.
+- **Framework-agnostic.** Works for Node, Python, Rust, Go, Ruby, Java, or any project with a test command.
+- **Subagent delegation.** Use `tester` for tests, `code-reviewer` for review, `journal-writer` for journal, `docs-manager` for docs. Don't inline.
+- **Reviewed merge delegation.** `--merge` MUST activate `pk:review-pr` with `--fix --reply --merge`; `--skip-review` skips only Step 5 and never the downstream review.
+- **Fail closed on downstream state.** When `--merge` is requested, social publishing and merged/green completion claims require terminal `Verdict=Approve`, `Merge=merged`, and `CI=green`; a blocked, red, pending, or unavailable tuple stops those actions. Without `--merge`, the existing Step 14 green-PR-check gate still owns social eligibility.
+- **Dry-run has no delegation side effects.** `--dry-run` stops before `kongming`, `pk:review-pr`, or social publishing.
+- **Background tasks.** Journal and docs run in background to not block the pipeline.
+
+## Workflow Position
+
+**Typically follows:** `/pk:code-review` (ship after review passes)
+**Typically precedes:** `/pk:journal` (document after shipping)
+**Related:** `/pk:code-review` (review before shipping), `/pk:test` (test before shipping)

package/skills/ship/references/auto-detect.md

@@ -0,0 +1,103 @@
+# Auto-Detection Logic
+
+Detect test runner, version file, and changelog format from project files.
+
+## Test Runner Detection
+
+Check in order (first match wins):
+
+| Check | Test Command |
+|-------|-------------|
+| `package.json` → `scripts.test` exists | `npm test` |
+| `Makefile` → has `test:` target | `make test` |
+| `pytest.ini` OR `pyproject.toml` has `[tool.pytest]` | `pytest` |
+| `Cargo.toml` exists | `cargo test` |
+| `go.mod` exists | `go test ./...` |
+| `Gemfile` + `Rakefile` with test task | `bundle exec rake test` |
+| `build.gradle` or `build.gradle.kts` | `./gradlew test` |
+| `pom.xml` | `mvn test` |
+| `mix.exs` | `mix test` |
+| `deno.json` | `deno test` |
+
+**Detection script:**
+```bash
+if [ -f package.json ] && grep -q '"test"' package.json 2>/dev/null; then
+  echo "npm test"
+elif [ -f Makefile ] && grep -q '^test:' Makefile 2>/dev/null; then
+  echo "make test"
+elif [ -f pytest.ini ] || ([ -f pyproject.toml ] && grep -q '\[tool.pytest' pyproject.toml 2>/dev/null); then
+  echo "pytest"
+elif [ -f Cargo.toml ]; then
+  echo "cargo test"
+elif [ -f go.mod ]; then
+  echo "go test ./..."
+else
+  echo "NONE"
+fi
+```
+
+**If NONE:** Use `ask_user capability` — "No test runner detected. Options: A) Skip tests, B) Provide test command"
+
+## Version File Detection
+
+Check in order:
+
+| Check | Read Pattern |
+|-------|-------------|
+| `VERSION` file | Read as semver string |
+| `package.json` → `version` field | `jq -r .version package.json` |
+| `pyproject.toml` → `version` | grep `version = "..."` |
+| `Cargo.toml` → `version` | grep `version = "..."` |
+| `mix.exs` → `@version` | grep `@version "..."` |
+
+**If none found:** Skip version bump silently. Not all projects use versioning.
+
+**Bump logic:**
+```
+Lines changed < 50  → patch (X.Y.Z → X.Y.Z+1)
+Lines changed >= 50 → patch (safe default)
+User explicitly says "breaking" or "major feature" → ask_user capability for minor/major
+```
+
+## Changelog Detection
+
+| Check | Format |
+|-------|--------|
+| `CHANGELOG.md` | Keep-a-changelog format |
+| `CHANGES.md` | Same |
+| `HISTORY.md` | Same |
+
+**If none found:** Skip changelog silently.
+
+**Entry format:**
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New features from commits with `feat:` prefix
+
+### Changed
+- Changes from commits with `refactor:`, `perf:` prefix
+
+### Fixed
+- Bug fixes from commits with `fix:` prefix
+
+### Removed
+- Removals mentioned in commit messages
+```
+
+**Infer categories from:**
+1. Conventional commit prefixes in `git log main..HEAD --oneline`
+2. File types changed (test files → test improvements, docs → documentation)
+3. Diff content (new functions = Added, modified functions = Changed)
+
+## Main Branch Detection
+
+```bash
+git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'
+```
+
+Fallback: check if `main` or `master` exists:
+```bash
+git rev-parse --verify origin/main 2>/dev/null && echo "main" || echo "master"
+```

package/skills/ship/references/dual-stage-workflow.md

@@ -0,0 +1,86 @@
+# Dual-Target Ship (`--both`) — Stage Sequencing
+
+`--both` runs the ship pipeline against both targets in strict sequence: the
+beta stage first, then a gated stable stage. It never runs the two stages in
+parallel and never starts the stable stage on an unproven beta result.
+
+## Flag semantics
+
+- `--both` supersedes a positional mode token (`official`, `beta`, aliases).
+  If a token is also present, warn once ("--both supersedes <token>") and
+  continue in dual-target mode. Never silently drop either input.
+- Composes with `--advice`, `--merge`, `--social`, and the skip flags. Each
+  stage applies the composed flags with its own canonical mode semantics
+  (beta stage skips docs update; stable stage runs the full official pipeline).
+- `--dry-run` simulates the beta stage only and reports the stable stage as
+  `not-simulated` — a dry-run cannot know the beta merge outcome the stable
+  stage is gated on.
+
+## Stage 1: beta stage
+
+1. Run the standard pipeline (`ship-workflow.md` Steps 1-12b) with canonical
+   mode `beta` (target = detected dev/beta/develop branch).
+2. If `--merge`: run Step 13 (load `review-and-merge-workflow.md`) and converge
+   the beta PR to terminal `Verdict=Approve`, `Merge=merged`, `CI=green`.
+3. If `--social`: Step 14 fires per its own gates, scoped to the beta PR.
+4. Record the beta PR URL; it appears in the final output regardless of how far
+   the stable stage proceeds.
+
+## Stable stage gate
+
+Do not start the stable stage until:
+
+- the beta PR exists, and
+- when `--merge` was requested: only after beta CI is green for the beta merge
+  commit on the target branch. A red, pending, cancelled, or unknown beta CI
+  state blocks the stable stage; report the blocker instead of proceeding.
+
+Without `--merge`, detect the repository's stable-delivery convention:
+
+- **Promotion convention** (stable receives dev/beta promotions, not feature
+  PRs): stop after the beta stage and report the stable stage as
+  `pending beta merge` — the promotion path needs the beta merge to exist
+  first. Do not open a promotion PR from an unmerged feature branch.
+- **Direct-PR convention** (stable accepts feature PRs directly): proceed to
+  the stable stage from the same branch.
+
+## Stage 2: stable stage
+
+Pick the path from how stable normally receives changes:
+
+1. **Promotion convention** (e.g. release PR from dev into main): follow that
+   convention. Before merging a promotion PR, list the commits it carries
+   (`git log <stable>..<dev> --oneline` or the PR commit list). If it
+   sweeps unrelated work beyond this ship, stop and ask the user before
+   merging — never merge a sweeping promotion silently.
+2. **Direct-PR convention**: run the standard pipeline again with canonical
+   mode `official` (target = detected default branch) from the same feature
+   branch — Steps 1-12b, then Step 13 when `--merge` is present.
+
+Stage-2 merges go through the same Step 13 reviewed-merge flow as any other
+`--merge` ship; this reference adds no separate merge mechanism and no
+alternative to branch protection.
+
+## Completion contract
+
+The dual-target ship is complete only when:
+
+- beta PR created (and, with `--merge`, merged with green target CI), and
+- stable stage either completed the same way, or is explicitly reported as
+  `pending beta merge` / blocked with the exact reason.
+
+Output both stages explicitly:
+
+```
+✓ Beta PR:   <url> (merged/green | open | blocked: <reason>)
+✓ Stable:    <url> (merged/green | open | pending beta merge | blocked: <reason>)
+```
+
+## Hard rules
+
+- Never force-push; never direct-push a protected target branch.
+- Never bypass branch protection, required checks, or the Step 13
+  merge-readiness gate in either stage.
+- Never merge a promotion PR that sweeps unrelated work without asking.
+- A failed or blocked beta stage always ends the run with the stable stage
+  reported as skipped — never attempt stable delivery around a broken beta.