@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/design-icon.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# design-icon.sh — every app wears its own rune.
+#
+# The icon set is runecoded (midgard/design-system/icons.md): an Elder Futhark
+# rune, stroked at the chisel bevel, tinted by the app's HOUSE colour. Not a
+# generic globe, not an emoji, not a screenshot of a UI.
+#
+#   bin/design-icon.sh list                 # the app -> rune -> house mapping
+#   bin/design-icon.sh mint [app]           # write <app>/public/icon.svg (+ the link hint)
+#   bin/design-icon.sh mint --all
+#
+# The tile is stone (--ymir-bg-0) with the rune in the house tint; the SVG is
+# self-contained, so a favicon needs no build step and no raster asset.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ICONS="$ROOT/midgard/design-system/icons"
+STONE="#0e0c09"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-list}"; shift || true
+
+# dir|glyph|tint|says|icon-name|exec|wm-class
+# FIVE UI surfaces, FIVE DIFFERENT glyphs — no app borrows another's rune.
+APPS=(
+  "apps/hlidskjalf|ehwaz|#c9973f|the seat — Hlidskjalf, the high seat of the control plane|ymir-hlidskjalf|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf|Ymir · Hlidskjalf"
+  "apps/hlidskjalf-mobile|raidho|#c9973f|the road — the seat carried, Hlidskjalf on a phone|ymir-hlidskjalf-mobile|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf-mobile|Ymir · Hlidskjalf Mobile"
+  "apps/odrerir|valhalla|#c9973f|the hall — Óðrerir, the Live Hall|ymir-odrerir|scripts/electron.sh start --view odrerir|ymir-odrerir|Ymir · Óðrerir"
+  "apps/sessrumnir|othala|#c9973f|the hall — Sessrúmnir, the seat that holds the cloth|ymir-sessrumnir|bin/sessrumnir.sh start|ymir-sessrumnir|Ymir · Sessrúmnir"
+  "apps/smidja-factory/apps/visualizer|kaunan|#f59e0b|the torch — the forge's eye, Smíðja's trace|ymir-visualizer|scripts/electron.sh start --view smidja|ymir-smidja|Ymir · Smíðja"
+)
+
+list() {
+  printf 'app_icons[%d]{app,rune,tint,says}:\n' "${#APPS[@]}"
+  for row in "${APPS[@]}"; do
+    IFS='|' read -r dir glyph tint says _icon _exec _klass _name <<<"$row"
+    printf '  "%s","%s","%s","%s"\n' "$(basename "$dir")" "$glyph" "$tint" "$says"
+  done
+  printf 'runes[6]{glyph,name,meaning}:\n'
+  printf '  "algiz","ᛉ","the Ymir emblem — the platform itself"\n'
+  printf '  "ehwaz","ᛖ","horse/journey — the seat and its transit"\n'
+  printf '  "ansuz","ᚨ","Odin'"'"'s breath — the forge"\n'
+  printf '  "sowilo","ᛊ","sun — light on the tree"\n'
+  printf '  "valhalla","ᚹ","the hall"\n'
+  printf '  "gjallarhorn","ᚷ","the horn — the tunnel"\n'
+}
+
+mint() {  # <app-dir> <glyph> <tint> <label>
+  local dir=$1 glyph=$2 tint=$3 label=$4
+  local g="$ICONS/$glyph.svg"
+  [ -r "$g" ] || { printf 'error: no glyph %s in midgard/design-system/icons/\nhelp: bin/design-icon.sh list\n' "$glyph" >&2; return 1; }
+  local path
+  path="$(sed -n 's/.*<path d="\([^"]*\)".*/\1/p' "$g" | head -1)"
+  [ -n "$path" ] || { printf 'error: %s carries no <path> to reuse\n' "$glyph" >&2; return 1; }
+  local outdir="$ROOT/$dir/public"
+  [ -d "$(dirname "$outdir")" ] || { printf '  "%s","SKIP (no such app)"\n' "$dir"; return 0; }
+  mkdir -p "$outdir"
+  {
+    printf '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="%s">\n' "$label"
+    printf '  <title>%s</title>\n' "$label"
+    printf '  <rect width="32" height="32" rx="7" fill="%s"/>\n' "$STONE"
+    printf '  <g transform="translate(4 4) scale(1.0)" fill="none" stroke="%s" stroke-width="1.8" stroke-linecap="square" stroke-linejoin="miter">\n' "$tint"
+    printf '    <path d="%s"/>\n' "$path"
+    printf '  </g>\n</svg>\n'
+  } >"$outdir/icon.svg"
+  printf '  "%s","%s","%s","<link rel=\\"icon\\" href=\\"/icon.svg\\" type=\\"image/svg+xml\\">"\n' \
+    "$(basename "$dir")" "$glyph" "${outdir#"$ROOT"/}/icon.svg"
+}
+
+
+# ── install into the user's system ───────────────────────────────────────────
+# An icon that only exists in the checkout is an icon the operator cannot pin.
+# This writes the rune into the user's icon theme and a .desktop entry per app,
+# rendered with THIS machine's root (never a hardcoded home), so every app is
+# dockable and carries the house mark. Idempotent.
+# The DESKTOP the operator actually sees, not whatever a session happened to
+# export: an agent harness may set XDG_DATA_HOME to a sandbox (this one does),
+# and an icon written there is an icon nobody can pin. YMIR_DESKTOP_DATA_HOME
+# exists for a test that genuinely wants a throwaway target.
+data_home="${YMIR_DESKTOP_DATA_HOME:-$HOME/.local/share}"
+icons_dir="$data_home/icons/hicolor/scalable/apps"
+apps_dir="$data_home/applications"
+# app | entry name | Exec | StartupWMClass
+ENTRIES=(
+  "hlidskjalf|Ymir · Hlidskjalf|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf"
+  "odrerir|Ymir · Óðrerir|scripts/electron.sh start --view odrerir|ymir-odrerir"
+  "sessrumnir|Ymir · Sessrúmnir|bin/sessrumnir.sh start|ymir-sessrumnir"
+  "visualizer|Ymir · Smíðja|scripts/electron.sh start --view smidja|ymir-smidja"
+  "hlidskjalf-mobile|Ymir · Hlidskjalf Mobile|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf-mobile"
+)
+install_all() {
+  # A phone app gets an icon for its own bundle, never a desktop entry.
+  local EXCLUDE=" hlidskjalf-mobile "
+
+  mkdir -p "$icons_dir" "$apps_dir" || { printf 'error: cannot write %s / %s\n' "$icons_dir" "$apps_dir" >&2; exit 1; }
+  printf 'installed[%d]{app,icon,entry}:\n' "${#APPS[@]}"
+  local row dir glyph tint says iconname exec klass src
+  for row in "${APPS[@]}"; do
+    IFS='|' read -r dir glyph tint says iconname exec klass display <<<"$row"
+    case "$EXCLUDE" in *" $(basename "$dir") "*) continue ;; esac
+    src="$ROOT/$dir/public/icon.svg"
+    if [ ! -f "$src" ]; then
+      # mint it first — the icon is defined by this table, so it is never absent
+      if [ -r "$ICONS/$glyph.svg" ]; then
+        mkdir -p "$(dirname "$src")" 2>/dev/null
+        path="$(sed -n 's/.*<path d="\([^"]*\)".*/\1/p' "$ICONS/$glyph.svg" | head -1)"
+        { printf '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="%s">\n' "$says"
+          printf '  <title>%s</title>\n  <rect width="32" height="32" rx="7" fill="%s"/>\n' "$says" "$STONE"
+          printf '  <g transform="translate(4 4)" fill="none" stroke="%s" stroke-width="1.8" stroke-linecap="square" stroke-linejoin="miter">\n' "$tint"
+          printf '    <path d="%s"/>\n  </g>\n</svg>\n' "$path"
+        } >"$src" 2>/dev/null || true
+      fi
+    fi
+    cp -f "$src" "$icons_dir/$iconname.svg" 2>/dev/null || { printf '  "%s","FAILED","-","no icon at %s"\n' "$dir" "${src#"$ROOT"/}"; continue; }
+    {
+      printf '[Desktop Entry]\nType=Application\nVersion=1.0\n'
+      printf 'Name=%s\n' "$display"
+      printf 'Comment=%s\n' "$says"
+      printf 'Exec=bash %s/%s\n' "$ROOT" "$exec"
+      printf 'Icon=%s\n' "$iconname"
+      printf 'Terminal=false\nCategories=Development;Utility;\n'
+      printf 'StartupWMClass=%s\nStartupNotify=true\n' "$klass"
+    } >"$apps_dir/$iconname.desktop"
+    printf '  "%s","%s.svg","%s.desktop"\n' "$iconname" "$iconname" "$iconname"
+  done
+  [ -f "$apps_dir/ymir-smidja.desktop" ] && rm -f "$apps_dir/ymir-smidja.desktop"
+  for stale in ymir-hlidskjalf-mobile; do rm -f "$apps_dir/$stale.desktop" "$icons_dir/$stale.svg"; done
+  command -v update-desktop-database >/dev/null 2>&1 && update-desktop-database "$apps_dir" >/dev/null 2>&1 || true
+}
+
+case "$ACTION" in
+  list) list ;;
+  install) install_all ;;
+  mint)
+    if [ "${1:-}" = "--all" ]; then
+      printf 'minted[%d]{app,rune,file,link}:\n' "${#APPS[@]}"
+      for row in "${APPS[@]}"; do IFS='|' read -r d g t l _i _e _k _n <<<"$row"; mint "$d" "$g" "$t" "$l"; done
+    else
+      want="${1:-}"; found=0
+      printf 'minted[1]{app,rune,file,link}:\n'
+      for row in "${APPS[@]}"; do
+        IFS='|' read -r d g t l _i _e _k _n <<<"$row"
+        case "$(basename "$d")" in "$want") mint "$d" "$g" "$t" "$l"; found=1 ;; esac
+      done
+      [ "$found" = 1 ] || { printf 'error: unknown app %s\nhelp: bin/design-icon.sh list\n' "$want" >&2; exit 2; }
+    fi ;;
+  *) printf 'error: unknown action %s\nhelp: bin/design-icon.sh [list|mint] [app|--all]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/desktop-place.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# desktop-place.sh — put the Ymir apps on their own Hyprland desktops.
+#
+# On Omarchy the numbered **desktops** (1 2 3 4 5 …) are the "screens" an
+# operator switches between, not physical monitors. Both Ymir apps should open
+# on their OWN desktop, preferring an EMPTY one, so they are separated and
+# reachable with Super+<n> instead of stacking on whatever is active.
+#
+# This writes a Hyprland user rule (Omarchy's own idiom:
+#   o.window("<class>", { workspace = "<n>" })  ) and applies it live where a
+# dispatcher is available. It never edits /usr/share/omarchy/.
+#
+# Usage:
+#   bin/desktop-place.sh plan              # show which desktop each app would take
+#   bin/desktop-place.sh apply [--dry-run] # write the rules + reload Hyprland
+#   bin/desktop-place.sh status
+#   bin/desktop-place.sh --version
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  for _ymir_c in "$_ymir_dir/ymir-platform.sh" "$(dirname "$_ymir_dir")/bin/ymir-platform.sh"; do
+    [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_dir _ymir_c
+fi
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HYPR_DIR="$HOME/.config/hypr"
+RULE_FILE="$HYPR_DIR/ymir-desktops.lua"
+# The three Ymir surfaces, in the order they should claim desktops.
+APPS=(hlidskjalf smidja sessrumnir odrerir)
+CLASS_hlidskjalf="ymir-hlidskjalf"
+CLASS_smidja="ymir-smidja"
+CLASS_sessrumnir="sessrumnir"
+CLASS_odrerir="ymir-odrerir"
+
+# ── launcher entries (Omarchy / Linux desktop only) ──────────────────────────
+# The .desktop files are templates (__YMIR_ROOT__, not an absolute path), because
+# where this checkout lives is a fact about the machine, not about Ymir. They are
+# rendered into the user's applications directory. This is DESKTOP INTEGRATION —
+# Omarchy/Hyprland is the supported environment; another OS needs its own launcher,
+# not a branch of this one.
+install_entries() {
+  local dst="$HOME/.local/share/applications" n=0
+  local dirs=("$ROOT/apps/hlidskjalf/electron" "$ROOT/apps/sessrumnir/resources" "$ROOT/apps/odrerir/electron")
+  if [ "$(ymir_os)" != linux ] && [ "$(ymir_os)" != wsl ]; then
+    printf 'skip: desktop entries are Omarchy/Linux-shaped; this host is %s\n' "$(ymir_os)" >&2
+    return 0
+  fi
+  mkdir -p "$dst" || return 1
+  local src found=0
+  for src in "${dirs[@]}"; do
+    [ -d "$src" ] || continue
+    found=1
+    for f in "$src"/*.desktop.in; do
+      [ -e "$f" ] || continue
+      sed -e "s|__YMIR_ROOT__|$ROOT|g" "$f" >"$dst/$(basename "$f" .in)" && n=$((n+1))
+    done
+  done
+  [ "$found" = 1 ] || { printf 'error: no launcher templates found\n' >&2; return 1; }
+  printf 'entries[%s]{installed_to}\:\n  "%s","%s"\n' "$n" "$n" "$dst"
+}
+
+have() { command -v "$1" >/dev/null 2>&1; }
+is_omarchy() { [ -d /usr/share/omarchy ]; }
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-plan}"; shift || true
+DRY=0
+[ "${1:-}" = "--dry-run" ] && DRY=1
+
+# An occupied desktop holds at least one window. Everything else in 1..N is free.
+occupied_desktops() {
+  hyprctl workspaces -j 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+for w in d:
+    if w.get("windows", 0) > 0:
+        print(w.get("id"))
+' 2>/dev/null | sort -n
+}
+
+plan_desktops() {
+  local n="${YMIR_DESKTOP_POOL:-10}"
+  local occ; occ="$(occupied_desktops | tr '\n' ' ')"
+  python3 - "$n" "$occ" "${APPS[@]}" <<'PY'
+import sys
+pool = int(sys.argv[1])
+occupied = {int(x) for x in sys.argv[2].split() if x.isdigit()}
+apps = sys.argv[3:]
+free = [d for d in range(1, pool + 1) if d not in occupied]
+# Prefer EMPTY desktops; fall back to the lowest free numbers if none are empty.
+chosen = []
+for i, app in enumerate(apps):
+    if i < len(free):
+        chosen.append((app, free[i]))
+    else:
+        chosen.append((app, i + 1))
+for app, d in chosen:
+    print(f"{app}\t{d}")
+PY
+}
+
+write_rules() {
+  local plan="$1"
+  local out=""
+  out+="-- Ymir desktop placement (generated by bin/desktop-place.sh)."$'\n'
+  out+="-- On Omarchy the numbered desktops are the operator's \"screens\"."$'\n'
+  out+="-- Each Ymir app opens on its own desktop, preferring an EMPTY one."$'\n'
+  out+="-- Regenerate with: bin/desktop-place.sh apply"$'\n\n'
+  while IFS=$'\t' read -r app d; do
+    [ -n "$app" ] || continue
+    local cls
+    case "$app" in
+      hlidskjalf) cls="$CLASS_hlidskjalf" ;;
+      smidja)     cls="$CLASS_smidja" ;;
+      sessrumnir) cls="$CLASS_sessrumnir" ;;
+      odrerir)     cls="$CLASS_odrerir" ;;
+      *)          cls="$app" ;;
+    esac
+    out+="o.window({ class = \"^${cls}\$\" }, { workspace = \"${d}\" })"$'\n'
+  done <<<"$plan"
+  if [ "$DRY" = 1 ]; then
+    printf '%s' "$out"
+    return 0
+  fi
+  mkdir -p "$HYPR_DIR"
+  printf '%s' "$out" >"$RULE_FILE"
+}
+
+include_rule_file() {
+  # Make hyprland.lua require our file, once. Never touch /usr/share/omarchy.
+  local main="$HYPR_DIR/hyprland.lua"
+  local line='require("hypr.ymir-desktops")'
+  [ -f "$main" ] || return 0
+  grep -qxF "$line" "$main" && return 0
+  [ "$DRY" = 1 ] && { printf 'would add to %s: %s\n' "$main" "$line"; return 0; }
+  printf '\n-- Ymir: place the desktop apps on their own desktops.\n%s\n' "$line" >>"$main"
+}
+
+reload_hypr() {
+  [ "$DRY" = 1 ] && return 0
+  have hyprctl || return 0
+  hyprctl reload >/dev/null 2>&1 || true
+}
+
+# ── speed-starts: one key per Ymir app ───────────────────────────────────────
+# An Omarchy user otherwise reaches the apps only through the launcher menu. The
+# binds live in their own file because editor-place.sh regenerates the desktop
+# rules file and preserves only window rules.
+write_launchers() {
+  local file="$HYPR_DIR/ymir-launchers.lua" out=""
+  out+="-- Ymir speed-starts (generated by bin/desktop-place.sh)."$'\n'
+  out+="-- One key raises each app; the placement rules send it to its own desktop."$'\n'
+  out+="-- Regenerate with: bin/desktop-place.sh apply"$'\n\n'
+  out+="o.bind(\"SUPER + Y\", \"Ymir Hlidskjalf\", \"bash $ROOT/scripts/electron.sh start --view hlidskjalf\")"$'\n'
+  out+="o.bind(\"SUPER + M\", \"Ymir Smiðja\", \"bash $ROOT/scripts/electron.sh start --view smidja\")"$'\n'
+  out+="o.bind(\"SUPER + B\", \"Ymir Sessrúmnir\", \"bash $ROOT/bin/sessrumnir.sh start\")"$'\n'
+  out+="o.bind(\"SUPER + O\", \"Ymir Óðrerir\", \"bash $ROOT/scripts/electron.sh start --view odrerir\")"$'\n'
+  if [ "$DRY" = 1 ]; then printf '%s' "$out"; return 0; fi
+  if [ -f "$file" ] && [ "$(cat "$file")" = "$out" ]; then return 0; fi
+  mkdir -p "$HYPR_DIR"
+  printf '%s' "$out" >"$file"
+}
+
+include_launchers_file() {
+  local main="$HYPR_DIR/hyprland.lua" line='require("hypr.ymir-launchers")'
+  [ -f "$main" ] || return 0
+  grep -qxF "$line" "$main" && return 0
+  [ "$DRY" = 1 ] && { printf 'would add to %s: %s\n' "$main" "$line"; return 0; }
+  printf '\n-- Ymir: one key per Ymir app (SUPER+Y Hlidskjalf, SUPER+M Smiðja, SUPER+B Sessrúmnir).\n%s\n' "$line" >>"$main"
+}
+
+case "$ACTION" in
+  plan)
+    plan="$(plan_desktops)"
+    printf 'desktop-place[%d]{app,desktop}:\n' "$(printf '%s\n' "$plan" | grep -c .)"
+    while IFS=$'\t' read -r app d; do
+      [ -n "$app" ] || continue
+      printf '  "%s",%s\n' "$app" "$d"
+    done <<<"$plan"
+    ;;
+  apply)
+    is_omarchy || { printf 'desktop-place[1]{state,detail}:\n  "skipped","not an Omarchy host"\n'; exit 0; }
+    plan="$(plan_desktops)"
+    write_rules "$plan"
+    include_rule_file
+    write_launchers
+    include_launchers_file
+    reload_hypr
+    # The launcher entries are part of the same desktop integration: render the
+    # templates (they hold __YMIR_ROOT__, not an absolute path) into the user's
+    # applications directory.
+    [ "$DRY" = 1 ] || install_entries >/dev/null 2>&1 || true
+    if [ "$DRY" = 1 ]; then
+      printf 'desktop-place[1]{state,file}:\n  "dry-run","%s"\n' "$RULE_FILE"
+    else
+      printf 'desktop-place[1]{state,file}:\n  "written","%s"\n' "$RULE_FILE"
+    fi
+    while IFS=$'\t' read -r app d; do
+      [ -n "$app" ] || continue
+      printf '  "%s","desktop %s"\n' "$app" "$d"
+    done <<<"$plan"
+    ;;
+  status)
+    if [ -f "$RULE_FILE" ]; then
+      printf 'desktop-place[1]{state,file}:\n  "present","%s"\n' "$RULE_FILE"
+      grep -E 'workspace' "$RULE_FILE" 2>/dev/null | sed 's/^/  /' || true
+    else
+      printf 'desktop-place[1]{state,file}:\n  "absent","%s"\n' "$RULE_FILE"
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/desktop-place.sh [plan|apply|status]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/docs-guard.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# docs-guard.sh — docs/ is the PUBLIC, user-facing tree. Block operator-private
+# documents (plans, strategy, roadmaps, the masterplan) before they are staged.
+# Those live at $YMIR_HOME/hodd/docs/ (Rule 04-hoard.md).
+#
+#   bin/docs-guard.sh            # scan the staged change (used as pre-commit)
+#   bin/docs-guard.sh --all      # scan every tracked file
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Private document shapes that must never be published under docs/.
+PATTERNS='(^docs/plans/|^docs/masterplan|^docs/append-only-log|^docs/ratatoskr\.md|^docs/.*-plan\.md$|^docs/.*(plan|strategy|roadmap|backlog|proposal|private)\.md$)'
+# Exception: public transformation plans (about separating private data for
+# open-source release). These are operational, not operator-private.
+PATTERN_ALLOW='(^docs/plans/0003-private-data-separation\.md$)'
+
+scan_list() {
+  local hit=0 f
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if printf '%s\n' "$f" | grep -Eq "$PATTERN_ALLOW"; then
+      continue
+    fi
+    if printf '%s\n' "$f" | grep -Eq "$PATTERNS"; then
+      printf 'docs-guard: private document under docs/: %s\n' "$f" >&2
+      hit=1
+    fi
+  done
+  return "$hit"
+}
+
+if [ "${1:-}" = "--all" ]; then
+  scan_list < <(git -C "$ROOT" ls-files)
+else
+  scan_list < <(git -C "$ROOT" diff --cached --name-only --diff-filter=ACM)
+fi || { printf 'docs-guard: blocked — docs/ is public; move it to $YMIR_HOME/hodd/docs/ (Rule 04)\n' >&2; exit 1; }
+exit 0

package/bin/editor-place.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# editor-place.sh — the editor is UNMANAGED by default: it opens on the
+# desktop you are on, focused and clickable, like any other app.
+#
+# It CAN pin the editor to its own desktop — never on yours — the same way the
+# Ymir apps do (bin/desktop-place.sh), the mechanism proven on this machine:
+#   YMIR_EDITOR_PIN=1 bin/editor-place.sh apply
+# The pin is opt-in because the old always-on behavior made the editor
+# un-focusable (no_focus) and dropped it onto a different desktop, which the
+# Allfather found unusable.
+#
+#   Hyprland applies window rules at MAP time, so the window never appears on the
+#   working desktop at all. Writing `o.window({ class = ... }, { workspace = ... })`
+#   into ~/.config/hypr/ymir-desktops.lua and reloading is strictly better than
+#   moving a window after it has already appeared.
+#
+# (The runtime dispatch form — `hyprctl dispatch movetoworkspacesilent 5,class:...`
+# does NOT work on this Hyprland 0.56, which replaced it with a Lua API. The rule
+# file is the road that holds.)
+#
+# Usage:
+#   bin/editor-place.sh plan             # which desktop the editor would take
+#   bin/editor-place.sh apply [--dry-run]# write the rule + reload
+#   bin/editor-place.sh status
+#   bin/editor-place.sh --version
+#
+# Env: YMIR_EDITOR_CLASS (default: the resolved editor, else `code`)
+#      YMIR_EDITOR_PIN  (1 = pin the editor to its own desktop; default unmanaged)
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HYPR_DIR="$HOME/.config/hypr"
+RULE_FILE="$HYPR_DIR/ymir-desktops.lua"
+DRY=0
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="${1:-plan}"; shift || true
+[ "${1:-}" = "--dry-run" ] && DRY=1
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# The editor's window class, as Hyprland reports it.
+editor_class() {
+  local bin="${YMIR_EDITOR:-}"
+  if [ -z "$bin" ]; then
+    for e in code cursor zed subl nvim vim; do have "$e" && { bin="$e"; break; }; done
+  fi
+  case "$(basename "${bin:-code}")" in
+    code|code-insiders|codium) printf 'code' ;;
+    cursor) printf 'cursor' ;;
+    zed) printf 'dev\\.zed\\.Zed' ;;
+    subl|sublime_text) printf 'sublime_text' ;;
+    *) printf '%s' "${bin:-code}" ;;
+  esac
+}
+
+free_desktop() {
+  have hyprctl || return 1
+  hyprctl workspaces -j 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+used={w.get("id") for w in d if w.get("windows",0)>0}
+for n in range(1,11):
+    if n not in used:
+        print(n); break
+' 2>/dev/null
+}
+
+# Read the desktops already claimed in the rule file, so we do not collide with
+# the apps (or the editor, on a re-run).
+claimed_desktops() {
+  [ -r "$RULE_FILE" ] || return 0
+  grep -oE 'workspace = "[0-9]+"' "$RULE_FILE" 2>/dev/null | grep -oE '[0-9]+' | sort -n -u
+}
+
+plan_desktop() {
+  local cls; cls="$(editor_class)"
+  # If the editor already has a rule AND that desktop is not claimed by the apps
+  # (nor holding their windows), keep it — stability matters. If it collides with
+  # an app, fall through and pick a truly free desktop.
+  local app_claims=""
+  if [ -x "$SCRIPT_DIR/desktop-place.sh" ]; then
+    app_claims="$("$SCRIPT_DIR/desktop-place.sh" plan 2>/dev/null | tail -n +2 \
+      | sed -nE 's/.*,([0-9]+)$/\1/p' | tr '\n' ' ')"
+  fi
+  if [ -r "$RULE_FILE" ]; then
+    local existing
+    existing="$(grep -E "class = \"\^${cls}\\\$" "$RULE_FILE" 2>/dev/null | grep -oE 'workspace = "[0-9]+"' | grep -oE '[0-9]+' | head -1)"
+    if [ -n "$existing" ]; then
+      local collides=0
+      for a in $app_claims; do [ "$a" = "$existing" ] && collides=1; done
+      [ "$collides" = 0 ] && { printf '%s' "$existing"; return 0; }
+    fi
+  fi
+  python3 - "$app_claims" <<'PY'
+import sys, subprocess, json
+used = {int(x) for x in sys.argv[1].split() if x.isdigit()}
+try:
+    d = json.loads(subprocess.run(["hyprctl","workspaces","-j"],capture_output=True,text=True).stdout)
+    for w in d:
+        if w.get("windows",0) > 0:
+            used.add(w.get("id"))
+except Exception:
+    pass
+for n in range(1, 13):
+    if n not in used:
+        print(n); break
+else:
+    print(1)
+PY
+}
+
+write_rule() {  # <desktop>
+  local d=$1 cls
+  cls="$(editor_class)"
+  local header='-- Ymir desktop placement (generated by bin/desktop-place.sh + bin/editor-place.sh).
+-- On Omarchy the numbered desktops are the operator'"'"'s "screens".
+-- Each Ymir window opens on its own desktop, preferring an EMPTY one, and is
+-- placed at MAP time so it never appears on the desktop you are working on.
+-- Regenerate with: bin/desktop-place.sh apply && bin/editor-place.sh apply
+
+'
+  local applines=""
+  # Preserve the app rules by reading desktop-place.sh's own plan and rewriting
+  # them in the SAME file, so one file owns every Ymir window placement. Rows
+  # look like:  "hlidskjalf",5
+  if [ -x "$SCRIPT_DIR/desktop-place.sh" ]; then
+    applines="$(
+      "$SCRIPT_DIR/desktop-place.sh" plan 2>/dev/null | tail -n +2 |
+      while IFS= read -r row; do
+        app="$(printf '%s' "$row" | sed -nE 's/^ *"([a-z]+)",.*/\1/p')"
+        num="$(printf '%s' "$row" | sed -nE 's/.*,([0-9]+)$/\1/p')"
+        [ -n "$app" ] && [ -n "$num" ] || continue
+        case "$app" in
+          hlidskjalf) printf 'o.window({ class = "^ymir-hlidskjalf$" }, { workspace = "%s" })\n' "$num" ;;
+          smidja)     printf 'o.window({ class = "^ymir-smidja$" }, { workspace = "%s" })\n' "$num" ;;
+        esac
+      done
+    )"
+  fi
+  local editorline=""
+  # Unmanaged by default: the editor opens on the active desktop, focused and
+  # clickable. Only pin it away (the old `no_focus` behavior) when the operator
+  # opts in with YMIR_EDITOR_PIN=1.
+  if [ "${YMIR_EDITOR_PIN:-0}" = "1" ]; then
+    editorline="$(printf 'o.window({ class = "^%s$" }, { workspace = "%s", no_focus = true })\n' "$cls" "$d")"
+  fi
+  if [ "$DRY" = 1 ]; then
+    printf '%s' "$header"
+    [ -n "$applines" ] && printf '%s\n' "$applines"
+    printf '%s' "$editorline"
+    return 0
+  fi
+  mkdir -p "$HYPR_DIR"
+  {
+    printf '%s' "$header"
+    # Command substitution strips the trailing newline, so re-add the separator.
+    [ -n "$applines" ] && printf '%s\n' "$applines"
+    printf '%s' "$editorline"
+  } >"$RULE_FILE"
+}
+
+include_rule_file() {
+  local main="$HYPR_DIR/hyprland.lua"
+  local line='require("hypr.ymir-desktops")'
+  [ -f "$main" ] || return 0
+  grep -qxF "$line" "$main" && return 0
+  [ "$DRY" = 1 ] && { printf 'would add to %s: %s\n' "$main" "$line"; return 0; }
+  printf '\n-- Ymir: place the desktop windows on their own desktops.\n%s\n' "$line" >>"$main"
+}
+
+case "$ACTION" in
+  plan)
+    cls="$(editor_class)"
+    if [ "${YMIR_EDITOR_PIN:-0}" = "1" ]; then
+      d="$(plan_desktop)"
+      printf 'editor-place[1]{class,desktop}:\n  "%s",%s\n' "$cls" "$d"
+    else
+      printf 'editor-place[1]{class,desktop}:\n  "%s","unmanaged (YMIR_EDITOR_PIN=1 to pin)"\n' "$cls"
+    fi
+    ;;
+  apply)
+    have hyprctl || { printf 'editor-place[1]{state}:\n  "skipped — no hyprctl (not a Hyprland host)"\n'; exit 0; }
+    d="$(plan_desktop)"
+    write_rule "$d"
+    include_rule_file
+    if [ "$DRY" != 1 ]; then
+      # Validate, per the Omarchy guide: reload then check for config errors.
+      hyprctl reload >/dev/null 2>&1 || true
+      errs="$(hyprctl configerrors 2>&1 | head -3)"
+      if [ -n "$errs" ]; then
+        printf 'editor-place[1]{state,desktop,configerrors}:\n  "written, but Hyprland reported errors","%s","%s"\n' "$d" "$(printf '%s' "$errs" | tr '\n' ' ')"
+        exit 1
+      fi
+      if [ "${YMIR_EDITOR_PIN:-0}" = "1" ]; then
+        printf 'editor-place[1]{state,class,desktop}:\n  "written","%s","%s"\n' "$(editor_class)" "$d"
+      else
+        printf 'editor-place[1]{state,class}:\n  "written (editor unmanaged)","%s"\n' "$(editor_class)"
+      fi
+    else
+      if [ "${YMIR_EDITOR_PIN:-0}" = "1" ]; then
+        printf 'editor-place[1]{state,desktop}:\n  "dry-run","%s"\n' "$d"
+      else
+        printf 'editor-place[1]{state}:\n  "dry-run (editor unmanaged)"\n'
+      fi
+    fi
+    ;;
+  status)
+    if [ -r "$RULE_FILE" ]; then
+      printf 'editor-place[1]{file}:\n  "%s"\n' "$RULE_FILE"
+      grep -E 'class = ' "$RULE_FILE" 2>/dev/null | sed 's/^/  /' || true
+    else
+      printf 'editor-place[1]{state}:\n  "no rule file yet"\n'
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/editor-place.sh [plan|apply|status]\n' "$ACTION" >&2; exit 2 ;;
+esac