@hippo-digital/hippocampus 1.0.0-rc.1

package/scripts/index-source-artefacts.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const { createContextOrExit } = require('../lib/context')
+
+// A durable record of what was ingested, and from where.
+//
+// The working assumption is that the shared drive is the system of record: a
+// file is downloaded into the inbox, its knowledge is extracted, and the copy is
+// deleted. That only works if a record in the knowledge base can still be
+// traced to a named original afterwards - and a path like
+// `hippocampus/source-artefacts/personas/x.docx` cannot, because it names the
+// copy that is supposed to be deleted.
+//
+// So this walks the artefacts while they are still here and writes down the
+// things that cannot be recovered once they are gone: the exact filename, the
+// size, and the sha256 that proves a file found later is the same one. Origins
+// are read from the manifests and the ingestion notes where they were recorded,
+// and left explicitly unknown where they were not - a guessed provenance is
+// worse than an admitted gap.
+
+const argv = process.argv.slice(2)
+const dryRun = argv.includes('--dry-run')
+const ctx = createContextOrExit({ argv })
+
+function main () {
+  const artefactsRoot = ctx.paths.sourceArtefactsDir
+  if (!fs.existsSync(artefactsRoot)) {
+    console.error(`No source artefacts directory at ${artefactsRoot}`)
+    process.exit(1)
+  }
+
+  const files = walk(artefactsRoot).sort()
+  const origins = readStatedOrigins(artefactsRoot, files)
+  const staged = readManifestEntries()
+  const citations = readCitations()
+
+  const entries = files.map((absolute) => {
+    const relative = path.relative(artefactsRoot, absolute).split(path.sep).join('/')
+    const contents = fs.readFileSync(absolute)
+    const sha256 = crypto.createHash('sha256').update(contents).digest('hex')
+    const stagedEntry = staged.bySha.get(sha256) || staged.byName.get(path.basename(relative))
+
+    // An ingestion note was written here; it has no upstream original, and
+    // counting it as one more artefact with an unknown origin overstates the gap.
+    const authoredHere = relative.endsWith('-ingestion.md')
+
+    return {
+      path: relative,
+      fileName: path.basename(relative),
+      authoredHere,
+      type: path.extname(relative).replace('.', '').toLowerCase() || 'none',
+      bytes: contents.length,
+      sha256,
+      roundId: stagedEntry?.roundId || roundFromPath(relative),
+      origin: origins.get(relative) || (stagedEntry
+        ? { stated: stagedEntry.sourcePath, statedIn: 'hippocampus/manifests/research.json' }
+        : { stated: null, statedIn: null }),
+      ingestedAs: stagedEntry?.id || null,
+      citedBy: citations.get(relative) || []
+    }
+  })
+
+  const index = {
+    version: 1,
+    generator: 'hippocampus source index',
+    indexedAt: new Date().toISOString(),
+    note: 'Written while the artefacts were still present. The shared drive is the ' +
+      'system of record; these files are working copies and may have been deleted ' +
+      'since. Match an original by fileName, and confirm it with sha256.',
+    artefactCount: entries.filter((e) => !e.authoredHere).length,
+    noteCount: entries.filter((e) => e.authoredHere).length,
+    withStatedOrigin: entries.filter((e) => !e.authoredHere && e.origin.stated).length,
+    missingOrigin: entries.filter((e) => !e.authoredHere && !e.origin.stated).map((e) => e.path),
+    cited: entries.filter((e) => e.citedBy.length).length,
+    artefacts: entries
+  }
+
+  const jsonPath = path.join(ctx.paths.manifestsDir, 'source-index.json')
+  const mdPath = path.join(ctx.paths.manifestsDir, 'source-index.md')
+
+  console.log(`${index.artefactCount} artefacts indexed (plus ${index.noteCount} ingestion notes written here)`)
+  console.log(`  ${index.withStatedOrigin} with a recorded origin, ${index.missingOrigin.length} without`)
+  console.log(`  ${index.cited} cited by a knowledge record`)
+  if (index.missingOrigin.length) {
+    console.log('\nNo origin recorded for these - worth writing down before the copies go:')
+    for (const missing of index.missingOrigin) console.log(`  ${missing}`)
+  }
+
+  if (dryRun) {
+    console.log(`\nwould write ${path.relative(ctx.root, jsonPath)} and ${path.relative(ctx.root, mdPath)}`)
+    return
+  }
+
+  fs.mkdirSync(ctx.paths.manifestsDir, { recursive: true })
+  fs.writeFileSync(jsonPath, JSON.stringify(index, null, 2) + '\n')
+  fs.writeFileSync(mdPath, renderMarkdown(index))
+  console.log(`\nwrote ${path.relative(ctx.root, jsonPath)}`)
+  console.log(`wrote ${path.relative(ctx.root, mdPath)}`)
+}
+
+function walk (dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) walk(full, out)
+    else if (!entry.name.startsWith('.')) out.push(full)
+  }
+  return out
+}
+
+function roundFromPath (relative) {
+  const match = relative.match(/(?:^|\/)round-(\d+)(?:\/|$)/i)
+  return match ? `round-${match[1]}` : null
+}
+
+/**
+ * Ingestion notes record where material came from, in prose. They are read two
+ * ways, most specific first.
+ *
+ * Notes tend to be written as "`<origin>` to `hippocampus/source-artefacts/...`",
+ * so a quoted destination is paired with the quoted origin before it. That
+ * catches a file named individually even when it landed in a different folder
+ * from the note - the first attempt attributed notes only to files beside them,
+ * which missed exactly that case.
+ *
+ * Anything still unclaimed falls back to the note in its own directory. Every
+ * origin records which note asserted it, so the claim can be checked rather
+ * than trusted.
+ */
+function readStatedOrigins (artefactsRoot, files) {
+  const origins = new Map()
+  const notes = files.filter((f) => f.endsWith('-ingestion.md'))
+  const relativeOf = (f) => path.relative(artefactsRoot, f).split(path.sep).join('/')
+
+  for (const note of notes) {
+    const text = fs.readFileSync(note, 'utf8')
+    const noteRel = path.relative(ctx.root, note).split(path.sep).join('/')
+    const quoted = [...text.matchAll(/`([^`]+)`/g)].map((m) => m[1])
+
+    let lastOrigin = null
+    for (const value of quoted) {
+      const destination = value.match(/source-artefacts\/(.+)$/)
+      if (!destination) {
+        if (/[/\\]/.test(value) && !value.startsWith('hippocampus/')) lastOrigin = value
+        continue
+      }
+      if (!lastOrigin) continue
+      const target = destination[1]
+      // A destination may be written with a placeholder, e.g. <user-id>; those
+      // stand for the folder rather than one file.
+      if (/[<>*]/.test(target)) continue
+      if (!origins.has(target)) origins.set(target, { stated: lastOrigin, statedIn: noteRel })
+    }
+  }
+
+  for (const note of notes) {
+    const text = fs.readFileSync(note, 'utf8')
+    const section = text.match(/^##\s+Sources?(?:\s+copied)?\s*$([\s\S]*?)(?=^##\s|\Z)/m)
+    const body = section ? section[1] : text.slice(0, 1200)
+    const quoted = [...body.matchAll(/`([^`]+)`/g)].map((m) => m[1])
+    const stated = quoted.find((q) => !q.startsWith('hippocampus/') && /[/\\]/.test(q))
+    if (!stated) continue
+
+    const noteDir = path.dirname(note)
+    const noteRel = path.relative(ctx.root, note).split(path.sep).join('/')
+    for (const file of files) {
+      if (path.dirname(file) !== noteDir || file === note) continue
+      const rel = relativeOf(file)
+      if (!origins.has(rel)) origins.set(rel, { stated, statedIn: noteRel })
+    }
+  }
+  return origins
+}
+
+function readManifestEntries () {
+  const bySha = new Map()
+  const byName = new Map()
+  for (const file of ['research.json', 'project.json']) {
+    const manifestPath = path.join(ctx.paths.manifestsDir, file)
+    if (!fs.existsSync(manifestPath)) continue
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    for (const entry of manifest.artefacts || []) {
+      if (entry.sha256) bySha.set(entry.sha256, entry)
+      if (entry.sourcePath) byName.set(path.basename(entry.sourcePath), entry)
+    }
+  }
+  return { bySha, byName }
+}
+
+/** Which knowledge records name each artefact, so a deletion is a known cost. */
+function readCitations () {
+  const citations = new Map()
+  const dir = ctx.paths.knowledgeSourceDir
+  if (!fs.existsSync(dir)) return citations
+
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.json') || file.startsWith('_')) continue
+    const data = JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'))
+    for (const record of Array.isArray(data) ? data : [data]) {
+      const sourcePath = record && record.sourcePath
+      if (!sourcePath) continue
+      // Filenames contain spaces; stopping at the first one silently drops the
+      // citation and makes an artefact look unused.
+      const match = sourcePath.match(/source-artefacts\/([^,]+)/)
+      if (!match) continue
+      const key = match[1].trim()
+      const list = citations.get(key) || []
+      list.push(record.id)
+      citations.set(key, list)
+    }
+  }
+  return citations
+}
+
+function renderMarkdown (index) {
+  const lines = [
+    '# Source artefact index',
+    '',
+    index.note.replace(/(.{1,78})(\s|$)/g, '$1\n').trim(),
+    '',
+    `Indexed ${index.indexedAt.slice(0, 10)} — ${index.artefactCount} artefacts, ` +
+      `${index.withStatedOrigin} with a recorded origin, ${index.cited} cited by a knowledge record.` +
+      (index.missingOrigin.length
+        ? ` **${index.missingOrigin.length} have no recorded origin** and should get one before the copies are deleted.`
+        : ''),
+    '',
+    '| File | Type | Size | Round | Recorded origin | Cited by |',
+    '| --- | --- | ---: | --- | --- | ---: |'
+  ]
+
+  for (const a of index.artefacts) {
+    if (a.authoredHere) continue
+    lines.push([
+      '',
+      `\`${a.fileName}\``,
+      a.type,
+      `${Math.max(1, Math.round(a.bytes / 1024))} KB`,
+      a.roundId || '—',
+      a.origin.stated ? `\`${a.origin.stated}\`` : '**not recorded**',
+      a.citedBy.length || '—',
+      ''
+    ].join(' | ').trim())
+  }
+
+  lines.push('', '## Checksums', '',
+    'sha256, so a file found on the drive later can be confirmed as the one that',
+    'was ingested rather than an edited descendant.', '', '```')
+  for (const a of index.artefacts) {
+    if (!a.authoredHere) lines.push(`${a.sha256}  ${a.path}`)
+  }
+  lines.push('```', '')
+  return lines.join('\n')
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}

package/scripts/init.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+const { resolveRoot, CONFIG_FILENAME } = require('../lib/resolve-root')
+const { CURRENT_SCHEMA_VERSION } = require('../lib/schema-version')
+const hostEdit = require('../lib/host-edit')
+
+// Set a host project up to use Hippocampus: write the config and an empty
+// knowledge base, then make the two host edits - both inside marked blocks, both
+// reversible with `hippocampus eject`.
+//
+// --dry-run       print what would change and write nothing
+// --no-wire       write the data, print the host edits to paste by hand
+// --private-artefacts  gitignore the copied research material
+
+const argv = process.argv.slice(2)
+const dryRun = argv.includes('--dry-run')
+const noWire = argv.includes('--no-wire')
+const privateArtefacts = argv.includes('--private-artefacts')
+
+const ROUTES_BODY = `const { createHippocampus } = require('@hippo-digital/hippocampus')
+router.use(createHippocampus().router)`
+
+const APP_VIEWS_ENTRY = "require('@hippo-digital/hippocampus').createHippocampus().viewsPath"
+
+const planned = []
+const manual = []
+
+function plan (description, write) {
+  planned.push({ description, write })
+}
+
+function main () {
+  const { root, source } = resolveRoot({ argv })
+  console.log(`Project root: ${root}`)
+  console.log(`Resolved from: ${source}\n`)
+
+  planConfig(root)
+  planKnowledgeBase(root)
+  planArtefactGovernance(root)
+  if (!noWire) {
+    planHostEdit(path.join(root, 'app/routes.js'), wireRoutes)
+    planHostEdit(path.join(root, 'app.js'), wireApp)
+  } else {
+    manual.push(manualInstructions())
+  }
+
+  if (!planned.length && !manual.length) {
+    console.log('Nothing to do - this project is already set up.')
+    return
+  }
+
+  for (const step of planned) {
+    console.log(`${dryRun ? 'would write' : 'wrote'}  ${step.description}`)
+    if (!dryRun) step.write()
+  }
+
+  for (const note of manual) {
+    console.log(`\n${note}`)
+  }
+
+  if (!dryRun) {
+    console.log('\nNext: npx hippocampus doctor')
+  }
+}
+
+function planConfig (root) {
+  const configPath = path.join(root, CONFIG_FILENAME)
+  if (fs.existsSync(configPath)) return
+  plan(CONFIG_FILENAME, () => fs.writeFileSync(configPath, JSON.stringify({
+    configVersion: 1,
+    dataDir: 'hippocampus',
+    artefactsDir: 'artefacts',
+    viewer: { basePath: '/hippocampus' }
+  }, null, 2) + '\n'))
+}
+
+function planKnowledgeBase (root) {
+  const sourceDir = path.join(root, 'hippocampus/source')
+  const projectPath = path.join(sourceDir, 'project.json')
+  if (fs.existsSync(projectPath)) return
+
+  // IDs are kebab-case throughout the schema, and a directory name is not
+  // required to be. Deriving one that fails validation the first time somebody
+  // runs `validate` is a bad first impression for the sake of two lines.
+  const dirName = path.basename(root)
+  const id = kebab(dirName) || 'prototype'
+  const name = dirName
+  plan('hippocampus/source/project.json and an empty knowledge base', () => {
+    for (const dir of ['source', 'inbox/project', 'inbox/research', 'imports/project', 'imports/research', 'manifests']) {
+      fs.mkdirSync(path.join(root, 'hippocampus', dir), { recursive: true })
+    }
+    fs.writeFileSync(projectPath, JSON.stringify({
+      id: `${id}-knowledge`,
+      name,
+      description: 'Describe what this service is for. Everything in the knowledge base hangs off this.',
+      phase: 'discovery',
+      serviceArea: 'unset',
+      prototypeSlice: 'unset'
+    }, null, 2) + '\n')
+    fs.writeFileSync(path.join(sourceDir, '_meta.json'), JSON.stringify({
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      generator: 'hippocampus init',
+      updatedAt: new Date().toISOString()
+    }, null, 2) + '\n')
+  })
+}
+
+// source-artefacts holds the research material a round was built from -
+// transcripts, scenario maps, quotes with participant identifiers attached.
+// Putting that in a prototype repo's history is a decision for the team, and
+// git history is not somewhere you can quietly take something back out of. So
+// this package neither commits it by default nor ignores it by default: it says
+// what is there and what the options are.
+const ARTEFACTS_IGNORE_LINE = 'hippocampus/source-artefacts/'
+
+function planArtefactGovernance (root) {
+  const artefactsDir = path.join(root, 'hippocampus/source-artefacts')
+  const gitignorePath = path.join(root, '.gitignore')
+  const current = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : ''
+  const alreadyIgnored = current.includes(ARTEFACTS_IGNORE_LINE)
+
+  if (privateArtefacts) {
+    if (alreadyIgnored) return
+    plan(`.gitignore (${ARTEFACTS_IGNORE_LINE})`, () => {
+      const prefix = current.trim() ? `${current.replace(/\n*$/, '\n')}\n` : ''
+      fs.writeFileSync(gitignorePath, prefix +
+        '# Research material copied into the knowledge base: transcripts and\n' +
+        '# participant quotes. Kept out of this repo by `hippocampus init --private-artefacts`.\n' +
+        `${ARTEFACTS_IGNORE_LINE}\n`)
+    })
+    return
+  }
+
+  if (alreadyIgnored) return
+
+  const count = countFiles(artefactsDir)
+  if (!count) return
+
+  manual.push([
+    `${count} files in hippocampus/source-artefacts/ are not gitignored.`,
+    '',
+    'That directory holds the research material rounds were built from -',
+    'transcripts, scenario maps and quotes with participants attached. Committing',
+    'it puts that in this repo\'s history, which is not somewhere you can quietly',
+    'take it back out of.',
+    '',
+    'If it should stay out of git:',
+    '  npx hippocampus init --private-artefacts',
+    '',
+    'If your team has decided it belongs here, nothing to do.'
+  ].join('\n'))
+}
+
+function countFiles (dir) {
+  if (!fs.existsSync(dir)) return 0
+  let total = 0
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    total += entry.isDirectory() ? countFiles(path.join(dir, entry.name)) : 1
+  }
+  return total
+}
+
+function planHostEdit (filePath, edit) {
+  if (!fs.existsSync(filePath)) {
+    manual.push(`${path.basename(filePath)} not found, so it was not edited.\n${manualInstructions()}`)
+    return
+  }
+
+  const before = fs.readFileSync(filePath, 'utf8')
+  const result = edit(before)
+
+  if (result.action === 'unchanged') return
+
+  if (!result.source) {
+    manual.push(`${path.relative(process.cwd(), filePath)}: ${result.reason}\n${manualInstructions()}`)
+    return
+  }
+
+  if (dryRun) {
+    console.log(`\nwould change ${path.relative(process.cwd(), filePath)}:`)
+    console.log(hostEdit.diff(before, result.source, path.relative(process.cwd(), filePath)))
+    return
+  }
+
+  plan(`${path.relative(process.cwd(), filePath)} (${result.action}, backed up)`, () => {
+    hostEdit.backup(filePath)
+    fs.writeFileSync(filePath, result.source)
+  })
+}
+
+function wireRoutes (source) {
+  return hostEdit.upsertBlock(source, {
+    id: 'hippocampus',
+    body: ROUTES_BODY,
+    anchor: (src) => {
+      const exports = src.lastIndexOf('module.exports')
+      return exports === -1 ? src.length : exports
+    }
+  })
+}
+
+function wireApp (source) {
+  return hostEdit.addToStringArray(source, { name: 'viewsPath', entry: APP_VIEWS_ENTRY })
+}
+
+function kebab (value) {
+  return String(value)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+function manualInstructions () {
+  return [
+    'Add these by hand:',
+    '',
+    '  app/routes.js',
+    `    ${ROUTES_BODY.split('\n').join('\n    ')}`,
+    '',
+    '  app.js - add to the viewsPath array',
+    `    ${APP_VIEWS_ENTRY}`
+  ].join('\n')
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}

package/scripts/install-skills.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const { resolveRoot } = require('../lib/resolve-root')
+const packagePaths = require('../lib/package-paths')
+
+// Skills are copied into the host, unlike docs, because an agent reads them as
+// repo files. Two rules follow from that:
+//
+//   1. A host may already have its own skills. The catalog is MERGED, never
+//      replaced - overwriting somebody's skills.json deletes their work, and it
+//      is the kind of thing that only shows up on a repo that already has some.
+//   2. Copies go stale, so each installed file records the hash of what was
+//      written. On a later run, a file that still matches is updated silently
+//      and one the team has edited is named and left alone.
+//
+// Shared files a host is entitled to own - the README, the format contract, the
+// schema - are written only when absent.
+
+const argv = process.argv.slice(2)
+const dryRun = argv.includes('--dry-run')
+const force = argv.includes('--force')
+const MANIFEST = '.hippocampus-skills.json'
+const NEVER_OVERWRITE = new Set(['README.md', 'SKILL-FORMAT.md', 'skills.schema.json', 'COVERAGE-MATRIX.md'])
+
+function hash (text) {
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16)
+}
+
+function main () {
+  const { root } = resolveRoot({ argv })
+  const targetDir = path.join(root, '.github/skills')
+  const manifestPath = path.join(targetDir, MANIFEST)
+  const manifest = fs.existsSync(manifestPath)
+    ? JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    : { files: {}, skillIds: [] }
+  manifest.files = manifest.files || {}
+  manifest.skillIds = manifest.skillIds || []
+
+  console.log(`Project root: ${root}`)
+  console.log(`Installing to: ${path.relative(root, targetDir)}\n`)
+
+  const written = []
+  const skipped = []
+  const unchanged = []
+  const kept = []
+
+  for (const name of fs.readdirSync(packagePaths.skillsDir)) {
+    if (name === 'skills.json' || !/\.(skill\.md|md|json)$/.test(name)) continue
+
+    const to = path.join(targetDir, name)
+    const content = fs.readFileSync(path.join(packagePaths.skillsDir, name), 'utf8')
+    const incoming = hash(content)
+
+    if (fs.existsSync(to)) {
+      const current = hash(fs.readFileSync(to, 'utf8'))
+      if (current === incoming) { unchanged.push(name); continue }
+      if (NEVER_OVERWRITE.has(name)) { kept.push(name); continue }
+      const installed = manifest.files[name]
+      if (installed && current !== installed && !force) { skipped.push(name); continue }
+    } else if (NEVER_OVERWRITE.has(name) && name !== 'SKILL-FORMAT.md' && name !== 'skills.schema.json') {
+      // A README the host does not have is worth providing; one it does is not.
+    }
+
+    written.push(name)
+    if (!dryRun) {
+      fs.mkdirSync(targetDir, { recursive: true })
+      fs.writeFileSync(to, content)
+    }
+    manifest.files[name] = incoming
+  }
+
+  const merged = mergeCatalog(targetDir, manifest)
+
+  if (!dryRun && (written.length || merged.added.length)) {
+    manifest.version = require('../package.json').version
+    manifest.updatedAt = new Date().toISOString()
+    fs.mkdirSync(targetDir, { recursive: true })
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+  }
+
+  console.log(`${dryRun ? 'would install' : 'installed'}: ${written.length} files`)
+  console.log(`${dryRun ? 'would add' : 'added'} to the catalog: ${merged.added.length} skills` +
+    (merged.existing ? ` (alongside ${merged.existing} already there)` : ''))
+  if (merged.refreshed) console.log(`refreshed in the catalog: ${merged.refreshed} entries`)
+  if (unchanged.length) console.log(`already current: ${unchanged.length}`)
+  if (kept.length) console.log(`left as yours: ${kept.join(', ')}`)
+  if (skipped.length) {
+    console.log(`\nleft alone because they have been edited here (${skipped.length}):`)
+    for (const name of skipped) console.log(`  ${name}`)
+    console.log('\nRe-install them with --force once you have kept whatever you changed.')
+  }
+}
+
+/**
+ * A host's skills.json is theirs. Package skills are added by id; the host's own
+ * entries are never touched.
+ *
+ * An entry we installed is refreshed when the skill file beside it is still
+ * byte-for-byte ours - because the host's validator compares the two field by
+ * field, so a file that matches us with an entry that does not is simply a
+ * broken catalog. Keying this off "did we write the file this run?" was the
+ * first attempt and it was wrong: an upgrade that rewrites files and then fails
+ * part-way leaves exactly that mismatch, and the next run has to be able to
+ * finish the job.
+ *
+ * If the file has been edited locally it is left alone, and so is its entry.
+ */
+function mergeCatalog (targetDir, manifest) {
+  const catalogPath = path.join(targetDir, 'skills.json')
+  const incoming = JSON.parse(fs.readFileSync(path.join(packagePaths.skillsDir, 'skills.json'), 'utf8'))
+
+  if (!fs.existsSync(catalogPath)) {
+    if (!dryRun) {
+      fs.mkdirSync(targetDir, { recursive: true })
+      fs.writeFileSync(catalogPath, JSON.stringify(incoming, null, 2) + '\n')
+    }
+    manifest.skillIds = incoming.skills.map((s) => s.id)
+    return { added: incoming.skills, existing: 0, refreshed: 0 }
+  }
+
+  const host = JSON.parse(fs.readFileSync(catalogPath, 'utf8'))
+  const present = new Set(host.skills.map((s) => s.id))
+  const added = incoming.skills.filter((s) => !present.has(s.id))
+
+  const ours = new Set(manifest.skillIds || [])
+  const incomingById = new Map(incoming.skills.map((s) => [s.id, s]))
+  let refreshed = 0
+  const updated = host.skills.map((entry) => {
+    const incomingEntry = incomingById.get(entry.id)
+    if (!incomingEntry || !ours.has(entry.id)) return entry
+    if (!fileIsStillOurs(targetDir, incomingEntry.file)) return entry
+    if (JSON.stringify(entry) === JSON.stringify(incomingEntry)) return entry
+    refreshed++
+    return incomingEntry
+  })
+
+  if ((added.length || refreshed) && !dryRun) {
+    host.skills = [...updated, ...added]
+    fs.writeFileSync(catalogPath, JSON.stringify(host, null, 2) + '\n')
+  }
+  manifest.skillIds = [...new Set([...manifest.skillIds, ...incoming.skills.map((s) => s.id)])]
+
+  return { added, existing: present.size, refreshed }
+}
+
+function fileIsStillOurs (targetDir, fileName) {
+  const hostFile = path.join(targetDir, fileName)
+  const packageFile = path.join(packagePaths.skillsDir, fileName)
+  if (!fs.existsSync(hostFile) || !fs.existsSync(packageFile)) return false
+  return fs.readFileSync(hostFile, 'utf8') === fs.readFileSync(packageFile, 'utf8')
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}