@zerwiz/ymir 0.1.33 → 0.1.35

package/apps/smidja-factory/templates/smidja/smidja_simple_sdlc.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Simple SDLC — plan, build, test, review, document, committing as it goes.
+
+Usage:
+    uv run smidja/smidja_simple_sdlc.py "<prompt or path/to/prompt.md>" [--config smidja/smidja_smidja_config/smidja.config.yaml] [--smidja-id a1b2c3d4]
+
+Phases: engineer(request) -> planner -> git(commit_plan)
+        -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
+        -> reviewer [-> builder(revise) -> reviewer ... bounded]
+        -> code(retest, only if a revision changed code)
+        -> git(commit_build) -> code(changes) -> documenter -> git(commit_docs)
+
+Three commits, three work products, three authors. The plan, the code, and the
+write-up each land in their own commit, and each commit message is the words of
+the agent that produced it — `commit_message` on PlanOutput describes the spec,
+on BuildOutput the code, on DocumentOutput the write-up. No agent's sentence is
+ever reused for another agent's diff.
+
+Testing is CODE, not an agent. `bun test` is a command, not a judgement call:
+an agent rediscovering it every run costs a million tokens to learn what a
+subprocess already knows. Failures travel back to the builder as an envelope,
+so the repair loop is unchanged — only the runner became free and repeatable.
+
+Two different questions still get asked, in order. The suite asks "does it
+run"; the reviewer asks "is this what was asked for", against `plan.md` — and
+neither can answer the other's. A revision that closes a review finding
+re-enters the suite, so the tree that gets committed is the tree that was both
+tested and approved.
+
+The code commit lands after verification, not straight after the build: fixes
+and revisions are part of the same work product, and red code has no business
+on the branch. A run that fails verification therefore leaves the plan
+committed and the working tree dirty — the spec is a real artifact either way,
+and the unfinished code stays where the engineer can see it.
+
+The documenter measures against the commit this run STARTED from, not against
+`main`, because by then the run has moved `main` itself. That baseline is
+pinned before the first commit phase and printed in the request phase.
+"""
+
+import argparse
+import sys
+
+from smidja_modules import agents, changes, gates, git_helper, quality, session, utils
+from smidja_modules.data_types import (AgentCall, BuildOutput, ChangeCapture,
+                                    DocumentOutput, PhaseParams, PlanOutput,
+                                    ReviewOutput)
+
+REQUIRED_AGENTS = ["planner", "builder", "reviewer", "documenter"]
+MAX_FIX_LOOPS = 3
+MAX_REVISION_LOOPS = 2
+
+DOCUMENT_NOTES = ("Read diff_path in full before writing. Document only what the "
+                  "diff shows, then copy the write-up into app_docs/ as your task "
+                  "describes.")
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)
+    agents.validate(cfg, REQUIRED_AGENTS)
+    run = session.ensure(cfg, smidja_id)
+    baseline = git_helper.rev("HEAD")     # pinned before this run commits anything
+
+    def commit(ph, envelope) -> None:
+        """Commit what the preceding phase produced, in that agent's own words."""
+        message = envelope.commit_message or f"smidja({run.smidja_id}): {envelope.summary}"
+        ph.log(sha=git_helper.commit_all(message), message=message)
+
+    def record(ph, result) -> None:
+        """Log a deterministic block's verdict — the same shape every smidja uses."""
+        passed = sum(1 for check in result.checks if check.passed)
+        ph.log(passed=result.passed, checks=f"{passed}/{len(result.checks)}",
+               artifacts=", ".join(result.artifacts))
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt, baseline=git_helper.short_sha(baseline))
+
+    with run.phase(PhaseParams(name="plan", kind="agent", owner="planner",
+                               description="Turn the request into an implementable plan")) as ph:
+        plan = ph.call(AgentCall(output_type=PlanOutput, prompt=prompt,
+                                 gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+    with run.phase(PhaseParams(name="commit_plan", kind="code", owner="git",
+                               description="Put the spec on record before any code exists to blur it")) as ph:
+        commit(ph, plan)
+
+    with run.phase(PhaseParams(name="build", kind="agent", owner="builder",
+                               description="Implement the plan exactly")) as ph:
+        build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=plan,
+                                  gates=[gates.diff_matches_claims]))
+
+    test = None
+    for i in range(1, MAX_FIX_LOOPS + 1):
+        with run.phase(PhaseParams(name=f"test_{i}", kind="code", owner="quality",
+                                   description="Run the suite — a known command, so code runs "
+                                               "it and no agent has to rediscover it")) as ph:
+            test = quality.run_tests(run)
+            record(ph, test)
+
+        if test.passed:
+            break
+
+        with run.phase(PhaseParams(name=f"fix_{i}", kind="agent", owner="builder", retries=1,
+                                   description="Repair what the suite reported, from its "
+                                               "verbatim output")) as ph:
+            build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt,
+                                      previous=quality.as_envelope(test, "tests"),
+                                      gates=[gates.diff_matches_claims]))
+
+    review = None
+    revised = False
+    for i in range(1, MAX_REVISION_LOOPS + 1):
+        with run.phase(PhaseParams(name=f"review_{i}", kind="agent", owner="reviewer",
+                                   description="Confirm the build matches the plan")) as ph:
+            review = ph.call(AgentCall(output_type=ReviewOutput, prompt=prompt, previous=build,
+                                       gates=[gates.artifacts_exist, gates.verdict_consistent]))
+
+        if review.approved or i == MAX_REVISION_LOOPS:
+            break
+
+        with run.phase(PhaseParams(name=f"revise_{i}", kind="agent", owner="builder", retries=1,
+                                   description="Close the reviewer's blocking findings")) as ph:
+            build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=review,
+                                      gates=[gates.diff_matches_claims]))
+            revised = True
+
+    # A revision edited code after the suite last ran, so the green light is
+    # stale. Re-run it rather than commit on a result that predates the change.
+    if revised and review is not None and review.approved:
+        with run.phase(PhaseParams(name="retest", kind="code", owner="quality",
+                                   description="Re-run the suite — the revision changed code "
+                                               "after the last green result")) as ph:
+            test = quality.run_tests(run)
+            record(ph, test)
+
+    # Red tests or a rejected review stop the chain here: the code stays
+    # uncommitted and nothing is documented, because there is nothing worth
+    # describing yet. The plan commit stands — it is a record of what was asked.
+    verified = (test is not None and test.passed
+                and review is not None and review.approved)
+    if verified:
+        with run.phase(PhaseParams(name="commit_build", kind="code", owner="git",
+                                   description="Land the code only now: green suite, approved review")) as ph:
+            commit(ph, build)
+
+        with run.phase(PhaseParams(name="changes", kind="code", owner="git",
+                                   description="Diff the whole run against its pinned baseline, for the documenter")) as ph:
+            changeset = changes.capture(run, ChangeCapture(base=baseline))
+            ph.log(base=f"{changeset.base.label} @ {changeset.base.commit[:7]}",
+                   reason=changeset.base.reason,
+                   files=len(changeset.files) + len(changeset.untracked),
+                   lines=f"+{changeset.insertions} -{changeset.deletions}",
+                   diff=changeset.diff_path)
+            if changeset.empty:
+                raise RuntimeError(
+                    f"nothing changed since {changeset.base.label} "
+                    f"({changeset.base.reason}) — there is nothing to document.")
+
+        with run.phase(PhaseParams(name="document", kind="agent", owner="documenter", retries=1,
+                                   description="Write up the completed change")) as ph:
+            document = ph.call(AgentCall(output_type=DocumentOutput, prompt=prompt,
+                                         previous=changes.as_envelope(changeset, DOCUMENT_NOTES),
+                                         gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+        with run.phase(PhaseParams(name="commit_docs", kind="code", owner="git",
+                                   description="Ship the write-up in its own commit, beside the code it describes")) as ph:
+            commit(ph, document)
+
+    return run.finish(accepted=verified,
+                      reason="the suite or the review never came back clean")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))

package/apps/smidja-factory/templates/smidja.config.yaml

@@ -0,0 +1,143 @@
+# smidja.config.yaml — the smidja's agent roster. One agent, one prompt, one purpose.
+# v1 runs the Pi coding agent only; coding_agent: claude_code arrives in v2.
+defaults:
+  coding_agent: pi
+  model: google/gemini-3.6-flash   # provider/id — a bare pattern is ambiguous across providers
+  thinking: medium                 # off | minimal | low | medium | high | xhigh | max
+  harness_engineering: []          # pi extensions loaded into the harness (-e)
+  # Roster-wide allowlist; any agent may override with its own list.
+  # NOTE: --tools filters extension and custom tools too, not just builtins. An agent
+  # whose harness_engineering extension registers a tool MUST name that tool in its own
+  # tools list — otherwise the extension loads and its tool is silently filtered out.
+  tools:
+    - read                         # read file contents
+    - bash                         # execute bash commands
+    - edit                         # find/replace edits
+    - write                        # create/overwrite files
+    - grep                         # search file contents  (pi default: OFF)
+    - find                         # find files by glob     (pi default: OFF)
+    - ls                           # list directories       (pi default: OFF)
+  # Off-limits to every agent that does not name them in its own `writes`.
+  # `tools` alone cannot protect these: bash runs `git checkout`, and write
+  # reaches any path. An agent must not be able to edit the machinery that
+  # decides whether its own work passed. Enforced in smidja_modules/permissions.py.
+  #
+  # `writes:` per agent says what it may change IN THE REPO. It never restricts
+  # the session runtime under data_dir — context_handoff/, envelopes, prompts,
+  # raw output. Every agent can always write its own report; `writes: []` means
+  # read-only with respect to the repo, not mute.
+  protected_files:
+    - smidja/smidja_modules/
+    - smidja/smidja_smidja_config/
+    - smidja/smidja_*.py
+  data_dir: smidja/smidja_data          # runtime home: {data_dir}/sessions/{smidja_id}/{agent_name}/
+
+observability:
+  db: smidja/smidja_data/smidja.db        # tracer writes here directly; the UI polls it
+  poll_ms: 500                     # visualizer live-poll cadence
+
+agents:
+  - name: planner
+    model: fireworks/accounts/fireworks/models/kimi-k3
+    thinking: high
+    color: "#a78bfa"                 # optional hex — the agent's lane color in the visualizer
+    purpose: Turn a request into a plan the builder can implement without asking questions.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/planner/system.md
+      user: smidja/smidja_data/prompt_engineering/planner/user.md
+    harness_engineering:
+      - smidja/smidja_data/harness_engineering/subagents.ts    # registers the four subagent_* tools below
+    writes:                        # the plan is the only thing it may leave in the repo
+      - specs/
+    tools:                         # full recon + write for plan.md; no edit — the planner never touches repo files
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - subagent_create            # extension tools MUST be named here or they are filtered out
+      - subagent_continue
+      - subagent_list
+      - subagent_remove
+
+  - name: builder
+    color: "#22d3ee"
+    purpose: Implement the plan exactly; report every changed file in the envelope.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/builder/system.md
+      user: smidja/smidja_data/prompt_engineering/builder/user.md
+    # No `writes` key: unrestricted, and the only agent that is. It still cannot
+    # touch defaults.protected_files — the builder does not get to edit its own grader.
+    tools:                         # the only agent that mutates the repo — everything on
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - edit
+      - write
+
+  - name: scout
+    color: "#fbbf24"
+    purpose: Find and report where things live; change nothing.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/scout/system.md
+      user: smidja/smidja_data/prompt_engineering/scout/user.md
+    harness_engineering:
+      - smidja/smidja_data/harness_engineering/subagents.ts    # registers the four subagent_* tools below
+    writes: []                     # read-only, and now actually read-only: its findings
+                                   # go to context_handoff/, which is runtime, not the repo
+    tools:                         # search-heavy recon; write only so scout_findings.md lands without a bash heredoc
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - subagent_create            # extension tools MUST be named here or they are filtered out
+      - subagent_continue
+      - subagent_list
+      - subagent_remove
+
+  # No tester agent: running the suite is a known command, so it is a kind="code"
+  # phase over smidja_modules/quality.py. See SKILL.md hard rule 8.
+
+  - name: reviewer
+    model: openai/gpt-5.6-terra
+    thinking: high
+    color: "#fb7185"
+    purpose: Confirm that what was built is what was asked for; change nothing.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/reviewer/system.md
+      user: smidja/smidja_data/prompt_engineering/reviewer/user.md
+    writes: []                     # a reviewer that cannot fix cannot quietly fix — the
+                                   # claim the tool list only implied, now enforced
+    tools:                         # full read surface; write only for review.md, no edit
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
+  - name: documenter
+    model: openai/gpt-5.6-luna
+    color: "#e879f9"
+    purpose: Write up the change that was just made, from the diff; document only.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/documenter/system.md
+      user: smidja/smidja_data/prompt_engineering/documenter/user.md
+    writes:                        # documentation only — "document only" is a rule now,
+      - app_docs/                  # not a line in a prompt the model may drift from.
+      - docs/                      # Markdown anywhere, because docs live next to the
+      - "**/*.md"                  # code they describe as often as in a docs folder.
+      - "*.md"
+    tools:                         # reads the diff and the code; writes/edits documentation only
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+      - edit

package/bin/app-build.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# app-build — build the in-tree apps (plan 35).
+#
+# apps/ ships as source, so the bundle each surface serves must be built from it
+# before the package is packed. This is the one door that does that, so a build
+# cannot be half-done in one place and forgotten in another (the fault class of
+# 2026-09-18: an artefact published without the file it needed).
+#
+#   bin/app-build.sh [surface …]      default: every app that carries a build script
+#
+# Skips an app that has no package.json (smidja's engine is Python; the smithy
+# arrives as @zerwiz/smidja-factory) and an app with no build script, naming it.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+want=("$@")
+[ ${#want[@]} -eq 0 ] && want=(hlidskjalf odrerir sessrumnir)
+
+built=0 skipped=0 failed=0
+for s in "${want[@]}"; do
+  d="$ROOT/apps/$s"
+  if [ ! -f "$d/package.json" ]; then
+    printf 'app-build[1]{%s}:\n  "skipped — no package.json (not an npm app)"\n' "$s"; skipped=$((skipped+1)); continue
+  fi
+  if ! grep -q '"build"' "$d/package.json"; then
+    printf 'app-build[1]{%s}:\n  "skipped — no build script"\n' "$s"; skipped=$((skipped+1)); continue
+  fi
+  printf 'app-build[1]{%s}:\n  "building…"\n' "$s"
+  if ( cd "$d" && { [ -d node_modules ] || npm install --no-audit --no-fund >/dev/null 2>&1; } && npm run build >/dev/null 2>&1 ); then
+    printf 'app-build[1]{%s}:\n  "built — dist/"\n' "$s"; built=$((built+1))
+  else
+    printf 'app-build[1]{%s}:\n  "FAILED — see its output above"\n' "$s"; failed=$((failed+1))
+  fi
+done
+printf 'app-build[1]{built,skipped,failed}:\n  "%d","%d","%d"\n' "$built" "$skipped" "$failed"
+[ "$failed" -eq 0 ] || exit 1

package/bin/electron-lib.sh

@@ -32,3 +32,28 @@ electron_remedy() {
   printf '  npm install-scripts approve electron && npm rebuild electron\n'
   printf 'yonder: bin/ymir-install.sh --no-desktop if the web surfaces are enough'
 }
+
+
+electron_fetch_runtime() {  # <app-dir> — place the runtime without npm's permission
+  # npm gates package install scripts by default, so Electron's postinstall never
+  # runs and the desktop windows cannot open — a fresh install of the whole platform
+  # with no windows, and no error a user could act on. `npm rebuild` reports success
+  # and changes nothing; `npm install-scripts approve` does not exist in every npm.
+  # What works, everywhere, is what the postinstall itself does: fetch the release
+  # and place it. Version-exact, npm-independent, and proven on this machine.
+  local dir="${1-}" app v url tmp
+  [ -d "$dir" ] || return 1
+  app="$dir/node_modules/electron"
+  [ -f "$app/path.txt" ] && [ -x "$app/dist/electron" ] && return 0
+  v="$(sed -n 's/.*"electron"[[:space:]]*:[[:space:]]*"[^0-9]*\([0-9][0-9.]*\).*/\1/p' "$dir/package.json" 2>/dev/null | head -1)"
+  [ -n "$v" ] || return 1
+  command -v curl >/dev/null 2>&1 || return 1
+  command -v unzip >/dev/null 2>&1 || return 1
+  tmp="$(mktemp -d)" || return 1
+  url="https://github.com/electron/electron/releases/download/v${v}/electron-v${v}-linux-x64.zip"
+  if curl -fsSL --max-time 300 -o "$tmp/e.zip" "$url"; then
+    mkdir -p "$app/dist" && unzip -q -o "$tmp/e.zip" -d "$app/dist" && printf 'electron' >"$app/path.txt"
+  fi
+  rm -rf "$tmp"
+  [ -f "$app/path.txt" ] && [ -x "$app/dist/electron" ] && { "$app/dist/electron" --version >/dev/null 2>&1; }
+}

package/bin/sessrumnir.sh

@@ -50,7 +50,7 @@ repair_runtime() {
   [ -f "$dir/node_modules/electron/path.txt" ] && return 0
   command -v npm >/dev/null 2>&1 || return 1
   echo "Sessrúmnir — its Electron runtime is absent; fetching it (this is the gated postinstall)…" >&2
-  ( cd "$dir" && npm rebuild electron >/dev/null 2>&1 ) && [ -f "$dir/node_modules/electron/path.txt" ]
+  ( cd "$dir" && npm rebuild electron >/dev/null 2>&1 ) || { [ -r "$(dirname "$0")/electron-lib.sh" ] && . "$(dirname "$0")/electron-lib.sh"; electron_fetch_runtime "$dir"; } && [ -f "$dir/node_modules/electron/path.txt" ]
 }
 
 case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac

package/bin/ymir-install.sh

@@ -302,6 +302,13 @@ step_apps() {
       add apps SKIP "a package install — the surfaces are dependencies (npm i -g @zerwiz/ymir)"
       return 0 ;;
   esac
+  # One repo (plan 35): when the surfaces ship IN this tree there is nothing to
+  # clone — the resolver's first shape (`<root>/apps/<surface>`) is already true.
+  if [ -f "$ROOT/apps/hlidskjalf/package.json" ] && [ -f "$ROOT/apps/odrerir/package.json" ] \
+     && [ -f "$ROOT/apps/sessrumnir/package.json" ]; then
+    add apps PASS "in-tree — apps/ ships with the package (plan 35)"
+    return 0
+  fi
   local reg="$HOARD/identity/projects.yaml"
   if [ ! -r "$reg" ]; then
     # The fork path: no private hoard — fall back to the PUBLIC app map so a

package/install.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# install.sh — the one-liner. Ymir into the operator's OWN prefix, with PATH set,
+# so `ymir` works in the shell they are standing in and every shell after it.
+#
+#   curl -fsSL https://raw.githubusercontent.com/zerwiz/ymir/main/install.sh | bash
+#
+# Why this exists, and why `npm install -g @zerwiz/ymir` alone is not enough: npm
+# puts a global command in its global prefix's bin directory, and on an ordinary
+# machine that directory is not on PATH. The command is installed and the shell
+# cannot see it — the most common "it does not work" in the whole Node ecosystem.
+# This script removes that class of failure:
+#
+#   · a prefix the user owns (no sudo, no EACCES on /usr/lib/node_modules)
+#   · the export written into the shell's rc, so it survives the session
+#   · and then it proves the door: `ymir --version`
+#
+# Env: YMIR_NPM_PREFIX (default ~/.npm-global), YMIR_PKG (default @zerwiz/ymir).
+set -eu
+
+PREFIX="${YMIR_NPM_PREFIX:-$HOME/.npm-global}"
+PKG="${YMIR_PKG:-@zerwiz/ymir}"
+
+say() { printf '%s\n' "$*" >&2; }
+
+command -v npm >/dev/null 2>&1 || {
+  say "error: npm is not installed, and this script does not install Node."
+  say "help: install Node 20+ (https://nodejs.org), then run this again."
+  exit 1
+}
+
+# 1. a prefix the user owns — every later install is painless
+mkdir -p "$PREFIX/bin"
+npm config set prefix "$PREFIX" >/dev/null 2>&1 || true
+export PATH="$PREFIX/bin:$PATH"
+
+# 2. the PATH FIRST — so a failed install still leaves the command reachable, and
+#    the user can simply run it again. (It used to be written after the install,
+#    and `"${@:-}"` handed npm an EMPTY argument, so the install failed and the
+#    script exited before any shell file was touched: "it never writes to .bashrc".)
+rc_written=""
+for rc in "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.zshrc" "$HOME/.profile"; do
+  [ -e "$rc" ] || continue
+  if ! grep -q "$PREFIX/bin" "$rc" 2>/dev/null; then
+    printf '\n# Ymir — the npm global bin, so `ymir` is found\ncase ":$PATH:" in *":%s/bin:"*) ;; *) export PATH="%s/bin:$PATH" ;; esac\n' "$PREFIX" "$PREFIX" >>"$rc"
+    rc_written="$rc_written ${rc##*/}"
+  fi
+done
+export PATH="$PREFIX/bin:$PATH"
+
+# 3. the package
+say "installing $PKG into $PREFIX …"
+# `@latest` AND --prefer-online: a stale cached `latest` is how an install
+# succeeds while changing nothing, and the user is left on an old build.
+install_args=(-g "$PKG@latest" --prefer-online)
+[ "$#" -gt 0 ] && install_args+=("$@")
+if ! npm install "${install_args[@]}"; then
+  say "error: the install failed — see npm's output above."
+  say "note: your PATH is already set, so a second run picks up where this left off."
+  exit 1
+fi
+
+
+# 4. the FIRST SETUP — the whole platform, not just a command
+# pi.dev and opencode finish here by running their own onboarding; an installer
+# that stops at a binary leaves the user with a tool that does nothing yet, and
+# with eight things still to go wrong. YMIR_SKIP_SETUP=1 installs the command only.
+if [ "${YMIR_SKIP_SETUP:-0}" != 1 ]; then
+  say ""
+  say "the first setup — the plan, then the work. This takes a few minutes."
+  if ! ymir install --yes; then
+    say "warn: the setup did not finish cleanly — nothing is lost; run \`ymir\` again to continue."
+  fi
+fi
+
+# 5. prove the doors rather than promise them
+if command -v ymir >/dev/null 2>&1; then
+  say ""
+  say "ymir $(ymir --version 2>/dev/null || printf '?') — installed."
+  say "what stands:"
+  ymir validate --quiet 2>/dev/null | grep -E "^  \"" | head -12 | sed 's/^/  /' >&2 || true
+  say "next:  ymir raise      # lift the hall (SPA :3888, the board :8437, the windows)"
+  say "       ymir --help     # every door"
+else
+  say "error: the package is installed but \`ymir\` is still not on PATH."
+  say "help: export PATH=\"$PREFIX/bin:\$PATH\"   (then open a new shell)"
+  exit 1
+fi
+[ -n "$rc_written" ] && say "PATH written into:$rc_written — open a new shell for other terminals."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerwiz/ymir",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Ymir — the single-tenant agent operating system. One command: curl -fsSL https://raw.githubusercontent.com/zerwiz/ymir/main/install.sh | bash  ·  or: npx @zerwiz/ymir  ·  or: npm i -g @zerwiz/ymir (if `ymir` is not found, the README has the three-line PATH cure)",
   "license": "Apache-2.0",
   "homepage": "https://github.com/zerwiz/ymir",
@@ -51,7 +51,13 @@
     ".cursor/",
     "assets/",
     "data/",
-    "deploy/"
+    "deploy/",
+    "apps/",
+    "install.sh",
+    "!apps/*/node_modules/",
+    "!apps/*/node_modules/**",
+    "!apps/*/.git/**",
+    "!apps/*/fork/**"
   ],
   "engines": {
     "node": ">=20"
@@ -65,12 +71,15 @@
   },
   "scripts": {
     "test": "bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh",
-    "compliance": "bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh"
+    "compliance": "bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh",
+    "prepack": "bin/app-build.sh"
   },
   "dependencies": {
-    "@zerwiz/hlidskjalf": "^0.1.1",
-    "@zerwiz/odrerir": "^0.1.1",
-    "@zerwiz/sessrumnir": "^0.1.10",
     "@zerwiz/smidja-factory": "^0.1.3"
-  }
+  },
+  "workspaces": [
+    "apps/hlidskjalf",
+    "apps/odrerir",
+    "apps/sessrumnir"
+  ]
 }

package/scripts/electron.sh

@@ -191,10 +191,14 @@ ensure_electron_binary() {
 repair_electron() {  # <app-dir>
   local dir="$1"
   command -v npm >/dev/null 2>&1 || return 1
-  ( cd "$dir" && npm install-scripts approve electron >/dev/null 2>&1 || true
-    cd "$dir" && npm rebuild electron >/dev/null 2>&1 )
+  # npm gates the rebuild as well as the postinstall: approve first, or the mend
+  # silently changes nothing and the window still never opens.
+  ( cd "$dir" && { npm install-scripts approve electron >/dev/null 2>&1 || true; npm rebuild electron >/dev/null 2>&1; } )
 }
 if ! ensure_electron_binary; then
+  # npm-independent: fetch the release as the postinstall would (bin/electron-lib.sh)
+  [ -r "$ROOT/bin/electron-lib.sh" ] && { . "$ROOT/bin/electron-lib.sh"; }
+  command -v electron_fetch_runtime >/dev/null 2>&1 && electron_fetch_runtime "$APP" || true
   # Try the mending ourselves before telling the user to do it by hand: npm's
   # gating is the cause, and the cure is one command we can run.
   echo "the Electron runtime is partial — mending it (npm rebuild electron)…" >&2

package/.agents/bus/messages.json

@@ -1 +0,0 @@
-[]

package/.agents/config/agents.machine.example.yaml

@@ -1,16 +0,0 @@
-# config/agents.<hostname>.yaml — a per-machine OVERLAY for the personal setup.
-#
-# Copies next to config/agents.yaml and is deep-merged over it when the
-# hostname matches (short form, before the first dot). Override the hostname
-# with YMIR_AGENTS_MACHINE. Use it so each machine runs its own model/harness
-# combination from one repo. Private (gitignored); this .example is the shape.
-
-# Example: this machine's hnoss runs a bigger local model, and its default
-# fallback differs.
-# agents:
-#   hnoss: { model: "llama.cpp/qwen3.6-35b-q4_k_s" }
-#   brokk: { model: opencode-go/deepseek-v4.1-flash }
-# providers:
-#   llama.cpp:
-#     base_url: "http://127.0.0.1:8080/v1"
-# default_model: opencode-go/deepseek-v4.1-flash

package/.pi/mcp.json

@@ -1,16 +0,0 @@
-{
-  "mcpServers": {
-    "engram": {
-      "command": "/home/zerwiz/.local/bin/engram-mcp",
-      "args": [
-        "--db",
-        "/home/zerwiz/Ymir/.agents/memory/kaia.engram"
-      ]
-    }
-  },
-  "skills": {
-    "paths": [
-      ".agents/skills"
-    ]
-  }
-}

package/assets/reference/state/.branch-eligible-owner

@@ -1,4 +0,0 @@
-fm-branch-eligible-owner-v1
-1760629
-linux-starttime=13963152 cmdline-hex=Usage:od[--port<n>][--host<addr>][--no-open]StartthelocaldaemonandopenthewebUI.odtoolslive-artifacts<create|list|update|refresh>[options]Manageliveartifactsthroughdaemonwrappercommands.odtoolsdirections[--id<id>|--label<label>][--json]Listthebuilt-indesigndirections,orprintonedirection'sfullpalette/fontstacks/posturespecforbindinginto:root.odartifactscreate--name<path>--input<file>[--project<id-or-name>]Createanormalprojectartifactthroughthelocaldaemon.odtoolsconnectors<list|execute|github-design-context>[options]Discoverandexecuteconfiguredconnectors.odtoolsdesign-systemsread--path<manifest-declared-path>Readactivedesign-systempull-layerfilesthroughdaemonwrappercommands.odmcplive-artifactsStarttheMCPserverexposinglive-artifactandconnectortools.odresearchsearch--query<text>[--max-sources5][--daemon-url<url>]Runagent-callableTavilyresearchthroughthelocaldaemon.odplugin<list|info|install|uninstall|apply|doctor|replay|trust>[args]Discover,install,andapplypluginsthroughthelocaldaemon.odpluginpublish-repo<folder>Create/updatetheauthor'sGitHubrepoforalocalpluginfolder.odpluginopen-design-pr<folder>Pushacommunity-catalogbranchandopentheOpenDesignPRform.odautomation<list|get|create|update|run|runs|pause|resume|delete>[args]DrivetheAutomationssurfaceheadlessly.SamestoreastheUI'sAutomationstab,soanexternalagent(hermes,openclaw,...)canschedule,trigger,orharvestresultsfromaroutinewithoutopeningthewebUI.odmessage-center<list|read|read-all>[args]Readandacknowledgemessage-centerinboxitemsthroughthesamedaemonendpointsthebellUIuses.odamr<login|status>[args]StartVelabrowsersign-inorinspectthecurrentVelaaccountthroughthelocalOpenDesigndaemon.odmemorytree<list|view|edit|move>[args]Inspectandeditthememorytreethatisinjectedintoagentprompts.odshare<open-design|url>[options]Buildlocalizedsocial-sharetargetsfortheOpenDesignrepooradeployedprojectURL.Use--jsonforscriptedintegrations.odui<list|show|respond|revoke|prefill>[args]ReadandanswerGenUIsurfaces(form/choice/confirmation/oauth-prompt)headlessly.odchatnew--project<id>[--seed-from<cid>][--fork-after<mid>][--title"<t>"][--json]CreateaSideChat:anewconversationthatinheritsanotherconversation'scontextbycopyingitsmessages(--seed-from),optionallystoppingatonemessage(--fork-after).Mirrorsthewebchatforkaction.oddiagnosticsexport[<path>][--json]Bundledaemon/web/desktoplogs,machineinfo,andrecentcrashreportsintoazipforsupporttickets.SameoutputasSettings→About→Exportdiagnostics.odexport<file>--project<id>--format<html|pdf|image|pptx>[--out<path>]ProgrammaticallyexportanHTML/deckartifacttoHTML,PDF,image,orPPTX(nomodel/agentcalls).MirrorsthewebDownloadmenu;rasterizationusesthedesktopruntime'sbundledChromium.odlint<file.html|->[--fail-on<p0|p1|p2|none>][--json]Runthedaemon'santi-slopartifactlinteragainstanHTMLfileorstdin(nomodel/agentcalls;headless-safe).Exits1whenfindingsmeetthe--fail-onthreshold,soitcangatecron/CIrenderpipelines."$OD_NODE_BIN""$OD_BIN"tools...Recommendedagent-runtimeform;avoidsrelyingonuserPATHforodornode.odmediagenerate--surface<image|video|audio>--model<id>[opts]Generateamediaartifactandwriteitintotheactiveproject.Designedtobeinvokedbyacodeagent-picksupOD_DAEMON_URLandOD_PROJECT_IDfromtheenvthatthedaemoninjectedonspawn.odmediascaffold--composition-dir.hyperframes-cache/<id>CreateadeterministicHyperFramescompositionwithoutnpxorglobalskillinstallation,beforedispatchingitthroughmediagenerate.odmcp[--daemon-url<url>]RunastdioMCPserverthatproxiesprojecttoolcallstoarunningOpenDesigndaemon.Wireitintoacodingagent(ClaudeCode,Cursor,VSCode,Zed,Windsurf)inanotherrepotopullfilesfromalocalOpenDesignprojectandcreateproject-scopedartifactswithoutexportingazip.Options:--port<n>Porttolistenon(default:7456,env:OD_PORT).--host<addr>Interfaceaddresstobindto(default:127.0.0.1,env:OD_BIND_HOST).SettoaspecificIP(e.g.aTailscaleaddress)torestrictaccesstothatinterfaceonly.--no-openDonotopenthebrowserafterstart.Whatthedaemondoes:*scansPATHforinstalledcode-agentCLIs(claude,codex,devin,opencode,cursor-agent,...)*servesthechatUIathttp://<host>:<port>*proxiesmessages(text+images)totheselectedagentviachild-processspawn*exposesproject-scopedmediascaffold/generateAPIs—theunifiedpaththattheagentcallsvia`odmediascaffold`and`odmediagenerate`.
-1

package/assets/reference/state/.branch-mirror-cursor

@@ -1 +0,0 @@
-{"file":"/home/zerwiz/.pi/agent/sessions/--home-zerwiz-firstmate--/2026-09-04T13-43-14-520Z_01a06ca8-c358-7166-8de7-f2dced4fc993.jsonl","index":428}

package/assets/reference/state/.branch-outcomes-cursor

@@ -1 +0,0 @@
-1

package/assets/reference/state/.branch-session

@@ -1 +0,0 @@
-/home/zerwiz/firstmate/state/branch-session/2026-09-04T16-49-38-671Z_01a06d53-6b6f-7619-930d-e6dfd9a4a29e.jsonl

package/assets/reference/state/.count-default_wF_p5

@@ -1 +0,0 @@
-3

package/assets/reference/state/.count-default_wF_p6

@@ -1 +0,0 @@
-2

package/assets/reference/state/.count-default_wR_p2

@@ -1 +0,0 @@
-5

package/assets/reference/state/.count-default_wS_p2

@@ -1 +0,0 @@
-0

package/assets/reference/state/.count-firstmate_fm-server-knowledge

@@ -1 +0,0 @@
-3