opencode-starterkit 1.0.1

package/docs/reports/2026-03-18-vat-opencode-classification-matrix.md

@@ -0,0 +1,180 @@
+# VAT `.opencode` Classification Matrix
+
+**Source repo:** `/Users/mrcagents/Work/projects/VAT`
+**Source path:** `/Users/mrcagents/Work/projects/VAT/.opencode`
+**Purpose:** classify VAT `.opencode` contents into `global baseline`, `thin project overlay`, and `runtime-only / remove from repo` for the new `mrc-opc` installer architecture.
+
+---
+
+## Executive Summary
+
+Current VAT `.opencode` is too heavy for per-project installation:
+
+- Total size: **42M**
+- `node_modules`: **35M**
+- `memory.db*`: **~2.4M**
+- skills files: **92** files under `.opencode/skill`
+
+### Decision
+
+- Promote most of VAT `.opencode` to **global baseline** under `~/.config/opencode`
+- Keep only a **thin project overlay** in each repo
+- Remove runtime/cache state from the repo-local `.opencode`
+
+---
+
+## Classification Rules
+
+### A. Global baseline
+Use for reusable OpenCode operating system content shared across repos.
+
+### B. Thin project overlay
+Use only for repo-specific instructions, memory, model overrides, MCP toggles, and repo-local hooks.
+
+### C. Runtime-only / remove from repo
+Use for cache, local DB, generated state, dependencies, and other machine-local artifacts.
+
+---
+
+## File/Folder Classification Matrix
+
+| Path | Category | Reason | Target handling |
+|---|---|---|---|
+| `.opencode/agent/` | Global baseline | Reusable agent definitions across repos | Move to global baseline package/templates |
+| `.opencode/command/` | Global baseline | Generic command set, not VAT-specific | Move to global baseline |
+| `.opencode/context/README.md` | Global baseline | Generic documentation | Move to global docs |
+| `.opencode/plugin/copilot-auth.ts` | Global baseline | Shared provider/auth integration | Move to global plugin |
+| `.opencode/plugin/sessions.ts` | Global baseline | Shared session search/read tooling | Move to global plugin |
+| `.opencode/plugin/skill-mcp.ts` | Global baseline | Shared MCP bridge behavior | Move to global plugin |
+| `.opencode/plugin/memory.ts` | Global baseline | Shared memory operating layer | Move to global plugin |
+| `.opencode/plugin/lib/*` | Global baseline | Shared implementation helpers | Move to global plugin library |
+| `.opencode/plugin/README.md` | Global baseline | Generic plugin docs | Move to global docs |
+| `.opencode/plugin/package.json` | Global baseline | Shared plugin package metadata | Move to global baseline |
+| `.opencode/plugin/tsconfig.json` | Global baseline | Shared plugin build config | Move to global baseline |
+| `.opencode/skill/` | Global baseline | Reusable skills, not repo-specific | Move to global baseline |
+| `.opencode/tool/context7.ts` | Global baseline | Reusable tool | Move to global baseline |
+| `.opencode/tool/grepsearch.ts` | Global baseline | Reusable tool | Move to global baseline |
+| `.opencode/README.md` | Global baseline | Generic OpenCode workspace docs | Move to global docs |
+| `.opencode/AGENTS.md` | Global baseline | Shared operating rules | Move to global baseline docs/policy |
+| `.opencode/AGENT_ALIGNMENT.md` | Global baseline | Shared agent alignment contract | Move to global baseline |
+| `.opencode/.template-manifest.json` | Global baseline | Template system metadata | Move to global baseline |
+| `.opencode/.version` | Global baseline | Baseline package/version metadata | Move to global baseline |
+| `.opencode/package.json` | Global baseline | Baseline package metadata | Move to global baseline |
+| `.opencode/package-lock.json` | Global baseline | Baseline dependency lockfile | Move to global baseline |
+| `.opencode/tsconfig.json` | Global baseline | Shared baseline config | Move to global baseline |
+| `.opencode/tui.json` | Global baseline | Shared TUI config | Move to global baseline |
+| `.opencode/dcp.jsonc` | Global baseline | Shared DCP config pattern | Move to global baseline, allow overlay override if needed |
+| `.opencode/memory/_templates/*` | Global baseline | Shared memory file templates | Move to global baseline template pack |
+| `.opencode/memory/README.md` | Global baseline | Shared memory docs | Move to global baseline |
+| `.opencode/plans/swarm-protocol.md` | Global baseline | Reusable process doc | Move to global docs/templates |
+| `.opencode/plans/*.md` (generated historical plans) | Runtime-only / maybe archive | Historical local planning artifacts, not baseline installer payload | Exclude from thin overlay; optionally archive externally |
+| `.opencode/memory/research/*` | Project overlay (optional archive) | VAT-specific research/history, useful context but not installer baseline | Keep only if user wants repo memory preserved; otherwise archive |
+| `.opencode/memory/project/project.md` | Thin project overlay | VAT-specific project context | Keep in repo overlay |
+| `.opencode/memory/project/state.md` | Thin project overlay | VAT-specific execution/state context | Keep in repo overlay |
+| `.opencode/memory/project/roadmap.md` | Thin project overlay | VAT-specific roadmap | Keep in repo overlay |
+| `.opencode/memory/project/tech-stack.md` | Thin project overlay | VAT-specific stack | Keep in repo overlay |
+| `.opencode/memory/project/user.md` | Thin project overlay | VAT-specific user/product context | Keep in repo overlay |
+| `.opencode/memory/project/gotchas.md` | Thin project overlay | Repo-specific footguns | Keep in repo overlay |
+| `.opencode/memory/session-context.md` | Thin project overlay (optional) | Session bootstrap context that may still be repo-specific | Keep only if actively used; otherwise generate on demand |
+| `.opencode/opencode.json` | Thin project overlay | Repo-specific resolved config, agent/model overrides, plugin enablement, MCP wiring | Rewrite into minimal overlay |
+| `.opencode/opencode.json.tui-migration.bak` | Runtime-only / remove | Backup artifact, not part of thin overlay | Remove from final overlay |
+| `.opencode/.env` | Thin project overlay or avoid | Repo-specific envs if absolutely needed | Prefer not to materialize by default |
+| `.opencode/.env.example` | Thin project overlay | Repo-specific example envs | Keep only if genuinely repo-specific |
+| `.opencode/node_modules/` | Runtime-only / remove | Machine-local dependencies, huge weight | Remove from project overlay |
+| `.opencode/memory.db` | Runtime-only / remove | Local DB state | Move out of repo / do not install in overlay |
+| `.opencode/memory.db-shm` | Runtime-only / remove | SQLite runtime artifact | Remove |
+| `.opencode/memory.db-wal` | Runtime-only / remove | SQLite runtime artifact | Remove |
+| `.opencode/plugin/notification.ts.bak` | Runtime-only / archive | Old experimental backup file | Remove or archive |
+
+---
+
+## Thin Overlay Shape for VAT (Target)
+
+```text
+.opencode/
+  opencode.json
+  memory/
+    project/
+      project.md
+      state.md
+      roadmap.md
+      tech-stack.md
+      user.md
+      gotchas.md
+```
+
+### Optional thin overlay additions
+Only if truly needed:
+
+```text
+.opencode/
+  .env.example
+  plugin/<repo-specific-hook>.ts
+  memory/session-context.md
+```
+
+---
+
+## Proposed Global Baseline Contents for `mrc-opc`
+
+Derived from VAT `.opencode`:
+
+```text
+templates/global/
+  agents/
+  commands/
+  plugins/
+  skills/
+  tools/
+  docs/
+  opencode.json
+  package.json
+  tsconfig.json
+  tui.json
+  dcp.jsonc
+  memory-templates/
+```
+
+---
+
+## Immediate Migration Priorities
+
+### Priority 1 — remove weight from repo overlay source while preserving per-project runtime memory
+- `.opencode/node_modules/`
+- generated backup/cache artifacts
+- keep `.opencode/memory.db*` as per-project runtime state, but do not ship/commit them in the thin overlay template
+
+### Priority 2 — promote reusable baseline
+- `agent/`
+- `command/`
+- `plugin/`
+- `skill/`
+- `tool/`
+- generic docs/manifests/configs
+
+### Priority 3 — rewrite project overlay
+- minimize `.opencode/opencode.json`
+- keep only VAT-specific memory/project policy
+
+---
+
+## Risks / Notes
+
+1. Some plugin files may feel shared but could still assume repo-local relative paths; migration must verify path assumptions.
+2. `opencode.json` rewrite must preserve VAT-specific model/MCP/plugin overrides while dropping baseline duplication.
+3. Historical research/plans under `.opencode/memory/research` and `.opencode/plans` should not be lost accidentally; archive strategy may be needed.
+4. `.env` handling should be conservative — avoid auto-moving secrets into global baseline.
+
+---
+
+## Recommendation
+
+Use VAT as the **canary repo** for the new two-layer architecture:
+
+- `npx mrc-opc install` -> install global baseline
+- `opc install` -> generate VAT thin overlay from templates + VAT-specific overrides
+
+Then apply the same classification logic to TAA and future repos.
+cific overrides
+
+Then apply the same classification logic to TAA and future repos.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "opencode-starterkit",
+  "version": "1.0.1",
+  "private": false,
+  "type": "module",
+  "description": "Global baseline + thin project overlay installer for OpenCode.",
+  "license": "MIT",
+  "bin": {
+    "opencode-starterkit": "./bin/opencode-starterkit.mjs",
+    "ocp": "./bin/ocp.mjs"
+  },
+  "files": [
+    "baseline",
+    "bin",
+    "docs",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test:smoke": "node ./bin/opencode-starterkit.mjs --help && node ./bin/ocp.mjs --help"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,41 @@
+export function parseArgs(argv) {
+  const args = [...argv]
+  const help = args.includes('--help') || args.includes('-h')
+  const command = args.find((arg) => !arg.startsWith('-')) || null
+
+  const getFlagValue = (name) => {
+    const prefix = `${name}=`
+    const inline = args.find((arg) => arg.startsWith(prefix))
+    if (inline) return inline.slice(prefix.length)
+    const index = args.indexOf(name)
+    if (index >= 0 && index + 1 < args.length) return args[index + 1]
+    return null
+  }
+
+  return {
+    help,
+    command,
+    args,
+    options: {
+      action: getFlagValue('--action'),
+      preset: getFlagValue('--preset'),
+      model: getFlagValue('--model'),
+      yes: args.includes('--yes'),
+    },
+  }
+}
+
+export function printHelp(binName) {
+  const isGlobal = binName === 'opencode-starterkit'
+  console.log(`${binName} <command>\n`)
+  console.log('Commands:')
+  console.log(`  ${binName} install    ${isGlobal ? 'Install global OpenCode baseline and expose ocp command' : 'Install thin project overlay in current repo'}`)
+  console.log('  --help, -h      Show help')
+  if (!isGlobal) {
+    console.log('\nProject install flags:')
+    console.log('  --action <name>   Non-interactive action selection')
+    console.log('  --preset <name>   free | recommended | custom | skip')
+    console.log('  --model <id>      Custom model id when using scripted install')
+    console.log('  --yes             Apply without confirmation prompt')
+  }
+}

package/src/config-merge.mjs

@@ -0,0 +1,61 @@
+import fs from 'node:fs'
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function mergeArraysAdditive(current = [], incoming = []) {
+  const out = [...current]
+  for (const item of incoming) {
+    if (!out.some((existing) => JSON.stringify(existing) === JSON.stringify(item))) {
+      out.push(item)
+    }
+  }
+  return out
+}
+
+function mergeObjectsAdditive(current = {}, incoming = {}) {
+  const out = { ...current }
+  for (const [key, value] of Object.entries(incoming)) {
+    if (!(key in out)) {
+      out[key] = value
+      continue
+    }
+
+    const existing = out[key]
+    if (Array.isArray(existing) && Array.isArray(value)) {
+      out[key] = mergeArraysAdditive(existing, value)
+    } else if (isPlainObject(existing) && isPlainObject(value)) {
+      out[key] = mergeObjectsAdditive(existing, value)
+    }
+  }
+  return out
+}
+
+export function mergeOpencodeConfigAdditive({ current, baseline }) {
+  const out = { ...current }
+
+  for (const [key, value] of Object.entries(baseline)) {
+    if (!(key in out)) {
+      out[key] = value
+      continue
+    }
+
+    const existing = out[key]
+    if (Array.isArray(existing) && Array.isArray(value)) {
+      out[key] = mergeArraysAdditive(existing, value)
+    } else if (isPlainObject(existing) && isPlainObject(value)) {
+      out[key] = mergeObjectsAdditive(existing, value)
+    }
+  }
+
+  return out
+}
+
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+
+export function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+}

package/src/constants.mjs

@@ -0,0 +1,58 @@
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const THIS_FILE = fileURLToPath(import.meta.url)
+const SRC_DIR = path.dirname(THIS_FILE)
+const PACKAGE_ROOT = path.resolve(SRC_DIR, '..')
+
+export const HOME = os.homedir()
+export const MRC_OPC_PACKAGE_ROOT = PACKAGE_ROOT
+export const MRC_OPC_BASELINE_ROOT = path.join(PACKAGE_ROOT, 'baseline')
+
+export const GLOBAL_CONFIG_ROOT = path.join(HOME, '.config', 'opencode')
+export const GLOBAL_PACKAGE_ROOT = path.join(GLOBAL_CONFIG_ROOT, 'opencode-starterkit')
+export const GLOBAL_BIN_DIR = path.join(HOME, '.local', 'bin')
+export const GLOBAL_OCP_SHIM = path.join(GLOBAL_BIN_DIR, 'ocp')
+
+export const GLOBAL_AGENTS_DIR = path.join(GLOBAL_CONFIG_ROOT, 'agents')
+export const GLOBAL_SKILLS_DIR = path.join(GLOBAL_CONFIG_ROOT, 'skills')
+export const GLOBAL_PLUGIN_DIR = path.join(GLOBAL_CONFIG_ROOT, 'plugin')
+export const GLOBAL_COMMAND_DIR = path.join(GLOBAL_CONFIG_ROOT, 'command')
+export const GLOBAL_TOOL_DIR = path.join(GLOBAL_CONFIG_ROOT, 'tool')
+export const GLOBAL_DOCS_DIR = path.join(GLOBAL_CONFIG_ROOT, 'docs', 'opencode-starterkit-baseline')
+export const GLOBAL_TEMPLATE_DIR = path.join(GLOBAL_CONFIG_ROOT, 'templates', 'project-overlay')
+
+export const PROJECT_MEMORY_FILES = ['project.md', 'state.md', 'roadmap.md', 'tech-stack.md', 'user.md', 'gotchas.md']
+
+export const ACTION_OPTIONS = [
+  'Initialize project',
+  'Config',
+  'Upgrade',
+  'List agents',
+  'Add agent',
+  'List skills',
+  'Add skill',
+  'Status',
+  'Doctor',
+  'Exit',
+]
+
+export const MODEL_PRESETS = {
+  free: {
+    label: 'Free models',
+    model: 'opencode/minimax-m2.5-free',
+  },
+  recommended: {
+    label: 'Recommended models',
+    model: 'proxy/gpt-5.3-codex',
+  },
+  custom: {
+    label: 'Custom',
+    model: null,
+  },
+  skip: {
+    label: 'Skip',
+    model: null,
+  },
+}

package/src/fs-utils.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true })
+}
+
+export function exists(targetPath) {
+  return fs.existsSync(targetPath)
+}
+
+export function copyFileIfExists(fromPath, toPath) {
+  if (!exists(fromPath)) return false
+  ensureDir(path.dirname(toPath))
+  fs.copyFileSync(fromPath, toPath)
+  return true
+}
+
+export function copyDirRecursive(fromDir, toDir) {
+  if (!exists(fromDir)) return false
+  ensureDir(toDir)
+  fs.cpSync(fromDir, toDir, { recursive: true, force: true })
+  return true
+}
+
+export function writeText(filePath, content) {
+  ensureDir(path.dirname(filePath))
+  fs.writeFileSync(filePath, content, 'utf8')
+}
+
+export function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8')
+}
+
+export function backupPath(targetPath) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  return `${targetPath}.bak-${stamp}`
+}
+
+export function backupIfExists(targetPath) {
+  if (!exists(targetPath)) return null
+  const backup = backupPath(targetPath)
+  ensureDir(path.dirname(backup))
+  fs.cpSync(targetPath, backup, { recursive: true, force: true })
+  return backup
+}

package/src/install-global.mjs

@@ -0,0 +1,102 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  GLOBAL_AGENTS_DIR,
+  GLOBAL_BIN_DIR,
+  GLOBAL_COMMAND_DIR,
+  GLOBAL_CONFIG_ROOT,
+  GLOBAL_DOCS_DIR,
+  GLOBAL_OCP_SHIM,
+  GLOBAL_PACKAGE_ROOT,
+  GLOBAL_PLUGIN_DIR,
+  GLOBAL_SKILLS_DIR,
+  GLOBAL_TEMPLATE_DIR,
+  GLOBAL_TOOL_DIR,
+  MRC_OPC_BASELINE_ROOT,
+  MRC_OPC_PACKAGE_ROOT,
+} from './constants.mjs'
+import { backupIfExists, copyDirRecursive, copyFileIfExists, ensureDir, writeText, exists } from './fs-utils.mjs'
+import { mergeOpencodeConfigAdditive, readJson, writeJson } from './config-merge.mjs'
+
+function installPackageRuntime() {
+  backupIfExists(GLOBAL_PACKAGE_ROOT)
+  ensureDir(GLOBAL_CONFIG_ROOT)
+  fs.cpSync(MRC_OPC_PACKAGE_ROOT, GLOBAL_PACKAGE_ROOT, {
+    recursive: true,
+    force: true,
+    filter: (src) => !src.includes(`${path.sep}.git${path.sep}`) && !src.endsWith(`${path.sep}.git`),
+  })
+}
+
+function copyMarkdownAgents() {
+  ensureDir(GLOBAL_AGENTS_DIR)
+  const sourceDir = path.join(MRC_OPC_BASELINE_ROOT, 'agent')
+  if (!exists(sourceDir)) return
+  for (const file of fs.readdirSync(sourceDir)) {
+    if (!file.endsWith('.md')) continue
+    copyFileIfExists(path.join(sourceDir, file), path.join(GLOBAL_AGENTS_DIR, file))
+  }
+}
+
+function copySkills() { copyDirRecursive(path.join(MRC_OPC_BASELINE_ROOT, 'skill'), GLOBAL_SKILLS_DIR) }
+function copyPlugins() { copyDirRecursive(path.join(MRC_OPC_BASELINE_ROOT, 'plugin'), GLOBAL_PLUGIN_DIR) }
+function copyCommands() { copyDirRecursive(path.join(MRC_OPC_BASELINE_ROOT, 'command'), GLOBAL_COMMAND_DIR) }
+function copyTools() { copyDirRecursive(path.join(MRC_OPC_BASELINE_ROOT, 'tool'), GLOBAL_TOOL_DIR) }
+
+function copyTemplatesAndDocs() {
+  copyDirRecursive(path.join(MRC_OPC_BASELINE_ROOT, 'memory', '_templates'), path.join(GLOBAL_TEMPLATE_DIR, 'memory'))
+  ensureDir(GLOBAL_DOCS_DIR)
+  for (const file of ['README.md', 'AGENTS.md', 'AGENT_ALIGNMENT.md', '.template-manifest.json', '.version', 'dcp.jsonc', 'tui.json', 'tsconfig.json', 'package.json', 'package-lock.json', 'opencode.json']) {
+    copyFileIfExists(path.join(MRC_OPC_BASELINE_ROOT, file), path.join(GLOBAL_DOCS_DIR, file.replace(/^\./, 'dot-')))
+  }
+  copyDirRecursive(path.join(MRC_OPC_BASELINE_ROOT, 'context'), path.join(GLOBAL_DOCS_DIR, 'context'))
+}
+
+function installOcpShim() {
+  ensureDir(GLOBAL_BIN_DIR)
+  const shim = `#!/usr/bin/env bash\nnode \"${path.join(GLOBAL_PACKAGE_ROOT, 'bin', 'ocp.mjs')}\" \"$@\"\n`
+  writeText(GLOBAL_OCP_SHIM, shim)
+  fs.chmodSync(GLOBAL_OCP_SHIM, 0o755)
+}
+
+function mergeGlobalOpencodeJson() {
+  const baselinePath = path.join(MRC_OPC_BASELINE_ROOT, 'opencode.json')
+  const globalPath = path.join(GLOBAL_CONFIG_ROOT, 'opencode.json')
+
+  if (!exists(baselinePath)) return { merged: false, reason: 'missing baseline opencode.json' }
+
+  const baseline = readJson(baselinePath)
+  const current = exists(globalPath) ? readJson(globalPath) : {}
+  const merged = mergeOpencodeConfigAdditive({ current, baseline })
+  backupIfExists(globalPath)
+  writeJson(globalPath, merged)
+  return { merged: true, globalPath }
+}
+
+export async function installGlobal({ cwd }) {
+  console.log('[opencode-starterkit] Global install starting')
+  console.log(`cwd=${cwd}`)
+  console.log(`baseline=${MRC_OPC_BASELINE_ROOT}`)
+  installPackageRuntime()
+  copyMarkdownAgents()
+  copySkills()
+  copyPlugins()
+  copyCommands()
+  copyTools()
+  copyTemplatesAndDocs()
+  const mergeResult = mergeGlobalOpencodeJson()
+  installOcpShim()
+  console.log(`[opencode-starterkit] Installed package runtime at ${GLOBAL_PACKAGE_ROOT}`)
+  console.log(`[opencode-starterkit] Synced agents -> ${GLOBAL_AGENTS_DIR}`)
+  console.log(`[opencode-starterkit] Synced skills -> ${GLOBAL_SKILLS_DIR}`)
+  console.log(`[opencode-starterkit] Synced plugins -> ${GLOBAL_PLUGIN_DIR}`)
+  console.log(`[opencode-starterkit] Synced commands -> ${GLOBAL_COMMAND_DIR}`)
+  console.log(`[opencode-starterkit] Synced tools -> ${GLOBAL_TOOL_DIR}`)
+  console.log(`[opencode-starterkit] Synced templates/docs -> ${GLOBAL_TEMPLATE_DIR}`)
+  if (mergeResult.merged) {
+    console.log(`[opencode-starterkit] Merged global config -> ${mergeResult.globalPath}`)
+  } else {
+    console.log(`[opencode-starterkit] Skipped global config merge: ${mergeResult.reason}`)
+  }
+  console.log(`[opencode-starterkit] Installed ocp shim at ${GLOBAL_OCP_SHIM}`)
+}

package/src/install-project.mjs

@@ -0,0 +1,81 @@
+import path from 'node:path'
+import { ACTION_OPTIONS, MODEL_PRESETS, PROJECT_MEMORY_FILES } from './constants.mjs'
+import { confirm, askText, selectOption } from './prompt.mjs'
+import { ensureDir, writeText } from './fs-utils.mjs'
+import { loadProjectMemoryTemplates, renderProjectOpencodeJson } from './templates.mjs'
+import { bootstrapProjectMemoryDb } from './memory-bootstrap.mjs'
+
+function printSummary({ cwd, action, model }) {
+  console.log('\n[opc] Summary')
+  console.log(`repo=${cwd}`)
+  console.log(`action=${action}`)
+  console.log(`model=${model || 'inherit/global-default'}`)
+  console.log('apply=.opencode/opencode.json + .opencode/memory/project/* + .opencode/memory.db')
+}
+
+function materializeThinOverlay({ cwd, model }) {
+  const root = path.join(cwd, '.opencode')
+  const memoryDir = path.join(root, 'memory', 'project')
+  ensureDir(memoryDir)
+
+  writeText(path.join(root, 'opencode.json'), renderProjectOpencodeJson({ model }))
+
+  const templates = loadProjectMemoryTemplates()
+  for (const name of PROJECT_MEMORY_FILES) {
+    writeText(path.join(memoryDir, name), templates[name])
+  }
+}
+
+function resolvePresetModel(presetKey, explicitModel) {
+  if (presetKey === 'custom') return explicitModel || null
+  return MODEL_PRESETS[presetKey]?.model || null
+}
+
+export async function installProjectOverlay({ cwd, args, options = {} }) {
+  console.log('[opc] Project overlay install')
+  console.log(`cwd=${cwd}`)
+
+  const optionBag = options || {}
+  let action = optionBag.action || null
+  if (!action) {
+    action = await selectOption({ title: 'Step 1/3 — Select action', options: ACTION_OPTIONS, defaultIndex: 0 })
+  }
+
+  if (action === 'Exit') {
+    console.log('[opc] Exit without changes')
+    return
+  }
+
+  if (action !== 'Initialize project') {
+    console.log(`[opc] Action \"${action}\" is not implemented yet in this scaffold. Use Initialize project first.`)
+    return
+  }
+
+  let presetKey = optionBag.preset || null
+  if (!presetKey) {
+    const preset = await selectOption({
+      title: 'Step 2/3 — Choose model preset',
+      options: Object.entries(MODEL_PRESETS).map(([key, item]) => `${key}: ${item.label}`),
+      defaultIndex: 1,
+    })
+    presetKey = preset.split(':')[0]
+  }
+
+  let model = resolvePresetModel(presetKey, optionBag.model)
+  if (presetKey === 'custom' && !model) {
+    model = await askText({ title: 'Enter custom model id', placeholder: 'provider/model' })
+  }
+
+  printSummary({ cwd, action, model })
+  const approved = optionBag.yes ? true : await confirm({ title: 'Step 3/3 — Apply thin overlay now?', defaultYes: true })
+  if (!approved) {
+    console.log('[opc] Cancelled before writing files')
+    return
+  }
+
+  materializeThinOverlay({ cwd, model })
+  const dbResult = bootstrapProjectMemoryDb({ cwd })
+  console.log(`[opc] Thin overlay installed`)
+  console.log(`[opc] Memory DB bootstrapped via ${dbResult.schemaPath}`)
+  console.log('[opc] Ready to code')
+}

package/src/memory-bootstrap.mjs

@@ -0,0 +1,29 @@
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { MRC_OPC_BASELINE_ROOT } from './constants.mjs'
+import { exists } from './fs-utils.mjs'
+
+function resolveSchemaPath() {
+  const baselineSchema = path.join(MRC_OPC_BASELINE_ROOT, 'plugin', 'lib', 'db', 'schema.ts')
+  if (exists(baselineSchema)) return baselineSchema
+  throw new Error(`schema.ts not found in baseline: ${baselineSchema}`)
+}
+
+export function bootstrapProjectMemoryDb({ cwd }) {
+  const schemaPath = resolveSchemaPath()
+  const code = `import { getMemoryDB, closeMemoryDB } from ${JSON.stringify(schemaPath)}; getMemoryDB(); closeMemoryDB(); console.log('MEMORY_DB_BOOTSTRAPPED');`
+  const result = spawnSync('bun', ['-e', code], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+
+  if (result.status !== 0) {
+    throw new Error(`memory db bootstrap failed\nstdout=${result.stdout || ''}\nstderr=${result.stderr || ''}`)
+  }
+
+  return {
+    schemaPath,
+    stdout: (result.stdout || '').trim(),
+  }
+}

package/src/prompt.mjs

@@ -0,0 +1,31 @@
+import readline from 'node:readline/promises'
+import { stdin as input, stdout as output } from 'node:process'
+
+export async function selectOption({ title, options, defaultIndex = 0 }) {
+  const rl = readline.createInterface({ input, output })
+  console.log(`\n${title}`)
+  options.forEach((option, index) => {
+    console.log(`${index + 1}. ${option}`)
+  })
+  const answer = await rl.question(`Choose [${defaultIndex + 1}]: `)
+  rl.close()
+  const selectedIndex = Number(answer || defaultIndex + 1) - 1
+  return options[selectedIndex] || options[defaultIndex]
+}
+
+export async function askText({ title, placeholder = '' }) {
+  const rl = readline.createInterface({ input, output })
+  const answer = await rl.question(`${title}${placeholder ? ` (${placeholder})` : ''}: `)
+  rl.close()
+  return answer.trim()
+}
+
+export async function confirm({ title, defaultYes = true }) {
+  const rl = readline.createInterface({ input, output })
+  const suffix = defaultYes ? '[Y/n]' : '[y/N]'
+  const answer = await rl.question(`${title} ${suffix}: `)
+  rl.close()
+  const normalized = answer.trim().toLowerCase()
+  if (!normalized) return defaultYes
+  return normalized === 'y' || normalized === 'yes'
+}