open-research-protocol 0.4.17 → 0.4.19

package/README.md

@@ -1,6 +1,6 @@
 # ORP — Open Research Protocol
 
-Maintained by Fractal Research Group (`frg.earth`).
+Maintained by SproutSeeds. Research stewardship: Fractal Research Group ([frg.earth](https://frg.earth)).
 
 [![npm version](https://img.shields.io/npm/v/open-research-protocol?color=111111&label=npm)](https://www.npmjs.com/package/open-research-protocol)
 [![npm downloads](https://img.shields.io/npm/dm/open-research-protocol?color=111111&label=downloads)](https://www.npmjs.com/package/open-research-protocol)
@@ -443,6 +443,11 @@ If you are using ORP normally, prefer:
 Reach for `orp pack ...` when you are doing advanced installs, ORP maintenance,
 or direct domain-template work.
 
+Pack installation is pack-owned: `pack.yml` can describe installable
+components, default includes, dependency checks, and report naming. That lets
+ORP consume repo-owned external packs through `--pack-path` without baking
+domain-specific install rules into ORP core.
+
 Install pack configs into a target repo (recommended):
 
 ```bash

package/cli/orp.py

@@ -8940,7 +8940,7 @@ def _about_payload() -> dict[str, Any]:
             "Frontier control is a built-in ORP ability exposed through `orp frontier ...`, separating the exact live point, the exact active milestone, the near structured checklist, and the farther major-version stack.",
             "Agent modes are lightweight optional overlays for taste, perspective shifts, and fresh movement; `orp mode nudge sleek-minimal-progressive --json` gives agents a deterministic reminder they can call on when they want a deeper, wider, top-down, or rotated lens without changing ORP's core artifact boundaries.",
             "Project/session linking is a built-in ORP ability exposed through `orp link ...` and stored machine-locally under `.git/orp/link/`.",
-            "Hosted secret inventory remains the canonical source of truth, while the local macOS Keychain cache is inspectable and usable through `orp secrets list`, `orp secrets ensure`, `orp secrets keychain-list`, `orp secrets sync-keychain`, and `orp secrets resolve --local-first`.",
+            "Secrets are easiest to understand as saved keys and tokens: humans usually run `orp secrets add ...` and paste the value at the prompt, agents usually pipe the value with `--value-stdin`, and local macOS Keychain caching plus hosted sync are optional layers on top.",
             "Machine runner identity, heartbeat, hosted sync, prompt-job execution, and lease control are built into ORP through `orp runner status`, `orp runner enable`, `orp runner disable`, `orp runner heartbeat`, `orp runner sync`, `orp runner work`, `orp runner cancel`, and `orp runner retry`.",
             "Repo governance is built into ORP through `orp init`, `orp status`, `orp branch start`, `orp checkpoint create`, `orp backup`, `orp ready`, `orp doctor`, and `orp cleanup`.",
             "Hosted workspace operations are built directly into ORP under `orp workspaces ...`, plus the linked auth/ideas/feature/world/checkpoint/agent surfaces.",
@@ -9046,11 +9046,11 @@ def _home_payload(repo_root: Path, config_arg: str) -> dict[str, Any]:
             "command": "orp workspace list",
         },
         {
-            "label": "Print exact copyable crash-recovery commands for the main workspace",
+            "label": "Inspect saved paths and exact recovery commands for the main workspace",
             "command": "orp workspace tabs main",
         },
         {
-            "label": "Add a new provider key interactively when you need one",
+            "label": "Save a new API key or token interactively when you need one",
             "command": 'orp secrets add --alias <alias> --label "<label>" --provider <provider>',
         },
         {
@@ -9076,10 +9076,6 @@ def _home_payload(repo_root: Path, config_arg: str) -> dict[str, Any]:
             "label": "Inspect the saved workspace ledger inventory",
             "command": "orp workspace list",
         },
-        {
-            "label": "Print exact copyable crash-recovery commands for the main workspace",
-            "command": "orp workspace tabs main",
-        },
         {
             "label": "Inspect the saved tabs in the main workspace ledger",
             "command": "orp workspace tabs main",
@@ -9113,11 +9109,11 @@ def _home_payload(repo_root: Path, config_arg: str) -> dict[str, Any]:
             "command": "orp workspaces list --json",
         },
         {
-            "label": "Inspect the global ORP secret inventory",
+            "label": "Inspect saved keys and tokens already known to ORP",
             "command": "orp secrets list --json",
         },
         {
-            "label": "Reuse a saved provider key or prompt for it and save it for this project",
+            "label": "Reuse a saved key or prompt for it and save it for this project",
             "command": "orp secrets ensure --alias <alias> --provider <provider> --current-project --json",
         },
         {
@@ -9408,11 +9404,11 @@ def _home_payload(repo_root: Path, config_arg: str) -> dict[str, Any]:
             },
             {
                 "id": "secrets",
-                "description": "Saved API keys and tokens, with create-if-missing flows, optional local macOS Keychain caching, and project-scoped resolution.",
+                "description": "Saved API keys and tokens, with an interactive human flow, a stdin agent flow, optional local macOS Keychain caching, and optional hosted sync.",
                 "entrypoints": [
                     "orp secrets list --json",
                     "orp secrets show <alias-or-id> --json",
-                    "orp secrets add --alias <alias> --provider <provider> --current-project",
+                    'orp secrets add --alias <alias> --label "<label>" --provider <provider>',
                     "orp secrets ensure --alias <alias> --provider <provider> --current-project --json",
                     "orp secrets keychain-list --json",
                     "orp secrets keychain-show <alias-or-id> --json",
@@ -9614,14 +9610,34 @@ def _render_home_screen(payload: dict[str, Any]) -> str:
     lines.append("")
     lines.append("Command Families")
     if isinstance(abilities, list) and abilities:
-        for row in abilities:
+        ability_map = {
+            str(row.get("id", "")).strip(): row
+            for row in abilities
+            if isinstance(row, dict) and str(row.get("id", "")).strip()
+        }
+        visible_ability_ids = [
+            "workspace",
+            "secrets",
+            "governance",
+            "frontier",
+            "schedule",
+            "modes",
+            "hosted",
+            "discover",
+        ]
+        shown = 0
+        for ability_id in visible_ability_ids:
+            row = ability_map.get(ability_id)
             if not isinstance(row, dict):
                 continue
-            ability_id = str(row.get("id", "")).strip()
             desc = _truncate(str(row.get("description", "")).strip())
             lines.append(f"  - {ability_id}")
             if desc:
                 lines.append(f"    {desc}")
+            shown += 1
+        remaining = max(len(ability_map) - shown, 0)
+        if remaining:
+            lines.append(f"  - ... and {remaining} more in `orp about --json`")
 
     lines.append("")
     lines.append("Collaboration")
@@ -9652,7 +9668,7 @@ def _render_home_screen(payload: dict[str, Any]) -> str:
     lines.append("")
     lines.append("Quick Actions")
     if isinstance(quick_actions, list):
-        for row in quick_actions[:14]:
+        for row in quick_actions[:10]:
             if not isinstance(row, dict):
                 continue
             label = str(row.get("label", "")).strip()
@@ -9661,7 +9677,7 @@ def _render_home_screen(payload: dict[str, Any]) -> str:
                 continue
             lines.append(f"  - {label}")
             lines.append(f"    {command}")
-        remaining = max(len(quick_actions) - 14, 0)
+        remaining = max(len(quick_actions) - 10, 0)
         if remaining:
             lines.append(f"  - ... and {remaining} more in `orp home --json`")
 
@@ -18544,10 +18560,31 @@ def build_parser() -> argparse.ArgumentParser:
     add_json_flag(s_youtube_inspect)
     s_youtube_inspect.set_defaults(func=cmd_youtube_inspect, json_output=False)
 
-    s_secrets = sub.add_parser("secrets", help="Hosted secret store and project binding operations")
+    s_secrets = sub.add_parser(
+        "secrets",
+        help="Save and reuse API keys and tokens locally, with optional hosted sync",
+        description=(
+            "ORP secrets are easiest to understand as saved keys and tokens.\n\n"
+            "Human flow:\n"
+            "  1. Run `orp secrets add ...`\n"
+            "  2. Paste the value when ORP prompts `Secret value:`\n"
+            "  3. Later run `orp secrets list` or `orp secrets resolve ...`\n\n"
+            "Agent flow:\n"
+            "  - Pipe the value with `--value-stdin` instead of typing it interactively.\n\n"
+            "Local macOS Keychain caching and hosted sync are optional layers on top."
+        ),
+        epilog=(
+            "Examples:\n"
+            "  orp secrets add --alias openai-primary --label \"OpenAI Primary\" --provider openai\n"
+            "  printf '%s' 'sk-...' | orp secrets add --alias openai-primary --label \"OpenAI Primary\" --provider openai --value-stdin\n"
+            "  orp secrets list\n"
+            "  orp secrets resolve openai-primary --reveal"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
     secrets_sub = s_secrets.add_subparsers(dest="secrets_cmd", required=True)
 
-    s_secrets_list = secrets_sub.add_parser("list", help="List hosted secrets for the current user")
+    s_secrets_list = secrets_sub.add_parser("list", help="List saved secrets known to ORP")
     s_secrets_list.add_argument("--provider", default="", help="Optional provider filter")
     add_secret_scope_flags(s_secrets_list)
     s_secrets_list.add_argument(
@@ -18559,13 +18596,16 @@ def build_parser() -> argparse.ArgumentParser:
     add_json_flag(s_secrets_list)
     s_secrets_list.set_defaults(func=cmd_secrets_list, json_output=False)
 
-    s_secrets_show = secrets_sub.add_parser("show", help="Show one hosted secret by alias or id")
+    s_secrets_show = secrets_sub.add_parser("show", help="Show one saved secret by alias or id")
     s_secrets_show.add_argument("secret_ref", help="Secret alias or id")
     add_base_url_flag(s_secrets_show)
     add_json_flag(s_secrets_show)
     s_secrets_show.set_defaults(func=cmd_secrets_show, json_output=False)
 
-    s_secrets_add = secrets_sub.add_parser("add", help="Create a hosted secret")
+    s_secrets_add = secrets_sub.add_parser(
+        "add",
+        help="Save a new secret; ORP prompts for the value unless you pass --value-stdin",
+    )
     s_secrets_add.add_argument("--alias", required=True, help="Stable secret alias")
     s_secrets_add.add_argument("--label", required=True, help="Human label for the secret")
     s_secrets_add.add_argument("--provider", required=True, help="Provider slug, for example openai")
@@ -18596,7 +18636,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     s_secrets_ensure = secrets_sub.add_parser(
         "ensure",
-        help="Use an existing hosted secret by alias or create it and bind it when missing",
+        help="Reuse a saved secret or prompt for it and save it when missing",
     )
     s_secrets_ensure.add_argument("--alias", required=True, help="Stable secret alias")
     s_secrets_ensure.add_argument("--label", default="", help="Human label for create-if-missing flows")
@@ -18637,7 +18677,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     s_secrets_keychain_list = secrets_sub.add_parser(
         "keychain-list",
-        help="List locally cached macOS Keychain secrets known to ORP on this machine",
+        help="List local macOS Keychain copies known to ORP on this machine",
     )
     s_secrets_keychain_list.add_argument("--provider", default="", help="Optional provider filter")
     add_secret_scope_flags(s_secrets_keychain_list)
@@ -18646,7 +18686,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     s_secrets_keychain_show = secrets_sub.add_parser(
         "keychain-show",
-        help="Show one locally cached macOS Keychain secret by alias or id",
+        help="Show one local macOS Keychain copy by alias or id",
     )
     s_secrets_keychain_show.add_argument("secret_ref", help="Secret alias or id")
     s_secrets_keychain_show.add_argument(
@@ -18659,7 +18699,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     s_secrets_sync_keychain = secrets_sub.add_parser(
         "sync-keychain",
-        help="Sync hosted secrets into the local macOS Keychain",
+        help="Copy one saved secret into the local macOS Keychain",
     )
     s_secrets_sync_keychain.add_argument("secret_ref", nargs="?", default="", help="Optional secret alias or id")
     s_secrets_sync_keychain.add_argument("--provider", default="", help="Provider slug for project-scoped sync")
@@ -18673,7 +18713,7 @@ def build_parser() -> argparse.ArgumentParser:
     add_json_flag(s_secrets_sync_keychain)
     s_secrets_sync_keychain.set_defaults(func=cmd_secrets_sync_keychain, json_output=False)
 
-    s_secrets_update = secrets_sub.add_parser("update", help="Update one hosted secret")
+    s_secrets_update = secrets_sub.add_parser("update", help="Update one saved secret")
     s_secrets_update.add_argument("secret_ref", help="Secret alias or id")
     s_secrets_update.add_argument("--alias", default=None, help="New alias")
     s_secrets_update.add_argument("--label", default=None, help="New label")
@@ -18702,13 +18742,13 @@ def build_parser() -> argparse.ArgumentParser:
     add_json_flag(s_secrets_update)
     s_secrets_update.set_defaults(func=cmd_secrets_update, json_output=False)
 
-    s_secrets_archive = secrets_sub.add_parser("archive", help="Archive one hosted secret")
+    s_secrets_archive = secrets_sub.add_parser("archive", help="Archive one saved secret")
     s_secrets_archive.add_argument("secret_ref", help="Secret alias or id")
     add_base_url_flag(s_secrets_archive)
     add_json_flag(s_secrets_archive)
     s_secrets_archive.set_defaults(func=cmd_secrets_archive, json_output=False)
 
-    s_secrets_bind = secrets_sub.add_parser("bind", help="Bind one secret to a hosted project/world")
+    s_secrets_bind = secrets_sub.add_parser("bind", help="Bind one saved secret to a hosted project/world")
     s_secrets_bind.add_argument("secret_ref", help="Secret alias or id")
     add_secret_scope_flags(s_secrets_bind)
     s_secrets_bind.add_argument("--purpose", default="", help="Optional project usage note")
@@ -18729,7 +18769,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     s_secrets_resolve = secrets_sub.add_parser(
         "resolve",
-        help="Resolve one hosted secret by alias/id or by provider plus project scope",
+        help="Resolve one saved secret by alias/id or by provider plus project scope",
     )
     s_secrets_resolve.add_argument("secret_ref", nargs="?", default="", help="Optional secret alias or id")
     s_secrets_resolve.add_argument("--provider", default="", help="Provider slug for project-scoped resolution")

package/docs/PROFILE_PACKS.md

@@ -39,6 +39,7 @@ Canonical fields:
 - `pack_id`: stable id
 - `name`, `version`, `description`
 - `orp_version_min`: optional compatibility floor
+- `install`: optional install contract for `orp pack install`
 - `variables`: render-time variables (for example `TARGET_REPO_ROOT`)
 - `templates`: available config templates
 
@@ -80,6 +81,10 @@ orp pack fetch \
   --install-target /path/to/repo
 ```
 
+Repo-owned local packs can also be installed directly with `--pack-path` as
+long as their `pack.yml` includes an `install` block describing components,
+default includes, and dependency-audit paths.
+
 This installs rendered config files and writes a dependency audit report:
 
 - `./orp.erdos-catalog-sync.yml`
@@ -218,6 +223,9 @@ orp erdos sync --problem-id 857 --problem-id 20
 - Packs can live in this repo (`packs/`) or external repos.
 - Users can copy/install packs without changing ORP core.
 - Version packs independently (for example `0.1.0`, `0.2.0`).
+- Repo-owned packs can ship their own install metadata in `pack.yml`, so ORP
+  can install external domain packs without hardcoding those domains into ORP
+  core.
 
 ## Quality guidance
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "ORP CLI (Open Research Protocol): workspace ledgers, secrets, scheduling, governed execution, and agent-friendly research workflows.",
   "license": "MIT",
   "author": "Fractal Research Group <cody@frg.earth>",

package/packages/orp-workspace-launcher/src/ledger.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import process from "node:process";
 
 import {
-  buildCanonicalResumeCommand,
+  buildDirectCommand,
   deriveBaseTitle,
   normalizeWorkspaceManifest,
   parseWorkspaceSource,
@@ -44,6 +44,17 @@ function validateAbsolutePath(value, label) {
   return normalized;
 }
 
+function resolveCurrentCodexResume() {
+  const sessionId = normalizeOptionalString(process.env.CODEX_THREAD_ID);
+  if (!sessionId) {
+    throw new Error("`--current-codex` requires `CODEX_THREAD_ID` in the current environment.");
+  }
+  return {
+    resumeTool: "codex",
+    resumeSessionId: sessionId,
+  };
+}
+
 function serializeManifest(manifest) {
   return `${JSON.stringify(materializeWorkspaceManifest(manifest), null, 2)}\n`;
 }
@@ -63,6 +74,26 @@ function materializeWorkspaceTab(tab) {
   );
 }
 
+function buildWorkspaceResultTab(tab) {
+  if (!tab) {
+    return null;
+  }
+  const materialized = materializeWorkspaceTab(tab);
+  return {
+    ...materialized,
+    restartCommand: buildDirectCommand(
+      {
+        path: materialized.path,
+        resumeCommand: materialized.resumeCommand || null,
+        resumeTool: materialized.resumeTool || null,
+        sessionId: materialized.resumeSessionId || null,
+        resumeSessionId: materialized.resumeSessionId || null,
+      },
+      { resume: true },
+    ),
+  };
+}
+
 function materializeWorkspaceManifest(manifest) {
   const normalized = normalizeWorkspaceManifest(manifest);
   return Object.fromEntries(
@@ -122,10 +153,16 @@ function normalizeEditableManifest(source, parsed) {
   return normalizeWorkspaceManifest(baseManifest);
 }
 
-function parseLedgerSelectorArgs(argv = [], { commandName, requirePath = false, requireSelector = true } = {}) {
+function parseLedgerSelectorArgs(
+  argv = [],
+  { commandName, requirePath = false, requireSelector = true, allowAppend = false, allowHere = false, allowCurrentCodex = false } = {},
+) {
   const options = {
     json: false,
     all: false,
+    append: false,
+    here: false,
+    currentCodex: false,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -143,6 +180,18 @@ function parseLedgerSelectorArgs(argv = [], { commandName, requirePath = false,
       options.all = true;
       continue;
     }
+    if (allowAppend && arg === "--append") {
+      options.append = true;
+      continue;
+    }
+    if (allowHere && arg === "--here") {
+      options.here = true;
+      continue;
+    }
+    if (allowCurrentCodex && arg === "--current-codex") {
+      options.currentCodex = true;
+      continue;
+    }
     if (arg.startsWith("--")) {
       const next = argv[index + 1];
       if (next == null || next.startsWith("--")) {
@@ -190,12 +239,24 @@ function parseLedgerSelectorArgs(argv = [], { commandName, requirePath = false,
   if (requireSelector && !options.ideaId && !options.workspaceFile && !options.hostedWorkspaceId) {
     throw new Error(`Provide a workspace selector for \`${commandName}\`.`);
   }
-  if (requirePath && !options.path) {
-    throw new Error(`--path is required for \`${commandName}\`.`);
+  if (options.here && options.path) {
+    throw new Error("Use either `--path` or `--here`, not both.");
+  }
+  if (requirePath && !options.path && !options.here) {
+    throw new Error(`\`--path\` or \`--here\` is required for \`${commandName}\`.`);
+  }
+  if (options.here) {
+    options.path = path.resolve(process.cwd());
   }
   if (options.path) {
     options.path = validateAbsolutePath(options.path, "--path");
   }
+  if (options.currentCodex) {
+    if (options.resumeCommand || options.resumeTool || options.resumeSessionId) {
+      throw new Error("`--current-codex` cannot be combined with explicit resume metadata.");
+    }
+    Object.assign(options, resolveCurrentCodexResume());
+  }
   if (options.index != null) {
     const parsed = Number.parseInt(String(options.index), 10);
     if (!Number.isInteger(parsed) || parsed < 1) {
@@ -212,6 +273,9 @@ export function parseWorkspaceAddTabArgs(argv = []) {
     commandName: "orp workspace add-tab",
     requirePath: true,
     requireSelector: true,
+    allowAppend: true,
+    allowHere: true,
+    allowCurrentCodex: true,
   });
 }
 
@@ -306,45 +370,107 @@ export function addTabToManifest(manifest, options = {}) {
     ...manifest,
     tabs: manifest.tabs.map((tab) => ({ ...tab })),
   });
-  const resume = resolveResumeMetadata({
-    resumeCommand: options.resumeCommand,
-    resumeTool: options.resumeTool,
-    resumeSessionId: options.resumeSessionId,
-  });
-  const nextTab = Object.fromEntries(
-    Object.entries({
-      title: normalizeOptionalString(options.title) || undefined,
-      path: validateAbsolutePath(options.path, "--path"),
-      resumeCommand: resume.resumeCommand || undefined,
-      resumeTool: resume.resumeTool || undefined,
-      resumeSessionId: resume.resumeSessionId || undefined,
-      codexSessionId: resume.resumeTool === "codex" ? resume.resumeSessionId || undefined : undefined,
-      claudeSessionId: resume.resumeTool === "claude" ? resume.resumeSessionId || undefined : undefined,
-    }).filter(([, value]) => value !== undefined),
+  const normalizedPath = validateAbsolutePath(options.path, "--path");
+  const normalizedTitle = normalizeOptionalString(options.title);
+  const explicitResumeRequested = Boolean(
+    normalizeOptionalString(options.resumeCommand) ||
+      normalizeOptionalString(options.resumeTool) ||
+      normalizeOptionalString(options.resumeSessionId),
   );
+  const requestedResume = explicitResumeRequested
+    ? resolveResumeMetadata({
+        resumeCommand: options.resumeCommand,
+        resumeTool: options.resumeTool,
+        resumeSessionId: options.resumeSessionId,
+      })
+    : null;
+
+  const buildTab = (existingTab = null) => {
+    const existingResume = resolveResumeMetadata(existingTab || {});
+    const chosenResume = requestedResume || existingResume;
+    return Object.fromEntries(
+      Object.entries({
+        title: normalizedTitle || normalizeOptionalString(existingTab?.title) || undefined,
+        path: normalizedPath,
+        resumeCommand: chosenResume.resumeCommand || undefined,
+        resumeTool: chosenResume.resumeTool || undefined,
+        resumeSessionId: chosenResume.resumeSessionId || undefined,
+        codexSessionId: chosenResume.resumeTool === "codex" ? chosenResume.resumeSessionId || undefined : undefined,
+        claudeSessionId: chosenResume.resumeTool === "claude" ? chosenResume.resumeSessionId || undefined : undefined,
+      }).filter(([, value]) => value !== undefined),
+    );
+  };
+
+  const nextTab = buildTab();
+  if (options.append) {
+    nextManifest.tabs.push(nextTab);
+    return {
+      manifest: normalizeWorkspaceManifest(nextManifest),
+      added: true,
+      updated: false,
+      unchanged: false,
+      mutation: "added",
+      tab: nextTab,
+    };
+  }
 
-  const duplicate = nextManifest.tabs.find((tab) => {
-    const existingResume = resolveResumeMetadata(tab);
-    return (
-      tab.path === nextTab.path &&
-      normalizeOptionalString(tab.title) === normalizeOptionalString(nextTab.title) &&
-      existingResume.resumeCommand === (nextTab.resumeCommand || null)
+  const pathMatchIndexes = nextManifest.tabs
+    .map((tab, index) => (tab.path === normalizedPath ? index : -1))
+    .filter((index) => index >= 0);
+  let matchedIndexes = [];
+
+  if (normalizedTitle) {
+    matchedIndexes = pathMatchIndexes.filter(
+      (index) => normalizeOptionalString(nextManifest.tabs[index]?.title) === normalizedTitle,
     );
-  });
+    if (matchedIndexes.length === 0 && pathMatchIndexes.length === 1) {
+      matchedIndexes = pathMatchIndexes;
+    }
+  } else if (pathMatchIndexes.length > 0) {
+    const uniqueTitles = new Set(
+      pathMatchIndexes.map((index) => normalizeOptionalString(nextManifest.tabs[index]?.title) || ""),
+    );
+    if (pathMatchIndexes.length === 1 || uniqueTitles.size <= 1) {
+      matchedIndexes = pathMatchIndexes;
+    } else {
+      throw new Error(
+        "Multiple saved tabs already use this path. Re-run with `--title` to target one tab or `--append` to add another.",
+      );
+    }
+  }
 
-  if (duplicate) {
+  if (matchedIndexes.length === 0) {
+    nextManifest.tabs.push(nextTab);
     return {
-      manifest: nextManifest,
-      added: false,
-      tab: duplicate,
+      manifest: normalizeWorkspaceManifest(nextManifest),
+      added: true,
+      updated: false,
+      unchanged: false,
+      mutation: "added",
+      tab: nextTab,
     };
   }
 
-  nextManifest.tabs.push(nextTab);
+  const [primaryIndex, ...duplicateIndexes] = matchedIndexes;
+  const currentTab = nextManifest.tabs[primaryIndex];
+  const updatedTab = buildTab(currentTab);
+  const currentMaterialized = JSON.stringify(materializeWorkspaceTab(currentTab));
+  const updatedMaterialized = JSON.stringify(materializeWorkspaceTab(updatedTab));
+  nextManifest.tabs[primaryIndex] = updatedTab;
+
+  if (duplicateIndexes.length > 0) {
+    const removalSet = new Set(duplicateIndexes);
+    nextManifest.tabs = nextManifest.tabs.filter((_, index) => !removalSet.has(index));
+  }
+
+  const changed = currentMaterialized !== updatedMaterialized || duplicateIndexes.length > 0;
   return {
     manifest: normalizeWorkspaceManifest(nextManifest),
-    added: true,
-    tab: nextTab,
+    added: false,
+    updated: changed,
+    unchanged: !changed,
+    mutation: changed ? "updated" : "unchanged",
+    tab: updatedTab,
   };
 }
 
@@ -481,16 +607,19 @@ function printWorkspaceAddTabHelp() {
   console.log(`ORP workspace add-tab
 
 Usage:
-  orp workspace add-tab <name-or-id> --path <absolute-path> [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
-  orp workspace add-tab --hosted-workspace-id <workspace-id> --path <absolute-path> [--json]
-  orp workspace add-tab --workspace-file <path> --path <absolute-path> [--json]
+  orp workspace add-tab <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
+  orp workspace add-tab --hosted-workspace-id <workspace-id> (--path <absolute-path> | --here) [--json]
+  orp workspace add-tab --workspace-file <path> (--path <absolute-path> | --here) [--json]
 
 Options:
   --path <absolute-path> Add this local project path to the saved workspace
+  --here                 Use the current working directory as the saved path
   --title <title>        Optional saved tab title
   --resume-command <text> Exact saved resume command, like \`codex resume ...\` or \`claude --resume ...\`
   --resume-tool <tool>   Build the resume command from \`codex\` or \`claude\`
   --resume-session-id <id> Resume session id to save with the tab
+  --current-codex        Save the current \`CODEX_THREAD_ID\` as a Codex resume target
+  --append               Always append a new saved tab instead of updating an existing matching tab
   --hosted-workspace-id <id> Edit a first-class hosted workspace directly
   --workspace-file <path> Edit a local structured workspace manifest
   --json                 Print the updated workspace edit result as JSON
@@ -498,6 +627,7 @@ Options:
 
 Examples:
   orp workspace add-tab main --path /absolute/path/to/new-project
+  orp workspace add-tab main --here --current-codex
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-tool claude --resume-session-id claude-456
 `);
@@ -560,14 +690,15 @@ function summarizeWorkspaceLedgerMutation(result) {
   const lines = [
     `Workspace: ${result.workspaceTitle || result.workspaceId || "workspace"}`,
     `Action: ${result.action}`,
+    ...(result.action === "add-tab" && result.mutation ? [`Result: ${result.mutation}`] : []),
     `Saved tabs: ${result.tabCount}`,
   ];
 
   if (result.action === "add-tab") {
-    lines.push(`Added: ${result.tab?.title || path.basename(result.tab?.path || "") || result.tab?.path}`);
+    lines.push(`Tab: ${result.tab?.title || path.basename(result.tab?.path || "") || result.tab?.path}`);
     lines.push(`Path: ${result.tab?.path}`);
-    if (result.tab?.resumeCommand) {
-      lines.push(`Resume: ${result.tab.resumeCommand}`);
+    if (result.tab?.resumeCommand && result.tab?.restartCommand) {
+      lines.push(`Resume: ${result.tab.restartCommand}`);
     }
   } else if (result.action === "remove-tab") {
     lines.push(`Removed: ${result.removedTabs.length}`);
@@ -603,9 +734,10 @@ async function runWorkspaceLedgerMutation(options, mutate, action) {
     action,
     workspaceId: finalManifest.workspaceId,
     workspaceTitle: finalManifest.title || source.title || null,
+    mutation: mutated.mutation || null,
     tabCount: finalManifest.tabs.length,
-    tab: mutated.tab ? materializeWorkspaceTab(mutated.tab) : null,
-    removedTabs: (mutated.removedTabs || []).map((tab) => materializeWorkspaceTab(tab)),
+    tab: buildWorkspaceResultTab(mutated.tab),
+    removedTabs: (mutated.removedTabs || []).map((tab) => buildWorkspaceResultTab(tab)),
     persistedTo: persisted.persistedTo,
     ideaId: persisted.ideaId || null,
     workspaceSourceId: persisted.workspaceId || null,

package/packages/orp-workspace-launcher/src/orp-command.js

@@ -1,4 +1,3 @@
-import { runWorkspaceCommands } from "./commands.js";
 import { runWorkspaceAddTab, runWorkspaceCreate, runWorkspaceRemoveTab } from "./ledger.js";
 import { runWorkspaceList } from "./list.js";
 import { runWorkspaceSlot } from "./slot.js";
@@ -10,36 +9,36 @@ function printWorkspaceHelp() {
 
 Usage:
   orp workspace create <title-slug> [--workspace-file <path>] [--slot <main|offhand>] [--path <absolute-path>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
-  orp workspace ledger <name-or-id> [--json]
-  orp workspace ledger add <name-or-id> --path <absolute-path> [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
-  orp workspace ledger remove <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
+  orp workspace list [--json]
   orp workspace tabs <name-or-id> [--json]
   orp workspace tabs --hosted-workspace-id <workspace-id> [--json]
   orp workspace tabs --notes-file <path> [--json]
   orp workspace tabs --workspace-file <path> [--json]
-  orp workspace add-tab <name-or-id> --path <absolute-path> [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
+  orp workspace add-tab <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
   orp workspace remove-tab <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
-  orp workspace list [--json]
   orp workspace slot <list|set|clear> ...
   orp workspace sync <name-or-id> [--workspace-file <path> | --notes-file <path>] [--dry-run] [--json]
+  orp workspace ledger <name-or-id> [--json]
+  orp workspace ledger add <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
+  orp workspace ledger remove <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
   orp workspace -h
 
 Commands:
   create  Create a local workspace ledger so ORP works without a hosted account
-  ledger  Terminal-native saved workspace ledger flow: inspect, add, and remove saved paths plus resume commands
+  list    List one merged inventory of hosted ORP workspaces and local manifests
   tabs    List the saved tabs inside a workspace with copyable resume/recovery lines
   add-tab Add a saved tab/path/session to the workspace ledger directly
   remove-tab Remove one or more saved tabs from the workspace ledger directly
-  list    List one merged inventory of hosted ORP workspaces and local manifests
   slot    Assign and inspect named workspace slots like main and offhand
   sync    Post a CLI-authored workspace manifest back to the hosted ORP idea
+  ledger  Compatibility alias for the same tabs/add/remove ledger flow
 
 Notes:
-  - Local-only usage works: create a workspace with \`orp workspace create <title-slug>\`, then use \`orp workspace add-tab ...\`, \`orp workspace tabs ...\`, and \`orp workspace remove-tab ...\` without authenticating.
-  - The ledger-first flow is: \`orp workspace ledger <workspace>\`, \`orp workspace ledger add ...\`, \`orp workspace ledger remove ...\`, and \`orp workspace tabs <workspace>\`.
+  - Local-only usage works: create a workspace with \`orp workspace create <title-slug>\`, then use \`orp workspace tabs ...\`, \`orp workspace add-tab ...\`, and \`orp workspace remove-tab ...\` without authenticating.
   - Use \`orp workspace list\` for the combined hosted + local workspace inventory.
   - Use \`orp workspace tabs <workspace>\` when you want saved paths plus copyable \`cd ... && codex resume ...\` / \`claude --resume ...\` recovery lines.
   - Use \`orp workspace add-tab ...\` and \`orp workspace remove-tab ...\` when you want to edit the saved workspace ledger explicitly from Terminal.app or any other shell.
+  - If you prefer the older ledger-prefixed wording, \`orp workspace ledger\`, \`orp workspace ledger add\`, and \`orp workspace ledger remove\` stay available as aliases.
   - \`main\` and \`offhand\` are reserved slot selectors; use \`orp workspace slot set ...\` to assign them.
   - Syncing or editing a hosted workspace writes a managed local cache on this Mac.
   - \`<name-or-id>\` can be a saved workspace title, workspace id, idea id, or local tracked workspace title/id.
@@ -47,17 +46,18 @@ Notes:
 Examples:
   orp workspace create main-cody-1
   orp workspace create main-cody-1 --slot main
-  orp workspace ledger main
-  orp workspace ledger add main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
-  orp workspace ledger remove main --title frg-site
+  orp workspace list
   orp workspace tabs main-cody-1
+  orp workspace add-tab main --here --current-codex
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
   orp workspace remove-tab main --path /absolute/path/to/frg-site --resume-session-id 019d348d-5031-78e1-9840-a66deaac33ae
   orp workspace slot set main main-cody-1
   orp workspace slot set offhand research-lab
   orp workspace slot list
+  orp workspace ledger main
+  orp workspace ledger add main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
+  orp workspace ledger remove main --title frg-site
   orp workspace tabs --hosted-workspace-id ws_orp_main
-  orp workspace list
   orp workspace sync main --workspace-file ./workspace.json
 `);
 }

package/packages/orp-workspace-launcher/test/ledger.test.js

@@ -97,6 +97,32 @@ test("parseWorkspaceAddTabArgs accepts explicit resume metadata", () => {
   assert.equal(parsed.json, true);
 });
 
+test("parseWorkspaceAddTabArgs resolves --here and --current-codex", () => {
+  const originalThreadId = process.env.CODEX_THREAD_ID;
+  const originalCwd = process.cwd();
+  process.env.CODEX_THREAD_ID = "019d4f24-c8ba-78b2-a726-48b1ce9f0fe9";
+  process.chdir("/Volumes/Code_2TB/code/orp");
+  try {
+    const parsed = parseWorkspaceAddTabArgs([
+      "main",
+      "--here",
+      "--current-codex",
+    ]);
+
+    assert.equal(parsed.ideaId, "main");
+    assert.equal(parsed.path, "/Volumes/Code_2TB/code/orp");
+    assert.equal(parsed.resumeTool, "codex");
+    assert.equal(parsed.resumeSessionId, "019d4f24-c8ba-78b2-a726-48b1ce9f0fe9");
+  } finally {
+    process.chdir(originalCwd);
+    if (originalThreadId == null) {
+      delete process.env.CODEX_THREAD_ID;
+    } else {
+      process.env.CODEX_THREAD_ID = originalThreadId;
+    }
+  }
+});
+
 test("parseWorkspaceCreateArgs validates slug titles and optional seed metadata", () => {
   const parsed = parseWorkspaceCreateArgs([
     "main-cody-1",
@@ -144,6 +170,63 @@ test("addTabToManifest canonicalizes Claude resume commands from tool plus sessi
   assert.equal(result.manifest.tabs[2]?.sessionId, "claude-456");
 });
 
+test("addTabToManifest updates an existing matching tab instead of appending a duplicate", () => {
+  const result = addTabToManifest(sampleManifest(), {
+    path: "/Volumes/Code_2TB/code/orp",
+    title: "orp",
+    resumeTool: "codex",
+    resumeSessionId: "019d4f24-c8ba-78b2-a726-48b1ce9f0fe9",
+  });
+
+  assert.equal(result.added, false);
+  assert.equal(result.updated, true);
+  assert.equal(result.mutation, "updated");
+  assert.equal(result.manifest.tabs.length, 2);
+  assert.equal(result.manifest.tabs[0]?.resumeCommand, "codex resume 019d4f24-c8ba-78b2-a726-48b1ce9f0fe9");
+});
+
+test("addTabToManifest preserves existing resume metadata when no new resume is provided", () => {
+  const result = addTabToManifest(sampleManifest(), {
+    path: "/Volumes/Code_2TB/code/frg-site",
+    title: "frg-site",
+  });
+
+  assert.equal(result.added, false);
+  assert.equal(result.updated, false);
+  assert.equal(result.unchanged, true);
+  assert.equal(result.mutation, "unchanged");
+  assert.equal(result.manifest.tabs.length, 2);
+  assert.equal(result.manifest.tabs[1]?.resumeCommand, "codex resume 019d348d-5031-78e1-9840-a66deaac33ae");
+});
+
+test("addTabToManifest asks for a title when multiple saved tabs share a path", () => {
+  const manifest = normalizeWorkspaceManifest({
+    version: "1",
+    workspaceId: "main-cody-1",
+    title: "main-cody-1",
+    tabs: [
+      {
+        title: "longevity-research",
+        path: "/Volumes/Code_2TB/code/longevity-research",
+      },
+      {
+        title: "longevity-research (2)",
+        path: "/Volumes/Code_2TB/code/longevity-research",
+      },
+    ],
+  });
+
+  assert.throws(
+    () =>
+      addTabToManifest(manifest, {
+        path: "/Volumes/Code_2TB/code/longevity-research",
+        resumeTool: "codex",
+        resumeSessionId: "019d4f24-c8ba-78b2-a726-48b1ce9f0fe9",
+      }),
+    /Multiple saved tabs already use this path/,
+  );
+});
+
 test("removeTabsFromManifest can target a saved tab by path and resume session id", () => {
   const result = removeTabsFromManifest(sampleManifest(), {
     path: "/Volumes/Code_2TB/code/frg-site",
@@ -186,6 +269,42 @@ test("runWorkspaceAddTab updates a local workspace manifest file", async () => {
   });
 });
 
+test("runWorkspaceAddTab upserts an existing tab and returns the rendered recovery command", async () => {
+  await withTempConfigHome(async () => {
+    const tempDir = await makeTempDir();
+    const manifestPath = path.join(tempDir, "workspace.json");
+    await fs.writeFile(manifestPath, `${JSON.stringify(sampleManifest(), null, 2)}\n`, "utf8");
+
+    const { code, stdout } = await captureStdout(() =>
+      runWorkspaceAddTab([
+        "--workspace-file",
+        manifestPath,
+        "--path",
+        "/Volumes/Code_2TB/code/orp",
+        "--resume-tool",
+        "codex",
+        "--resume-session-id",
+        "019d4f24-c8ba-78b2-a726-48b1ce9f0fe9",
+        "--json",
+      ]),
+    );
+    const payload = JSON.parse(stdout);
+    const saved = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+
+    assert.equal(code, 0);
+    assert.equal(payload.action, "add-tab");
+    assert.equal(payload.mutation, "updated");
+    assert.equal(payload.tabCount, 2);
+    assert.equal(payload.tab.resumeCommand, "codex resume 019d4f24-c8ba-78b2-a726-48b1ce9f0fe9");
+    assert.equal(
+      payload.tab.restartCommand,
+      "cd '/Volumes/Code_2TB/code/orp' && codex resume 019d4f24-c8ba-78b2-a726-48b1ce9f0fe9",
+    );
+    assert.equal(saved.tabs.length, 2);
+    assert.equal(saved.tabs[0]?.resumeCommand, "codex resume 019d4f24-c8ba-78b2-a726-48b1ce9f0fe9");
+  });
+});
+
 test("runWorkspaceRemoveTab updates a local workspace manifest file", async () => {
   await withTempConfigHome(async () => {
     const tempDir = await makeTempDir();

package/packages/orp-workspace-launcher/test/orp-command.test.js

@@ -29,10 +29,16 @@ test("runOrpWorkspaceCommand shows the ledger-first help surface", async () => {
   const { code, stdout } = await captureStdout(() => runOrpWorkspaceCommand(["-h"]));
 
   assert.equal(code, 0);
+  assert.match(stdout, /orp workspace list \[--json\]/);
+  assert.match(stdout, /orp workspace add-tab <name-or-id>/);
+  assert.match(stdout, /--here/);
+  assert.match(stdout, /--current-codex/);
+  assert.match(stdout, /orp workspace remove-tab <name-or-id>/);
   assert.match(stdout, /orp workspace ledger <name-or-id>/);
   assert.match(stdout, /orp workspace ledger add <name-or-id>/);
   assert.match(stdout, /orp workspace ledger remove <name-or-id>/);
   assert.match(stdout, /orp workspace tabs <name-or-id>/);
+  assert.match(stdout, /Compatibility alias for the same tabs\/add\/remove ledger flow/);
 });
 
 test("runOrpWorkspaceCommand routes ledger help to the tabs help surface", async () => {

package/packs/erdos-open-problems/pack.yml

@@ -129,3 +129,57 @@ templates:
     output_hint: orp.erdos-catalog-sync.yml
     default_profiles:
       - erdos_catalog_sync_active
+
+install:
+  default_includes:
+    - catalog
+    - live_compare
+    - problem857
+  report_name: orp.erdos.pack-install-report.md
+  components:
+    catalog:
+      template_id: erdos_problems_catalog_sync
+      output_name: orp.erdos-catalog-sync.yml
+      description: Erdos catalog sync (all/open/closed/active snapshots).
+    live_compare:
+      template_id: sunflower_live_compare_suite
+      output_name: orp.erdos-live-compare.yml
+      description: Side-by-side atomic-board compare for Problems 857/20/367.
+      required_paths:
+        - analysis/problem857_counting_gateboard.json
+        - analysis/problem20_k3_gateboard.json
+        - analysis/problem367_sharp_gateboard.json
+        - scripts/problem857_ops_board.py
+        - scripts/problem20_ops_board.py
+        - scripts/problem367_ops_board.py
+        - scripts/frontier_status.py
+    problem857:
+      template_id: sunflower_problem857_discovery
+      output_name: orp.erdos-problem857.yml
+      description: Problem 857 discovery profile (board refresh/ready/spec/lean/frontier).
+      required_paths:
+        - analysis/problem857_counting_gateboard.json
+        - docs/PROBLEM857_COUNTING_OPS_BOARD.md
+        - orchestrator/v2/scopes/problem_857.yaml
+        - orchestrator/problem857_public_spec_check.py
+        - scripts/problem857_ops_board.py
+        - scripts/frontier_status.py
+        - sunflower_lean
+    governance:
+      template_id: sunflower_mathlib_pr_governance
+      output_name: orp.erdos-mathlib-pr-governance.yml
+      description: Mathlib PR governance profile set (pre-open, draft-readiness, full flow).
+      required_paths:
+        - docs/MATHLIB_SUBMISSION_CHECKLIST.md
+        - docs/MATHLIB_DRAFT_PR_TEMPLATE.md
+        - docs/MATHLIB_ISSUE_VIABILITY_GATE.md
+        - docs/UPSTREAM_PR_LANE.md
+        - analysis/UPSTREAM_PR_PLAN.yaml
+        - scripts/upstream-pr-plan.py
+        - scripts/upstream-pr-lane.sh
+        - scripts/mathlib-issue-viability-gate.py
+        - scripts/mathlib-naturality-snippet.sh
+        - scripts/mathlib-issue-local-gate.sh
+        - scripts/mathlib-tighten-fine-tooth-gate.sh
+        - scripts/mathlib-ready-to-draft-gate.sh
+        - scripts/mathlib-pr-body-preflight.py

package/packs/external-pr-governance/pack.yml

@@ -144,3 +144,20 @@ templates:
     output_hint: orp.external-pr-feedback-hardening.yml
     default_profiles:
       - external_feedback_hardening
+
+install:
+  default_includes:
+    - governance
+    - feedback_hardening
+  report_name: orp.external-pr.pack-install-report.md
+  components:
+    governance:
+      template_id: oss_pr_governance
+      output_name: orp.external-pr-governance.yml
+      description: Generic external contribution governance profiles (watch/select, pre-open, local-readiness, draft transition, draft lifecycle, full flow).
+      required_paths:
+        - analysis/PR_DRAFT_BODY.md
+    feedback_hardening:
+      template_id: oss_feedback_hardening
+      output_name: orp.external-pr-feedback-hardening.yml
+      description: Generic maintainer-feedback hardening profile.

package/packs/issue-smashers/pack.yml

@@ -176,3 +176,28 @@ templates:
     output_hint: orp.issue-smashers-feedback-hardening.yml
     default_profiles:
       - issue_smashers_feedback_hardening
+
+install:
+  default_includes:
+    - workspace
+    - feedback_hardening
+  report_name: orp.issue-smashers.pack-install-report.md
+  components:
+    workspace:
+      template_id: issue_smashers_workspace
+      output_name: orp.issue-smashers.yml
+      description: Opinionated issue-smashers workspace and external contribution governance profiles.
+      required_paths:
+        - issue-smashers/README.md
+        - issue-smashers/WORKSPACE_RULES.md
+        - issue-smashers/setup-issue-smashers.sh
+        - issue-smashers/analysis/ISSUE_SMASHERS_WATCHLIST.json
+        - issue-smashers/analysis/ISSUE_SMASHERS_STATUS.md
+        - issue-smashers/analysis/PR_DRAFT_BODY.md
+    feedback_hardening:
+      template_id: issue_smashers_feedback_hardening
+      output_name: orp.issue-smashers-feedback-hardening.yml
+      description: Issue-smashers maintainer-feedback hardening profile.
+      required_paths:
+        - issue-smashers/WORKSPACE_RULES.md
+        - issue-smashers/analysis/ISSUE_SMASHERS_STATUS.md

package/scripts/orp-pack-install.py

@@ -24,7 +24,7 @@ from typing import Any
 import yaml
 
 
-PACK_SPECS: dict[str, dict[str, Any]] = {
+LEGACY_PACK_SPECS: dict[str, dict[str, Any]] = {
     "erdos-open-problems": {
         "default_includes": ["catalog", "live_compare", "problem857"],
         "report_name": "orp.erdos.pack-install-report.md",
@@ -1267,18 +1267,99 @@ def _load_yaml(path: Path) -> dict[str, Any]:
     return payload
 
 
-def _pack_spec(pack_id: str) -> dict[str, Any]:
-    spec = PACK_SPECS.get(pack_id)
+def _legacy_pack_spec(pack_id: str) -> dict[str, Any]:
+    spec = LEGACY_PACK_SPECS.get(pack_id)
     if not isinstance(spec, dict):
         raise RuntimeError(f"unsupported pack for install flow: {pack_id}")
     return spec
 
 
-def _pack_components(pack_id: str) -> dict[str, dict[str, Any]]:
-    components = _pack_spec(pack_id).get("components", {})
+def _pack_install_spec(pack_meta: dict[str, Any], pack_id: str) -> dict[str, Any]:
+    install = pack_meta.get("install")
+    if isinstance(install, dict):
+        return install
+    return _legacy_pack_spec(pack_id)
+
+
+def _pack_templates(pack_meta: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    raw = pack_meta.get("templates", {})
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for key, value in raw.items():
+        if isinstance(key, str) and isinstance(value, dict):
+            out[key] = value
+    return out
+
+
+def _normalize_install_component(
+    component_key: str,
+    raw_component: dict[str, Any],
+    *,
+    templates: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    template_id = str(raw_component.get("template_id", "")).strip()
+    if not template_id:
+        raise RuntimeError(f"install component missing template_id: {component_key}")
+
+    template_meta = templates.get(template_id)
+    if not isinstance(template_meta, dict):
+        raise RuntimeError(
+            f"install component {component_key} references unknown template_id: {template_id}"
+        )
+
+    output_name = str(raw_component.get("output_name") or template_meta.get("output_hint") or "").strip()
+    if not output_name:
+        raise RuntimeError(
+            f"install component {component_key} is missing output_name and template {template_id} has no output_hint"
+        )
+
+    description = str(raw_component.get("description") or template_meta.get("description") or "").strip()
+    required_paths_raw = raw_component.get("required_paths", [])
+    if required_paths_raw is None:
+        required_paths: list[str] = []
+    elif isinstance(required_paths_raw, list):
+        required_paths = [str(path) for path in required_paths_raw]
+    else:
+        raise RuntimeError(f"install component required_paths must be a list: {component_key}")
+
+    return {
+        "template_id": template_id,
+        "output_name": output_name,
+        "description": description,
+        "required_paths": required_paths,
+    }
+
+
+def _pack_components(pack_meta: dict[str, Any], pack_id: str) -> dict[str, dict[str, Any]]:
+    install = _pack_install_spec(pack_meta, pack_id)
+    components = install.get("components", {})
     if not isinstance(components, dict) or not components:
         raise RuntimeError(f"pack has no installable components: {pack_id}")
-    return components
+
+    templates = _pack_templates(pack_meta)
+    out: dict[str, dict[str, Any]] = {}
+    for key, value in components.items():
+        if not isinstance(key, str) or not isinstance(value, dict):
+            raise RuntimeError(f"invalid install component entry in pack {pack_id}: {key!r}")
+        out[key] = _normalize_install_component(key, value, templates=templates)
+    return out
+
+
+def _pack_default_includes(pack_meta: dict[str, Any], pack_id: str) -> list[str]:
+    install = _pack_install_spec(pack_meta, pack_id)
+    raw = install.get("default_includes", [])
+    if not isinstance(raw, list):
+        return []
+    return [str(x) for x in raw if isinstance(x, str)]
+
+
+def _pack_report_name(pack_meta: dict[str, Any], pack_id: str) -> str:
+    install = _pack_install_spec(pack_meta, pack_id)
+    raw = install.get("report_name")
+    if isinstance(raw, str) and raw.strip():
+        return raw.strip()
+    return f"orp.{pack_id}.pack-install-report.md"
 
 
 def _validate_var(raw: str) -> str:
@@ -2153,15 +2234,13 @@ def main() -> int:
     pack_id = str(pack_meta.get("pack_id", args.pack_id))
     pack_version = str(pack_meta.get("version", "unknown"))
     generated_at_utc = _now_utc()
-    components = _pack_components(pack_id)
+    components = _pack_components(pack_meta, pack_id)
     effective_vars = _vars_map(pack_meta, list(args.var or []))
     problem857_source_mode = _problem857_source_mode(effective_vars)
 
     includes = list(args.include or [])
     if not includes:
-        default_includes = _pack_spec(pack_id).get("default_includes", [])
-        if isinstance(default_includes, list):
-            includes = [str(x) for x in default_includes if isinstance(x, str)]
+        includes = _pack_default_includes(pack_meta, pack_id)
     if not includes:
         includes = sorted(components.keys())
 
@@ -2227,7 +2306,7 @@ def main() -> int:
         else:
             report_path = report_path.resolve()
     else:
-        report_name = str(_pack_spec(pack_id).get("report_name", f"orp.{pack_id}.pack-install-report.md"))
+        report_name = _pack_report_name(pack_meta, pack_id)
         report_path = (target_repo_root / report_name).resolve()
 
     _write_report(

package/spec/v1/profile-pack.schema.json

@@ -34,6 +34,9 @@
     "orp_version_min": {
       "type": "string"
     },
+    "install": {
+      "$ref": "#/$defs/install"
+    },
     "variables": {
       "type": "object",
       "additionalProperties": {
@@ -90,6 +93,51 @@
           }
         }
       }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default_includes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "report_name": {
+          "type": "string"
+        },
+        "components": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/installComponent"
+          }
+        }
+      }
+    },
+    "installComponent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "template_id"
+      ],
+      "properties": {
+        "template_id": {
+          "type": "string"
+        },
+        "output_name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "required_paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
     }
   }
 }