# Usage: curl -sSL https://dom.vin/portdown | bash -s <install-path>
# <install-path> is the directory where the file should land.

set -euo pipefail
[ -z "${1:-}" ] && {
  echo "install requires a path: curl -sSL https://dom.vin/portdown | bash -s <install-path>" >&2
  exit 1
}
TARGET="$1"
mkdir -p "$TARGET"
DEST="$TARGET/skill.folded.md"

cat > "$DEST" <<'PORTDOWN_853241C2'
<!--
This is a `.folded.md` archive — a directory packed into one markdown
file. The markers below are load-bearing; don't edit them directly.

To unpack:
  1. If your environment lacks bash (Read/Edit only, no shell), stop
     and tell the user this needs `fold` from https://dom.vin/fold —
     you can't proceed yourself.
  2. Install fold once:
       curl -sSL https://dom.vin/fold | bash -s <install-path>
     then unpack:
       <install-path>/scripts/unfold <this-file>
-->

---
fold: true
marker: fb7aff
at: 2026-05-01T18:54:18Z
root: skill
---

<!--fold:fb7aff@file path="SKILL.md" mode="644"-->
---
name: portdown
description: >
  Make a markdown file self-installing — a single file that reads as
  markdown when pasted to an agent and lays itself down on disk when
  piped to bash with an install path. Optional pre/post bash scripts
  run around the write. Use when the user wants to publish a markdown
  artifact at a URL that can be installed with
  `curl ... | bash -s <path>`, bootstrap a skill or context bundle
  from a URL, or extend portdown with custom unpacking logic (e.g.
  fold uses it with a post script that unfolds the artifact into a
  directory).
---

# portdown

Portable markdown that ports itself down to disk. Take a markdown file, optionally add a pre and/or post bash script, get back a self-installing polyglot:

```
portdown <file.md> [--pre <script>] [--post <script>] [--url <url>] [-o <output>]
```

The output is a markdown file that:

- **Reads as markdown** when pasted to an agent — the bash machinery is at the top in `#` comments + a heredoc; the agent sees the install line and the embedded content.
- **Runs as bash** when piped to bash with a path — writes the markdown to `<install-path>/<basename>`, runs optional pre and post scripts around the write.

## Contract

The output takes the install path as a positional argument:

```
curl -sSL <url> | bash -s <install-path>
```

`<install-path>` is whatever the caller decides — typically the agent's skills directory plus a subdirectory for this artifact (e.g. `$CLAUDE_SKILLS_DIR/fold`). No env-var convention to learn, no fallbacks, no detection. If no path is given, the polyglot exits with a message that quotes the same usage line — so the error IS the doc.

Inside the pre/post scripts, `$TARGET` and `$DEST` (= `$TARGET/<basename>`) are in scope.

## When to reach for it

- The user wants to host a markdown artifact at a URL with `curl | bash` install.
- A skill, prompt, or context bundle should bootstrap from a single URL.
- A tool wants to wrap its own artifacts (e.g. fold portdowns a `.folded.md` with a post script that unfolds it into a directory).

## What it doesn't do

- Doesn't pack directories — it takes a single file. To ship a directory, fold it first into a single `.folded.md` and portdown that with a post script that unfolds.
- Doesn't choose the install path — the caller passes it as `$1`.
- Doesn't symlink to PATH or modify anything outside `<install-path>`. The install is contained.
- Doesn't host anything — it just produces the polyglot. Hosting is your job (e.g. drop the output in `prompts/` of a dom.vin-style repo).
<!--fold:fb7aff@file path="scripts/portdown" mode="755"-->
#!/usr/bin/env bash
# portdown — make a markdown file self-installing.
#
# Wraps a markdown file with bash so `curl <url> | bash -s <install-path>`
# writes the markdown to <install-path>/<basename>. Optional pre/post
# bash scripts run before/after the write (with $TARGET and $DEST in
# scope).
#
# Usage:
#   portdown <markdown-file> [--pre <script>] [--post <script>]
#                            [--url <url>] [-o <output>]
#
# Inputs:
#   <markdown-file>   the markdown content to embed
#   --pre  <script>   bash to run before writing the file
#   --post <script>   bash to run after writing the file
#   --url  <url>      URL the polyglot will be served from (used in
#                     the header + error message so they're copy-paste
#                     ready). Defaults to "<url>".
#   -o, --output      output file (default: stdout)
#
# The wrapped output expects the install path as $1 (positional), e.g.
# `curl ... | bash -s ~/.claude/skills/fold`. Exits with a message
# pointing to the same usage line if no path is given.

set -euo pipefail

die() { echo "portdown: $*" >&2; exit 1; }

usage() {
  sed -n '2,24p' "$0" | sed 's/^# //; s/^#//'
}

main() {
  local SRC="" PRE="" POST="" OUT="" URL="<url>"
  while [ $# -gt 0 ]; do
    case "$1" in
      --pre)       PRE="$2"; shift 2 ;;
      --post)      POST="$2"; shift 2 ;;
      --url)       URL="$2"; shift 2 ;;
      -o|--output) OUT="$2"; shift 2 ;;
      -h|--help)   usage; exit 0 ;;
      *)
        if [ -z "$SRC" ]; then SRC="$1"; shift
        else die "unexpected arg: $1"; fi
        ;;
    esac
  done
  [ -z "$SRC" ] && { usage >&2; exit 1; }
  [ ! -f "$SRC" ]  && die "not a file: $SRC"
  [ -n "$PRE"  ] && [ ! -f "$PRE"  ] && die "not a file: $PRE"
  [ -n "$POST" ] && [ ! -f "$POST" ] && die "not a file: $POST"

  local BASENAME SENTINEL
  BASENAME=$(basename "$SRC")
  SENTINEL="PORTDOWN_$(LC_ALL=C dd if=/dev/urandom bs=256 count=1 2>/dev/null | tr -dc '0-9A-F' | head -c 8)"

  if grep -qF "$SENTINEL" "$SRC"; then
    die "sentinel collision in markdown content (cosmic luck — re-run)"
  fi

  if [ -n "$OUT" ]; then exec > "$OUT"; fi

  cat <<HEADER
# Usage: curl -sSL $URL | bash -s <install-path>
# <install-path> is the directory where the file should land.

set -euo pipefail
[ -z "\${1:-}" ] && {
  echo "install requires a path: curl -sSL $URL | bash -s <install-path>" >&2
  exit 1
}
TARGET="\$1"
mkdir -p "\$TARGET"
DEST="\$TARGET/$BASENAME"

HEADER

  if [ -n "$PRE" ]; then
    echo "# ── pre ──"
    cat "$PRE"
    [ -n "$(tail -c 1 "$PRE" 2>/dev/null)" ] && echo
    echo
  fi

  echo "cat > \"\$DEST\" <<'$SENTINEL'"
  cat "$SRC"
  [ -n "$(tail -c 1 "$SRC" 2>/dev/null)" ] && echo
  echo "$SENTINEL"
  echo

  if [ -n "$POST" ]; then
    echo "# ── post ──"
    cat "$POST"
    [ -n "$(tail -c 1 "$POST" 2>/dev/null)" ] && echo
    echo
  else
    # No post script — emit a minimal success line so a bare drop
    # gives the user feedback. With a post script, the post is
    # responsible for its own messaging.
    echo "echo \"✓ $BASENAME → \$DEST\" >&2"
  fi
}

main "$@"
<!--fold:fb7aff@end-->
PORTDOWN_853241C2

# ── post ──
# GENERATED by playground/portdown-publish/build.sh — do not edit.
# Inlines playground/fold/scripts/unfold so the bootstrap can
# extract before any unfold is on disk.

#!/usr/bin/env bash
# unfold — unpack a .folded.md file back into a directory
#
# Usage:
#   unfold <file.folded.md>             unpack → <basename>/
#   unfold <file.folded.md> -o <dir>    unpack → <dir>/
#   unfold --help                     this help

set -euo pipefail

MAX_BYTES_DEFAULT=5242880   # 5 MB — symmetric with fold's cap

usage() {
  cat <<EOF
unfold — unpack a .folded.md file back into a directory

Usage:
  unfold <file.folded.md>                 unpack → <parent>/<basename>/
  unfold <file.folded.md> <dir>           unpack → <dir>/   (positional)
  unfold <file.folded.md> -o <dir>        unpack → <dir>/   (flag form)
  unfold <file.folded.md> -f              overwrite existing destination
  unfold <file.folded.md> --max-size <n>  override the default size cap
                                          (current default: ${MAX_BYTES_DEFAULT} bytes)
  unfold --help                           this help
EOF
}

main() {
  local SRC="" OUT="" FORCE=0 MAX_BYTES="$MAX_BYTES_DEFAULT"
  while [ $# -gt 0 ]; do
    case "$1" in
      -o|--output)  OUT="$2"; shift 2 ;;
      -f|--force)   FORCE=1; shift ;;
      --max-size)   MAX_BYTES="$2"; shift 2 ;;
      -h|--help) usage; exit 0 ;;
      *)
        if [ -z "$SRC" ]; then SRC="$1"; shift
        elif [ -z "$OUT" ]; then OUT="$1"; shift
        else echo "unfold: unexpected arg: $1" >&2; exit 1; fi
        ;;
    esac
  done
  [ -z "$SRC" ] && { usage >&2; exit 1; }
  [ ! -f "$SRC" ] && { echo "unfold: not a file: $SRC" >&2; exit 1; }

  local SRC_SIZE
  SRC_SIZE=$(stat -c "%s" "$SRC" 2>/dev/null) \
    || SRC_SIZE=$(stat -f "%z" "$SRC" 2>/dev/null) \
    || SRC_SIZE=0
  if [ "$SRC_SIZE" -gt "$MAX_BYTES" ]; then
    echo "unfold: refusing — input ${SRC_SIZE} bytes exceeds ${MAX_BYTES} cap. Pass --max-size <bytes> to override." >&2
    exit 1
  fi

  local MARKER
  MARKER=$(awk '
    /^---$/ { f++; if (f==2) exit; next }
    f==1 && /^marker:[[:space:]]/ { sub(/^marker:[[:space:]]+/, ""); print; exit }
  ' "$SRC")
  [ -z "$MARKER" ] && { echo "unfold: no 'marker:' in frontmatter — not a .folded.md artifact" >&2; exit 1; }

  if [ -z "$OUT" ]; then
    local base parent
    base=$(basename "$SRC")
    parent=$(cd "$(dirname "$SRC")" && pwd)
    OUT="${base%.folded.md}"
    [ "$OUT" = "$base" ] && OUT="${base%.*}"
    OUT="${parent}/${OUT}"
  fi

  if [ -e "$OUT" ] && [ "$FORCE" = "0" ]; then
    echo "unfold: refusing to write into existing $OUT — pass -f to overwrite, or pick a different destination: unfold $SRC <new-dir>" >&2
    exit 1
  fi

  mkdir -p "$OUT"
  OUT=$(cd "$OUT" && pwd)

  awk -v marker="$MARKER" -v outdir="$OUT" '
    BEGIN {
      # Match a fold @file marker: capture path, optionally a mode= attribute.
      file_re = "^<!--fold:" marker "@file path=\"[^\"]+\"( mode=\"[0-7]+\")?-->$"
      end_re  = "^<!--fold:" marker "@end-->$"
    }
    $0 ~ end_re { if (current) close(current); exit }
    $0 ~ file_re {
      if (current) close(current)
      # Extract path (between path=" and the closing ")
      path = $0
      sub(/^<!--fold:[^@]+@file path="/, "", path)
      sub(/".*$/, "", path)
      # Extract mode if present
      mode = ""
      if (match($0, /mode="[0-7]+"/)) {
        mode = substr($0, RSTART+6, RLENGTH-7)
      }
      current = outdir "/" path
      dir = current; sub(/\/[^\/]*$/, "", dir)
      if (dir != current) system("mkdir -p \"" dir "\"")
      printf "" > current
      pending_mode[current] = mode
      next
    }
    current { print >> current }
    END {
      for (f in pending_mode) {
        if (pending_mode[f] != "") {
          system("chmod " pending_mode[f] " \"" f "\"")
        }
      }
    }
  ' "$SRC"

  local COUNT
  COUNT=$(find "$OUT" -type f | wc -l | tr -d ' ')
  echo "✓ unfolded $COUNT files from $SRC → $OUT/" >&2
}


# ── install bootstrap wrapper ──
main "$DEST" "$TARGET" -f --max-size 10485760

rm -f "$DEST"
echo "✓ portdown skill installed at $TARGET" >&2
cat "$TARGET/SKILL.md" >&2