agent-bios 0.19.2 → 0.19.3

package/codex/guides/ui-design/visual-direction.md

@@ -0,0 +1,88 @@
+---
+language: en
+status: active
+---
+
+# Choosing a visual direction for an operational interface
+
+Use when a new visual direction or a material arrangement decision remains
+unresolved in the requested work. For an established direction or a bounded copy
+correction, use the existing system and verify the affected result proportionately.
+
+## Start from the task and supported system
+
+Identify the content people must read, compare, select, edit or act on. Preserve
+the working scope, authority and state distinctions that matter to that task.
+Inspect the project's existing components and tokens before introducing a new
+visual vocabulary. An external reference does not itself justify replacing the
+project's framework or component library.
+
+Consult a reference when it helps resolve the remaining visual decision; reuse
+sufficient existing evidence. Research more when the decision needs it or the
+user requests research. Prefer task-relevant product views or official pattern
+documentation. Distinguish live observations, release screenshots, historical
+images and explanatory artwork. Record the source and date, what it informs,
+and its applicability limits in the ordinary design note. Do not infer token
+values or usability from an image alone.
+
+## Choose only the patterns the task needs
+
+| Task | Useful arrangement | Meaning to preserve |
+| --- | --- | --- |
+| Reading and review | Give the artifact sufficient space; keep necessary evidence nearby when switching would obstruct comparison | The artifact, source, applicable conditions and review target |
+| Repeated record comparison | Align comparable values; distinguish whole-list, selected-set and individual-record actions | Units, comparison basis, exceptions and each action's scope |
+| Selection-driven editing | Keep relevant properties bound to the selected object | Selection, draft and resulting changes remain attached to the same target |
+| Input and result confirmation | Keep input, consequential effects and results close enough to follow | Entered, saved, approved and actually executed states stay distinct |
+
+These are conditional patterns, not a required navigation structure or panel
+count. Choose persistent supporting panels or transient overlays according to
+their role. Give prose a readable measure and comparisons sufficient width.
+Adapt the arrangement to the supported viewport while preserving the current
+selection, return context, reading order and keyboard focus order. Compact
+navigation when needed to keep the main task reachable on a narrow screen.
+
+## Define roles before values
+
+Explain the proposed reading order, emphasis, density and grouping briefly.
+Map foregrounds, surfaces, action states, spacing relationships and any required
+depth to the existing semantic tokens. Keep focus, selection, feedback and
+disabled states distinct even when values initially coincide. Add a pattern
+token only when it represents an independent decision. The role of a token
+must survive theme changes; check its actual foreground/background pairing.
+
+For information-dense operational work, start with typography, alignment and
+spacing to organize content; add containers, color or elevation when they
+communicate a needed relationship or interaction. Large introductory areas,
+repeated summary cards, badges and icon backgrounds need a task or brand purpose.
+Ordinary content need not look raised. Use depth when it clarifies a floating,
+movable or otherwise distinct object. Preserve useful brand and user preferences.
+
+Do not impose a reference palette, fixed pixel scale, permanently dim navigation,
+universal card ban or identical layout across tasks. When no system exists, mark
+initial values as project proposals. Define consistent text roles and spacing
+within and between groups, then check the resulting density. Resolve crowded
+content through grouping, widths and wrapping before shrinking text. Keep words
+and meaningful phrases together where the language permits, with a fallback for
+unbroken strings. Check representative Korean text when the product uses Korean.
+
+## Compare only enough to resolve the decision
+
+Use representative content, long labels, important exceptions and relevant
+states at the target sizes. Keep task, content and capability constant while
+comparing visual alternatives; use a credible baseline. Distinguish token
+changes from changes to regions, information order and grouping. Typography
+and spacing can still alter wrapping and geometry. Where narrow layouts
+converge, do not claim a difference the user cannot see.
+
+Inspect the actual rendered result when appearance is being judged. Check
+contrast, clipping, wrapping, state distinctions, action targets and focus
+visibility under the applicable accessibility requirements. Verify that
+rearrangement preserves semantic reading and keyboard order. For interactive
+changes, exercise selection, draft retention and the relevant failure/recovery
+paths; styling does not establish permission or execution.
+
+Record visual preference separately from observed task performance. Rendered
+samples support visual inspection; interaction and user-performance claims need
+their own evidence. Preserve the result and remaining uncertainty in ordinary
+team artifacts. No prescribed number of variants or new research report is
+needed for every task.

package/codex/guides/ui-design.md

@@ -0,0 +1,90 @@
+---
+guide_id: ui-design
+language: en
+status: active
+description: For designing, reviewing, or changing task flows, information layout, visual hierarchy, or interaction in operational user interfaces; keep bounded corrections proportionate.
+use_when:
+  - designing or reviewing a work application, operations tool, or interactive work surface
+  - changing information arrangement, visual hierarchy, design tokens, or interaction states
+  - preserving scope, evidence, authority, and continuity through a user interface
+---
+
+# Operational interface design and delivery
+
+Use for interfaces where people inspect evidence, compose work, make decisions
+or act on records. Match the deliverable to the user's requested stage and scope.
+A clear text correction needs that correction and a proportionate check.
+
+1. **Establish what the sources mean now.** Separate implemented behavior,
+   accepted requirements, proposed design choices and illustrative states.
+   Reconcile amendments and decisions before reusing an older screen. A newer
+   date alone does not establish authority. Keep material contradictions and
+   unknowns visible instead of silently choosing a convenient interpretation.
+
+2. **Preserve requested coverage; bound the work at the right level.** Identify
+   the operator, outcome and evidence that would complete this deliverable.
+   Distinguish people consuming work context from those authoring or managing
+   it; do not invent their visit frequency or force a common starting screen.
+   For a complete design request, cover the required operations even when their
+   backend is not built; specify their subjects, inputs, effects, dependencies
+   and recovery rather than claiming implementation. For a bounded change,
+   complete the requested path before expanding neighboring features. Include
+   adjacent repairs when that path depends on them or this change causes a
+   regression, and state why. An unavailable implementation does not erase a
+   requested design contract.
+
+3. **Organize around a meaningful next decision.** Show the working scope,
+   evidence to compare, current state, available action and resulting next step
+   together. Internal modules or protocol phases are not automatically menus
+   or buttons. Combine preparation steps behind one authorized intent when no
+   user choice is needed, while keeping distinct outcomes understandable. Use
+   the team's visual language to assign emphasis according to the task, and
+   make typography, spacing, color and boundaries express meaningful
+   relationships. Test whether actual task content is prominent at the target
+   size; decorative summaries must earn their space. When layout uncertainty
+   matters, compare arrangements at the lowest useful fidelity, explaining the
+   task tradeoff and what evidence would change the choice.
+
+   When a new visual direction or a material arrangement decision remains
+   unresolved, use
+   `${CODEX_HOME:-$HOME/.codex}/guides/ui-design/visual-direction.md`.
+   An established direction or a bounded correction does not require new
+   reference research or multiple designs.
+
+4. **Keep qualifications with the thing they qualify.** Preserve applicable
+   conditions, exceptions, units, source/version, time meaning and affected
+   scope through summaries, edits, comparisons and exports. Keep independent
+   dimensions separate. Missing evidence is not an empty result or a zero, and
+   an index or relationship view is not proof of its underlying body or meaning.
+   Expand technical detail when useful without hiding a consequential limit.
+
+5. **Make each action's authority and effect precise.** Name the exact target,
+   base and changed content when reviewing a change. Recheck a changed base or
+   permission instead of carrying approval onto different input. Distinguish
+   selection, saved draft, approval, execution and recipient use as applicable;
+   one positive state does not prove the next. Preserve request identity when
+   an outcome is uncertain and reconcile its actual result before retrying.
+   UI controls reflect the existing authoritative policy; they do not create it.
+   If policy is unsettled, label proposed choices and the responsible decision
+   owner rather than implying permission or omitting the required design.
+
+6. **Carry the same work across views and people.** Preserve the draft, target,
+   review/request identity and return context when moving between surfaces.
+   Equivalent outcomes need suitable representations, not identical layouts or
+   duplicated business rules. Provide keyboard and structured alternatives for
+   necessary spatial interactions. Verify evidence for the actual recipient;
+   another worker's receipt does not establish their access or delivery.
+
+7. **Verify this deliverable, then finish it.** Walk a design's concrete scenario
+   and relevant exceptions against its sources; inspect its proposed composition.
+   For working changes, exercise the changed runtime path, relevant failures,
+   keyboard and recovery. When a visual change is material, inspect the affected
+   composition with representative content and relevant states at the target
+   size, distinguishing token changes from changes to information arrangement.
+   Check that visual, reading and focus order remain coherent across layouts.
+   Report visual preference separately from observed task performance. Keep
+   simulation, observed runtime and user evidence distinct. Once the required
+   checks are complete, leave the result, material decisions, source bindings
+   and remaining work in ordinary team artifacts. Keep private facts within
+   their permitted boundary. Choose dependencies only when a requirement
+   demands a decision, using the supported environment first.

package/codex/guides/verification-discipline.md

@@ -77,6 +77,7 @@ cheapest one to write.
 - A/B or on/off measurements: before accepting a null result, verify the arms actually received different treatment in the mechanism under test — a shared default or unconditional upstream step can silently apply the treatment to both arms.
 - Multi-stage pipelines with nondeterministic stages: a final-output diff cannot attribute an effect or a regression to a stage — it conflates the change with run-to-run variance. Persist every stage's output, tabulate what each creates, may edit, and only guards, restrict the suspects to the stages that edit the content in question, and find the first stage where the intended effect disappears or the defect appears. Fix there, preferring a structural recheck over another prompt-level instruction that already failed.
 - Before/after comparisons: pin the input to an immutable copy — a snapshot or versioned artifact — and run both arms against it, because a live artifact (a growing log, a regenerated upstream stage) drifts between runs and any diff over it, a matching one included, is evidence of nothing; when the arms are metered, restore the baseline's exact upstream inputs and re-run only the changed stage. This is input identity, not the separate unit-and-denominator basis rule.
+- Cost figures from provider usage records: before pricing, map every provider's token fields onto one schema — uncached input, cache read, cache write, output. Some providers report input as a total that already includes cached tokens: treating that total as uncached input and then adding the cache-read field again counts the cached portion twice, while charging the inclusive total once at the full rate misprices that portion instead. Other providers exclude cached tokens from the input field. When a provider reports or prices cache writes separately, keep them in their own field. Confirm each provider's field meaning against its own usage documentation or a known sample, never by analogy with another provider, and derive the cache hit rate from the normalized fields.
 - Model-behavior guardrails: verify by changed behavior, not recitation — a staged battery from named-trigger cases through disguised, deconfounded, category-wide, and single-variable framings; a clean pass means "no known defect", so re-run the battery when the model changes.
 - Branch/version test builds against real data: explicitly separate every state sink the app touches (files, DB, OS-level stores that ignore env overrides), confirm the launch path propagates the isolation to child processes, and back up live data before the first run — a mismatched schema that drops unknown fields on write is data loss, not a no-op.
 - Sandbox, replay, or re-adjudication runs on production-derived config: enumerate every outbound channel the stage can reach — publish, upload, notify, external write — and disable or redirect each one before the run, proving each disarm fires as you would prove a path guard; a guard on the input or target path alone leaves egress armed. Fingerprint every external destination before the run and diff it after, so an escaped write is caught by the run rather than by a recipient.
@@ -151,6 +152,11 @@ produce a green with no evidence behind it:
 - **The suspiciously fast or empty run.** When a check goes green unexpectedly quickly, or reports
   nothing at all, dump what it actually ran over before believing it. A harness that crashed early
   and one that found nothing produce the same exit code.
+- **The verdict that ran before its checks.** If a runner computes or prints its overall verdict
+  before all checks finish, later failures cannot change it. Accumulate one failure count across
+  every check, then compute the verdict and exit status once, after the last check. Read a
+  multi-check run from that final count and an exit status verified to derive from it — never from
+  `tail` or collapsed last lines, which hide failures printed earlier.
 - **The control that failed by crashing.** A negative control is evidence only when it fails
   through the assertion it names: a traceback and a caught violation share an exit code, and an
   early crash can pre-empt every control after it. Treat each traceback in a control run as a
@@ -173,7 +179,10 @@ produce a green with no evidence behind it:
 - **The mutant that never ran.** A mutation verdict counts only if the mutant is valid: it
   compiled, sits on a path the exercised test traverses, and changes the guarded behavior, not
   healed downstream or coinciding with a default. The runner must report build failure,
-  unreachable, and equivalent distinctly from KILLED and SURVIVED, and halt on a moved anchor.
+  unreachable, equivalent, and timed out distinctly from KILLED and SURVIVED, and halt on a moved
+  anchor. A timeout is not a kill: it moves with machine load, so set the limit well above the
+  unmutated suite's runtime and accept a verdict only when repeated runs agree on which mutants
+  timed out.
   More tests red than the mutation should touch indicts it; classify a survivor (rebuild,
   discard, genuine gap) before writing a test. **Equivalent is a verdict about the probe as
   much as the mutant**: a probe that is dead or returns a constant reports every mutant as

package/compose/app_bridge/scripts/bridge.py

@@ -10,9 +10,13 @@ import sys
 
 
 def main() -> int:
+    # A Windows PowerShell 5.1 caller may prefix piped input with a UTF-8 BOM.
+    for stream, encoding in ((sys.stdin, "utf-8-sig"), (sys.stdout, "utf-8"), (sys.stderr, "utf-8")):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding=encoding, errors="strict")
     root = Path(__file__).resolve().parents[1]
     expected = {"SKILL.md", "agents/openai.yaml", "scripts/bridge.py",
-                "scripts/instructions_transaction.py", "bridge.json"}
+                "scripts/instructions_transaction.py", "scripts/host_platform.py", "bridge.json"}
     try:
         paths = list(root.rglob("*"))
         if any(path.is_symlink() for path in paths):
@@ -32,6 +36,8 @@ def main() -> int:
             if not isinstance(config.get(key), str) or not Path(config[key]).is_absolute():
                 raise RuntimeError("registered bridge needs absolute private roots")
         sys.dont_write_bytecode = True
+        sys.path.insert(0, str(root / "scripts"))
+        from host_platform import cli_argv, python_argv, runtime_environment
         from instructions_transaction import confirmed_release, guard_pending, reject_symlink_ancestors
         state = Path(config["state_root"])
         reject_symlink_ancestors(state)
@@ -52,27 +58,38 @@ def main() -> int:
             if not isinstance(value, str) or (value and not Path(value).is_absolute()):
                 raise RuntimeError("registered bridge has an invalid managed runtime path")
             env["AGENT_LAUNCH_VENV"] = value
+        if "python_binding" in config:
+            bound = config["python_binding"]
+            if not isinstance(bound, dict):
+                raise RuntimeError('registered Python binding must be an object')
+            env.update(runtime_environment(bound))
         args = sys.argv[1:]
         command = args[0] if args else "session"
         tail = args[1:] if args else ["status", "--json"]
         if command == "bootstrap":
-            print((release / "compose/bootstrap/SKILL.md").read_text(encoding="utf-8"), end="")
+            text = (release / "compose/bootstrap/SKILL.md").read_text(encoding="utf-8")
+            if os.name == "nt":
+                prefix = "& '" + sys.executable.replace("'", "''") + "' '" + str(root / "scripts/bridge.py").replace("'", "''") + "' instructions"
+                text = text.replace('bash "$AGENT_BIOS_PACKAGE_ROOT/install.sh" instructions', prefix).replace('agent-bios instructions', prefix)
+            print(text, end="")
             return 0
         if command == "tui":
             operation = "instructions" if (release / "compose/instructions.py").is_file() else "corpus"
-            argv = ["/bin/bash", str(release / "install.sh"), operation, *tail]
+            argv = python_argv(release / 'compose/native_cli.py', operation, *tail, environ=env) if os.name == 'nt' else cli_argv(release, operation, *tail)
         elif command in {"setup", "instructions", "corpus", "import", "learn"}:
             if command == "instructions" and not (release / "compose/instructions.py").is_file():
                 command = "corpus"
-            argv = ["/bin/bash", str(release / "install.sh"), command, *tail]
+            argv = python_argv(release / 'compose/native_cli.py', command, *tail, environ=env) if os.name == 'nt' else cli_argv(release, command, *tail)
         elif command == "session":
             manager = release / "compose/instructions_app.py"
             if not manager.is_file():
                 manager = release / "compose/corpus_app.py"
-            argv = [sys.executable, str(manager), "--repo", str(release),
-                    "--state-dir", config["state_root"], "--user-dir", config["user_root"], "session", *tail]
+            argv = python_argv(manager, "--repo", str(release), "--state-dir", config["state_root"], "--user-dir", config["user_root"], "session", *tail, environ=env)
         else:
             raise RuntimeError("bridge supports setup, session, instructions, import, learn, bootstrap and tui")
+        if os.name == "nt":
+            import subprocess
+            return subprocess.call(argv, env=env)
         os.execve(argv[0], argv, env)
     except (OSError, RuntimeError, ValueError, KeyError) as exc:
         print(f"agent-bios app bridge: {exc}", file=sys.stderr)

package/compose/app_desktop/server.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""Claude Desktop MCP server for explicit agent-bios instructions delivery.
+
+It is a transport at the same layer as `compose/app_bridge/scripts/bridge.py`: it
+owns no selection, ContentRef, receipt or identifier. Each tool call resolves the
+confirmed private release again and runs that release's
+`compose/instructions_app.py session <op> --host claude-desktop` in a child
+process, so a package update answers from the next call and this long-lived
+process holds nothing across requests.
+
+Protocol 2025-11-25 over stdio, the revision Desktop speaks; a call that arrives
+without a handshake is still answered, because nothing here depends on one.
+Standard library only; stdout carries protocol messages and nothing else.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+from typing import Any
+
+HERE = Path(__file__).resolve().parent
+PROTOCOL = "2025-11-25"
+KNOWN_PROTOCOLS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+CALL_TIMEOUT = 120
+
+_SESSION_ID = {"type": "string", "description": "The session_id an earlier preview or use returned in this conversation."}
+_DOMAINS = {"type": "array", "items": {"type": "string"},
+            "description": "Only when the user names a selection; omit to use their saved installation selection."}
+# One owner: the bundle builder reads this list for the manifest.
+TOOLS = [
+    {"name": "status",
+     "description": "Show whether agent-bios instructions were delivered to this conversation. After reading a "
+                    "delivery to its last line, call this with end_marker_seen set to that line.",
+     "inputSchema": {"type": "object", "properties": {
+         "session_id": _SESSION_ID,
+         "end_marker_seen": {"type": "string", "description": "The delivery's last line, exactly as read."}},
+         "required": ["session_id"]}},
+    {"name": "preview",
+     "description": "Describe the agent-bios work environment use would return, without delivering it. "
+                    "Call only when the user asks for their agent-bios instructions or environment.",
+     "inputSchema": {"type": "object", "properties": {"session_id": _SESSION_ID, "domains": _DOMAINS}}},
+    {"name": "use",
+     "description": "Return the user's selected agent-bios work environment as context for this conversation. "
+                    "Call only when the user asks for it.",
+     "inputSchema": {"type": "object", "properties": {
+         "session_id": _SESSION_ID, "domains": _DOMAINS,
+         "expected_content_ref": {"type": "string", "description": "The content_ref preview returned, to refuse a changed snapshot."}}}},
+    {"name": "off",
+     "description": "Stop agent-bios delivery in this conversation. Text already returned stays in context.",
+     "inputSchema": {"type": "object", "properties": {"session_id": _SESSION_ID}, "required": ["session_id"]}},
+]
+
+
+class ToolError(RuntimeError):
+    pass
+
+
+def _config() -> dict[str, Any]:
+    config = json.loads((HERE / "desktop.json").read_text(encoding="utf-8"))
+    if config.get("schema_version") != 1:
+        raise ToolError("this agent-bios Desktop bundle has an unsupported configuration; generate it again with agent-bios app desktop")
+    for key in ("home", "state_root", "user_root"):
+        if not isinstance(config.get(key), str) or not Path(config[key]).is_absolute():
+            raise ToolError("this agent-bios Desktop bundle needs absolute private roots")
+    return config
+
+
+def _string(arguments: dict[str, Any], key: str) -> str | None:
+    value = arguments.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise ToolError(f"{key} must be a nonempty string")
+    return value.strip()
+
+
+def _argv(operation: str, arguments: dict[str, Any]) -> list[str]:
+    tail = ["--host", "claude-desktop"]
+    session = _string(arguments, "session_id")
+    if session is not None:
+        tail += ["--session", session]
+    if operation in {"preview", "use"} and arguments.get("domains") is not None:
+        domains = arguments["domains"]
+        if not isinstance(domains, list) or not domains or not all(isinstance(v, str) and v.strip() for v in domains):
+            raise ToolError("domains must be a nonempty list of selection names")
+        tail += ["--domains", ",".join(v.strip() for v in domains)]
+    if operation == "use" and (ref := _string(arguments, "expected_content_ref")) is not None:
+        tail += ["--expected-content-ref", ref]
+    if operation == "status" and (marker := _string(arguments, "end_marker_seen")) is not None:
+        tail += ["--end-marker-seen", marker]
+    return tail
+
+
+def run_session(operation: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    config = _config()
+    sys.dont_write_bytecode = True
+    sys.path.insert(0, str(HERE))
+    from host_platform import python_argv, runtime_environment
+    from instructions_transaction import confirmed_release, guard_pending, reject_symlink_ancestors
+    state = Path(config["state_root"])
+    reject_symlink_ancestors(state)
+    reject_symlink_ancestors(Path(config["user_root"]))
+    guard_pending(state)
+    release = confirmed_release(state)
+    reject_symlink_ancestors(release)
+    env = dict(os.environ)
+    env.update({"HOME": config["home"], "AGENT_BIOS_STATE_DIR": config["state_root"],
+                "AGENT_BIOS_INSTRUCTIONS_DIR": config["user_root"], "AGENT_BIOS_CORPUS_DIR": config["user_root"],
+                "AGENT_BIOS_PACKAGE_ROOT": str(release), "AGENT_BIOS_PRIVATE_INSTRUCTIONS": "1",
+                "AGENT_BIOS_PRIVATE_CORPUS": "1", "AGENT_BIOS_LEGACY_INSTALL": "0",
+                "PYTHONDONTWRITEBYTECODE": "1"})
+    if "python_binding" in config:
+        if not isinstance(config["python_binding"], dict):
+            raise ToolError("the bundle's Python binding must be an object")
+        env.update(runtime_environment(config["python_binding"]))
+    manager = release / "compose/instructions_app.py"
+    argv = python_argv(manager, "--repo", str(release), "--state-dir", config["state_root"],
+                       "--user-dir", config["user_root"], "--json", "session", operation,
+                       *_argv(operation, arguments), environ=env)
+    try:
+        done = subprocess.run(argv, env=env, stdin=subprocess.DEVNULL, capture_output=True,
+                              text=True, encoding="utf-8", timeout=CALL_TIMEOUT)
+    except subprocess.TimeoutExpired as exc:
+        raise ToolError(f"agent-bios did not answer within {CALL_TIMEOUT} seconds") from exc
+    if done.returncode != 0:
+        raise ToolError(done.stderr.strip() or f"agent-bios session {operation} failed")
+    try:
+        return json.loads(done.stdout)
+    except ValueError as exc:
+        raise ToolError("agent-bios returned an unreadable session result") from exc
+
+
+def _scope(result: dict[str, Any]) -> str:
+    return ("Project scope: none. Desktop names no project, so project-scoped imported "
+            "instructions are not included.") if result.get("project_scope") == "none" else ""
+
+
+def _size_note(result: dict[str, Any]) -> str:
+    if not result.get("host_may_save_to_file"):
+        return ""
+    return (f"{result['instruction_bytes']} bytes is above the smallest limit Desktop has kept inline; "
+            "Desktop may save this result to a file instead of showing it.")
+
+
+def _unavailable(result: dict[str, Any]) -> str:
+    items = result.get("unavailable") or []
+    names = [f"{item.get('ref')} ({item.get('reason')})" if isinstance(item, dict) else str(item) for item in items]
+    return "Not included: " + "; ".join(names) if names else ""
+
+
+def render(operation: str, result: dict[str, Any]) -> str:
+    session = result.get("session_id")
+    if operation == "use" and isinstance(result.get("instruction_text"), str):
+        lines = [f"agent-bios session_id: {session} — pass it to status, off and use in this conversation.",
+                 f"content_ref: {result['content_ref']}", _scope(result), _size_note(result)]
+        if result.get("repeat"):
+            lines.append("Same snapshot as this conversation's latest delivery; returned again with its existing receipt.")
+        lines.append(_unavailable(result))
+        lines.append("The text below ends with a line beginning 'agent-bios end'. After reading to it, "
+                     "call status with that whole line as end_marker_seen.")
+        header = "\n".join(line for line in lines if line)
+        return f"{header}\n\n{result['instruction_text'].rstrip()}\n\n{result['end_marker']}"
+    if operation == "preview":
+        if result.get("selection_mode") == "none":
+            return f"agent-bios session_id: {session}\nNo instructions are selected; use would return nothing."
+        lines = [f"agent-bios session_id: {session} — pass it to use, status and off in this conversation.",
+                 f"content_ref: {result['content_ref']}",
+                 f"Size: {result.get('instruction_characters')} characters, {result.get('instruction_bytes')} bytes.",
+                 _scope(result), _size_note(result),
+                 _unavailable(result),
+                 "Nothing was delivered. Call use to return this text."]
+        return "\n".join(line for line in lines if line)
+    lines = [f"agent-bios session_id: {session}",
+             f"Delivery: {'on' if result.get('enabled') else 'off'}; "
+             f"deliveries recorded: {len(result.get('deliveries', []))}.",
+             f"Latest delivery read to its end: {'yes' if result.get('latest_end_confirmed') else 'no'}."
+             if result.get("ever_delivered") else "",
+             result.get("message", "")]
+    return "\n".join(line for line in lines if line)
+
+
+def call_tool(params: dict[str, Any]) -> dict[str, Any]:
+    name = params.get("name")
+    arguments = params.get("arguments") or {}
+    if name not in {tool["name"] for tool in TOOLS}:
+        return {"content": [{"type": "text", "text": f"unknown tool: {name}"}], "isError": True}
+    if not isinstance(arguments, dict):
+        return {"content": [{"type": "text", "text": "arguments must be an object"}], "isError": True}
+    try:
+        text = render(name, run_session(name, arguments))
+        return {"content": [{"type": "text", "text": text}], "isError": False}
+    except (ToolError, OSError, RuntimeError, ValueError, KeyError) as exc:
+        return {"content": [{"type": "text", "text": f"agent-bios: {exc}"}], "isError": True}
+
+
+def respond(message: Any) -> dict[str, Any] | None:
+    if not isinstance(message, dict):
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "expected one JSON-RPC request object"}}
+    method, ident = message.get("method"), message.get("id")
+    params = message.get("params") if isinstance(message.get("params"), dict) else {}
+    if method == "initialize":
+        asked = params.get("protocolVersion")
+        result: dict[str, Any] = {"protocolVersion": asked if asked in KNOWN_PROTOCOLS else PROTOCOL,
+                                  "capabilities": {"tools": {}},
+                                  "serverInfo": {"name": "agent-bios", "version": _version()}}
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = {"tools": TOOLS}
+    elif method == "tools/call":
+        result = call_tool(params)
+    elif ident is None:
+        return None
+    else:
+        return {"jsonrpc": "2.0", "id": ident, "error": {"code": -32601, "message": f"method not supported: {method}"}}
+    return None if ident is None else {"jsonrpc": "2.0", "id": ident, "result": result}
+
+
+def _version() -> str:
+    try:
+        return str(json.loads((HERE.parent / "manifest.json").read_text(encoding="utf-8"))["version"])
+    except (OSError, ValueError, KeyError):
+        return "unknown"
+
+
+def main() -> int:
+    for stream in (sys.stdin, sys.stdout):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8")
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            message = json.loads(line)
+        except ValueError:
+            reply: dict[str, Any] | None = {"jsonrpc": "2.0", "id": None,
+                                            "error": {"code": -32700, "message": "parse error"}}
+        else:
+            reply = respond(message)
+        if reply is not None:
+            sys.stdout.write(json.dumps(reply, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/compose/domains.json

@@ -108,6 +108,7 @@
     "slide-writing.md": {"tier": "domain", "domains": ["office-work", "visualization-docs"], "item_id": "skill-slide-writing"},
     "verification-discipline.md": {"tier": "domain", "domains": ["builder-base"], "item_id": "guide-verification-discipline"},
     "tooling-gotchas.md": {"tier": "domain", "domains": ["builder-base"], "item_id": "guide-tooling-gotchas"},
+    "ui-design.md": {"tier": "domain", "domains": ["builder-base"], "item_id": "guide-ui-design"},
     "korean-writing.md": {"tier": "core", "domains": [], "item_id": "korean-writing"}
   },
   "hooks": {