ship-sails-app

What this skill does

## Preamble (run first)

```bash
_VS_DIR=""
for _d in \
  "${VARA_SKILLS_DIR:-}" \
  "$HOME/.claude/skills/vara-skills" \
  ".claude/skills/vara-skills" \
  "$HOME"/.claude/plugins/cache/vara-skills/vara-skills/*; do
  if [ -n "$_d" ] && [ -f "$_d/bin/vara-skills-update-check" ]; then
    _VS_DIR="$_d"; break
  fi
done
if [ -n "$_VS_DIR" ]; then
  export VARA_SKILLS_DIR="$_VS_DIR"
  _UPD=$("$_VS_DIR/bin/vara-skills-update-check" 2>/dev/null || true)
  [ -n "$_UPD" ] && echo "$_UPD" || true
fi
```

If output shows `UPGRADE_AVAILABLE <old> <new>`: read `../vara-skills-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise ask user with 3 options, write snooze if declined). If `JUST_UPGRADED <from> <to>`: tell user "Running vara-skills v{to} (upgraded from v{from})!" and continue.

# Ship Sails App

## Role

Use this as the first stop for the provisional Sails-builder pack. Route the builder by repo state and next required artifact, then hand off to the narrower skill.

## Local Handbook

- `../../references/gear-execution-model.md`
- `../../references/gear-messaging-and-replies.md`
- `../../references/gear-gas-reservations-and-waitlist.md`
- `../../references/sails-rs-imports.md`
- `../../references/delayed-message-pattern.md`
- `../../references/sails-program-and-service-architecture.md`
- `../../references/sails-idl-client-pipeline.md`
- `../../references/sails-gtest-and-local-validation.md`
- `../../references/scale-binary-decoding-guide.md`
- `../../references/voucher-and-signless-flows.md`

## Standard Defaults

- Start with Sails for standard Vara work, not raw low-level `gstd`. Use `sails-rs 1.0.0` as the current baseline unless the target repo already pins a different version.
- In standard Sails repos, `cargo build` runs `build.rs`: program or wasm crates usually call `sails_rs::build_wasm()`, while the repo may also emit `.idl` and typed client outputs from that same build flow.
- For dedicated Rust client crates, prefer `sails-rs = { version = "...", features = ["build"] }`
  with `sails_rs::build_client::<Program>()`.
- Treat direct `sails-client-gen-v2` and `sails-idl-gen` wiring as a manual pipeline for explicitly non-standard repo layouts.
- In `#[program]`, public constructors return `Self`; name that constructor shape and the chosen state ownership pattern explicitly in planning artifacts.
- In `#[service]`, only methods tagged with `#[export]` are public Sails routes. Event-producing paths should use `emit_event`.
- Standard Vara account addresses are Substrate `SS58` addresses, not Ethereum `0x` addresses. Local tooling commonly uses Vara prefix `137`.
- Treat the program `.idl` as the source of truth. The normal JS or TS path is `sails-js` or `sails-cli` plus `GearApi`, generating outputs such as `lib.ts` and typed program or service classes. Use `parseIdl` only for an explicitly dynamic runtime path.
- For normal Sails constructor or service calls, generated clients or equivalent Sails Header-aware encoding are the default path; do not model the payload as a bare raw struct.
- If shared DTO derives or event derives start failing in a standard Sails crate, check the `#[codec(crate = sails_rs::scale_codec)]` and `#[scale_info(crate = sails_rs::scale_info)]` pattern before deeper debugging.
- Deferred work uses delayed messages measured in blocks. A program can send a delayed message to itself or another actor. If the flow needs gas to survive across blocks, use reserved gas or `ReservationId`; reservation duration is bounded and is not a value top-up.
- For delayed self-messages, use the named payload-plus-guard recipe in `../../references/delayed-message-pattern.md` instead of inventing a one-off byte layout.
- If the flow checks remaining execution budget, use `Syscall::gas_available()`.
- For gasless and signless UX patterns (vouchers, sessions, EZ-transactions), see `../../references/voucher-and-signless-flows.md`.
- For local validation, use dev accounts or user-provided `SS58` addresses, keep seed phrases and private keys out of commit-ready examples, and do not invent program IDs, voucher IDs, or account addresses.
- Check the repo's `build.rs` before inventing manual generation commands.
  Prefer this order:
  1. `sails_rs::build_client::<Program>()`
  2. explicit `sails_idl_gen::generate_idl_to_file::<Program>(...)` plus `ClientGenerator::from_idl_path(...)`
- For binary decoding questions, match the decoder to the source: generated client or `.idl` for standard Sails interface paths, `ProgramMetadata` for full state, and `state.meta.wasm` for state-function output. Use plain `Decode::<T>` only when the bytes are known to be a bare SCALE payload.

## Greenfield Bootstrap

- For a new Sails/Vara project from scratch, prefer the official template bootstrap:
  `cargo sails new <project-name>`.
- This creates the standard workspace layout with `app`, `client`, `src`, `tests`, top-level `build.rs`, and baseline Cargo wiring.
- For an existing repository, follow the repo’s current layout instead of re-bootstrapping it through the CLI template.

## Route By Situation

- Missing local Rust toolchains, Wasm targets, `cargo-sails`, or the `gear` binary: `../sails-dev-env/SKILL.md`
- No repo or greenfield workspace request: `../sails-new-app/SKILL.md`
- Existing Sails repo with feature or behavior change: `../sails-feature-workflow/SKILL.md`
- Confusion about `#[program]`, `#[service]`, state, or service boundaries: `../sails-architecture/SKILL.md`
- Need to reason about replies, delays, timeouts, reservations, or waitlist behavior: `../gear-message-execution/SKILL.md`
- Broken `build.rs`, missing IDL, or generated client drift: `../sails-idl-client/SKILL.md`
- Need to author or debug `gtest`: `../sails-gtest/SKILL.md`
- `gtest` is green and the next step is a typed live-node smoke run: `../sails-local-smoke/SKILL.md`
- Need to add a fungible token or token-backed accounting layer with awesome-sails: `../awesome-sails-vft/SKILL.md`
- Need a frontend for a Sails app (new or existing project without one): `npx create-vara-app <name> --idl <idl-path>`, then `../sails-frontend/SKILL.md` for customization
- Need to extend or repair an existing React or TypeScript frontend: `../sails-frontend/SKILL.md`
- Raw hex, reply-byte ambiguity, event decoding confusion, or metadata-vs-IDL uncertainty: `../gear-message-execution/SKILL.md`
- Building for the ethexe feature (EVM-compatible Gear programs): `../sails-ethexe-architecture/SKILL.md` (planning) or `../sails-ethexe-implementer/SKILL.md` (implementation)

## Required Artifact Chain

Keep the builder on this document chain inside `docs/plans/`:

`YYYY-MM-DD-<topic>-spec.md -> ...-architecture.md -> ...-tasks.md -> ...-gtest.md`

Use shared templates from:

- `../../assets/spec-template.md`
- `../../assets/architecture-template.md`
- `../../assets/task-plan-template.md`
- `../../assets/gtest-report-template.md`

## Routing Reminder

- Route to the new-app path when the builder is starting from scratch.
- Mention later architecture, `gtest`, and local-node validation so the builder sees the full Sails path instead of just the first step.

## Guardrails

- Treat this as a candidate first-wave catalog, not a frozen public taxonomy.
- Keep the flow standard Gear/Vara Sails only.
- If the task jumps straight to deployment or a live network without green `gtest`, redirect to testing first.