docs(examples): add publish-* configuration examples

Publisher configuration examples for each target:
- publish-github.yaml - GitHub Releases (foundation)
- publish-npm.yaml - npm binary wrapper
- publish-homebrew.yaml - Homebrew formula + tap
- publish-scoop.yaml - Scoop manifest (Windows)
- publish-aur.yaml - AUR PKGBUILD (Arch Linux)
- publish-chocolatey.yaml - Chocolatey NuSpec (Windows)
- publish-docker.yaml - Multi-arch containers
- publish-linuxkit.yaml - Immutable images
- publish-all.yaml - All publishers combined

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/examples/publish-all.yaml

@@ -0,0 +1,68 @@
+# Example: All Publishers Combined
+# Use in .core/release.yaml publishers array
+
+publishers:
+  # 1. GitHub - always first (others reference these artifacts)
+  - type: github
+    prerelease: false
+    draft: false
+
+  # 2. npm - JavaScript ecosystem
+  - type: npm
+    package: "@myorg/mycli"
+    access: public
+
+  # 3. Homebrew - macOS/Linux
+  - type: homebrew
+    tap: myorg/homebrew-tap
+    official:
+      enabled: true
+      output: dist/homebrew
+
+  # 4. Scoop - Windows
+  - type: scoop
+    bucket: myorg/scoop-bucket
+    official:
+      enabled: true
+      output: dist/scoop
+
+  # 5. AUR - Arch Linux
+  - type: aur
+    maintainer: "Your Name <your@email.com>"
+
+  # 6. Chocolatey - Windows enterprise
+  - type: chocolatey
+    push: false
+
+  # 7. Docker - Containers
+  - type: docker
+    registry: ghcr.io
+    image: myorg/mycli
+    platforms:
+      - linux/amd64
+      - linux/arm64
+    tags:
+      - latest
+      - "{{.Version}}"
+
+  # 8. LinuxKit - Immutable infrastructure
+  - type: linuxkit
+    config: .core/linuxkit/server.yml
+    formats:
+      - iso
+      - qcow2
+      - docker
+    platforms:
+      - linux/amd64
+      - linux/arm64
+
+# Required environment variables:
+#   GITHUB_TOKEN  - via gh CLI auth
+#   NPM_TOKEN     - npm publish
+#   CHOCOLATEY_API_KEY - if push: true
+#
+# Required tools:
+#   gh        - GitHub CLI
+#   npm       - Node package manager
+#   docker    - Docker with buildx
+#   linuxkit  - LinuxKit CLI

docs/examples/publish-aur.yaml

@@ -0,0 +1,28 @@
+# Example: AUR Publisher (Arch Linux)
+# PKGBUILD generation and AUR push
+
+type: aur
+
+# Package name (will be suffixed with -bin)
+package: mycli
+
+# Maintainer info (required by AUR)
+maintainer: "Your Name <your@email.com>"
+
+# Generate files only (don't push to AUR)
+official:
+  enabled: true
+  output: dist/aur
+
+# Environment: SSH key for aur.archlinux.org
+#
+# Usage after publish:
+#   yay -S mycli-bin
+#   # or
+#   paru -S mycli-bin
+#
+# Generated files:
+#   - PKGBUILD
+#   - .SRCINFO
+#
+# Supports both x86_64 and aarch64

docs/examples/publish-chocolatey.yaml

@@ -0,0 +1,29 @@
+# Example: Chocolatey Publisher (Windows)
+# NuSpec package for Windows enterprise
+
+type: chocolatey
+
+# Package name
+package: mycli
+
+# Push to Chocolatey community repo
+push: false  # Set true to auto-publish
+
+# Generate files only
+official:
+  enabled: true
+  output: dist/chocolatey
+
+# Environment: CHOCOLATEY_API_KEY required if push: true
+#
+# Usage after publish:
+#   choco install mycli
+#
+# Generated files:
+#   - mycli.nuspec
+#   - tools/chocolateyinstall.ps1
+#
+# Manual publish:
+#   cd dist/chocolatey
+#   choco pack
+#   choco push mycli.1.0.0.nupkg --source https://push.chocolatey.org/

docs/examples/publish-docker.yaml

@@ -0,0 +1,38 @@
+# Example: Docker Publisher
+# Multi-arch container images
+
+type: docker
+
+# Registry (default: ghcr.io)
+registry: ghcr.io
+
+# Image name
+image: myorg/myapp
+
+# Dockerfile path (default: Dockerfile)
+dockerfile: Dockerfile
+
+# Target platforms
+platforms:
+  - linux/amd64
+  - linux/arm64
+
+# Image tags
+tags:
+  - latest
+  - "{{.Version}}"
+  - "{{.Version}}-alpine"
+
+# Build arguments
+build_args:
+  VERSION: "{{.Version}}"
+  BUILD_DATE: "{{.Date}}"
+
+# Environment: Docker login to registry
+#
+# For ghcr.io:
+#   echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
+#
+# Usage after publish:
+#   docker pull ghcr.io/myorg/myapp:latest
+#   docker run ghcr.io/myorg/myapp:v1.0.0

docs/examples/publish-github.yaml

@@ -0,0 +1,14 @@
+# Example: GitHub Releases Publisher
+# Foundation publisher - others reference these artifacts
+
+type: github
+
+# Release settings
+prerelease: false
+draft: false
+
+# Auto-detect from git tag, or override
+# version: v1.0.0
+
+# Auto-detect from git remote, or specify
+# repository: myorg/myapp

docs/examples/publish-homebrew.yaml

@@ -0,0 +1,29 @@
+# Example: Homebrew Publisher
+# Formula generation and tap management
+
+type: homebrew
+
+# Your tap repository
+tap: myorg/homebrew-tap
+
+# Formula name (defaults to project name)
+formula: mycli
+
+# Generate files for official homebrew-core PR
+official:
+  enabled: true
+  output: dist/homebrew
+
+# Environment: Uses gh CLI authentication
+#
+# Usage after publish:
+#   brew tap myorg/tap
+#   brew install mycli
+#
+# Or directly:
+#   brew install myorg/tap/mycli
+#
+# Generated formula includes:
+#   - Multi-platform support (macOS Intel/ARM, Linux)
+#   - SHA256 checksums from GitHub release
+#   - Version from git tag

docs/examples/publish-linuxkit.yaml

@@ -0,0 +1,36 @@
+# Example: LinuxKit Publisher
+# Immutable Linux images uploaded to GitHub release
+
+type: linuxkit
+
+# LinuxKit YAML configuration
+config: .core/linuxkit/server.yml
+
+# Output formats
+formats:
+  - iso           # Bootable ISO (bare metal, VMs)
+  - qcow2         # QEMU/KVM/Proxmox
+  - raw           # Raw disk image
+  - vmdk          # VMware
+  - docker        # Docker-loadable tarball
+
+# Target platforms
+platforms:
+  - linux/amd64
+  - linux/arm64
+
+# Environment: linuxkit CLI installed
+#
+# Artifacts uploaded to GitHub release:
+#   - myapp-v1.0.0-amd64.iso
+#   - myapp-v1.0.0-amd64.qcow2
+#   - myapp-v1.0.0-amd64.docker.tar
+#   - myapp-v1.0.0-arm64.iso
+#   - ...
+#
+# Usage:
+#   # Boot ISO
+#   qemu-system-x86_64 -cdrom myapp-v1.0.0-amd64.iso -m 1024
+#
+#   # Load Docker image
+#   docker load < myapp-v1.0.0-amd64.docker.tar

docs/examples/publish-npm.yaml

@@ -0,0 +1,21 @@
+# Example: npm Publisher
+# Binary wrapper pattern - downloads correct platform binary on install
+
+type: npm
+
+# Package name (scoped recommended)
+package: "@myorg/mycli"
+
+# Access level
+access: public  # or "restricted" for private
+
+# Environment: NPM_TOKEN required
+#
+# Usage after publish:
+#   npm install -g @myorg/mycli
+#   npx @myorg/mycli --help
+#
+# The published package contains:
+#   - package.json
+#   - install.js (postinstall downloads binary)
+#   - bin/run.js (wrapper that executes binary)

docs/examples/publish-scoop.yaml

@@ -0,0 +1,23 @@
+# Example: Scoop Publisher (Windows)
+# JSON manifest for Windows package manager
+
+type: scoop
+
+# Your bucket repository
+bucket: myorg/scoop-bucket
+
+# Generate files for official scoop-main PR
+official:
+  enabled: true
+  output: dist/scoop
+
+# Environment: Uses gh CLI authentication
+#
+# Usage after publish:
+#   scoop bucket add myorg https://github.com/myorg/scoop-bucket
+#   scoop install mycli
+#
+# Generated manifest includes:
+#   - 64-bit and ARM64 Windows support
+#   - SHA256 checksums
+#   - Auto-update configuration