@rahmantech/knl-view 0.1.0 → 0.3.0

package/server/install.js

@@ -1,6 +1,8 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
+import net from 'node:net'
+import { globalConfigPath } from './config.js'
 
 // AnchorDB installer for knl-view. Two paths:
 // - Linux: binary from GitHub Releases (tar.gz per architecture, verified
@@ -11,10 +13,64 @@ import crypto from 'node:crypto'
 // orchestration (prompts, spawn) stays in bin/knl-view.js.
 
 export const GHCR_IMAGE = 'ghcr.io/rachmanzz/anchordb'
-export const HTTP_PORT_DEFAULT = 7447
-export const WIRE_PORT_DEFAULT = 7448
+export const HTTP_PORT_DEFAULT = 17447
+export const WIRE_PORT_DEFAULT = 17448
 export const CONTAINER_NAME = 'anchordb-knlview'
 
+/** Check if a TCP port is currently free on a host. */
+export async function isPortAvailable(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const server = net.createServer()
+    server.once('error', () => resolve(false))
+    server.once('listening', () => {
+      server.close(() => resolve(true))
+    })
+    server.listen(port, host)
+  })
+}
+
+/** Find the next available TCP port sequentially starting from startPort. */
+export async function findNextAvailablePort(startPort, host = '127.0.0.1') {
+  let port = Number(startPort)
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new RangeError(`Invalid start port: ${startPort}`)
+  }
+  while (!(await isPortAvailable(port, host))) {
+    port++
+    if (port > 65535) {
+      throw new Error(`No available port found up to 65535 starting from ${startPort}`)
+    }
+  }
+  return port
+}
+
+/** Check desired AnchorDB ports and suggest alternatives if any is taken. */
+export async function resolveAnchorPorts({
+  desiredWirePort = WIRE_PORT_DEFAULT,
+  desiredHttpPort = HTTP_PORT_DEFAULT,
+  host = '127.0.0.1'
+} = {}) {
+  const wireAvailable = await isPortAvailable(desiredWirePort, host)
+  const httpAvailable = desiredHttpPort !== desiredWirePort && (await isPortAvailable(desiredHttpPort, host))
+
+  const suggestedWirePort = wireAvailable ? desiredWirePort : await findNextAvailablePort(desiredWirePort + 1, host)
+  let candidateHttp = (httpAvailable && desiredHttpPort !== suggestedWirePort)
+    ? desiredHttpPort
+    : await findNextAvailablePort(desiredHttpPort + 1, host)
+  if (candidateHttp === suggestedWirePort) {
+    candidateHttp = await findNextAvailablePort(candidateHttp + 1, host)
+  }
+
+  return {
+    wirePort: desiredWirePort,
+    httpPort: desiredHttpPort,
+    wireAvailable,
+    httpAvailable,
+    suggestedWirePort,
+    suggestedHttpPort: candidateHttp
+  }
+}
+
 /** Release asset name for a platform/architecture, per the AnchorDB release pattern. */
 export function releaseAssetName(version, platform = process.platform, arch = process.arch) {
   const archName = arch === 'arm64' ? 'arm64' : 'amd64'
@@ -66,12 +122,12 @@ export async function verifySha256(filePath, sumsText) {
 }
 
 /**
- * Merge the anchordb block into the global config (~/.knlview/knl-config.json)
+ * Merge the anchordb block into the global config (knl-config.json)
  * without dropping other fields that may live there. Returns the config
  * contents before the overwrite (as a backup, in case the caller shows it).
  */
-export async function mergeGlobalAnchordb(home, anchordb) {
-  const file = path.join(home, '.knlview', 'knl-config.json')
+export async function mergeGlobalAnchordb(home, anchordb, options = {}) {
+  const file = globalConfigPath(home, options)
   let before = null
   let raw = {}
   try {
@@ -83,15 +139,299 @@ export async function mergeGlobalAnchordb(home, anchordb) {
     // Missing/broken file: start from an empty object.
   }
   raw.anchordb = anchordb
-  await fs.mkdir(path.dirname(file), { recursive: true })
-  await fs.writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8')
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
+  await fs.writeFile(file, JSON.stringify(raw, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+  try { await fs.chmod(file, 0o600) } catch {}
   return before
 }
 
-/** Pick an available container runtime: podman first, then docker. */
-export async function detectContainerRuntime(which) {
+/** List all available container runtimes on the system. */
+export async function availableContainerRuntimes(which) {
+  const found = []
+  for (const runtime of ['docker', 'podman']) {
+    if (await which(runtime)) found.push(runtime)
+  }
+  return found
+}
+
+/** Pick an available container runtime: preferred first, or first detected. */
+export async function detectContainerRuntime(which, preferred = null) {
+  if (preferred) {
+    if (await which(preferred)) return preferred
+    return null
+  }
+  const available = await availableContainerRuntimes(which)
+  return available[0] || null
+}
+
+/**
+ * Inspect detailed container lifecycle status across available runtimes.
+ * Returns exists, runtime, running, valid, status, id, created, token, wire_port.
+ */
+export async function inspectContainerStatus(exec, name = CONTAINER_NAME) {
   for (const runtime of ['podman', 'docker']) {
-    if (await which(runtime)) return runtime
+    try {
+      const { stdout } = await exec(runtime, [
+        'inspect',
+        '--format',
+        '{{.Id}}|{{.Created}}|{{.State.Status}}|{{.State.Running}}|{{json .Config.Env}}',
+        name
+      ])
+      const parts = stdout.trim().split('|')
+      if (parts.length >= 4 && parts[0]) {
+        const id = parts[0].trim()
+        const created = parts[1].trim()
+        const status = (parts[2] || '').trim().toLowerCase()
+        const running = (parts[3] || '').trim().toLowerCase() === 'true'
+        const valid = !['dead', 'removal', 'corrupt'].includes(status) && id.length >= 12
+        const envStr = parts.slice(4).join('|')
+        let token = null
+        let port = String(WIRE_PORT_DEFAULT)
+        try {
+          const envs = JSON.parse(envStr)
+          for (const e of envs) {
+            if (e.startsWith('ANCHORDB_AUTH_TOKEN=')) token = e.slice('ANCHORDB_AUTH_TOKEN='.length)
+            if (e.startsWith('ANCHORDB_WIRE_PORT=')) port = e.slice('ANCHORDB_WIRE_PORT='.length)
+          }
+        } catch {}
+
+        return {
+          exists: true,
+          runtime,
+          name,
+          id,
+          created,
+          status,
+          running,
+          valid,
+          token,
+          wire_port: port
+        }
+      }
+    } catch {
+      // not in this runtime
+    }
+  }
+
+  return {
+    exists: false,
+    runtime: null,
+    name,
+    id: null,
+    created: null,
+    status: null,
+    running: false,
+    valid: false,
+    token: null,
+    wire_port: String(WIRE_PORT_DEFAULT)
+  }
+}
+
+export async function startContainer(exec, runtime, name = CONTAINER_NAME) {
+  await exec(runtime, ['start', name])
+}
+
+export async function removeContainer(exec, runtime, name = CONTAINER_NAME) {
+  await exec(runtime, ['rm', '-f', name])
+}
+
+export async function detectGraphify(exec) {
+  try {
+    await exec('which', ['graphify'])
+    return true
+  } catch {
+    return false
   }
+}
+
+export const DECISIONSKILLS_REPO = 'rachmanzz/decisionskills'
+
+/**
+ * Check if the decision-history skill (from rachmanzz/decisionskills) is
+ * installed in project or global agent directories, and if an update is available.
+ */
+export async function checkDecisionSkillsStatus({ cwd = process.cwd(), home = process.env.HOME }) {
+  const projectSkill = path.join(cwd, '.agents', 'skills', 'decision-history', 'SKILL.md')
+  let hasProject = false
+  try {
+    await fs.stat(projectSkill)
+    hasProject = true
+  } catch {}
+
+  const globalPaths = [
+    path.join(home || '', '.codex', 'skills', 'decision-history', 'SKILL.md'),
+    path.join(home || '', '.claude', 'skills', 'decision-history', 'SKILL.md'),
+    path.join(home || '', '.config', 'opencode', 'skills', 'decision-history', 'SKILL.md'),
+    path.join(home || '', '.gemini', 'config', 'plugins', 'decision-history', 'skills', 'decision-history', 'SKILL.md'),
+    path.join(home || '', '.agents', 'skills', 'decision-history', 'SKILL.md')
+  ]
+
+  let hasGlobal = false
+  for (const p of globalPaths) {
+    try {
+      await fs.stat(p)
+      hasGlobal = true
+      break
+    } catch {}
+  }
+
+  let currentVersion = null
+  let latestVersion = null
+  let status = 'not_installed'
+
+  if (hasProject || hasGlobal) {
+    status = 'installed'
+    const versionCandidates = [
+      path.join(cwd, '.agents', 'skills', 'decision-history', 'VERSION'),
+      path.join(home || '', '.gemini', 'config', 'plugins', 'decision-history', 'VERSION')
+    ]
+    for (const vFile of versionCandidates) {
+      try {
+        const text = await fs.readFile(vFile, 'utf8')
+        if (text.trim()) {
+          currentVersion = text.trim()
+          break
+        }
+      } catch {}
+    }
+
+    try {
+      const res = await fetch('https://raw.githubusercontent.com/rachmanzz/decisionskills/main/VERSION', {
+        signal: AbortSignal.timeout(2000)
+      })
+      if (res.ok) {
+        latestVersion = (await res.text()).trim()
+        if (currentVersion && latestVersion && currentVersion !== latestVersion) {
+          status = 'needs_update'
+        }
+      }
+    } catch {}
+  }
+
+  return {
+    hasProject,
+    hasGlobal,
+    status, // 'not_installed' | 'installed' | 'needs_update'
+    currentVersion,
+    latestVersion,
+    projectPath: projectSkill
+  }
+}
+
+/**
+ * Install or update the decision-history skill from rachmanzz/decisionskills.
+ * Scope: 'project' | 'global' | 'both'.
+ */
+export async function installDecisionSkills({
+  scope = 'project',
+  cwd = process.cwd(),
+  home = process.env.HOME,
+  exec
+}) {
+  const results = []
+
+  const copyDir = async (src, dest) => {
+    await fs.mkdir(dest, { recursive: true })
+    const entries = await fs.readdir(src, { withFileTypes: true })
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name)
+      const destPath = path.join(dest, entry.name)
+      if (entry.isDirectory()) {
+        await copyDir(srcPath, destPath)
+      } else {
+        await fs.copyFile(srcPath, destPath)
+      }
+    }
+  }
+
+  const doInstall = async (isGlobal) => {
+    let success = false
+    if (exec) {
+      try {
+        const args = ['--yes', 'skills', 'add', DECISIONSKILLS_REPO, '--skill', 'decision-history', '-y', '--copy']
+        if (isGlobal) args.push('-g')
+        await exec('npx', args, { cwd })
+        success = true
+      } catch {}
+    }
+
+    if (!success) {
+      const fallbackSources = [
+        path.join(home || '', '.gemini', 'config', 'plugins', 'decision-history', 'skills', 'decision-history'),
+        path.join(home || '', '.agents', 'skills', 'decision-history'),
+        path.join(home || '', '.codex', 'skills', 'decision-history')
+      ]
+      let srcDir = null
+      for (const candidate of fallbackSources) {
+        try {
+          await fs.stat(path.join(candidate, 'SKILL.md'))
+          srcDir = candidate
+          break
+        } catch {}
+      }
+
+      if (srcDir) {
+        const dest = isGlobal
+          ? path.join(home || '', '.agents', 'skills', 'decision-history')
+          : path.join(cwd, '.agents', 'skills', 'decision-history')
+        await copyDir(srcDir, dest)
+        success = true
+      }
+    }
+
+    if (isGlobal && exec) {
+      const agyDir = path.join(home || '', '.gemini', 'config', 'plugins', 'decision-history')
+      try {
+        await fs.stat(agyDir)
+        await exec('git', ['pull'], { cwd: agyDir })
+      } catch {
+        try {
+          await fs.mkdir(path.dirname(agyDir), { recursive: true })
+          await exec('git', ['clone', 'https://github.com/rachmanzz/decisionskills.git', agyDir])
+        } catch {}
+      }
+    }
+
+    return success
+  }
+
+  if (scope === 'project' || scope === 'both') {
+    const ok = await doInstall(false)
+    results.push({ scope: 'project', success: ok })
+  }
+  if (scope === 'global' || scope === 'both') {
+    const ok = await doInstall(true)
+    results.push({ scope: 'global', success: ok })
+  }
+
+  return results
+}
+
+/**
+ * Detect a running AnchorDB daemon on the system (docker, podman, or binary).
+ * Inspects containers for CONTAINER_NAME or checks running processes.
+ */
+export async function detectRunningDaemon(exec) {
+  const container = await inspectContainerStatus(exec)
+  if (container.exists && container.running && container.valid) {
+    return {
+      daemon: container.runtime,
+      deamon: container.runtime,
+      container_name: container.name,
+      container_id: container.id,
+      container_created_on: container.created,
+      token: container.token,
+      wire_port: container.wire_port
+    }
+  }
+
+  // Check if binary process is running
+  try {
+    const { stdout } = await exec('pgrep', ['-f', 'anchordb-server'])
+    if (stdout.trim()) {
+      return { daemon: 'binary', deamon: 'binary' }
+    }
+  } catch {}
+
   return null
 }

package/server/models_registry.js

@@ -1,8 +1,12 @@
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import crypto from 'node:crypto'
+import os from 'node:os'
+import { knlGlobalDir } from './config.js'
 
-// Global registry of AnchorDB model names: ~/.knlview/models.json.
+// Global registry of AnchorDB model names:
+// - %APPDATA%\knlview\models.json on Windows
+// - ~/.knlview/models.json on Linux and macOS
 //
 // Model names may be random; what makes a random name meaningful is this
 // registry: the mapping of name → project, role, and project location.
@@ -11,8 +15,8 @@ import crypto from 'node:crypto'
 
 const REGISTRY_FILE = 'models.json'
 
-export function modelRegistryPath(home = process.env.HOME) {
-  return path.join(home || '', '.knlview', REGISTRY_FILE)
+export function modelRegistryPath(home = null, options = {}) {
+  return path.join(knlGlobalDir(home, options), REGISTRY_FILE)
 }
 
 /**
@@ -31,9 +35,31 @@ export function generateModelName() {
  * Read the registry. Missing/broken file = empty registry, not an error.
  * @returns {Promise<{models: object, error: string|null}>}
  */
-export async function readModelRegistry(home = process.env.HOME) {
+export async function readModelRegistry(home = null, options = {}) {
+  const primary = modelRegistryPath(home, options)
+  let content = null
   try {
-    const parsed = JSON.parse(await fs.readFile(modelRegistryPath(home), 'utf8'))
+    content = await fs.readFile(primary, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      const platform = options.platform || process.platform
+      const env = options.env || process.env
+      if (platform === 'win32' && !home) {
+        const winHome = env.USERPROFILE || env.HOME || (typeof os.homedir === 'function' ? os.homedir() : null)
+        if (winHome) {
+          try {
+            content = await fs.readFile(path.join(winHome, '.knlview', REGISTRY_FILE), 'utf8')
+          } catch {}
+        }
+      }
+      if (!content) return { models: {}, error: null }
+    } else {
+      return { models: {}, error: err.message }
+    }
+  }
+
+  try {
+    const parsed = JSON.parse(content)
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
       return { models: {}, error: 'registry contents are not an object' }
     }
@@ -45,7 +71,6 @@ export async function readModelRegistry(home = process.env.HOME) {
     }
     return { models, error: null }
   } catch (err) {
-    if (err?.code === 'ENOENT') return { models: {}, error: null }
     return { models: {}, error: err.message }
   }
 }
@@ -56,8 +81,8 @@ export async function readModelRegistry(home = process.env.HOME) {
  * whether to warn.
  * @returns {Promise<{previous: object|null, written: boolean, error: string|null}>}
  */
-export async function registerModel(name, { role, project, cwd }, home = process.env.HOME) {
-  const { models, error } = await readModelRegistry(home)
+export async function registerModel(name, { role, project, cwd }, home = null, options = {}) {
+  const { models, error } = await readModelRegistry(home, options)
   if (error) return { previous: null, written: false, error }
 
   const previous = models[name] || null
@@ -74,7 +99,7 @@ export async function registerModel(name, { role, project, cwd }, home = process
   }
 
   try {
-    const file = modelRegistryPath(home)
+    const file = modelRegistryPath(home, options)
     await fs.mkdir(path.dirname(file), { recursive: true })
     await fs.writeFile(file, JSON.stringify(models, null, 2) + '\n', 'utf8')
     return { previous: null, written: true, error: null }

package/server/scaffold.js

@@ -31,16 +31,18 @@ Nothing here yet. Put markdown files in this folder.
 
 export async function scaffoldBase({ root, structure, folders = [] }) {
   const actions = []
-  await fs.mkdir(root, { recursive: true })
-  actions.push({ kind: 'dir', path: root, status: 'created' })
+  const rootAbs = path.resolve(root)
+  await fs.mkdir(rootAbs, { recursive: true })
+  actions.push({ kind: 'dir', path: rootAbs, status: 'created' })
 
   if (structure === 'empty') return actions
 
   const dirs = structure === 'custom' ? folders.map(cleanRel).filter(Boolean) : STANDARD_DIRS
 
-  await writeFileSafe(path.join(root, 'README.md'), ROOT_README, actions)
+  await writeFileSafe(path.join(rootAbs, 'README.md'), ROOT_README, actions)
   for (const dir of dirs) {
-    const abs = path.join(root, dir)
+    const abs = path.resolve(rootAbs, dir)
+    if (!abs.startsWith(rootAbs + path.sep)) continue
     await fs.mkdir(abs, { recursive: true })
     actions.push({ kind: 'dir', path: abs, status: 'created' })
     await writeFileSafe(path.join(abs, 'README.md'), SECTION_README(dir), actions)
@@ -78,6 +80,89 @@ export async function ensureGitignore({ cwd }) {
   return { path: abs, status: 'created' }
 }
 
+export function buildAgentInstructionBlock(hasGraphify = false) {
+  const fallback = hasGraphify
+    ? `- Graphify is the fallback. Use it only when a specific need remains unresolved by KNL-View or the user explicitly requests Graphify. If KNL-View answers the task, stop; do not run Graphify for duplicate analysis.
+- When the user explicitly invokes \`/graphify\`, honor that request without automatically running both tools.
+
+`
+    : ''
+
+  return `<!-- knl-view:start -->
+# Knowledge graph tools
+- KNL-View is the primary graph tool. For \`.knowledges\`, source graphs, and project graph questions, read the project's \`knl-view\` skill and use the relevant KNL-View feature first.
+${fallback}## KNL-View graph access
+- Use the KNL-View feature that fits the task (\`graph trace\`, \`sources trace/sync/collect\`, \`model check/new\`, consensus commands, or the viewer). Do not approximate a supported KNL-View operation with ad-hoc graph queries.
+- Route all graph reads and writes through KNL-View's documented CLI, viewer, or application endpoints. Never connect to AnchorDB directly through AnchorWire, its CLI, direct database endpoints, files, SQL, or custom clients/scripts. If KNL-View cannot perform a requested operation, explain the limitation; do not bypass it.
+- Keep graph work targeted: specify the relevant node/path, direction, and smallest useful hop count; summarize only relevant nodes and edges; avoid dumping whole graphs or large raw JSON.
+- Follow the KNL-View skill's trace-before-edit and \`sources sync\`-after-change rules. Treat edge direction as lineage; do not claim causality without separate evidence.
+<!-- knl-view:end -->`
+}
+
+export function stripLegacyKnlInstructions(text) {
+  let cleaned = text
+  cleaned = cleaned.replace(/<!-- knl-view:start -->[\s\S]*?<!-- knl-view:end -->/g, '\n')
+  cleaned = cleaned.replace(/<!--\s*knl-view:(?:start|end)\s*-->/g, '\n')
+  cleaned = cleaned.replace(
+    /(?:^|\n)# Knowledge graph tools[\s\S]*?(?=(?:\n#+\s)|$)/g,
+    '\n'
+  )
+  cleaned = cleaned.replace(
+    /(?:^|\n)## KNL-View graph access[\s\S]*?(?=(?:\n#+\s)|$)/g,
+    '\n'
+  )
+  return cleaned.trim()
+}
+
+export async function seedAgentInstructions({ cwd = process.cwd(), home = process.env.HOME, hasGraphify = false }) {
+  const block = buildAgentInstructionBlock(hasGraphify)
+  const candidatePaths = [
+    // Project files:
+    path.join(cwd, 'AGENTS.md'),
+    path.join(cwd, 'GEMINI.md'),
+    path.join(cwd, 'CLAUDE.md'),
+    // Global files:
+    path.join(home || '', '.codex', 'AGENTS.md'),
+    path.join(home || '', '.gemini', 'GEMINI.md'),
+    path.join(home || '', '.claude', 'CLAUDE.md'),
+    path.join(home || '', '.agents', 'AGENTS.md')
+  ]
+
+  const actions = []
+
+  for (const abs of candidatePaths) {
+    const parentDir = path.dirname(abs)
+    const parentExists = await statOrNull(parentDir)
+    if (!parentExists) continue
+
+    const stat = await statOrNull(abs)
+    if (stat && stat.isFile()) {
+      const content = await fs.readFile(abs, 'utf8')
+      const cleaned = stripLegacyKnlInstructions(content)
+      const next = cleaned.length ? `${cleaned}\n\n${block}\n` : `${block}\n`
+
+      if (next !== content) {
+        await fs.writeFile(abs, next, 'utf8')
+        actions.push({ path: abs, status: 'updated' })
+      } else {
+        actions.push({ path: abs, status: 'skipped' })
+      }
+    }
+  }
+
+  // If no project file was found/updated, create ./AGENTS.md
+  const projectAgent = path.join(cwd, 'AGENTS.md')
+  if (!actions.some((a) => a.path.startsWith(cwd))) {
+    const stat = await statOrNull(projectAgent)
+    if (!stat) {
+      await fs.writeFile(projectAgent, `${block}\n`, 'utf8')
+      actions.push({ path: projectAgent, status: 'created' })
+    }
+  }
+
+  return actions
+}
+
 async function writeFileSafe(abs, content, actions) {
   const exists = await statOrNull(abs)
   if (exists) {
@@ -89,7 +174,12 @@ async function writeFileSafe(abs, content, actions) {
 }
 
 function cleanRel(value) {
-  return String(value).trim().replace(/^\/+/, '').replace(/\/+$/, '')
+  const cleaned = String(value || '').trim()
+  const normalized = path.normalize(cleaned).replace(/^(\.\.[\/\\])+/, '').replace(/^[\/\\]+/, '').replace(/[\/\\]+$/, '')
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('..' + path.sep)) {
+    return ''
+  }
+  return normalized
 }
 
 async function statOrNull(abs) {
@@ -152,10 +242,10 @@ then folders.
   },
   "files": {
     "personal-assistant.md": { "title": "Personal Assistant" },
-    "rahasia.md": { "ignore": true }
+    "secret.md": { "ignore": true }
   },
   "dirs": {
-    "draft-lama": { "ignore": true }
+    "old-drafts": { "ignore": true }
   }
 }
 \`\`\`
@@ -173,7 +263,7 @@ then folders.
 bring it back:
 
 \`\`\`json
-{ "files": { "rahasia.md": { "ignore": true } }, "dirs": { "draft-lama": { "ignore": true } } }
+{ "files": { "secret.md": { "ignore": true } }, "dirs": { "old-drafts": { "ignore": true } } }
 \`\`\`
 
 Paths are relative to the \`.knowledges\` root, use \`/\` separators, and
@@ -276,6 +366,12 @@ file or symbol is tombstoned (attribute \`tombstone = 2\`) after its
 edges are unlinked; if it comes back, the tombstone lifts and the edges
 are relinked.
 
+External modules graph (third-party dependencies): stored in global AnchorDB
+models per ecosystem (\`modules-npm\`, \`modules-go\`, \`modules-cargo\`, \`modules-pypi\`)
+and cataloged in \`~/.knlview/modules/<eco>.json\`. Built on-demand via
+\`knl-view modules build-graph <eco>::<name>\`, avoiding polluting project models.
+Traceable via \`knl-view modules trace <eco>::<name> [symbol]\`.
+
 Decision history skill: recording architectural decisions is delegated
 to the separate decision-history skill (its decision block format is its
 own domain; this skill never writes decision blocks). If it is not
@@ -340,7 +436,7 @@ of that directory.
 
 Every roast must state:
 - \`Severity\`: \`P0|P1|P2|P3\`
-- \`Class\`: \`BUG|PERF|VULN|DEBT|CEILING|PROSES\`
+- \`Class\`: \`BUG|PERF|VULN|DEBT|CEILING|PROCESS\`
 
 ## When the agent triggers the graph
 
@@ -364,6 +460,10 @@ this.
 - Before renaming a symbol or moving it to another file: remember its
   record id contains the old name/path. Sync tombstones the stale record
   and creates the new one; trace by the new id afterwards.
+- Before reading raw third-party library source files:
+  run \`knl-view modules build-graph <eco>::<module>\` (e.g. \`npm::express\`, \`go::github.com/gin-gonic/gin\`)
+  to index it on-demand into global AnchorDB model \`modules-<eco>\`, then trace
+  its methods with \`knl-view modules trace <eco>::<module> [symbol]\` to save context tokens.
 - A new architectural decision: trigger the decision-history skill
   (install it first if missing; see "Decision history skill" above).
   The decision block format is that skill's domain; this skill never

package/dist/assets/channel-BZ2_TTTJ.js

@@ -1 +0,0 @@
-import{ot as e,st as t}from"./chunk-DSNLSHJZ-BM5PBFmz.js";var n=(n,r)=>t.lang.round(e.parse(n)[r]);export{n as t};

package/dist/assets/flowDiagram-IUGLLWBU-l7L5DTb5.js

@@ -1 +0,0 @@
-import"./src-dClg85lX.js";import"./chunk-DSNLSHJZ-BM5PBFmz.js";import"./chunk-7S6XSTFO-B0p3o547.js";import"./chunk-YZO67HFG-DJqACL5V.js";import"./chunk-AQDTSKZB-CCxwNyyA.js";import"./chunk-UHW7PFBP-CJs0VwBY.js";import"./chunk-HAGFOTED-UCDVFuN_.js";import"./chunk-ZAUX2LTX-CWfaYtwb.js";import"./chunk-WQQL4CDK-DcjPeAfQ.js";import"./chunk-55XCU76K-QR_ARj8I.js";import"./chunk-XXDRQBXY-glA0kB5s.js";import"./chunk-VQ5W62QI-DQxjgE4_.js";import"./chunk-HNE4Q36P-C_1sakp2.js";export{n as diagram}from"./chunk-NQOKRVIF-b2D1Z4oK.js";import"./mermaid.core-DPTRaYLy.js";

package/dist/assets/swimlanesDiagram-AYQRV4AK-BGFq4t7O.js

@@ -1,8 +0,0 @@
-import{n as e}from"./chunk-Y2CYZVJY-DsF7k-Jl.js";import"./src-dClg85lX.js";import"./chunk-DSNLSHJZ-BM5PBFmz.js";import"./chunk-7S6XSTFO-B0p3o547.js";import"./chunk-YZO67HFG-DJqACL5V.js";import"./chunk-AQDTSKZB-CCxwNyyA.js";import"./chunk-UHW7PFBP-CJs0VwBY.js";import"./chunk-HAGFOTED-UCDVFuN_.js";import"./chunk-ZAUX2LTX-CWfaYtwb.js";import"./chunk-WQQL4CDK-DcjPeAfQ.js";import"./chunk-55XCU76K-QR_ARj8I.js";import"./chunk-XXDRQBXY-glA0kB5s.js";import"./chunk-VQ5W62QI-DQxjgE4_.js";import"./chunk-HNE4Q36P-C_1sakp2.js";import{r as t,t as n}from"./chunk-NQOKRVIF-b2D1Z4oK.js";import"./mermaid.core-DPTRaYLy.js";var r=n({styles:e(e=>`${t(e)}
-  .swimlane.cluster:not([data-color-id]) rect {
-    stroke: ${e.clusterBorder} !important;
-  }
-  [data-look="neo"].cluster rect {
-    filter: none;
-  }
-`,`getStyles`)});export{r as diagram};