jorgex-stack 1.0.25 → 1.0.27

package/README.md

@@ -9,7 +9,7 @@ Portable multi-agent harness: one configuration source — 15 agents, 17 skills,
 Install and run via npm without cloning the repository:
 
 ```
-pnpm dlx jorgex-stack install    # apply config to your runtimes (interactive pick; idempotent, removes orphans)
+pnpm dlx jorgex-stack install    # install runtimes; first OpenCode setup selects connected models
 pnpm dlx jorgex-stack models     # model picker by runtime and tier (strong/standard/cheap)
 pnpm dlx jorgex-stack sync       # alias of install (same idempotent apply)
 pnpm dlx jorgex-stack doctor     # checks that everything is healthy (Engram, drift, hooks, keys)
@@ -24,7 +24,7 @@ For development from a clone, run the same commands through `pnpm cli <command>`
 
 Every command supports `--dry-run`, `--yes`, and `--target-dir <dir>` for testing without touching the real config. Writes create automatic backups and verify idempotency; merges into user config are surgical (marked markdown sections, JSON/TOML upserts), so user-owned content is never touched.
 
-Runtime defaults are documented in [docs/references/permissions.md](docs/references/permissions.md) for permissions and [docs/references/models.md](docs/references/models.md) for model selection, GPT-5.6 subagent tiers, and orchestrator inheritance.
+Runtime defaults are documented in [docs/references/permissions.md](docs/references/permissions.md) for permissions and [docs/references/models.md](docs/references/models.md) for provider-aware model selection, Codex tiers, and orchestrator inheritance. OpenCode has no provider defaults.
 
 ### Modes: Human and Programmatic
 
@@ -52,6 +52,8 @@ Flags:
 
   This installs into all detected runtimes. To be explicit, add `--agents opencode,claude-code,codex` or a comma-separated subset. Always pass `--mode programmatic`; without `--mode`, `--yes` and non-TTY installs default to `human`.
 
+  OpenCode also requires an existing selection in `~/.jorgex-stack/model-map.json`; run `pnpm dlx jorgex-stack models --agents opencode` interactively once before a headless install.
+
 - `--mode human` cannot be combined with `--subagent-concurrency`.
 - Without `--mode`, the first run asks interactively; `--yes`, non-TTY, and `--target-dir` default to `human`.
 - `pnpm dlx jorgex-stack sync` reuses the saved mode; pass `--mode` to change and save the preference.

package/dist/cli.js

@@ -178,11 +178,6 @@ function resolveAgentModel(models, agentName, tier) {
   };
 }
 var DEFAULT_MODEL_MAP = {
-  opencode: {
-    strong: { model: "openai/gpt-5.6-terra", variant: "xhigh" },
-    standard: { model: "openai/gpt-5.6-terra", variant: "xhigh" },
-    cheap: { model: "openai/gpt-5.6-luna", variant: "medium" }
-  },
   "claude-code": {
     strong: { model: "fable" },
     standard: { model: "sonnet" },
@@ -209,7 +204,7 @@ function loadModelMap() {
   } catch {
     return DEFAULT_MODEL_MAP;
   }
-  const merged = {};
+  const merged = { ...fromDisk };
   for (const id of Object.keys(DEFAULT_MODEL_MAP)) {
     merged[id] = { ...DEFAULT_MODEL_MAP[id], ...fromDisk[id] ?? {} };
   }
@@ -1649,7 +1644,8 @@ async function runInstall(opts) {
     }
     const models = modelMap[id];
     if (!models) {
-      p.log.warn(`${adapter.name}: sin model-map para este runtime \u2014 omitido.`);
+      p.log.error(`${adapter.name}: sin modelos seleccionados \u2014 ejecuta 'jorgex-stack models --agents ${id}'.`);
+      exitCode = 1;
       continue;
     }
     const ctx = {
@@ -2867,8 +2863,12 @@ function agentsByTier() {
   }
   return grouped;
 }
+function isCompleteRuntimeModelMap(models) {
+  return TIERS.every((tier) => models[tier]?.model);
+}
 async function askModel(det, subject, current) {
   if (det.id === "codex") {
+    if (!current) throw new Error("Codex requiere un model-map base.");
     const effort = await p5.select({
       message: `${det.name} \xB7 ${subject} \u2014 reasoning effort`,
       options: EFFORTS.map((v) => ({ value: v, label: v })),
@@ -2902,16 +2902,18 @@ async function askModel(det, subject, current) {
   }
   const optionsList = det.options;
   const options = optionsList.map((m) => ({ value: m, label: m }));
-  if (!optionsList.includes(current.model)) options.unshift({ value: current.model, label: `${current.model} (actual)` });
+  if (current && !optionsList.includes(current.model)) {
+    options.unshift({ value: current.model, label: `${current.model} (actual)` });
+  }
   const choice = await p5.select({
     message: `${det.name} \xB7 ${subject} \u2014 modelo`,
     options,
-    initialValue: current.model,
+    initialValue: current?.model,
     maxItems: 12
   });
   if (p5.isCancel(choice)) return CANCEL;
   if (det.id === "claude-code") return { model: choice };
-  const keptCurrent = choice === current.model && current.variant ? current.variant : null;
+  const keptCurrent = current && choice === current.model && current.variant ? current.variant : null;
   const variant = await p5.select({
     message: `${det.name} \xB7 ${subject} \u2014 reasoning effort (variant; solo si el modelo lo soporta)`,
     options: [
@@ -2926,12 +2928,16 @@ async function askModel(det, subject, current) {
 }
 async function runModelsPicker(opts) {
   const file = ensureModelMapFile();
+  const map = loadModelMap();
   if (opts.yes || !process.stdout.isTTY) {
-    console.log(`Model-map en ${file} (defaults). Ed\xEDtalo o ejecuta 'models' sin --yes para el picker.`);
+    if (opts.runtimes.includes("opencode") && !map.opencode) {
+      console.error("OpenCode requiere selecci\xF3n interactiva desde los proveedores conectados; ejecuta 'models --agents opencode' sin --yes.");
+      return 1;
+    }
+    console.log(`Model-map en ${file}. Ed\xEDtalo o ejecuta 'models' sin --yes para el picker.`);
     return 0;
   }
   p5.intro("jorgex-stack models \u2014 modelos por tier o por subagente");
-  const map = loadModelMap();
   const grouped = agentsByTier();
   const tierLine = (tier) => grouped[tier].join(", ");
   const agentCount = TIERS.reduce((n, tier) => n + grouped[tier].length, 0);
@@ -2960,7 +2966,10 @@ async function runModelsPicker(opts) {
       p5.log.warn("OpenCode: no se pudo listar `opencode models` \u2014 se mantiene la selecci\xF3n actual.");
       continue;
     }
-    const runtimeMap = { ...map[det.id] };
+    const existingRuntimeMap = map[det.id];
+    const runtimeMap = {
+      ...existingRuntimeMap
+    };
     p5.log.message(
       `${det.name} \u2014 tiers y sus subagentes:
   strong   \u2192 ${tierLine("strong")}
@@ -2978,7 +2987,7 @@ async function runModelsPicker(opts) {
     if (p5.isCancel(mode)) return cancelled();
     if (mode === "tier") {
       for (const tier of TIERS) {
-        const asked = await askModel(det, `tier ${tier} (${tierLine(tier)})`, runtimeMap[tier]);
+        const asked = await askModel(det, `tier ${tier} (${tierLine(tier)})`, existingRuntimeMap?.[tier]);
         if (asked === CANCEL) return cancelled();
         runtimeMap[tier] = asked;
       }
@@ -2991,10 +3000,15 @@ async function runModelsPicker(opts) {
     } else {
       const overrides = { ...runtimeMap.overrides ?? {} };
       for (const tier of TIERS) {
-        const base = runtimeMap[tier];
+        let base = runtimeMap[tier];
         for (const name of grouped[tier]) {
-          const asked = await askModel(det, `${name} (tier ${tier})`, resolveAgentModel(runtimeMap, name, tier));
+          const current = existingRuntimeMap ? resolveAgentModel(existingRuntimeMap, name, tier) : void 0;
+          const asked = await askModel(det, `${name} (tier ${tier})`, current);
           if (asked === CANCEL) return cancelled();
+          if (!base) {
+            base = asked;
+            runtimeMap[tier] = base;
+          }
           const sameAsTier = asked.model === base.model && (asked.variant ?? "") === (base.variant ?? "");
           if (sameAsTier) {
             delete overrides[name];
@@ -3009,6 +3023,9 @@ async function runModelsPicker(opts) {
       if (Object.keys(overrides).length > 0) runtimeMap.overrides = overrides;
       else delete runtimeMap.overrides;
     }
+    if (!isCompleteRuntimeModelMap(runtimeMap)) {
+      throw new Error(`${det.name}: selecci\xF3n de modelos incompleta.`);
+    }
     map[det.id] = runtimeMap;
   }
   writeText(file, JSON.stringify(map, null, 2) + "\n");
@@ -3052,6 +3069,18 @@ function readPackageMetadata() {
 // src/cli.ts
 var VERSION = readPackageVersion();
 var COMMANDS = ["install", "sync", "models", "update", "doctor", "restore", "uninstall"];
+async function ensureOpenCodeModelsForInstall(command, flags, runtimes) {
+  if (!runtimes.includes("opencode") || loadModelMap().opencode) return true;
+  const canPrompt = command === "install" && !flags.yes && !flags.dryRun && process.stdout.isTTY;
+  if (canPrompt) {
+    const code = await runModelsPicker({ yes: false, runtimes: ["opencode"] });
+    if (code === 0 && loadModelMap().opencode) return true;
+  }
+  console.error(
+    "OpenCode no tiene modelos configurados. Ejecuta 'jorgex-stack models --agents opencode' de forma interactiva antes de install/sync."
+  );
+  return false;
+}
 function parseFlags(args) {
   const flags = {
     agents: [],
@@ -3204,9 +3233,9 @@ function printHelp() {
 Uso: pnpm dlx jorgex-stack [comando] [opciones]
 
 Comandos:
-  install     Instala el stack en los runtimes elegidos (default, interactivo)
-  sync        Re-aplica la config (idempotente; alias de install)
-  models      Picker de modelos por tier (OpenCode: lista en vivo de 'opencode models')
+  install     Instala el stack; OpenCode fresh exige elegir modelos conectados
+  sync        Re-aplica la config y el model-map existente (idempotente; sin picker)
+  models      Picker por tier o subagente (OpenCode: 'opencode models' en vivo)
   update      --check: compara stack/Engram/skills con sus upstreams
   doctor      Estado: Engram, drift de config, hooks de Codex, key de context7
   restore     --list para ver backups \xB7 'restore <id>' para restaurar
@@ -3266,6 +3295,10 @@ Flags disponibles: jorgex-stack --help`
         process.exitCode = 1;
         return;
       }
+      if (!await ensureOpenCodeModelsForInstall(command, flags, runtimes)) {
+        process.exitCode = 1;
+        return;
+      }
       process.exitCode = await runInstall({ runtimes, targetDir: flags.targetDir, dryRun: flags.dryRun, yes: flags.yes, mode });
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI y OpenCode",
   "type": "module",
   "license": "MIT",

package/stack/agents/docs-maintainer.md

@@ -1,6 +1,6 @@
 ---
 name: docs-maintainer
-description: Documentation specialist. Use it AFTER behavior or APIs change to keep the repo's /docs folder and any public docs site (website, app, docs portal) up to date and in sync — content, navigation and metadata. Writes docs only — not for product logic, features or bug fixes.
+description: Evidence-first documentation specialist. Use it AFTER behavior or APIs change to keep the repo's /docs folder and any public docs site (website, app, docs portal) accurate and in sync — content, navigation and metadata. Writes docs only — not for product logic, features or bug fixes.
 mode: subagent
 tier: cheap
 readonly: false
@@ -42,10 +42,24 @@ If you change a page, check whether navigation or metadata must also be updated.
 
 ## Before editing
 
+- Establish the **allowed write root**. An explicit worktree or write-root path in the assignment always wins; otherwise use the current repository root.
+- Run `git rev-parse --show-toplevel` and inspect the current branch before the first write. Resolve every target path and confirm it stays inside the allowed write root. If the current checkout or any target does not match, do not write: return `blocked` with the mismatch.
 - Search for references to the title, slug, path or concept you are about to change.
 - Identify whether the documentation is public, internal or hybrid.
 - Follow the project's real pattern; do not impose a new one without need.
 
+## Factual accuracy
+
+Documentation is an evidence task, not a creative reconstruction.
+
+- Build a **source-to-claim** map before drafting: every new technical claim must trace to current code, schemas or migrations, tests, canonical project docs, or git history.
+- Use implementation to classify components. An invocation name is not proof of its implementation type; inspect the defining file before calling something an RPC, database function, API route, Edge Function, job or service.
+- Use git history only when claiming when or in which change something was introduced. Current existence does not prove recent origin.
+- **Never invent** names, paths, symbols, chronology, or snippets. Copy identifiers exactly from a source that exists in the allowed write root.
+- A code snippet must come from a real file you inspected. If the task explicitly needs illustrative pseudocode, label it as pseudocode and never attribute it to a repository file.
+- When sources conflict, prefer executable code and migrations over comments or stale docs. Do not silently choose a convenient version.
+- If a material claim cannot be verified, omit it when nonessential; otherwise return `partial` or `blocked` with one concrete question. Never fill the gap with a plausible guess.
+
 ## While editing
 
 - Keep the scope minimal.
@@ -54,6 +68,12 @@ If you change a page, check whether navigation or metadata must also be updated.
 - If there is a sidebar or manual index, update it.
 - If there is SEO or technical metadata, keep it in sync.
 
+## Before reporting
+
+- Review the final documentation diff sentence by sentence. Re-check each added or changed factual claim against its source and confirm every mentioned file exists.
+- Re-run the location check and confirm all changed files are inside the allowed write root.
+- Remove unsupported claims instead of weakening them with vague language.
+
 ## Rules
 
 - Scope your work to the affected documentation.
@@ -67,6 +87,8 @@ If you change a page, check whether navigation or metadata must also be updated.
 - [ ] Metadata updated if applicable
 - [ ] Internal links valid
 - [ ] Tone consistent with the rest of the docs
+- [ ] Every factual claim and snippet verified against a real source
+- [ ] All writes confined to the allowed write root
 
 ## Report format
 
@@ -77,6 +99,7 @@ If you change a page, check whether navigation or metadata must also be updated.
 **Content:** [what changed]
 **Navigation:** [if applicable]
 **Metadata:** [if applicable]
+**Evidence:** [source paths and, for chronology claims, commits used]
 ```
 
 ## Result contract