feat(run): preamble streaming + docs (Customization)

README.md

@@ -123,6 +123,27 @@ git shiplog config --interactive --emit-github-workflow
 
 ---
 
+## Customization
+
+- Preamble (run): wrap live command output with a start/end marker on TTYs.
+  - Enable per‑invocation: `git shiplog run --preamble -- …`
+  - Enable globally: `git config shiplog.preamble true` (or `SHIPLOG_PREAMBLE=1`)
+  - Defaults: Start `🚢🪵🎬`, End `🚢🪵✅` (success) / `🚢🪵❌` (failure)
+  - Override text: `SHIPLOG_PREAMBLE_START_TEXT`, `SHIPLOG_PREAMBLE_END_TEXT`, `SHIPLOG_PREAMBLE_END_TEXT_FAIL`
+
+- Confirmation glyph (after write): one‑line success indicator
+  - Default: `🚢🪵⚓️` when an anchor exists; otherwise `🚢🪵✅`
+  - Override: `SHIPLOG_CONFIRM_TEXT="…"`
+  - Suppress: `SHIPLOG_QUIET_ON_SUCCESS=1`
+
+- Auto‑push behavior
+  - Default: auto‑push is on and uses `git push --no-verify` to avoid pre‑push hooks during deployments.
+  - Disable per‑run: `--no-push` (or `SHIPLOG_AUTO_PUSH=0`); publish later with `git shiplog publish` (also uses `--no-verify`).
+
+See also: docs/reference/env.md for a complete list of environment variables and config toggles.
+
+---
+
 ## How It Works: Ref Structure
 
 Shiplog stores all its data in lightweight Git refs, separate from your main code branches.

docs/README.md

@@ -5,6 +5,7 @@
 - [Feature Guides](features)
   - [Config Wizard](features/config.md)
 - [Structured Entry Schema](reference/json-schema.md)
+- [Environment & Config Reference](reference/env.md)
 - Release Notes:
   - [v0.4.0-alpha](releases/v0.4.0-alpha.md)
   - [v0.2.1](releases/v0.2.1.md)

docs/features/command-reference.md

@@ -55,7 +55,7 @@ A concise, code-sourced reference for Shiplog commands, flags, and examples. Glo
     - Success case: `git shiplog run --service deploy --reason "Smoke test" -- env printf hi`
     - Failure case: `git shiplog run --service deploy --status-failure failed -- false`
   - Flags: `--service`, `--reason`, `--status-success`, `--status-failure`, `--ticket`, `--region`, `--cluster`, `--namespace`, `--env`, `--dry-run`.
-  - Notes: captures stdout/stderr to a temporary log that is attached as a git note (skipped if empty) and merges `{run:{...}}` into the JSON trailer via `SHIPLOG_EXTRA_JSON`. Prints a minimal confirmation after the run (default `🪵`), configurable via `SHIPLOG_CONFIRM_TEXT`. `--dry-run` prints the command that would execute and exits without running it or writing a journal entry. See `docs/features/run.md` for details.
+  - Notes: captures stdout/stderr to a temporary log that is attached as a git note (skipped if empty) and merges `{run:{...}}` into the JSON trailer via `SHIPLOG_EXTRA_JSON`. Prints a one‑line confirmation after the run (default `🚢🪵⚓️` when an anchor exists or `🚢🪵✅` otherwise); override via `SHIPLOG_CONFIRM_TEXT` or suppress with `SHIPLOG_QUIET_ON_SUCCESS=1`. Optional console preamble can be enabled with `--preamble` or `SHIPLOG_PREAMBLE=1`. `--dry-run` prints what would execute and exits without running or writing. See `docs/features/run.md`.
 
 - `ls [ENV] [LIMIT]`
   - Purpose: list recent entries.
@@ -88,7 +88,7 @@ A concise, code-sourced reference for Shiplog commands, flags, and examples. Glo
 - `publish [ENV] [--no-notes] [--policy] [--trust] [--all]`
   - Purpose: push Shiplog refs (journals/notes, and optionally policy/trust) to origin without writing a new entry.
   - Usage: `git shiplog publish` (current env), `git shiplog publish --env prod`, `git shiplog publish --all --policy`
-  - Notes: use this at the end of a deployment if you disable auto-push. Precedence for pushing: command flags > `git config shiplog.autoPush` > `SHIPLOG_AUTO_PUSH`.
+  - Notes: use this at the end of a deployment if you disable auto-push. Precedence for pushing: command flags > `git config shiplog.autoPush` > `SHIPLOG_AUTO_PUSH`. Shiplog uses `git push --no-verify` to avoid pre‑push hooks by design.
 
 - `policy [show|validate|require-signed|toggle] [--json] [--boring]`
   - Purpose: inspect/change effective policy and signing requirement.

docs/features/run.md

@@ -14,6 +14,11 @@ git shiplog run --dry-run --service deploy --reason "Smoke test" -- env printf h
 
 - `--service` is required in non-interactive mode (and strongly recommended for clarity).
 - Place the command to execute after `--`; all arguments are preserved and logged.
+ - Place the command to execute after `--`; all arguments are preserved and logged. If you need shell features (globbing, expansions like `$(...)`), pass a shell explicitly, e.g.:
+   ```bash
+   git shiplog run --service deploy -- bash -lc 'echo $(date) && run_deploy'
+   ```
+   Shiplog emits a warning when it sees literal backticks or `$()` tokens in arguments, since those are usually evaluated by your shell before Shiplog can capture them.
 - Successful executions inherit `--status-success` (default `success`); failures use `--status-failure` (default `failed`).
 
 ## Dry Run Mode (`--dry-run`)
@@ -45,10 +50,20 @@ git shiplog run --dry-run --service deploy --reason "Smoke test" -- env printf h
 
 ### Confirmation Output
 
-- After the wrapped command completes, Shiplog prints a minimal confirmation line.
-- Default: a log emoji only (`🪵`).
-- Customize with `SHIPLOG_CONFIRM_TEXT` (e.g., `> Shiplogged`, `Recorded`).
-- The previous verbose preview is suppressed to keep terminals quiet; use `git shiplog show` if you want to inspect the entry that was written.
+- After the wrapped command completes and Shiplog records the entry, it prints a one‑line confirmation.
+- Default (when not overridden): `🚢🪵⚓️` if an anchor exists for the env, otherwise `🚢🪵✅`.
+- Customize entirely with `SHIPLOG_CONFIRM_TEXT` (e.g., `> Shiplogged`).
+- Suppress with `SHIPLOG_QUIET_ON_SUCCESS=1`.
+
+### Optional Preamble
+
+- Enable a start/end preamble around the command’s live output (console only); the saved note remains unprefixed.
+- Start line defaults to `🚢🪵🎬`; end line defaults to `🚢🪵✅` (success) or `🚢🪵❌` (failure).
+- Turn on via `SHIPLOG_PREAMBLE=1` (or `git config shiplog.preamble true`), or per‑invocation with `--preamble`.
+- Customize glyphs with:
+  - `SHIPLOG_PREAMBLE_START_TEXT`
+  - `SHIPLOG_PREAMBLE_END_TEXT`
+  - `SHIPLOG_PREAMBLE_END_TEXT_FAIL`
 
 ## Exit Codes
 - Dry run
@@ -65,7 +80,10 @@ git shiplog run --dry-run --service deploy --reason "Smoke test" -- env printf h
 - `--reason <text>` — Optional free-form description.
 - `--status-success <status>` — Status recorded when the wrapped command exits 0. Default `success`.
 - `--status-failure <status>` — Status recorded when the command fails. Default `failed`.
+- `--preamble` / `--no-preamble` — Toggle the live preamble and output prefixing for this invocation (overrides env/config).
 - `--ticket <id>`, `--region <r>`, `--cluster <c>`, `--namespace <ns>` — Override standard write metadata.
+
+See also: test/29_run_preamble_and_warnings.bats for executable examples.
 - When there is no output, log attachment is skipped and `log_attached=false` is recorded in the trailer.
 - Confirmation text: set `SHIPLOG_CONFIRM_TEXT` to override the default emoji (see above).
 

docs/features/write.md

@@ -9,7 +9,8 @@ git shiplog write [ENV] \
   [--service NAME] [--status success|failed|in_progress|skipped|override|revert|finalize] \
   [--reason TEXT] [--ticket ID] \
   [--region R] [--cluster C] [--namespace NS] \
-  [--image IMG] [--tag TAG] [--run-url URL]
+  [--image IMG] [--tag TAG] [--run-url URL] \
+  [--log PATH]   # alias: --attach PATH
 
 # Non-interactive
 SHIPLOG_BORING=1 git shiplog --yes write prod --service release --reason "MVP release"
@@ -21,11 +22,12 @@ Tip (non‑interactive/CI): avoid prompts by passing required fields via flags o
 - Validates the author against the resolved allowlist and performs a signing precheck when signatures are required.
 - Prompts for service, status, change details, and artifact information. You can prefill or bypass prompts with flags (`--service`, `--reason`, etc.) or environment variables listed below.
 - Defaults the namespace to the journal environment when left blank (e.g., `prod`).
-- Generates both a human-readable header and a JSON trailer; optionally attaches NDJSON logs via `SHIPLOG_LOG`.
+- Generates both a human-readable header and a JSON trailer; optionally attaches NDJSON logs via `--log/--attach` or `SHIPLOG_LOG`.
 - Human-readable header hides missing location parts: if you only provide `env=prod`, it renders `→ prod` (no placeholders for region/cluster/namespace).
 - Accepts `--yes` to skip confirmation prompts (sets `SHIPLOG_ASSUME_YES=1`).
 - Fast-forwards the journal ref; aborts if the ref is missing or would require a force update.
-- Automatically pushes the updated journal (and attached notes) to `origin` when available; disable with `SHIPLOG_AUTO_PUSH=0` or `--no-push`.
+- Automatically pushes the updated journal (and attached notes) to the configured remote when available; disable with `SHIPLOG_AUTO_PUSH=0` or `--no-push`.
+  - Implementation detail: Shiplog uses `git push --no-verify` for these pushes to avoid triggering repository pre‑push hooks during deployments. Use `git shiplog publish` later if you prefer to push explicitly (it also uses `--no-verify`).
 
 ## Flags and Environment Overrides
 | Variable | Purpose | Accepted values | Default | Example |

docs/reference/env.md

@@ -24,6 +24,7 @@ This is a compact reference for key `SHIPLOG_*` environment variables. Most can
 - `SHIPLOG_AUTO_PUSH` — Auto-push Shiplog refs to the configured remote when available (`write`, some `setup` flows)
   - Values: `1` (default) or `0`
   - Precedence: command flags > `git config shiplog.autoPush` > `SHIPLOG_AUTO_PUSH`.
+  - Note: Shiplog invokes `git push --no-verify` for these pushes to avoid triggering pre-push hooks during deployments. Use `git shiplog publish` to push later; it also uses `--no-verify`.
 
 - `SHIPLOG_REMOTE` — Remote name shiplog commands use for fetch/publish/push operations
   - Default: `origin` (or `git config shiplog.remote` when set)
@@ -37,9 +38,22 @@ This is a compact reference for key `SHIPLOG_*` environment variables. Most can
 
 ## UX
 
-- `SHIPLOG_CONFIRM_TEXT` — Override the confirmation line printed by `git shiplog run` after a successful write.
-  - Default: the log emoji `🪵`
-  - Example: `export SHIPLOG_CONFIRM_TEXT="> Shiplogged"`
+- `SHIPLOG_PREAMBLE` — Enable a start/end preamble around `run` output (console only).
+  - Values: `1|true|yes|on` to enable; `0|false|no|off` to disable (default `0`).
+  - Git config equivalent: `git config shiplog.preamble true`
+  - Related overrides:
+    - `SHIPLOG_PREAMBLE_START_TEXT` (default: `🚢🪵🎬`)
+    - `SHIPLOG_PREAMBLE_END_TEXT` (default: `🚢🪵✅`)
+    - `SHIPLOG_PREAMBLE_END_TEXT_FAIL` (default: `🚢🪵❌`)
+  - CLI toggles for a single invocation: `git shiplog run --preamble` / `--no-preamble`.
+
+- `SHIPLOG_CONFIRM_TEXT` — Override the one-line confirmation printed after a successful entry write.
+  - Default when unset: a context-aware glyph built from `🚢🪵` and:
+    - `⚓️` if an anchor exists for the env, otherwise `✅`.
+  - Example: `export SHIPLOG_CONFIRM_TEXT="> entry recorded"`
+
+- `SHIPLOG_QUIET_ON_SUCCESS` — Suppress the success confirmation line entirely.
+  - Values: `1` to suppress; `0` (default) to print.
 
 ## Policy & Signing
 

lib/commands.sh

@@ -637,16 +637,40 @@ cmd_run() {
 
   local cmd_status run_status
   local log_attached_bool="false"
+  # Optional pretty preamble around command output (console only)
+  local preamble=0
+  case "${SHIPLOG_PREAMBLE:-$(git config --bool shiplog.preamble 2>/dev/null || echo 0)}" in
+    1|true|yes|on) preamble=1 ;;
+  esac
 
   if [ "$skip_execution" -eq 0 ]; then
     started_at="$(fmt_ts)"
     start_epoch=$(date -u +%s)
 
     if [ "$tee_output" -eq 1 ]; then
+      # Optional start preamble
+      if [ $preamble -eq 1 ]; then
+        printf '%s\n' "${SHIPLOG_PREAMBLE_START_TEXT:-🚢🪵🎬}"
+      fi
       set +e
-      "${run_argv[@]}" > >(tee -a "$log_path") 2> >(tee -a "$log_path" >&2)
+      if [ $preamble -eq 1 ]; then
+        # Prefix console output with " |  " while keeping raw logs in $log_path
+        "${run_argv[@]}" \
+          > >(tee -a "$log_path" | sed 's/^/ |  /') \
+          2> >(tee -a "$log_path" >&2 | sed 's/^/ |  /')
+      else
+        "${run_argv[@]}" > >(tee -a "$log_path") 2> >(tee -a "$log_path" >&2)
+      fi
       cmd_status=$?
       set -e
+      # Optional end preamble reflecting command success/failure
+      if [ $preamble -eq 1 ]; then
+        if [ $cmd_status -eq 0 ]; then
+          printf '%s\n' "${SHIPLOG_PREAMBLE_END_TEXT:-🚢🪵✅}"
+        else
+          printf '%s\n' "${SHIPLOG_PREAMBLE_END_TEXT_FAIL:-🚢🪵❌}"
+        fi
+      fi
     else
       set +e
       "${run_argv[@]}" >"$log_path" 2>&1