@rahmantech/knl-view 0.0.0-stage → 0.1.0

package/server/install.js

@@ -0,0 +1,97 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+// AnchorDB installer for knl-view. Two paths:
+// - Linux: binary from GitHub Releases (tar.gz per architecture, verified
+//   against the release's official SHA256SUMS.txt).
+// - Non-Linux: AnchorDB needs Linux mmap, so the path is the
+//   ghcr.io/rachmanzz/anchordb:<version> container via docker/podman.
+// Everything here is as pure/deterministic as possible; interactive
+// 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 CONTAINER_NAME = 'anchordb-knlview'
+
+/** 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'
+  const platformName = platform === 'darwin' ? 'darwin' : 'linux'
+  return `anchordb_${version}_${platformName}_${archName}.tar.gz`
+}
+
+/** Random token for ANCHORDB_AUTH_TOKEN: 32 bytes of hex. */
+export function generateToken() {
+  return crypto.randomBytes(32).toString('hex')
+}
+
+/** Fetch the latest release from the GitHub API. */
+export async function latestRelease(repo = 'rachmanzz/anchordb') {
+  const res = await fetch(`https://api.github.com/repos/${repo}/releases/latest`)
+  if (!res.ok) throw new Error(`GitHub API ${res.status}: failed to read the latest release`)
+  const body = await res.json()
+  if (!body.tag_name) throw new Error('Latest release has no tag_name')
+  const version = String(body.tag_name).replace(/^v/, '')
+  return { tag: body.tag_name, version }
+}
+
+/** Download one file to disk. */
+export async function downloadFile(url, dest) {
+  const res = await fetch(url, { redirect: 'follow' })
+  if (!res.ok) throw new Error(`Download failed (${res.status}): ${url}`)
+  const buf = Buffer.from(await res.arrayBuffer())
+  await fs.writeFile(dest, buf)
+  return buf.length
+}
+
+/**
+ * Verify a file against SHA256SUMS.txt contents in the standard format:
+ * "<hash>  <name>" per line. Throws an Error when the name is missing or
+ * the hash does not match.
+ */
+export async function verifySha256(filePath, sumsText) {
+  const fileName = path.basename(filePath)
+  const line = String(sumsText)
+    .split('\n')
+    .find((l) => l.trim().endsWith(fileName))
+  if (!line) throw new Error(`${fileName} is not in SHA256SUMS.txt`)
+  const expected = line.trim().split(/\s+/)[0].toLowerCase()
+  const actual = crypto.createHash('sha256').update(await fs.readFile(filePath)).digest('hex')
+  if (actual !== expected) {
+    throw new Error(`SHA256 mismatch for ${fileName}\n  wanted  ${expected}\n  got     ${actual}`)
+  }
+  return expected
+}
+
+/**
+ * Merge the anchordb block into the global config (~/.knlview/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')
+  let before = null
+  let raw = {}
+  try {
+    const text = await fs.readFile(file, 'utf8')
+    before = text
+    const parsed = JSON.parse(text)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) raw = parsed
+  } catch {
+    // 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')
+  return before
+}
+
+/** Pick an available container runtime: podman first, then docker. */
+export async function detectContainerRuntime(which) {
+  for (const runtime of ['podman', 'docker']) {
+    if (await which(runtime)) return runtime
+  }
+  return null
+}

package/server/map.js

@@ -0,0 +1,126 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+// The optional map (map.json): pure annotation on top of the disk structure.
+// Principle: the disk is the truth, the map is an overlay. The map NEVER
+// defines the existence of files/folders. A file missing from disk stays
+// missing from the viewer even when the map still lists it (orphan entries
+// are silently ignored). The map only decorates: title, order, metadata.
+
+const MAP_FILE = 'map.json'
+const MAX_MAP_BYTES = 1024 * 1024
+
+export async function readMap(rootAbs) {
+  const abs = path.join(rootAbs, MAP_FILE)
+  const stat = await statOrNull(abs)
+  if (!stat || !stat.isFile() || stat.size > MAX_MAP_BYTES) return null
+
+  let parsed
+  try {
+    parsed = JSON.parse(await fs.readFile(abs, 'utf8'))
+  } catch {
+    // A broken map must never bring the viewer down: ignore it quietly.
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+  return parsed
+}
+
+// Normalize shapes: the map may write the title in `title` (root/files),
+// `sections`/`dirs` (folders), and `docs`/`files` (files). Only one clean
+// representation matters for the overlay. Each entry may carry
+// `ignore: true` to hide it (the disk still owns the file).
+export function normalizeMap(map) {
+  if (!map) return { title: null, entries: new Map() }
+  const entries = new Map()
+
+  const dirs = { ...asObject(map.sections), ...asObject(map.dirs) }
+  for (const [key, value] of Object.entries(dirs)) {
+    const entry = asObject(value)
+    if (!entry) continue
+    mergeEntry(entries, cleanKey(key), entry)
+  }
+
+  // `docs`/`files` can be placed per folder:
+  // { "features/x": { "docs": { "a.md": {...} } } } or globally.
+  // Both are written into the same file entries.
+  const globalDocs = { ...asObject(map.docs), ...asObject(map.files) }
+  applyDocs(entries, '', globalDocs)
+  for (const [key, value] of Object.entries(dirs)) {
+    const docs = asObject(asObject(value)?.docs)
+    if (docs) applyDocs(entries, cleanKey(key), docs)
+  }
+
+  const ignoreList = Array.isArray(map.ignore) ? map.ignore : []
+  for (const path of ignoreList) {
+    if (typeof path !== 'string' || !path.trim()) continue
+    mergeEntry(entries, cleanKey(path), { ignore: true })
+  }
+
+  return {
+    title: typeof map.title === 'string' ? map.title.trim() : null,
+    entries
+  }
+}
+
+function applyDocs(entries, dirKey, docs) {
+  for (const [name, value] of Object.entries(docs)) {
+    const entry = asObject(value) || {}
+    const key = dirKey ? `${dirKey}/${name}` : name
+    mergeEntry(entries, cleanKey(key), entry)
+  }
+}
+
+function mergeEntry(entries, key, entry) {
+  const prev = entries.get(key) || {}
+  entries.set(key, {
+    title: typeof entry.title === 'string' ? entry.title.trim() : prev.title ?? null,
+    order: toOrder(entry.order) ?? prev.order ?? null,
+    meta: typeof entry.meta === 'string' ? entry.meta.trim() : prev.meta ?? null,
+    ignore: entry.ignore === true || entry.hidden === true ? true : prev.ignore === true
+  })
+}
+
+// Apply the overlay to one node. Returns a new node (without corrupting the
+// original object from disk), or the same node when the map does not touch it.
+export function decorateNode(node, norm) {
+  const entry = norm?.entries?.get(node.path)
+  let next = node
+
+  const title = entry?.title
+  if (title) {
+    // A map title beats the heading title read from the file contents.
+    // `titleFromMap` marks that this label came from the map, so the view
+    // may use it directly as the label (not just as a subtitle).
+    next = { ...next, title, titleFromMap: true }
+  }
+  const order = entry?.order
+  if (order != null) next = { ...next, order }
+  const meta = entry?.meta
+  if (meta != null) next = { ...next, meta }
+
+  // Children are already decorated by buildTree while walking the disk,
+  // so here it is enough to touch this node only.
+  return next
+}
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null
+}
+
+function cleanKey(key) {
+  return String(key).replace(/^\.?\//, '').replace(/\/+$/, '')
+}
+
+function toOrder(value) {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : null
+}
+
+async function statOrNull(abs) {
+  try {
+    return await fs.stat(abs)
+  } catch {
+    return null
+  }
+}

package/server/models_registry.js

@@ -0,0 +1,84 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+// Global registry of AnchorDB model names: ~/.knlview/models.json.
+//
+// Model names may be random; what makes a random name meaningful is this
+// registry: the mapping of name → project, role, and project location.
+// knl-view code never guesses model names: it only knows roles (knowledges,
+// consensus, etc.) and reads each role from the project map.
+
+const REGISTRY_FILE = 'models.json'
+
+export function modelRegistryPath(home = process.env.HOME) {
+  return path.join(home || '', '.knlview', REGISTRY_FILE)
+}
+
+/**
+ * Random name for a model: 8 Crockford base32 characters (no I, L, O, U
+ * so humans never misread/mistype them).
+ */
+export function generateModelName() {
+  const alphabet = '0123456789abcdefghjkmnpqrstvwxyz'
+  const bytes = crypto.randomBytes(8)
+  let name = ''
+  for (const byte of bytes) name += alphabet[byte % alphabet.length]
+  return name
+}
+
+/**
+ * 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) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(modelRegistryPath(home), 'utf8'))
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { models: {}, error: 'registry contents are not an object' }
+    }
+    const models = {}
+    for (const [name, entry] of Object.entries(parsed)) {
+      if (entry && typeof entry === 'object' && typeof entry.role === 'string') {
+        models[name] = entry
+      }
+    }
+    return { models, error: null }
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { models: {}, error: null }
+    return { models: {}, error: err.message }
+  }
+}
+
+/**
+ * Register (or update) one model in the registry. Returns the previous owner
+ * when the name is already claimed by another project; the caller decides
+ * 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)
+  if (error) return { previous: null, written: false, error }
+
+  const previous = models[name] || null
+  const sameOwner = previous && path.resolve(previous.cwd || '') === path.resolve(cwd)
+  if (previous && !sameOwner) {
+    return { previous, written: false, error: null }
+  }
+
+  models[name] = {
+    role,
+    project,
+    cwd: path.resolve(cwd),
+    registeredAt: new Date().toISOString()
+  }
+
+  try {
+    const file = modelRegistryPath(home)
+    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 }
+  } catch (err) {
+    return { previous: null, written: false, error: err.message }
+  }
+}

package/server/scaffold.js

@@ -0,0 +1,376 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+// Knowledge base builder for --init and --seed-skill.
+// Same principle as the map: NEVER destroy anything that already exists.
+// Existing files are skipped, and the .gitignore line is only added when
+// not already present.
+
+export const STANDARD_DIRS = ['roadmap', 'features', 'docs']
+export const SKILL_ID = 'knl-view'
+
+const ROOT_README = `# Knowledge Base
+
+Lede: write a one-paragraph summary of this base here.
+
+## How to read
+
+- \`roadmap/\`: direction and plans.
+- \`features/\`: feature notes.
+- \`docs/\`: general documents.
+
+Add \`map.json\` to this folder if you want to control menu labels and
+display order without moving files. See the \`knl-view\` skill for the
+full format.
+`
+
+const SECTION_README = (name) => `# ${name}
+
+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' })
+
+  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)
+  for (const dir of dirs) {
+    const abs = path.join(root, dir)
+    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)
+  }
+  return actions
+}
+
+export async function seedSkill({ scope, cwd, home = process.env.HOME, xdgConfig = process.env.XDG_CONFIG_HOME }) {
+  const base =
+    scope === 'global'
+      ? path.join(xdgConfig || path.join(home, '.config'), 'opencode', 'skills')
+      : path.join(cwd, '.agents', 'skills')
+  const target = path.join(base, SKILL_ID, 'SKILL.md')
+
+  const exists = await statOrNull(target)
+  if (exists) return { path: target, status: 'skipped' }
+
+  await fs.mkdir(path.dirname(target), { recursive: true })
+  await fs.writeFile(target, SKILL_MD, 'utf8')
+  return { path: target, status: 'created' }
+}
+
+export async function ensureGitignore({ cwd }) {
+  const abs = path.join(cwd, '.gitignore')
+  const line = '.knowledges/'
+  let content = ''
+  const stat = await statOrNull(abs)
+  if (stat && stat.isFile()) content = await fs.readFile(abs, 'utf8')
+
+  const present = content.split(/\r?\n/).some((row) => row.trim() === line || row.trim() === '.knowledges')
+  if (present) return { path: abs, status: 'skipped' }
+
+  const next = content.length && !content.endsWith('\n') ? `${content}\n${line}\n` : `${content}${line}\n`
+  await fs.writeFile(abs, next, 'utf8')
+  return { path: abs, status: 'created' }
+}
+
+async function writeFileSafe(abs, content, actions) {
+  const exists = await statOrNull(abs)
+  if (exists) {
+    actions.push({ kind: 'file', path: abs, status: 'skipped' })
+    return
+  }
+  await fs.writeFile(abs, content, 'utf8')
+  actions.push({ kind: 'file', path: abs, status: 'created' })
+}
+
+function cleanRel(value) {
+  return String(value).trim().replace(/^\/+/, '').replace(/\/+$/, '')
+}
+
+async function statOrNull(abs) {
+  try {
+    return await fs.stat(abs)
+  } catch {
+    return null
+  }
+}
+
+// The skill is in English, following skill ecosystem conventions. It teaches
+// the agent how to read the .knowledges base: README first, then map.json as
+// the source of labels and menu order, then the anchor-connector-like
+// structure.
+const SKILL_MD = `---
+name: knl-view
+description: Read and maintain .knowledges knowledge bases. Use whenever a task involves a .knowledges folder, its map.json, or the knl-view viewer.
+---
+
+# Knowledges base
+
+A \`.knowledges\` folder is a plain-directory knowledge base, viewed with
+knl-view. The disk is the source of truth: files and folders exist because
+they exist on disk, never because a map says so.
+
+## Read in this order
+
+1. \`README.md\` at the base root: the lede and the overview.
+2. \`map.json\` at the base root, when present: the authoritative menu
+   labels, grouping, and order for everything below.
+3. Then the structure the map (or the disk) describes. A typical base
+   mirrors anchor-connector: \`roadmap/\`, \`features/\`, \`futures/\`,
+   \`audit/\`, \`roasted/\`, plus root files \`coding-rules.md\` and
+   \`documentation-rules.md\`. Anything not on disk does not exist; do not
+   invent it from map entries.
+
+## map.json
+
+Optional. Every entry is decoration only. It sets the label shown in the
+menu, the order in menus, and a short note. It never creates, moves, or
+deletes files. Entries pointing at paths that are not on disk are ignored
+silently. Without \`map.json\`, the viewer falls back to the first
+\`# heading\` of each markdown file and plain name order: files first,
+then folders.
+
+\`\`\`json
+{
+  "title": "Base title shown in the masthead",
+  "sections": {
+    "roadmap": { "title": "Roadmap", "order": 1, "meta": "Where this is going" },
+    "features": {
+      "title": "Features",
+      "order": 2,
+      "docs": { "auth.md": { "title": "Auth", "order": 1 } }
+    }
+  },
+  "docs": {
+    "coding-rules.md": { "title": "Coding rules", "order": 1 },
+    "documentation-rules.md": { "title": "Documentation rules", "order": 2 }
+  },
+  "files": {
+    "personal-assistant.md": { "title": "Personal Assistant" },
+    "rahasia.md": { "ignore": true }
+  },
+  "dirs": {
+    "draft-lama": { "ignore": true }
+  }
+}
+\`\`\`
+
+| Field | Applies to | Effect |
+| --- | --- | --- |
+| \`title\` | the whole file | Masthead title; wins over the README heading |
+| \`sections.<dir>\` / \`dirs.<path>\` | a directory | \`title\` is the menu label, \`meta\` is a short note |
+| \`sections.<dir>.docs.<file>\` | a file inside that directory | same shape as \`docs\` entries |
+| \`docs.<file>\` / \`files.<path>\` | a file | \`title\` is the menu label |
+| \`order\` | any entry | Ascending menu order. Entries without \`order\` follow, still files before folders |
+| \`ignore\` (or \`hidden\`) | any entry | \`true\` hides the file or folder from the menu, lists, search, home, and contents. Hiding a folder hides everything inside it |
+
+\`ignore\` is view-only: the file still exists on disk. Remove the flag to
+bring it back:
+
+\`\`\`json
+{ "files": { "rahasia.md": { "ignore": true } }, "dirs": { "draft-lama": { "ignore": true } } }
+\`\`\`
+
+Paths are relative to the \`.knowledges\` root, use \`/\` separators, and
+must match the on-disk path exactly as the viewer shows it, for example
+\`features/auth.md\`. Nested folders use the full relative path as the key.
+
+The sidebar always opens with two fixed entries above the tree: \`index\`
+(the root \`README.md\`) and \`contents\` (\`#/a/contents\`, a system route with
+no file on disk that lists the whole base). The root README is therefore
+not repeated inside the tree.
+
+## Config (two layers)
+
+knl-view reads two optional config files. A missing file is never an error;
+a broken file is ignored with one warning.
+
+**Global (\`~/.knlview/knl-config.json\`)**: shared by every project on this
+machine. Holds the \`anchordb\` block (connection). Without it, AnchorDB
+stays completely off:
+
+\`\`\`json
+{
+  "anchordb": {
+    "url": "wire://127.0.0.1:7448",
+    "token": "your-token",
+    "sync": true
+  }
+}
+\`\`\`
+
+**Per project: \`knl-config.json\` at the project root**, machine-local,
+gitignored. Holds only \`path\`, \`port\`, \`host\`, and the \`models\` map:
+
+\`\`\`json
+{
+  "path": ".knowledges",
+  "port": 8085,
+  "models": { "knowledges": "vez0vqrp" }
+}
+\`\`\`
+
+The map owns model naming: role → AnchorDB model name, names may be
+random; the map records what each name is for, and names stay stable
+across project renames. Create names with \`knl-view model new <role>\`
+and inspect ownership with \`knl-view model check\`. Without a map entry
+for a role, that role runs fully local. CLI flags always win over
+config values.
+
+Installing AnchorDB (optional; the viewer runs fully local without it):
+\`knl-view install anchordb\`: native binary from GitHub Releases on
+Linux and macOS (SHA256-verified), or a container from
+ghcr.io/rachmanzz/anchordb via docker/podman on other platforms. Flags:
+\`--yes\`, \`--method=binary|container\`, \`--token=...\`.
+
+Two-way lineage: graph traces take \`--direction\` (CLI) or
+\`?direction=\` (HTTP): \`out\` follows edges leaving the target, \`in\`
+follows edges entering it, \`both\` is the local default. Direction is
+mechanical (edge direction), never cause-and-effect interpretation.
+Each node in the result carries \`via\` (\`center\`, \`in\`, \`out\`,
+\`in+out\`). On /api/anchordb/trace the default is \`out\`; \`in\` is
+walked backwards from the local sync mirror and reported with
+\`mirrored: true\`.
+
+Consensus (claims): a second AnchorDB model (the \`consensus\` role in
+the models map) holds agreement and conflict between claims only (never
+decisions or files). Claims are content-addressed:
+\`knl-view consensus claim "<statement>"\` prints the id (\`c-\` + 16 hex
+chars of the statement hash); the same text is the same claim everywhere.
+Relations: \`agree\`, \`contradict\`, \`retract\` take two claim
+ids. \`status <id>\` derives: any incoming \`contradicts\` → \`disputed\`,
+else incoming \`agrees_with\` → \`consensus\`, else \`uncontested\`.
+\`list\` shows every locally known claim. Mutations are CLI-only;
+\`GET /api/consensus?target=<claimId>\` is read-only. Requires AnchorDB
+plus a mapped \`consensus\` role.
+
+Sources graph (whole project): a third AnchorDB model, the \`sources\`
+role, holds the dependency graph of the whole project: files and their
+named symbols. Every file is a node (id = repo-relative path); import
+edges are extracted with tree-sitter syntax parsing (JS family and Go
+today) and stored in both directions (\`imports\`, \`imported_by\`).
+Each file also defines symbol nodes: ids are \`<path>#<name>\` (class
+methods \`Class.method\`; a name defined more than once in one file gets
+a line suffix \`<path>#<name>@<line>\`), kinds are \`function\`,
+\`class\`, \`method\`, \`type\`. Edges: \`defines\`/\`defined_in\`
+(file → symbol) and \`calls\`/\`called_by\` (symbol → symbol), both
+directions stored. Call resolution is conservative: the call belongs to
+its innermost enclosing symbol and the callee must match exactly one
+definition project-wide; ambiguous names are skipped, never guessed.
+Label text (symbol names and kinds; AnchorDB attributes are
+numeric-only) lives in \`.knowledges/.knl-data/<path>.md\`, one file per
+source file that has symbols; override with \`labelDir\` in the project
+config. Hidden folders are skipped except .github; node_modules, dist,
+and .gitignore patterns are ignored. \`knl-view sources sync\` is
+idempotent and server-authoritative (no local mirror);
+\`knl-view sources trace --target=<id>\` and
+\`GET /api/sources/trace?target=<id>\` answer lineage: a target
+containing \`#\` walks symbol lineage (\`calls\`/\`called_by\`), a
+plain path walks file lineage (\`imports\`/\`imported_by\`). A removed
+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.
+
+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
+installed in the project yet, install it first:
+\`npx skills add rachmanzz/decisionskills --skill decision-history\`
+or, with agy: \`agy plugin install https://github.com/rachmanzz/decisionskills\`.
+
+## Rules
+
+- Never move or delete files to satisfy the map. Either add the file or
+  remove the stale map entry.
+- Give every markdown file a top-level \`# heading\` so it still reads well
+  when no map entry covers it.
+- Keep \`order\` values small and dense per menu level (1, 2, 3).
+- When the map and disk disagree about existence, the disk wins.
+
+## Features writing rules
+
+Under \`features/{feature_name}/\`, prefer to keep at least:
+- \`prd.md\`: Product Requirements Document for this feature
+- \`detail-plan.md\`: concrete implementation plan, decisions, trade-offs
+
+Names are kebab-case for the folder. Keep other artifacts minimal and cover
+them via \`map.json\` if they need custom menu labels/order.
+
+## Futures writing rules
+
+Under \`futures/\`, the base typically has:
+- \`README.md\`: vision/overview
+- \`prd.md\`: global PRD covering proposed future work
+
+Use kebab-case for any additional future documents. Defer exotic filenames
+to \`map.json\`.
+
+## Roadmap writing rules
+
+Under \`roadmap/\`, maintain milestone-oriented notes. Keep \`README.md\` as
+the index and split by milestones only when they grow large. Use
+\`map.json\` to reorder milestones/files without renaming.
+
+## Roasted writing rules
+
+All artifacts from roasting/audits go under \`roasted/\` (relative to the
+knowledge base root in use; i.e. the directory passed via \`--path\`, which
+may be \`.knowledges\` or a custom one). Do **not** place them in the root
+of that directory.
+
+### Naming
+
+\`roasted/{roasted_name}_v{number}.md\`: kebab-case name, integer
+\`number\` starting at \`1\`.
+
+### Stack order
+
+- \`_v1\` is the first roast → placed at the bottom of the stack
+- each new roast increments number and goes at the top (highest number =
+  newest)
+- files are immutable by number; updates belong to the same file, not a
+  new one
+
+### Classification
+
+Every roast must state:
+- \`Severity\`: \`P0|P1|P2|P3\`
+- \`Class\`: \`BUG|PERF|VULN|DEBT|CEILING|PROSES\`
+
+## When the agent triggers the graph
+
+The graph stays true only if the agent feeds it. Every trigger goes
+through the single \`knl-view\` entrypoint with the existing subcommands
+below; never invent another binary, script, or wrapper to fire any of
+this.
+
+- After creating, editing, renaming, or deleting any project file:
+  run \`knl-view sources sync\`. It is server-authoritative and
+  idempotent: run it again and only the difference is applied.
+- Before changing a file that other files may depend on:
+  \`knl-view sources trace --target=<path> --direction=in\` shows who
+  depends on it first (the blast radius).
+- Before adding an import to, or moving logic out of, another file:
+  \`knl-view sources trace --target=<path> --direction=out\` shows what
+  it already touches.
+- Before changing or removing a function, method, or type:
+  \`knl-view sources trace --target=<path>#<name> --direction=in\` shows
+  every symbol that calls it first.
+- 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.
+- 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
+  writes decision blocks.
+- A technical disagreement worth recording as claims:
+  \`knl-view consensus claim "<statement>"\`, then
+  \`knl-view consensus agree <id> <id>\` or
+  \`knl-view consensus contradict <id> <id>\`. A claim that lost its
+  ground: \`knl-view consensus retract <id> <id>\`.
+`