@sangyaahub/pi-marg 1.0.0

package/core/model-routing.ts

@@ -0,0 +1,348 @@
+export type AutoStage = "A" | "B" | "C" | "D";
+export type CandidateTier = "frontier" | "execution";
+export type RuntimeName = "OMP" | "Pi";
+
+export interface ModelLike {
+  provider: string;
+  id: string;
+  name?: string;
+  cost?: Record<string, unknown>;
+}
+
+export interface ModelCandidate {
+  selector: string;
+  identity: string;
+  label: string;
+  provider: string;
+  tier: CandidateTier;
+  choice:
+    | "claude-frontier"
+    | "openai-frontier"
+    | "grok-frontier"
+    | "claude-mid"
+    | "openai-mid"
+    | "cursor-composer"
+    | "included-cursor"
+    | "devin-swe"
+    | "included-devin"
+    | "devin-external";
+  access: "runtime-model" | "external-agent";
+  billingNote?: string;
+}
+
+export interface ModelSelection extends ModelCandidate {
+  selectedAt: string;
+}
+
+export interface ModelRouteState {
+  version: 1;
+  workType?: number;
+  selections: Partial<Record<AutoStage, ModelSelection>>;
+}
+
+export interface ModelRouteParams {
+  action: "catalog" | "select" | "activate" | "status";
+  stage?: AutoStage;
+  target?: string;
+  workType?: number;
+}
+
+export interface ModelRoutePort {
+  runtimeName: RuntimeName;
+  models: ModelLike[];
+  hasExternalDevin: boolean;
+  activate(model: ModelLike): Promise<boolean | void>;
+  persist(state: ModelRouteState): void;
+  now?(): string;
+}
+
+export interface ModelRouteExecution {
+  state: ModelRouteState;
+  response: ReturnType<typeof toolResult>;
+}
+
+export const MODEL_STATE_TYPE = "co.sangyaa.pi-marg.model-routing.v1";
+export const STAGES: AutoStage[] = ["A", "B", "C", "D"];
+
+const FRONTIER_PATTERNS: Array<[ModelCandidate["choice"], RegExp]> = [
+  ["claude-frontier", /(?:claude[^\n]*(?:fable|opus)|(?:fable|opus)[^\n]*claude)/i],
+  ["openai-frontier", /(?:gpt[^\n]*(?:astra|\bsol\b)|(?:astra|\bsol\b)[^\n]*gpt)/i],
+  ["grok-frontier", /grok[^\n]*4[._ -](?:[6-9]|\d{2,})(?:\b|[-_])/i],
+];
+
+const EXECUTION_PATTERNS: Array<[ModelCandidate["choice"], RegExp]> = [
+  ["claude-mid", /claude[^\n]*sonnet/i],
+  ["openai-mid", /(?:gpt|codex)[^\n]*(?:terra|luna|mini|codex)/i],
+  ["cursor-composer", /composer/i],
+];
+
+export function emptyModelRouteState(): ModelRouteState {
+  return { version: 1, selections: {} };
+}
+
+export function isStage(value: unknown): value is AutoStage {
+  return typeof value === "string" && STAGES.includes(value as AutoStage);
+}
+
+export function requiredStagesForWorkType(workType: number): AutoStage[] {
+  switch (workType) {
+    case 2:
+    case 3:
+      return ["A", "C", "B", "D"];
+    case 4:
+      return ["A", "B", "D"];
+    case 1:
+    case 5:
+    case 6:
+    case 7:
+      return ["A", "C"];
+    default:
+      return [];
+  }
+}
+
+export function normalizeModelIdentity(value: string): string {
+  let normalized = value
+    .toLowerCase()
+    .replace(/^[^/]+\//, "")
+    .replace(/(?:-latest|:latest)$/g, "")
+    .replace(/[^a-z0-9.]+/g, "-")
+    .replace(/^-|-$/g, "");
+
+  normalized = normalized
+    .replace(/^cursor-/, "")
+    .replace(/-\d{4}-(?:non-)?reasoning$/, "")
+    .replace(/-multi-agent-\d{4}$/, "")
+    .replace(/-\d{8}$/, "")
+    .replace(/(\d)-(?=\d)/g, "$1.")
+    .replace(/^claude-(\d+(?:\.\d+)?)-(opus|sonnet)/, "claude-$2-$1")
+    .replace(/-1m$/, "");
+
+  let previous: string;
+  do {
+    previous = normalized;
+    normalized = normalized.replace(
+      /-(?:thinking-)?(?:minimal|low|medium|high|xhigh|max|fast|lightning)$/,
+      "",
+    );
+  } while (normalized !== previous);
+
+  return normalized;
+}
+
+export function classifyModel(model: ModelLike): ModelCandidate | undefined {
+  const selector = `${model.provider}/${model.id}`;
+  const haystack = `${model.provider} ${model.id} ${model.name ?? ""}`;
+
+  for (const [choice, pattern] of FRONTIER_PATTERNS) {
+    if (pattern.test(haystack)) return candidate(model, selector, choice, "frontier");
+  }
+  for (const [choice, pattern] of EXECUTION_PATTERNS) {
+    if (pattern.test(haystack)) return candidate(model, selector, choice, "execution");
+  }
+
+  if (/^devin$/i.test(model.provider) && /^swe[-_. ]/i.test(model.id)) {
+    return candidate(model, selector, "devin-swe", "execution");
+  }
+  if (/cursor/i.test(model.provider) && isZeroMetered(model.cost)) {
+    return {
+      ...candidate(model, selector, "included-cursor", "execution"),
+      billingNote: "The runtime reports zero metered token cost; plan quotas or pool limits may still apply.",
+    };
+  }
+  if (/^devin$/i.test(model.provider) && isZeroMetered(model.cost)) {
+    return {
+      ...candidate(model, selector, "included-devin", "execution"),
+      billingNote: "The runtime reports zero metered token cost; Devin plan quotas or pool limits may still apply.",
+    };
+  }
+  return undefined;
+}
+
+export function buildModelCatalog(models: ModelLike[], hasExternalDevin: boolean) {
+  const candidates = models
+    .map(classifyModel)
+    .filter((item): item is ModelCandidate => Boolean(item))
+    .sort(compareCandidates);
+
+  if (hasExternalDevin) {
+    candidates.push({
+      selector: "devin/external-session",
+      identity: "devin-external-session",
+      label: "Devin external session",
+      provider: "devin",
+      tier: "execution",
+      choice: "devin-external",
+      access: "external-agent",
+      billingNote: "Uses Devin quota rather than a runtime model slot; session creation requires post-web approval.",
+    });
+  }
+
+  const frontier = candidates.filter((item) => item.tier === "frontier");
+  const execution = candidates.filter((item) => item.tier === "execution");
+  return { A: frontier, B: execution, C: frontier, D: execution } satisfies Record<AutoStage, ModelCandidate[]>;
+}
+
+export function validateDistinctSelection(
+  state: ModelRouteState,
+  stage: AutoStage,
+  candidate: ModelCandidate,
+): string | undefined {
+  const opposite: Record<AutoStage, AutoStage> = { A: "C", C: "A", B: "D", D: "B" };
+  const otherStage = opposite[stage];
+  const other = state.selections[otherStage];
+  if (other && other.identity === candidate.identity) {
+    return `Stage ${stage} cannot use ${candidate.label}; Stage ${otherStage} already uses the same model. Choose a different model.`;
+  }
+  return undefined;
+}
+
+export function restoreModelRouteState(entries: readonly any[]): ModelRouteState {
+  let restored = emptyModelRouteState();
+  for (const entry of entries) {
+    if (entry?.type === "custom" && entry.customType === MODEL_STATE_TYPE && entry.data?.version === 1) {
+      restored = entry.data as ModelRouteState;
+    }
+  }
+  return restored;
+}
+
+export async function executeModelRoute(
+  currentState: ModelRouteState,
+  params: ModelRouteParams,
+  port: ModelRoutePort,
+): Promise<ModelRouteExecution> {
+  const catalog = buildModelCatalog(port.models, port.hasExternalDevin);
+
+  if (params.action === "catalog") {
+    const workType = Number(params.workType);
+    const requiredStages = Number.isInteger(workType) ? requiredStagesForWorkType(workType) : STAGES;
+    return {
+      state: currentState,
+      response: toolResult(
+        JSON.stringify({ runtime: port.runtimeName, requiredStages, catalog, notes: catalogNotes(port.runtimeName, catalog) }, null, 2),
+        { runtime: port.runtimeName, requiredStages, catalog, state: currentState },
+      ),
+    };
+  }
+
+  if (params.action === "status") {
+    return { state: currentState, response: toolResult(JSON.stringify(currentState, null, 2), { state: currentState }) };
+  }
+
+  if (!isStage(params.stage)) {
+    return { state: currentState, response: toolResult("A valid stage A, B, C, or D is required.", { state: currentState }, true) };
+  }
+
+  const stage = params.stage;
+  if (params.action === "select") {
+    if (typeof params.target !== "string") {
+      return { state: currentState, response: toolResult("Select an exact selector from the current catalog.", { catalog, state: currentState }, true) };
+    }
+    const selected = catalog[stage].find((item) => item.selector === params.target);
+    if (!selected) {
+      return { state: currentState, response: toolResult(`Target ${params.target} is not an available Stage ${stage} choice. Refresh the catalog.`, { catalog, state: currentState }, true) };
+    }
+    const conflict = validateDistinctSelection(currentState, stage, selected);
+    if (conflict) return { state: currentState, response: toolResult(conflict, { catalog, state: currentState }, true) };
+
+    if (selected.access === "runtime-model") {
+      const model = port.models.find((item) => `${item.provider}/${item.id}` === selected.selector);
+      if (!model) return { state: currentState, response: toolResult("The selected model disappeared; refresh the catalog.", { state: currentState }, true) };
+      const activated = await port.activate(model);
+      if (activated === false) return { state: currentState, response: toolResult(`Could not activate ${selected.selector}; verify provider authentication.`, { state: currentState }, true) };
+    }
+
+    const workType = Number(params.workType);
+    const nextState: ModelRouteState = {
+      version: 1,
+      workType: Number.isInteger(workType) && workType >= 1 && workType <= 7 ? workType : currentState.workType,
+      selections: {
+        ...currentState.selections,
+        [stage]: { ...selected, selectedAt: port.now?.() ?? new Date().toISOString() },
+      },
+    };
+    port.persist(nextState);
+    return {
+      state: nextState,
+      response: toolResult(
+        selected.access === "external-agent"
+          ? `Selected ${selected.label} for Stage ${stage}. Obtain post-web approval before creating its session.`
+          : `Selected and activated ${selected.label} (${selected.selector}) for Stage ${stage}.`,
+        { state: nextState, selected },
+      ),
+    };
+  }
+
+  const selected = currentState.selections[stage];
+  if (!selected) {
+    return { state: currentState, response: toolResult(`No model is selected for Stage ${stage}. Run catalog, then select first.`, { state: currentState }, true) };
+  }
+  if (selected.access === "external-agent") {
+    if (!port.hasExternalDevin) return { state: currentState, response: toolResult("Devin was selected but no external Devin tool is available.", { state: currentState }, true) };
+    return { state: currentState, response: toolResult(`Stage ${stage} uses an external Devin session. Delegate only after post-web approval.`, { state: currentState, selected }) };
+  }
+  const model = port.models.find((item) => `${item.provider}/${item.id}` === selected.selector);
+  if (!model) return { state: currentState, response: toolResult(`Saved model ${selected.selector} is unavailable. Select a replacement.`, { state: currentState }, true) };
+  const activated = await port.activate(model);
+  if (activated === false) return { state: currentState, response: toolResult(`Could not activate ${selected.selector}; verify provider authentication.`, { state: currentState }, true) };
+  return { state: currentState, response: toolResult(`Activated ${selected.label} (${selected.selector}) for Stage ${stage}.`, { state: currentState, selected }) };
+}
+
+function candidate(
+  model: ModelLike,
+  selector: string,
+  choice: ModelCandidate["choice"],
+  tier: CandidateTier,
+): ModelCandidate {
+  return {
+    selector,
+    identity: normalizeModelIdentity(model.id),
+    label: model.name?.trim() || model.id,
+    provider: model.provider,
+    tier,
+    choice,
+    access: "runtime-model",
+  };
+}
+
+function isZeroMetered(cost: Record<string, unknown> | undefined): boolean {
+  if (!cost) return false;
+  const values = Object.values(cost).filter((value): value is number => typeof value === "number");
+  return values.length > 0 && values.every((value) => value === 0);
+}
+
+function versionParts(candidate: ModelCandidate): number[] {
+  return `${candidate.label} ${candidate.selector}`.match(/\d+(?:\.\d+)*/g)?.flatMap((part) => part.split(".").map(Number)) ?? [];
+}
+
+function compareCandidates(left: ModelCandidate, right: ModelCandidate): number {
+  if (left.choice !== right.choice) return left.choice.localeCompare(right.choice);
+  const a = versionParts(left);
+  const b = versionParts(right);
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (b[index] ?? 0) - (a[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return left.selector.localeCompare(right.selector);
+}
+
+function toolResult(text: string, details: unknown, isError = false) {
+  return {
+    content: [{ type: "text" as const, text }],
+    details,
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+function catalogNotes(runtimeName: RuntimeName, catalog: Record<AutoStage, ModelCandidate[]>): string[] {
+  const notes = [
+    `The catalog is built from ${runtimeName}'s authenticated model registry at call time; selectors are never guessed or pinned.`,
+    "A and C use frontier candidates. B and D use execution candidates, including eligible Cursor or Devin routes when the runtime exposes them.",
+    "Zero-metered describes the runtime's reported token price; it does not promise unlimited subscription usage.",
+  ];
+  if (catalog.A.length === 0) notes.push("No frontier matches are authenticated. Connect a provider, then refresh.");
+  if (catalog.B.length === 0) notes.push("No execution matches are authenticated and no external Devin tool was detected.");
+  return notes;
+}

package/core/runtime-capabilities.ts

@@ -0,0 +1,77 @@
+import type { RuntimeName } from "./model-routing";
+
+export interface RuntimeCapabilityReport {
+  runtime: RuntimeName;
+  tools: Record<string, boolean>;
+  commands: Record<string, boolean>;
+  memory: {
+    configured: boolean;
+    recall: boolean;
+    retain: boolean;
+    reflect: boolean;
+    learn: boolean;
+  };
+  notes: string[];
+}
+
+export const TOOL_CAPABILITIES = [
+  "codegraph_explore",
+  "lsp",
+  "ast_grep",
+  "ast_edit",
+  "task",
+  "checkpoint",
+  "rewind",
+  "debug",
+  "security_scan",
+  "eval",
+  "browser",
+  "computer",
+  "recall",
+  "retain",
+  "reflect",
+  "learn",
+] as const;
+
+export const COMMAND_CAPABILITIES = ["advisor", "review", "memory", "collab", "share"] as const;
+
+export function normalizeCapabilityNames(items: unknown[]): string[] {
+  return items
+    .map((item: any) => (typeof item === "string" ? item : String(item?.name ?? "")))
+    .filter(Boolean);
+}
+
+export function buildRuntimeCapabilityReport(
+  runtime: RuntimeName,
+  toolNames: string[],
+  commandNames: string[],
+  memoryConfigured: boolean,
+): RuntimeCapabilityReport {
+  const tools = new Set(toolNames.map((name) => name.trim().toLowerCase()));
+  const commands = new Set(commandNames.map((name) => name.trim().toLowerCase().replace(/^\//, "")));
+  const toolStatus = Object.fromEntries(TOOL_CAPABILITIES.map((name) => [name, tools.has(name)])) as Record<string, boolean>;
+  const commandStatus = Object.fromEntries(COMMAND_CAPABILITIES.map((name) => [name, commands.has(name)])) as Record<string, boolean>;
+  const notes: string[] = [];
+
+  if (!toolStatus.codegraph_explore) notes.push("CodeGraph tool integration is unavailable. Use an installed CodeGraph CLI through bash, or pause repository-wide architecture claims.");
+  if (!toolStatus.lsp) notes.push("Native LSP is unavailable. Use repository-native language tooling and label exact symbol analysis as limited.");
+  if (!toolStatus.checkpoint || !toolStatus.rewind) notes.push("Checkpoint/rewind is unavailable. Preserve decisions in the Markdown ledger and use normal compaction when needed.");
+  if (!toolStatus.security_scan) notes.push("Native security_scan is unavailable. Use repository-native scanners plus an independent read-only security review.");
+  if (!memoryConfigured) notes.push("No approved persistent-memory integration was detected. Write lessons.md locally and leave retention off.");
+  if (!commandStatus.advisor) notes.push(runtime === "Pi" ? "OMP Advisor is not native to Pi. Keep the required independent C/D stages instead." : "Advisor is unavailable. Keep the required independent C/D stages.");
+  if (!commandStatus.review) notes.push("Native review command is unavailable. Run the recorded C/D review contract directly.");
+
+  return {
+    runtime,
+    tools: toolStatus,
+    commands: commandStatus,
+    memory: {
+      configured: memoryConfigured,
+      recall: toolStatus.recall,
+      retain: toolStatus.retain,
+      reflect: toolStatus.reflect,
+      learn: toolStatus.learn,
+    },
+    notes,
+  };
+}

package/core/workflow-policy.ts

@@ -0,0 +1,3 @@
+export const UNIVERSAL_WORKFLOW_POLICY = `PiMarg is active.
+
+For each new substantive request, load and follow the auto-mode-router skill before solution work. Infer the likely intent first; confirm or ask only for missing choices that materially change the route. Establish job/client versus personal context, classify one of the seven work types, choose a dedicated skill spine or Option 4, discover live model choices, and enforce A different from C plus B different from D. Resume an active session for ordinary follow-ups instead of restarting intake. Keep the Markdown plan, decisions, evidence, and one session lesson. Use CodeGraph first for repository-wide architecture and impact when available. Never bypass PiMarg protected-action approvals.`;

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@sangyaahub/pi-marg",
+  "version": "1.0.0",
+  "description": "A governed, model-routed development path for Pi Agent and Oh My Pi.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sangyaa",
+  "homepage": "https://github.com/sangyaahub/pi-marg#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sangyaahub/pi-marg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sangyaahub/pi-marg/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "omp-plugin",
+    "pi-agent",
+    "oh-my-pi",
+    "agent-workflow",
+    "model-routing",
+    "approval-gates",
+    "multi-agent",
+    "sangyaa"
+  ],
+  "files": [
+    ".mcp.json",
+    ".omp-plugin",
+    "BRAND.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "MODEL-SETUP.md",
+    "PUBLISHING.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "adapters",
+    "agents",
+    "assets",
+    "commands",
+    "core",
+    "rules",
+    "scripts",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "validate": "./scripts/validate.sh"
+  },
+  "pi": {
+    "extensions": [
+      "./adapters/pi/extensions/approval-guard.ts",
+      "./adapters/pi/extensions/model-router.ts",
+      "./adapters/pi/extensions/runtime-capabilities.ts",
+      "./adapters/pi/extensions/workflow-bootstrap.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./adapters/pi/prompts"
+    ],
+    "image": "https://raw.githubusercontent.com/sangyaahub/pi-marg/main/assets/pi-marg-banner.png"
+  },
+  "omp": {
+    "extensions": [
+      "./adapters/omp/extensions/approval-guard.ts",
+      "./adapters/omp/extensions/model-router.ts",
+      "./adapters/omp/extensions/runtime-capabilities.ts"
+    ]
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  }
+}

package/rules/auto-mode.md

@@ -0,0 +1,32 @@
+---
+description: Start and enforce PiMarg for each new substantive task.
+alwaysApply: true
+---
+
+# PiMarg global rule
+
+For every new substantive user task, load and follow the `auto-mode-router` skill before doing the work.
+
+- Do not restart intake for acknowledgements, clarifications, approval replies, or follow-ups that belong to the active task.
+- If the conversation already contains an active Auto Mode session record, reuse it. Start a new intake only when the user starts a materially different task or invokes `/auto-reset`.
+- The first intake question is always whether the work is for a job/client or personal.
+- Confirm one of work types 1–7, then confirm skill mode 1–4 before execution.
+- After skill mode, use the live `auto_model_route` catalog and record required A/B/C/D choices. A and C must use different underlying models; B and D must use different underlying models.
+- Activate the saved model before each A/B/C/D stage. Never guess or pin a version absent from the active Pi or OMP registry.
+- Call `auto_runtime_status` during intake and route only through capabilities it reports available.
+- Use exactly one primary workflow spine for the task. Do not let multiple skill families maintain competing plans or state.
+- For work types 2–6, load `codegraph-first` and require a healthy initialized CodeGraph before repository-wide architecture or impact claims. Use detected LSP/AST or repository-native tools for precise questions. Never conceal missing graph coverage behind a broad grep/glob crawl.
+- Keep C and D as independent recorded review stages. A detected advisor may watch continuously, but it cannot approve actions or replace the final C/D verdict.
+- Use OMP `workflowz`/`orchestrate` or a detected `task` fan-out only when work is genuinely independent. Isolate parallel writes, integrate them into one canonical tree, and verify again before D.
+- Run conditional verification after B: repository checks always, DAP debugging for supported runtime defects, browser/desktop QA for affected user flows, and security review for type 5 or high-risk changes.
+- Use checkpoint/rewind only when the runtime exposes those tools with the documented disposable-investigation semantics. They are not filesystem checkpoints or stage-completion markers.
+- Ponytail, Hindsight, and language skills are supporting add-ons only. Verify they are discovered, isolate job/client memory, and never let them create a competing plan.
+- Prefer the runtime's detected memory integration. Recalled memory is heuristic; job/client retention stays off until policy permits it.
+- Track the plan, decisions, evidence, approval events, and lessons status in Markdown as defined by the router.
+- For job/client work, never add Sangyaa branding, names, logos, metadata, promotional copy, or footers unless the user explicitly approves that exact artifact. Preserve the existing client/employer brand.
+- For personal work, do not add Sangyaa branding automatically. Use it only when requested or already established by the project.
+- Never claim an unavailable skill, model, plugin, or tool was used. Offer a compatible route when a requested family is unavailable.
+- Before final completion, run `session-lessons` exactly once for the active Auto Mode session and record it in the session ledger.
+- After review passes, offer a local commit through the runtime or repository-native path. Never combine that step with push or merge.
+- Keep `/collab` and `/share` off by default when present. Both require one-use `post-web` approval; job/client sharing should default to view-only.
+- Delete/remove actions, pushing to main, merging a PR, and posting or publishing to a web platform require explicit one-use user approval. The runtime guard is authoritative when it blocks a tool.

package/scripts/check-prerequisites.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+found_runtime="false"
+
+if command -v pi >/dev/null 2>&1; then
+  echo "[ok] Pi: $(pi --version 2>/dev/null | head -n 1)"
+  found_runtime="true"
+else
+  echo "[optional] Pi is not on PATH"
+fi
+
+if command -v omp >/dev/null 2>&1; then
+  echo "[ok] OMP: $(omp --version 2>/dev/null | head -n 1)"
+  found_runtime="true"
+else
+  echo "[optional] OMP is not on PATH"
+fi
+
+if [[ "${found_runtime}" != "true" ]]; then
+  echo "Install Pi or OMP before installing PiMarg." >&2
+  exit 1
+fi
+
+if command -v codegraph >/dev/null 2>&1; then
+  echo "[ok] CodeGraph CLI is available"
+else
+  echo "[optional] CodeGraph is missing; use setup-codegraph.sh for existing repositories"
+fi
+
+for tool in git bun; do
+  if command -v "${tool}" >/dev/null 2>&1; then
+    echo "[ok] ${tool} is available"
+  else
+    echo "[optional] ${tool} is not on PATH"
+  fi
+done

package/scripts/install.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+runtime=""
+mode="dry-run"
+
+usage() {
+  echo "Usage: $0 --runtime <pi|omp|both> [--apply]" >&2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --runtime)
+      [[ $# -ge 2 ]] || { usage; exit 2; }
+      runtime="$2"
+      shift 2
+      ;;
+    --apply)
+      mode="apply"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+case "${runtime}" in
+  pi|omp|both) ;;
+  *)
+    echo "--runtime must be pi, omp, or both." >&2
+    usage
+    exit 2
+    ;;
+esac
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+package_root="$(cd "${script_dir}/.." && pwd)"
+
+print_pi() {
+  echo "[Pi] pi install ${package_root}"
+}
+
+print_omp() {
+  echo "[OMP] omp plugin marketplace add ${package_root}"
+  echo "[OMP] omp plugin install --scope user pi-marg@pi-marg-marketplace"
+}
+
+if [[ "${mode}" == "dry-run" ]]; then
+  echo "Preview only; no configuration will be changed."
+  [[ "${runtime}" == "pi" || "${runtime}" == "both" ]] && print_pi
+  [[ "${runtime}" == "omp" || "${runtime}" == "both" ]] && print_omp
+  echo "Run again with --apply to install."
+  exit 0
+fi
+
+if [[ "${runtime}" == "pi" || "${runtime}" == "both" ]]; then
+  command -v pi >/dev/null 2>&1 || { echo "Pi is not available on PATH." >&2; exit 1; }
+  pi install "${package_root}"
+fi
+
+if [[ "${runtime}" == "omp" || "${runtime}" == "both" ]]; then
+  command -v omp >/dev/null 2>&1 || { echo "OMP is not available on PATH." >&2; exit 1; }
+  omp plugin marketplace add "${package_root}"
+  omp plugin install --scope user pi-marg@pi-marg-marketplace
+fi
+
+echo "PiMarg v1.0.0 installed for ${runtime}. Start a fresh runtime session, then run /auto-runtime status."