device-devtools-mcp 0.1.0

package/scripts/common/waypoint.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# waypoint.sh — name where you are, and come back to it after a rebuild.
+#
+#   waypoint.sh mark <name>
+#   waypoint.sh goto <name>
+#   waypoint.sh list
+#   waypoint.sh forget <name>
+#
+# Installing a new build puts the app back on its first screen. Walking a login
+# and three taps back to the screen you were debugging costs more than the code
+# change did, and an agent doing it from conversational memory does it
+# differently the fourth time.
+#
+# `mark` names the current position in the session journal, which every landed
+# action appends to. `goto` relaunches the app and replays the actions up to
+# that position.
+#
+# WHAT THIS IS NOT. There are no assertions here, nothing scores anything, and
+# nothing is rescued. When a step no longer resolves, goto stops and says which
+# step and what it was looking for. The fingerprint machinery was deleted
+# deliberately and this is not it wearing a different name — the answer to a
+# changed screen is snapshot.sh, which costs almost nothing.
+#
+# exit 0  done
+# exit 1  usage error
+# exit 2  nothing is marked under that name, or the mark file is unwritable
+# exit 3  the app could not be relaunched
+# exit 4  replay stopped part-way
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+CMD="${1-}"
+case "$CMD" in
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+esac
+[ -n "$CMD" ] || die "missing subcommand (usage: waypoint.sh mark <name> | goto <name> | list | forget <name>)" 1
+shift
+
+load_config
+MARKS="$(state_dir)/waypoints.json"
+[ -f "$MARKS" ] || printf '{}' > "$MARKS"
+JOURNAL="$(journal_path)"
+
+need_name() {
+  [ -n "${1-}" ] || die "waypoint.sh $CMD needs a name" 1
+  case "$1" in
+    */*|..*) die "a waypoint name must not contain '/' or start with '..': $1" 1 ;;
+  esac
+}
+
+case "$CMD" in
+  mark)
+    need_name "${1-}"
+    [ $# -eq 1 ] || die "too many arguments (usage: waypoint.sh mark <name>)" 1
+    n=0
+    [ -f "$JOURNAL" ] && n="$(wc -l < "$JOURNAL" | tr -d ' ')"
+    tmp="$MARKS.new"
+    jq --arg k "$1" --argjson v "$n" '.[$k] = $v' "$MARKS" > "$tmp" \
+      && mv "$tmp" "$MARKS" || die "could not write $MARKS" 2
+    printf 'OK waypoint "%s" — %s action(s) between the app launching and here\n' "$1" "$n"
+    ;;
+
+  forget)
+    need_name "${1-}"
+    [ $# -eq 1 ] || die "too many arguments (usage: waypoint.sh forget <name>)" 1
+    jq -e --arg k "$1" 'has($k)' "$MARKS" >/dev/null 2>&1 \
+      || die "no waypoint called '$1'" 2
+    tmp="$MARKS.new"
+    jq --arg k "$1" 'del(.[$k])' "$MARKS" > "$tmp" && mv "$tmp" "$MARKS" \
+      || die "could not write $MARKS" 2
+    printf 'OK waypoint "%s" forgotten\n' "$1"
+    ;;
+
+  list)
+    [ $# -eq 0 ] || die "waypoint.sh list takes no arguments" 1
+    if [ "$(jq -r 'length' "$MARKS")" = "0" ]; then
+      printf 'OK no waypoints yet — waypoint.sh mark <name> makes one\n'
+      exit 0
+    fi
+    jq -r 'to_entries[] | "\(.key)\t\(.value) action(s)"' "$MARKS" | sort
+    ;;
+
+  goto)
+    need_name "${1-}"
+    [ $# -eq 1 ] || die "too many arguments (usage: waypoint.sh goto <name>)" 1
+    n="$(jq -r --arg k "$1" '.[$k] // empty' "$MARKS")"
+    [ -n "$n" ] || die "no waypoint called '$1' — waypoint.sh list shows what there is" 2
+    [ -f "$JOURNAL" ] || die "the session journal is empty; there is nothing to replay" 2
+    if [ "$n" -eq 0 ]; then
+      "$DT_HOME/scripts/app.sh" relaunch >/dev/null \
+        || die "could not relaunch the app — run $(as_cmd doctor)" 3
+      printf 'OK arrived at "%s" — it was marked at the first screen, so relaunching was the whole journey\n' "$1"
+      exit 0
+    fi
+
+    "$DT_HOME/scripts/app.sh" relaunch >/dev/null \
+      || die "could not relaunch the app — run $(as_cmd doctor)" 3
+
+    # Replaying must not append to the journal it is reading, or every goto
+    # doubles the path and the second one replays the first one's replay.
+    export DEVICETOOLS_JOURNAL=/dev/null
+
+    i=0
+    while IFS= read -r line; do
+      i=$((i + 1))
+      [ "$i" -le "$n" ] || break
+      verb="$(printf '%s' "$line" | jq -r '.verb')"
+      label="$(printf '%s' "$line" | jq -r '.label')"
+      eid="$(printf '%s' "$line" | jq -r '.id')"
+      args="$(printf '%s' "$line" | jq -r '.args')"
+
+      # The recorded identifier is preferred over the recorded label: a label is
+      # application copy and gets rewritten between builds, an identifier is
+      # chosen by an engineer and rarely does. Neither is scored — if the chosen
+      # one does not resolve, this stops.
+      if   [ -n "$eid" ];   then sel="id:$eid"
+      elif [ -n "$label" ]; then sel="label:$label"
+      else                       sel="$args"
+      fi
+
+      rc=0
+      case "$verb" in
+        tap)    "$DT_HOME/scripts/tap.sh"  "$sel"  >/dev/null 2>&1 || rc=$? ;;
+        type)   "$DT_HOME/scripts/type.sh" "$args" >/dev/null 2>&1 || rc=$? ;;
+        back)   "$DT_HOME/scripts/back.sh"         >/dev/null 2>&1 || rc=$? ;;
+        scroll) "$DT_HOME/scripts/scroll.sh" $args >/dev/null 2>&1 || rc=$? ;;
+        swipe)  "$DT_HOME/scripts/swipe.sh"  $args >/dev/null 2>&1 || rc=$? ;;
+        open)   "$DT_HOME/scripts/open.sh"  "$args" >/dev/null 2>&1 || rc=$? ;;
+        *)      rc=0 ;;
+      esac
+      if [ "$rc" -ne 0 ]; then
+        die "replay stopped at step $i of $n: '$verb $sel' no longer resolves (exit $rc). The screen has changed since this path was recorded — read it with snapshot.sh and walk the rest yourself" 4
+      fi
+      printf 'REPLAY %s/%s %s %s\n' "$i" "$n" "$verb" "$sel"
+    done < "$JOURNAL"
+
+    printf 'OK arrived at "%s" after %s step(s)\n' "$1" "$n"
+    ;;
+
+  *) die "unknown subcommand '$CMD' (usage: waypoint.sh mark <name> | goto <name> | list | forget <name>)" 1 ;;
+esac

package/scripts/dispatch.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# DeviceTools — verb dispatcher.
+#
+# Every scripts/<verb>.sh is a symlink to this file. Invoked as scripts/tap.sh,
+# it resolves the configured platform and execs scripts/<platform>/tap.sh.
+#
+# Callers therefore use one stable path per verb and never name a platform, and
+# adding Android is a matter of dropping scripts/android/ into place. Symlinks
+# rather than nine near-identical wrapper files: two copies of a dispatch rule
+# is one copy too many, and nine is worse.
+
+source "$(dirname "$0")/lib.sh"
+load_config
+
+verb="$(basename "$0")"
+target="$(adapter_dir)/$verb"
+
+[ -x "$target" ] \
+  || die "verb '${verb%.sh}' is not implemented for platform '$(platform)' — expected $target" 2
+
+exec "$target" "$@"

package/scripts/flow.sh

@@ -0,0 +1,266 @@
+#!/usr/bin/env bash
+# flow.sh — a batch worth keeping, under a name.
+#
+#   flow.sh save <name> --steps '<json array>' [--description S]
+#   flow.sh run <name> [--var NAME=VALUE]... [--vars '<json>'] [--dry-run]
+#                       [--snapshot] [--logs]
+#   flow.sh <name>                             the same as `run <name>`
+#   flow.sh list
+#   flow.sh show <name>
+#   flow.sh delete <name>
+#
+# WHY A NAME
+#
+# Every flow in an application starts by logging in. Written out each time, that
+# is the same twelve steps rebuilt from scratch on every session, by a caller
+# that has to rediscover the screens to write them. `run` made those twelve
+# steps one call; this makes them one word.
+#
+# WHERE THEY LIVE, AND WHY IT IS NOT config.json
+#
+# flows/<name>.json inside the project — paths.flows_dir moves it. A flow is
+# knowledge about the app: that logging in means these steps, on these screens,
+# in this order. That belongs in the app's repository, next to the app, reviewed
+# like the code it describes, and shared with everyone working on it. In
+# config.json it would be per-machine, gitignored, and known only to whoever
+# wrote it.
+#
+# WHAT MAKES IT MORE THAN A RECORDED MACRO
+#
+# Parameters. Credentials are {{ name }} and are filled at run time from --var,
+# from DEVICETOOLS_VAR_<NAME>, or from .vars in the config. A password written
+# into the file is a password in the repository. The names a flow needs are
+# recorded when it is saved — read out of its own steps, not declared by hand —
+# and a run that cannot supply one is refused before it touches the device.
+#
+# A starting state it can check. On the app this was built against, "log in"
+# has three different routes depending on whether the device is already
+# activated, and there is no way to tell them apart except by looking. So a
+# flow's first step should be an assertion:
+#
+#   {"expect": "screen:Auth.LoginView"}
+#
+# which fails in three seconds and says which screen it is actually on, instead
+# of tapping into a screen it was not written for and producing a session's
+# worth of confident nonsense. `expect` is `wait` with a deadline that means
+# "now" — the same script, one spelling for each of the two things a caller
+# means by it.
+#
+# Composition. A step of {"flow": "login"} runs a saved flow inside this one, so
+# `activate` is `login` plus the OTP, and `goto-settings` is `login` plus one
+# tap, rather than three copies of logging in. Variables pass down. Nesting is
+# capped, because a flow that includes itself would otherwise drive the phone
+# until somebody noticed.
+#
+# NOT RECORDED FROM WHAT SOMEBODY DID. There is no `flow record`, deliberately.
+# Watching a person tap produces a list of coordinates, which is the one
+# spelling guaranteed to break the first time the layout moves. A flow is
+# written in selectors, by somebody who decided what the step means.
+#
+# Everything `run` understands is handed straight through — --var, --vars,
+# --dry-run, --snapshot, --logs — rather than re-implemented here. Two parsers
+# for --var is two places for it to mean something slightly different.
+#
+# exit 0  done
+# exit 1  usage error, or no such flow
+# exit 2  the flow file is unusable
+# exit *  from `run`, the exit code of the step that stopped it
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+# A flow that includes itself is a phone being driven until somebody notices.
+# Three is deeper than any real composition — login, then activate, then the
+# thing you actually wanted — and shallow enough to stop a cycle quickly.
+DT_FLOW_DEPTH="${DT_FLOW_DEPTH:-0}"
+[ "$DT_FLOW_DEPTH" -lt 3 ] \
+  || die "flows are nested three deep already — one of them includes itself" 1
+export DT_FLOW_DEPTH=$((DT_FLOW_DEPTH + 1))
+
+# The subcommands, which is also the list of names a flow may not have: with
+# `flow.sh <name>` meaning `run <name>`, a flow called "list" could never be run.
+SUBCOMMANDS="save run list show delete"
+
+ACTION=""
+NAME=""
+STEPS=""
+DESCRIPTION=""
+PASS=()
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --steps)
+      [ $# -ge 2 ] || die "--steps needs a JSON array, or @file" 1
+      case "$2" in
+        @*) STEPS="$(cat "$(expand_path "${2#@}")" 2>/dev/null || true)"
+            [ -n "$STEPS" ] || die "could not read the step list at ${2#@}" 1 ;;
+        *)  STEPS="$2" ;;
+      esac
+      shift 2 ;;
+    --description)
+      [ $# -ge 2 ] || die "--description needs a line of text" 1
+      DESCRIPTION="$2"; shift 2 ;;
+    # Everything run.sh understands is handed straight through rather than
+    # re-implemented here. Two parsers for --var is two places for it to mean
+    # something slightly different.
+    --var|--vars)
+      [ $# -ge 2 ] || die "$1 needs a value" 1
+      PASS+=("$1" "$2"); shift 2 ;;
+    --dry-run|--snapshot|--logs) PASS+=("$1"); shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) die "unknown argument: $1 (usage: flow.sh save|run|list|show|delete)" 1 ;;
+    *)
+      if [ -z "$ACTION" ]; then
+        case " $SUBCOMMANDS " in
+          *" $1 "*) ACTION="$1" ;;
+          # A bare name is a run. `flow login` is what anybody types, and it is
+          # also what a {"flow": "login"} step becomes.
+          *)        ACTION=run; NAME="$1" ;;
+        esac
+      elif [ -z "$NAME" ]; then NAME="$1"
+      else die "flow.sh $ACTION takes one name, got '$NAME' and '$1'" 1
+      fi
+      shift ;;
+  esac
+done
+
+[ -n "$ACTION" ] || die "missing action (usage: flow.sh save|run|list|show|delete)" 1
+load_config
+
+DIR="$(flows_dir)"
+
+check_name() {
+  case "$1" in
+    "") die "missing flow name (usage: flow.sh $ACTION <name>)" 1 ;;
+    # The name becomes a filename, so it may not be a path. `flow run ../../etc`
+    # is not a flow.
+    *[!A-Za-z0-9_-]*) die "a flow name may only hold letters, digits, dashes and underscores — got '$1'" 1 ;;
+  esac
+  return 0
+}
+flow_file() { printf '%s/%s.json' "$DIR" "$1"; }
+
+case "$ACTION" in
+  save)
+    check_name "$NAME"
+    case " $SUBCOMMANDS " in
+      *" $NAME "*) die "'$NAME' is one of this command's own words ($SUBCOMMANDS), so \`flow $NAME\` could never run it — pick another name" 1 ;;
+    esac
+    [ -n "$STEPS" ] || die "missing --steps (usage: flow.sh save $NAME --steps '[...]')" 1
+    printf '%s' "$STEPS" | jq -e 'type == "array" and length > 0' >/dev/null 2>&1 \
+      || die "--steps must be a non-empty JSON array of step objects" 1
+
+    # VALIDATED BY THE THING THAT WILL RUN IT. A dry run puts the list through
+    # run.sh's own checks — one verb per step, no uids, every key known — so a
+    # flow cannot be saved in a shape that will be refused the first time
+    # somebody in a hurry tries to use it. The placeholders are what a dry run
+    # would refuse for want of a value, so they are supplied as themselves.
+    names="$(printf '%s' "$STEPS" | jq -r '
+      [ .. | strings | match("\\{\\{ *([A-Za-z0-9_]+) *\\}\\}"; "g").captures[0].string ]
+      | unique | join(" ")')"
+
+    # WHAT A NESTED FLOW NEEDS, THIS FLOW NEEDS.
+    #
+    # `outer` is [{"flow": "login"}, …] and has no placeholder of its own, but it
+    # cannot run without login's password. Declaring only its own would make
+    # `flow list` under-report it and `flow run outer` fail at the step rather
+    # than at the door. Read from the child's own record, so there is one place
+    # a flow's requirements are written down.
+    for child in $(printf '%s' "$STEPS" | jq -r '
+                     .[] | select(has("flow")) | .flow
+                     | if type == "array" then .[-1] else . end'); do
+      cf="$(flow_file "$child")"
+      [ -f "$cf" ] || continue
+      names="$names $(jq -r '(.vars // []) | join(" ")' "$cf" 2>/dev/null || true)"
+    done
+    names="$(printf '%s' "$names" | tr ' ' '\n' | sort -u | sed '/^$/d' | join_lines ' ')"
+
+    fake='{}'
+    for n in $names; do
+      fake="$(printf '%s' "$fake" | jq -c --arg k "$n" '.[$k] = "placeholder"')"
+    done
+    out="$("$DT_HOME/scripts/run.sh" --dry-run --vars "$fake" --steps "$STEPS" 2>&1)" \
+      || die "these steps would not run — $(printf '%s' "$out" | join_lines '; ')" 1
+
+    mkdir -p "$DIR" || die "could not create $DIR" 2
+    f="$(flow_file "$NAME")"
+    jq -n --arg n "$NAME" --arg d "$DESCRIPTION" --argjson s "$STEPS" \
+          --argjson v "$(jq -cn --arg s "$names" '$s | split(" ") | map(select(. != ""))')" \
+      '{name: $n, description: $d, vars: $v, steps: $s}' > "$f.new" \
+      || { rm -f "$f.new"; die "could not write $f" 2; }
+    mv "$f.new" "$f" || { rm -f "$f.new"; die "could not replace $f" 2; }
+
+    printf 'OK saved %s — %s step(s)%s\n' "$NAME" \
+      "$(printf '%s' "$STEPS" | jq 'length')" \
+      "$( [ -n "$names" ] && printf ', needs: %s' "$names" )"
+    printf '       %s\n' "$f"
+
+    # SAYING "IN THE PROJECT" WHEN IT WENT INTO THE TOOL IS THE KIND OF CLAIM
+    # THIS WHOLE PROGRAM EXISTS TO NOT MAKE.
+    #
+    # DT_ROOT falls back to the checkout when no .devicetools marker is found
+    # above the working directory, which is most of the time — so a flow saved
+    # from anywhere lands inside the DeviceTools installation. That is global:
+    # it does not travel with the app's repository, nobody reviews it, and two
+    # apps on one machine collide on the name `login`. It still works, so this
+    # is a note and not a refusal, but it is said plainly and every time.
+    if [ "$DT_ROOT" = "$DT_HOME" ]; then
+      # NAMING A REMEDY THE CALLER CANNOT REACH IS WORSE THAN NAMING NONE.
+      #
+      # This used to say "run `init` in that repository", and over MCP there was
+      # no init tool and no working directory to run it in — an agent following
+      # its own advice into a dead end. Both halves are now callable from both
+      # sides: init takes the directory, every verb takes the project.
+      printf 'NOTE   that is inside the DeviceTools checkout, not a project — every app on\n'
+      printf '       this machine shares it, and it is not in the app repository. Two steps:\n'
+      printf '         %s\n' "$(as_cmd init '<the app repository>')"
+      printf '         %s save %s %s\n' "$(as_cmd flow)" "$NAME" "$(as_flag project '<the same path>')"
+    fi
+    ;;
+
+  run)
+    check_name "$NAME"
+    f="$(flow_file "$NAME")"
+    [ -f "$f" ] || die "no flow called '$NAME' in $DIR — $(as_cmd flow list) shows what there is" 1
+    jq -e 'type == "object" and (.steps | type) == "array"' "$f" >/dev/null 2>&1 \
+      || die "$f is not a flow file — it needs a .steps array" 2
+
+    printf 'FLOW   %s%s\n' "$NAME" \
+      "$(jq -r 'if .description == "" or .description == null then "" else " — " + .description end' "$f")"
+
+    # run.sh reports which variable is missing, and reports it against the step
+    # list rather than against the declaration — which is the true statement,
+    # since a declaration can go stale and the steps cannot.
+    exec "$DT_HOME/scripts/run.sh" --steps "$(jq -c '.steps' "$f")" ${PASS[@]+"${PASS[@]}"}
+    ;;
+
+  list)
+    [ -z "$NAME" ] || die "flow.sh list takes no name" 1
+    n=0
+    for f in "$DIR"/*.json; do
+      [ -f "$f" ] || continue
+      n=$((n + 1))
+      jq -r '"OK     \(.name)  \(.steps | length) step(s)"
+             + (if (.vars | length) > 0 then "  needs: " + (.vars | join(" ")) else "" end)
+             + (if .description == "" or .description == null then "" else "\n       " + .description end)' \
+        "$f" 2>/dev/null || printf 'WARN   %s — not a readable flow file\n' "$f"
+    done
+    [ "$n" -gt 0 ] || printf 'OK no flows yet in %s — %s\n' "$DIR" "$(as_cmd flow 'save <name> --steps ...')"
+    ;;
+
+  show)
+    check_name "$NAME"
+    f="$(flow_file "$NAME")"
+    [ -f "$f" ] || die "no flow called '$NAME' in $DIR — $(as_cmd flow list) shows what there is" 1
+    jq . "$f"
+    ;;
+
+  delete)
+    check_name "$NAME"
+    f="$(flow_file "$NAME")"
+    [ -f "$f" ] || die "no flow called '$NAME' in $DIR — nothing to delete" 1
+    rm -f "$f" || die "could not remove $f" 2
+    printf 'OK deleted %s — %s\n' "$NAME" "$f"
+    ;;
+
+  *) die "unknown action '$ACTION' (usage: flow.sh save|run|list|show|delete)" 1 ;;
+esac

package/scripts/init.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# init.sh — make a directory into a DeviceTools project.
+#
+#   init.sh [dir]
+#
+# A project is where config.json, flows/, .state/ and .runs/ live. Without one,
+# all of those resolve into the DeviceTools checkout — which is global: it does
+# not travel with the app's repository, nobody reviews what lands there, and two
+# apps on one machine collide on the name `login`.
+#
+# WHY THIS IS A VERB AND NOT A BRANCH OF bin/devicetools ANY MORE.
+#
+# It was one, and that made it invisible over MCP: an agent was told by
+# `flow save` to run `init` in its repository and had no tool that could. The
+# advice was correct and unreachable, which is worse than no advice. Every verb
+# in scripts/ is callable from both sides; a `case` arm in the command-line
+# wrapper is callable from one.
+#
+# IT WRITES INTO SOMEBODY ELSE'S REPOSITORY, so it never overwrites: an existing
+# .devicetools, config.json or .gitignore entry is reported and left alone. The
+# only new content is a config copied from the example, which is a template
+# nobody has filled in yet.
+#
+# OVER MCP THE DIRECTORY IS REQUIRED. On the command line "no argument" sensibly
+# means "here". A server has no here — its working directory is whatever the
+# host set at spawn time, which is the checkout, so defaulting would quietly
+# initialise DeviceTools itself.
+#
+# exit 0  the directory is a project
+# exit 1  usage error
+# exit 2  something could not be written
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    -*) die "unknown argument: $1 (usage: init.sh [dir])" 1 ;;
+    *)
+      [ -z "$TARGET" ] || die "init.sh takes one directory, got '$TARGET' and '$1'" 1
+      TARGET="$1"; shift ;;
+  esac
+done
+
+if [ -z "$TARGET" ]; then
+  [ -z "${DT_MCP:-}" ] \
+    || die "init needs the directory to initialise — there is no working directory on this side of the connection, and defaulting would make the DeviceTools checkout itself the project. Pass the absolute path of the app's repository" 1
+  TARGET="$PWD"
+fi
+
+TARGET="$(expand_path "$TARGET")"
+[ -d "$TARGET" ] || die "no such directory: $TARGET" 1
+TARGET="$(cd "$TARGET" && pwd)"
+
+[ "$TARGET" != "$DT_HOME" ] \
+  || die "that is the DeviceTools checkout itself — a project is your app's repository, which is the thing a flow should travel with" 1
+
+# THE PROJECT FORMAT THIS BUILD WRITES. A tool upgraded past a project is the
+# failure nobody sees coming: it reads a config in a shape it no longer means
+# and does something plausible with it. The number is what lets a later build
+# refuse rather than half-read.
+PROJECT_FORMAT=1
+
+if [ -f "$TARGET/.devicetools" ]; then
+  printf 'SKIP    .devicetools — already a project\n'
+else
+  printf 'devicetools-project %s\n' "$PROJECT_FORMAT" > "$TARGET/.devicetools" \
+    || die "could not write $TARGET/.devicetools" 2
+  printf 'OK      .devicetools\n'
+fi
+
+if [ -f "$TARGET/config.json" ]; then
+  printf 'SKIP    config.json — exists\n'
+else
+  cp "$DT_HOME/config.example.json" "$TARGET/config.json" \
+    || die "could not write $TARGET/config.json" 2
+  printf 'OK      config.json — from config.example.json, fill it in\n'
+fi
+
+# .runs/ and .state/ are per-machine and can hold screenshots of a real account,
+# and .state/ holds the session journal, which records typed text so that
+# `waypoint goto` can walk back. None of it is something a project should commit.
+if grep -q '^\.runs/' "$TARGET/.gitignore" 2>/dev/null; then
+  printf 'SKIP    .gitignore — already covers .runs/\n'
+else
+  cat >> "$TARGET/.gitignore" <<'EOF'
+
+# DeviceTools: per-machine state and run artefacts (screenshots, trees, journals).
+.runs/
+.state/
+config.json
+EOF
+  printf 'OK      .gitignore — ignores .runs/ .state/ config.json\n'
+fi
+
+# flows/ is the opposite: it is the reason to have a project at all, so it is
+# NOT ignored. A flow is knowledge about the app and belongs in the repository.
+printf 'NOTE    flows/ is deliberately not ignored — a flow belongs in this repository\n'
+printf 'NEXT    fill in %s/config.json, then: %s\n' "$TARGET" "$(as_cmd doctor)"
+printf 'NEXT    every verb takes %s, which is how to reach this project\n' "$(as_flag project "$TARGET")"