api/write_session_bootstrap.sh

#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
JSON_OUT="${1:-$ROOT/api/session_bootstrap.json}"
MD_OUT="${2:-$ROOT/api/session_bootstrap.md}"

TMP_JSON="$(mktemp)"
TMP_JSON_OUT="$(mktemp)"
TMP_MD_OUT="$(mktemp)"
TMP_JSON_CLEAN="$(mktemp)"
TMP_MD_CLEAN="$(mktemp)"
trap 'rm -f "$TMP_JSON" "$TMP_JSON_OUT" "$TMP_MD_OUT" "$TMP_JSON_CLEAN" "$TMP_MD_CLEAN"' EXIT

"$ROOT/api/build_system_context.sh" "$TMP_JSON" >/dev/null

mkdir -p "$(dirname "$JSON_OUT")" "$(dirname "$MD_OUT")"
cp "$TMP_JSON" "$TMP_JSON_OUT"

{
  echo "# Session Bootstrap"
  echo
  echo "Clean product one-liner: this is the reusable onboarding packet for a fresh agent session."
  echo
  echo "Why: one file should tell the next session where it is, what governs it, and what payloads it may emit."
  echo
  echo "## Start Here"
  echo
  echo "- Read [$JSON_OUT]($JSON_OUT) first for the machine-readable context."
  echo "- Then run \`./bin/bvtctl context\` to refresh the live view."
  echo "- Use \`./bin/bvtctl \"<question>\"\` for reasoning or \`./bin/bvtctl ask \"<question>\" [manifest]\` for bounded execution."
  echo
  echo "## Current Position"
  echo
  jq -r '
    "- Entry slice: " + .current_position.slice_id + "\n" +
    "- Default profile: " + .current_position.default_profile + "\n" +
    "- Lineage view: " + .current_position.lineage_view + "\n" +
    "- Role: " + .current_position.role
  ' "$TMP_JSON"
  echo
  echo "## System Lineage"
  echo
  jq -r '.lineage.views.operator_lineage[] | "- " + . ' "$TMP_JSON"
  echo
  echo "## Governance"
  echo
  jq -r '.policy.vsm.agent_rules[] | "- " + .' "$TMP_JSON"
  echo
  echo "## Payload Shapes"
  echo
  echo "- Turn request: \`POST /turn\` with auto-hydrated \`system_context\`, \`policy_context\`, and \`lineage_context\`."
  echo "- Turn response: lane, control vector, tensor surface, execution gate, decision brief, and \`system_context\`."
  echo "- Work manifest: bounded actions plus receipt-backed execution."
  echo
  echo "## Stable Commands"
  echo
  echo "- \`./bin/bvtctl context\`"
  echo "- \`./bin/bvtctl bootstrap-context\`"
  echo "- \`./bin/bvtctl \"summarise the current runtime\"\`"
  echo "- \`./bin/bvtctl ask \"run the demo manifest\" runtime/examples/demo_manifest.json\`"
} > "$TMP_MD_OUT"

tr -cd '\11\12\15\40-\176' < "$TMP_JSON_OUT" > "$TMP_JSON_CLEAN"
tr -cd '\11\12\15\40-\176' < "$TMP_MD_OUT" > "$TMP_MD_CLEAN"

mv "$TMP_JSON_CLEAN" "$JSON_OUT"
mv "$TMP_MD_CLEAN" "$MD_OUT"

printf '%s\n' "$JSON_OUT"
printf '%s\n' "$MD_OUT"