@indigoai-us/hq-cli 5.280.0 → 5.282.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [5.282.0] — 2026-09-29
+
+### Changed
+
+- Pin the third-party package setup action in the fast-route benchmark workflow to its resolved commit.
+
+### Fixed
+
+- `hq lanes reconcile` admits every queued lane that fits its caps in one pass
+  once CPU throttle clears or the starvation bound is reached.
+- Reconcile compares cumulative CPU counters between passes and records the
+  measurement source; a queued Outpost lane with a changed worker profile now
+  reports the expected and actual hashes plus the senior re-pin command without
+  blocking later eligible lanes.
+
+## [5.281.0] — 2026-09-29
+
+### Added
+
+- Add native TypeScript handlers for six `hq core ontology` commands. The new path is gated by `core-native-ontology`, which defaults off; the original scripts stay bundled for rollback.
+
+### Fixed
+
+- The default-off `lanes.remote-done-mirror` hq-flags gate refreshes nonterminal
+  Outpost mirrors before hire admission and during reconcile. It copies the
+  owner's terminal state and envelope summary to the primary. Unreachable
+  mirrors stay counted and are reported as unverified. `hq lanes logs` reads
+  logs from the owning Outpost.
+
 ## [5.280.0] — 2026-09-29
 
 ### Fixed
@@ -10,6 +39,8 @@
   defaulting to 120 seconds. `hq lanes list` capacity probes use a separate
   15-second timeout. A lane ID with a registered host suffix routes to that
   Outpost first.
+- hq group-grants outbound help now makes --group required. hq auth status
+  displays token expiry as a UTC time and relative duration.
 
 ## [5.279.0] — 2026-09-29
 

package/assets/scaffold/core/scripts/knowledge-prefs.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# knowledge-prefs.sh — resolve a company's knowledge-store preference.
+#
+# Usage: knowledge-prefs.sh get <company> <field>
+#
+# Resolution, per field, first match wins:
+#   1. companies/<company>/settings/knowledge/preferences.yaml
+#   2. personal/settings/knowledge-preferences.yaml
+#   3. built-in default (below)
+#
+# Built-in defaults:
+#   signals_enabled   true    readers (/signals) look for signals
+#   ontology_enabled  true    readers (/ontology) look for ontology
+#   signals_capture   false   session-close skills write signal candidates
+#   ontology_capture  false   session-close skills write entity candidates
+#   meeting_notes_source hq-native
+#   notetaker         recall
+#
+# Capture is opt-in per company, so installs that never set it see no change.
+# Only top-level scalar keys are read; a commented-out line does not count.
+# Exits 2 on bad usage, unknown field, or missing company directory.
+set -euo pipefail
+
+usage() { echo "usage: knowledge-prefs.sh get <company> <field>" >&2; exit 2; }
+[ "${1:-}" = "get" ] || usage
+co="${2:-}"; field="${3:-}"
+[ -n "$co" ] && [ -n "$field" ] || usage
+
+root="${HQ_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+
+case "$field" in
+  signals_enabled|ontology_enabled) default=true ;;
+  signals_capture|ontology_capture) default=false ;;
+  meeting_notes_source) default=hq-native ;;
+  notetaker) default=recall ;;
+  *) echo "knowledge-prefs: unknown field '$field'" >&2; exit 2 ;;
+esac
+
+[ -d "$root/companies/$co" ] || { echo "knowledge-prefs: no company '$co'" >&2; exit 2; }
+
+read_field() {
+  local file="$1"
+  [ -f "$file" ] || return 1
+  awk -v k="$field" '
+    $0 ~ "^"k":" {
+      sub("^"k":[[:space:]]*", ""); sub("[[:space:]]+#.*$", ""); gsub(/^["\x27]|["\x27]$/, "")
+      if (length($0)) { print; found=1; exit }
+    }
+    END { exit found ? 0 : 1 }
+  ' "$file"
+}
+
+read_field "$root/companies/$co/settings/knowledge/preferences.yaml" \
+  || read_field "$root/personal/settings/knowledge-preferences.yaml" \
+  || echo "$default"

package/assets/scaffold/core/scripts/ontology-audience-grant.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# ontology-audience-grant.sh — grant each scoped audience folder to exactly the
+# people in its audience, and prove every grant by readback.
+# Spec: core/knowledge/public/hq-core/ontology-local-spec.md
+#
+# Usage: ontology-audience-grant.sh --company <co> [--dry-run]
+#
+# For every signals/@{key}/_audience.yaml under companies/<co>/:
+#   - grants read on signals/@{key}/, ontology/facts/@{key}/, and each
+#     sources/{channel}/@{key}/ that exists, to each principal that is an
+#     active company member (non-members are skipped with a warning);
+#   - one prefix grant per principal per folder, never per file;
+#   - each grant is the recursive shared glob `<folder>/*` (a bare `<folder>/`
+#     is a private create-only folder since hq-pro #3662);
+#   - reads every grant back with `hq files acl --json`; a missing grant exits 3.
+# Company-audience paths get @all read on signals/{type}/ and
+# ontology/facts/@company/ only. Nothing else under ontology/, signals/,
+# sources/ is granted to @all.
+# Local-only companies (company.yaml cloud: false or absent cloud_uid) exit 0
+# with "local-only, no grants".
+set -uo pipefail
+HQ="${HQ_BIN:-hq}"
+root="${HQ_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+co="" dry=0
+while [ $# -gt 0 ]; do
+  case "$1" in --company) co="$2"; shift 2 ;; --dry-run) dry=1; shift ;; *) echo "unknown flag $1" >&2; exit 2 ;; esac
+done
+[ -n "$co" ] || { echo "usage: ontology-audience-grant.sh --company <co> [--dry-run]" >&2; exit 2; }
+C="$root/companies/$co"; [ -d "$C" ] || { echo "no company $co" >&2; exit 2; }
+
+cloud=no
+grep -Eq '^cloud:[[:space:]]*true' "$C/company.yaml" 2>/dev/null && cloud=yes
+if [ "$cloud" = no ] && [ -f "$root/companies/manifest.yaml" ]; then
+  # manifest: companies:\n  <co>:\n    cloud_uid: ...  (two-space company keys)
+  awk -v co="$co" '/^  [^ #][^:]*:/{inco=($1==co":")} inco && /^    cloud_uid:[[:space:]]*[^[:space:]]/{f=1} END{exit !f}' "$root/companies/manifest.yaml" && cloud=yes
+fi
+[ "$cloud" = yes ] || { echo "local-only, no grants"; exit 0; }
+
+members="$("$HQ" members --company "$co" list 2>/dev/null | awk 'NR>1{print tolower($1)}')"
+[ -n "$members" ] || { echo "could not list members of $co" >&2; exit 3; }
+
+granted=0 skipped=0 failed=0
+grant() { # <folder/> <principal>
+  # Grant the recursive shared glob `<folder>/*`, never the bare `<folder>/`:
+  # since hq-pro #3662 a bare trailing slash is a private create-only folder
+  # (read on it exposes no children) and ACL reads echo the pattern verbatim.
+  local p="${1%/}/*" who="$2"
+  if [ "$dry" = 1 ]; then echo "would grant read $p -> $who"; return 0; fi
+  "$HQ" files --company "$co" share "$p" --with "$who" --permission read >/dev/null 2>&1 || true
+  if "$HQ" files --company "$co" acl "$p" --json 2>/dev/null | jq -e --arg w "$who" \
+      '.direct[]? | select((.granteeId==$w) or ($w=="@all" and .granteeType=="company-wide")) | select(.permission=="read" or .permission=="write" or .permission=="admin")' >/dev/null; then
+    granted=$((granted+1)); echo "granted read $p -> $who"
+  else
+    failed=$((failed+1)); echo "READBACK FAILED: $p -> $who" >&2
+  fi
+}
+
+for aud in "$C"/signals/@*/_audience.yaml; do
+  [ -f "$aud" ] || continue
+  key="$(basename "$(dirname "$aud")")"; key="${key#@}"
+  principals="$(sed -n 's/^principals:[[:space:]]*\[\(.*\)\]/\1/p' "$aud" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | awk '/@/ { print tolower($0); next } { print }' | grep -v '^$')"
+  prefixes="signals/@$key/"
+  [ -d "$C/ontology/facts/@$key" ] && prefixes="$prefixes ontology/facts/@$key/"
+  for d in "$C"/sources/*/@"$key"; do [ -d "$d" ] && prefixes="$prefixes sources/$(basename "$(dirname "$d")")/@$key/"; done
+  for who in $principals; do
+    # prs_/agt_ principals come from the source's own vault ACL (e.g. meeting
+    # attendees), so they are already company identities; emails must be members.
+    case "$who" in
+      prs_*|agt_*) ;;
+      *) if ! printf '%s\n' "$members" | grep -qxF "$who"; then echo "skip $who (not a member of $co)" >&2; skipped=$((skipped+1)); continue; fi ;;
+    esac
+    for p in $prefixes; do grant "$p" "$who"; done
+  done
+done
+[ -d "$C/ontology/facts/@company" ] && grant "ontology/facts/@company/" "@all"
+for t in action_item commitment decision risk question key_point participant_contribution summary; do
+  [ -d "$C/signals/$t" ] && grant "signals/$t/" "@all"
+done
+
+echo "audience grants for $co: $granted granted, $skipped skipped, $failed failed"
+[ "$failed" -eq 0 ] || exit 3

package/assets/scaffold/core/scripts/ontology-brief.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// ontology-brief.mjs — render a company brief from the reader's LOCAL tree.
+// Spec: core/knowledge/public/hq-core/ontology-local-spec.md
+//
+// Usage: node core/scripts/ontology-brief.mjs --company <co> [--hq-root <p>] [--days N] [--top N] [--json]
+//
+// Reads ontology/entities/, every ontology/facts/@*/ and signals/{type}/ +
+// signals/@*/{type}/ present locally. Sync pull only delivers what the reader
+// may read, so the brief shows exactly their visible facts and signals.
+// Writes nothing. Prints markdown (default) or JSON. Exit 0 with an empty brief
+// ("no local ontology") when nothing is there.
+import fs from "node:fs";
+import path from "node:path";
+
+const TYPES = ["decision", "commitment", "risk", "question", "action_item", "key_point", "participant_contribution", "summary"];
+const args = process.argv.slice(2);
+const opt = { days: 14, top: 10, json: false };
+for (let i = 0; i < args.length; i++) {
+  const k = args[i];
+  if (k === "--company") opt.company = args[++i];
+  else if (k === "--hq-root") opt.root = args[++i];
+  else if (k === "--days") opt.days = Number(args[++i]);
+  else if (k === "--top") opt.top = Number(args[++i]);
+  else if (k === "--json") opt.json = true;
+  else { console.error(`ontology-brief: unknown flag ${k}`); process.exit(2); }
+}
+if (!opt.company) { console.error("usage: ontology-brief.mjs --company <co> [--days N] [--top N] [--json]"); process.exit(2); }
+opt.root = opt.root || process.env.HQ_ROOT || path.resolve(path.dirname(new URL(import.meta.url).pathname), "../..");
+const C = path.join(opt.root, "companies", opt.company);
+if (!fs.existsSync(C)) { console.error(`ontology-brief: no company ${opt.company}`); process.exit(2); }
+
+function fm(file) {
+  const t = fs.readFileSync(file, "utf8");
+  const m = t.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  const out = { _body: (m ? m[2] : t).trim() };
+  if (m) for (const line of m[1].split("\n")) {
+    const mm = line.match(/^([A-Za-z_]+):\s*(.*)$/);
+    if (mm) out[mm[1]] = mm[2].trim().replace(/^"(.*)"$/, "$1");
+  }
+  return out;
+}
+const walk = (dir, pred) => {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) { if (!e.name.startsWith("_")) out.push(...walk(p, pred)); }
+    else if (pred(p)) out.push(p);
+  }
+  return out;
+};
+
+const entities = walk(path.join(C, "ontology", "entities"), p => p.endsWith(".md")).map(f => fm(f));
+const cutoff = Date.now() - opt.days * 86400e3;
+const signals = walk(path.join(C, "signals"), p => p.endsWith(".md") && !p.includes(`${path.sep}_`))
+  .map(f => ({ ...fm(f), _scope: f.includes(`${path.sep}signals${path.sep}@`) ? "scoped" : "company" }))
+  .filter(s => TYPES.includes(s.type));
+const recent = signals.filter(s => !s.created_at || Date.parse(s.created_at) >= cutoff)
+  .sort((a, b) => (b.created_at || "").localeCompare(a.created_at || ""));
+const facts = new Map(); // slug -> [{scope, line}]
+for (const f of walk(path.join(C, "ontology", "facts"), p => p.endsWith(".md"))) {
+  const d = fm(f); const scope = f.includes(`${path.sep}@company${path.sep}`) ? "company" : "scoped";
+  const slug = d.entity || path.basename(f, ".md");
+  for (const line of d._body.split("\n").filter(l => l.startsWith("- "))) {
+    if (!facts.has(slug)) facts.set(slug, []);
+    facts.get(slug).push({ scope, line: line.slice(2) });
+  }
+}
+const hot = entities.map(e => ({ ...e, _facts: facts.get(e.slug) || [] }))
+  .sort((a, b) => (b._facts.length - a._facts.length) || ((+b.signal_count || 0) - (+a.signal_count || 0)))
+  .slice(0, opt.top);
+
+if (opt.json) {
+  console.log(JSON.stringify({ company: opt.company, entities: entities.length, signals: signals.length,
+    recent: recent.slice(0, opt.top * 2).map(s => ({ type: s.type, scope: s._scope, text: s.canonical_content || s._body })),
+    hot: hot.map(e => ({ name: e.canonical_name, type: e.type, facts: e._facts })) }));
+  process.exit(0);
+}
+if (!entities.length && !signals.length) { console.log(`# ${opt.company} — no local ontology yet\n\nNothing under ontology/ or signals/ that you can see.`); process.exit(0); }
+const out = [`# ${opt.company} — company brief (local)`, "", `${entities.length} entities · ${signals.length} signals you can see · last ${opt.days} days`, "", "## Recent Signals"];
+for (const t of TYPES) {
+  const rows = recent.filter(s => s.type === t).slice(0, 5);
+  if (!rows.length) continue;
+  out.push("", `### ${t.replace("_", " ")}`);
+  for (const s of rows) out.push(`- ${s.canonical_content || s._body} _(${s._scope})_`);
+}
+out.push("", "## Entities");
+for (const e of hot) {
+  out.push("", `### ${e.canonical_name} — ${e.type}`);
+  if (!e._facts.length) out.push("- no facts you can see");
+  for (const f of e._facts.slice(0, 6)) out.push(`- ${f.line} _(${f.scope})_`);
+}
+console.log(out.join("\n"));

package/assets/scaffold/core/scripts/ontology-candidate.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# ontology-candidate.sh — write one signal or entity candidate for the ontology
+# worker to garden. Deterministic, no model call. Spec:
+# core/knowledge/public/hq-core/ontology-local-spec.md
+#
+# Usage:
+#   ontology-candidate.sh write --company <co> --kind signal|entity --type <t> \
+#     --audience <company|email[,email...]> --source-ref <ref> \
+#     (--body-file <path> | --body <text>) [--created-by <email>]
+#   ontology-candidate.sh key <company|email[,email...]>   # print the audience key
+#
+# Exit 0: written, already present (no-op), or capture disabled for the company.
+# Exit 2: bad usage, unknown type, or empty body.
+set -euo pipefail
+
+root="${HQ_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
+here="$(cd "$(dirname "$0")" && pwd)"
+
+SIGNAL_TYPES="action_item commitment decision risk question key_point participant_contribution summary"
+ENTITY_TYPES="person project company concept"
+
+die() { echo "ontology-candidate: $*" >&2; exit 2; }
+
+sha() { if command -v sha256sum >/dev/null 2>&1; then sha256sum | awk '{print $1}'; else shasum -a 256 | awk '{print $1}'; fi; }
+
+normalize_audience() { # stdout: sorted, lowercased, trimmed, comma-joined
+  # Emails are lowercased; person/agent uids (prs_…, agt_…) keep their case.
+  printf '%s' "$1" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
+    | awk '/@/ { print tolower($0); next } { print }' \
+    | grep -v '^$' | LC_ALL=C sort -u | paste -sd, -
+}
+
+audience_key() {
+  local a; a="$(printf '%s' "$1" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  [ -n "$a" ] || die "empty audience"
+  if [ "$(printf '%s' "$a" | tr '[:upper:]' '[:lower:]')" = "company" ]; then echo company; return; fi
+  printf '%s' "$(normalize_audience "$a")" | sha | cut -c1-16
+}
+
+cmd="${1:-}"; shift || true
+case "$cmd" in
+  key) audience_key "${1:-}"; exit 0 ;;
+  write) ;;
+  *) die "usage: ontology-candidate.sh write|key ..." ;;
+esac
+
+co="" kind="" type="" audience="" ref="" body="" body_file="" by="${HQ_USER_EMAIL:-}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --company) co="$2"; shift 2 ;;
+    --kind) kind="$2"; shift 2 ;;
+    --type) type="$2"; shift 2 ;;
+    --audience) audience="$2"; shift 2 ;;
+    --source-ref) ref="$2"; shift 2 ;;
+    --body) body="$2"; shift 2 ;;
+    --body-file) body_file="$2"; shift 2 ;;
+    --created-by) by="$2"; shift 2 ;;
+    *) die "unknown flag $1" ;;
+  esac
+done
+[ -n "$co" ] && [ -n "$kind" ] && [ -n "$type" ] && [ -n "$audience" ] && [ -n "$ref" ] || die "missing required flag"
+[ -n "$body_file" ] && { [ -f "$body_file" ] || die "no body file $body_file"; body="$(cat "$body_file")"; }
+body="$(printf '%s' "$body" | tr '\n' ' ' | sed 's/[[:space:]]\{1,\}/ /g;s/^ //;s/ $//')"
+[ -n "$body" ] || die "empty body"
+
+case "$kind" in
+  signal) allowed="$SIGNAL_TYPES"; flag=signals_capture; store=signals ;;
+  entity) allowed="$ENTITY_TYPES"; flag=ontology_capture; store=ontology ;;
+  *) die "kind must be signal or entity" ;;
+esac
+case " $allowed " in *" $type "*) ;; *) die "unknown $kind type '$type' (allowed: $allowed)" ;; esac
+
+enabled="$(HQ_ROOT="$root" bash "$here/knowledge-prefs.sh" get "$co" "$flag")" || exit 2
+if [ "$enabled" != "true" ]; then echo "disabled for $co ($flag=false)"; exit 0; fi
+
+key="$(audience_key "$audience")"
+norm_body="$(printf '%s' "$body" | tr '[:upper:]' '[:lower:]')"
+id="$(printf '%s\n%s\n%s\n%s' "$kind" "$type" "$key" "$norm_body" | sha)"
+
+dir="$root/companies/$co/$store/_candidates/$(date -u +%Y-%m-%d)"
+# Idempotent across days: the same candidate already written (pending or done) is a no-op.
+if find "$root/companies/$co/$store/_candidates" -name "$id.md" 2>/dev/null | grep -q .; then
+  echo "exists $id"; exit 0
+fi
+mkdir -p "$dir"
+{
+  echo "---"
+  echo "kind: $kind"
+  echo "type: $type"
+  echo "audience_key: $key"
+  if [ "$key" != "company" ]; then
+    echo "audience: [$(normalize_audience "$audience" | sed 's/,/, /g')]"
+  fi
+  echo "source_ref: \"$ref\""
+  [ -n "$by" ] && echo "created_by: $by"
+  echo "created_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo "---"
+  echo "$body"
+} > "$dir/$id.md.tmp" && mv "$dir/$id.md.tmp" "$dir/$id.md"
+echo "wrote $store/_candidates/$(basename "$dir")/$id.md"

package/assets/scaffold/core/scripts/ontology-garden.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// ontology-garden.mjs — promote signal and entity candidates into a company's
+// local ontology and signal stores. Deterministic: no model call, no network.
+// Spec: core/knowledge/public/hq-core/ontology-local-spec.md
+//
+// Usage: node core/scripts/ontology-garden.mjs --company <co> [--hq-root <path>] [--dry-run] [--json]
+//
+// What it does, in order:
+//   1. Entity candidates  -> ontology/entities/{type}/{slug}.md (identity only).
+//      Stopword names and a name already held by an entity of another type are
+//      rejected to ontology/_rejected/{date}.jsonl.
+//   2. Signal candidates  -> signals/{type}/{sha}.md (audience company) or
+//      signals/@{key}/{type}/{sha}.md (scoped), plus signals/@{key}/_audience.yaml
+//      and signals/_index/{date}.json.
+//   3. Facts              -> for each promoted signal, every known entity whose
+//      name or alias appears in it gets a line in
+//      ontology/facts/@{key}/{type}/{slug}.md (never in the entity file).
+//      Company-audience signals bump the entity's signal_count.
+//   4. Processed candidates move to _candidates/_done/{date}/; .last-run is
+//      bumped only when at least one candidate was processed.
+// A second run over the same input changes nothing.
+import fs from "node:fs";
+import path from "node:path";
+
+const STOPWORDS = new Set([
+  "for", "calls", "call", "context", "summary", "reason", "the", "a", "an", "and",
+  "or", "this", "that", "it", "we", "they", "you", "i", "notes", "meeting", "update",
+  "question", "decision", "risk", "todo", "none", "n/a", "unknown",
+]);
+const SIGNAL_TYPES = new Set(["action_item", "commitment", "decision", "risk", "question",
+  "key_point", "participant_contribution", "summary"]);
+const ENTITY_TYPES = new Set(["person", "project", "company", "concept"]);
+
+function parseArgs(argv) {
+  const a = { dryRun: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === "--company") a.company = argv[++i];
+    else if (k === "--hq-root") a.root = argv[++i];
+    else if (k === "--dry-run") a.dryRun = true;
+    else if (k === "--json") a.json = true;
+    else { console.error(`ontology-garden: unknown flag ${k}`); process.exit(2); }
+  }
+  if (!a.company) { console.error("usage: ontology-garden.mjs --company <co> [--hq-root <p>] [--dry-run] [--json]"); process.exit(2); }
+  a.root = a.root || process.env.HQ_ROOT || path.resolve(path.dirname(new URL(import.meta.url).pathname), "../..");
+  return a;
+}
+
+// Minimal frontmatter reader for the flat key: value shape the writers emit.
+function readDoc(file) {
+  const text = fs.readFileSync(file, "utf8");
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { fm: {}, body: text.trim() };
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const mm = line.match(/^([A-Za-z_]+):\s*(.*)$/);
+    if (!mm) continue;
+    let v = mm[2].trim();
+    if (v.startsWith("[") && v.endsWith("]")) v = v.slice(1, -1).split(",").map(s => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    else v = v.replace(/^["']|["']$/g, "");
+    fm[mm[1]] = v;
+  }
+  return { fm, body: m[2].trim() };
+}
+
+function writeDoc(file, fm, body, dry) {
+  if (dry) return;
+  const lines = ["---"];
+  for (const [k, v] of Object.entries(fm)) {
+    if (v === undefined || v === null || v === "") continue;
+    lines.push(`${k}: ${Array.isArray(v) ? `[${v.join(", ")}]` : v}`);
+  }
+  lines.push("---", body, "");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, lines.join("\n"));
+  fs.renameSync(tmp, file);
+}
+
+const slugify = s => s.toLowerCase().normalize("NFKD").replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+const today = () => new Date().toISOString().slice(0, 10);
+const now = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
+function listCandidates(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const d of fs.readdirSync(dir).sort()) {
+    if (d === "_done") continue;
+    const full = path.join(dir, d);
+    if (!fs.statSync(full).isDirectory()) continue;
+    for (const f of fs.readdirSync(full).sort()) if (f.endsWith(".md")) out.push(path.join(full, f));
+  }
+  return out;
+}
+
+function main() {
+  const a = parseArgs(process.argv.slice(2));
+  const co = path.join(a.root, "companies", a.company);
+  if (!fs.existsSync(co)) { console.error(`ontology-garden: no company ${a.company}`); process.exit(2); }
+  const ont = path.join(co, "ontology"), sig = path.join(co, "signals");
+  const report = { company: a.company, entities_created: 0, entities_updated: 0, signals_promoted: 0,
+    facts_written: 0, rejected: 0, candidates_processed: 0, dry_run: a.dryRun };
+  const rejected = [];
+  const moves = [];
+
+  // Load the current entity index: slug -> {type, file, fm, names[]}
+  const entities = new Map();
+  const nameIndex = new Map(); // lowercased name/alias -> slug
+  const entDir = path.join(ont, "entities");
+  if (fs.existsSync(entDir)) for (const t of fs.readdirSync(entDir)) {
+    const td = path.join(entDir, t);
+    if (!fs.statSync(td).isDirectory()) continue;
+    for (const f of fs.readdirSync(td)) {
+      if (!f.endsWith(".md")) continue;
+      const file = path.join(td, f); const { fm } = readDoc(file);
+      const slug = fm.slug || f.replace(/\.md$/, "");
+      const names = [fm.canonical_name, ...(Array.isArray(fm.aliases) ? fm.aliases : [])].filter(Boolean);
+      entities.set(slug, { type: fm.type || t, file, fm, names });
+      for (const n of names) nameIndex.set(n.toLowerCase(), slug);
+    }
+  }
+
+  // 1. Entity candidates
+  for (const file of listCandidates(path.join(ont, "_candidates"))) {
+    const { fm, body } = readDoc(file);
+    const name = body.split("\n")[0].trim();
+    const type = fm.type;
+    const reject = reason => { rejected.push({ at: now(), name, type, reason, candidate: path.relative(co, file) }); report.rejected++; };
+    if (!ENTITY_TYPES.has(type)) reject("unknown-type");
+    else if (!name || STOPWORDS.has(name.toLowerCase()) || name.length < 2) reject("stopword");
+    else {
+      const slug = slugify(name);
+      const held = nameIndex.get(name.toLowerCase());
+      const existing = entities.get(held || slug);
+      if (existing && existing.type !== type) reject(`type-conflict:${existing.type}`);
+      else if (existing) {
+        const aliases = new Set(Array.isArray(existing.fm.aliases) ? existing.fm.aliases : []);
+        if (name !== existing.fm.canonical_name && !aliases.has(name)) {
+          aliases.add(name); existing.fm.aliases = [...aliases]; existing.fm.last_updated = now();
+          writeDoc(existing.file, existing.fm, "", a.dryRun); report.entities_updated++;
+          nameIndex.set(name.toLowerCase(), held || slug);
+        }
+      } else {
+        const efile = path.join(ont, "entities", type, `${slug}.md`);
+        const efm = { type, canonical_name: name, slug, aliases: [], signal_count: 0,
+          first_seen: fm.created_at || now(), last_updated: now(), enriched_by: "ontology-worker" };
+        writeDoc(efile, efm, "", a.dryRun);
+        entities.set(slug, { type, file: efile, fm: efm, names: [name] });
+        nameIndex.set(name.toLowerCase(), slug);
+        report.entities_created++;
+      }
+    }
+    moves.push(file); report.candidates_processed++;
+  }
+
+  // 2 + 3. Signal candidates -> signals + facts
+  const index = [];
+  for (const file of listCandidates(path.join(sig, "_candidates"))) {
+    const { fm, body } = readDoc(file);
+    const type = fm.type; const key = fm.audience_key;
+    moves.push(file); report.candidates_processed++;
+    if (!SIGNAL_TYPES.has(type) || !key || !body) {
+      rejected.push({ at: now(), type, reason: !key ? "missing-audience" : "invalid", candidate: path.relative(co, file) }); report.rejected++;
+      continue;
+    }
+    if (key !== "company" && !(Array.isArray(fm.audience) && fm.audience.length)) {
+      rejected.push({ at: now(), type, reason: "scoped-without-principals", candidate: path.relative(co, file) }); report.rejected++;
+      continue;
+    }
+    const id = path.basename(file, ".md");
+    const scopeDir = key === "company" ? sig : path.join(sig, `@${key}`);
+    const out = path.join(scopeDir, type, `${id}.md`);
+    if (!fs.existsSync(out)) {
+      writeDoc(out, { signal_id: id, type, canonical_content: JSON.stringify(body.split("\n")[0]), audience_key: key,
+        source_ref: JSON.stringify(fm.source_ref || ""), created_at: fm.created_at || now() }, body, a.dryRun);
+      report.signals_promoted++;
+      index.push({ signal_id: id, type, audience_key: key, path: path.relative(co, out) });
+      if (key !== "company") {
+        const audFile = path.join(scopeDir, "_audience.yaml");
+        if (!fs.existsSync(audFile) && !a.dryRun) {
+          fs.mkdirSync(scopeDir, { recursive: true });
+          fs.writeFileSync(audFile, `audience_key: ${key}\nprincipals: [${fm.audience.join(", ")}]\n`);
+        }
+      }
+      // Facts: every known entity named in the signal.
+      const lower = body.toLowerCase();
+      const hit = new Set();
+      for (const [n, slug] of nameIndex) {
+        if (n.length < 3) continue;
+        const re = new RegExp(`(^|[^\\p{L}\\p{N}])${n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}($|[^\\p{L}\\p{N}])`, "u");
+        if (re.test(lower)) hit.add(slug);
+      }
+      for (const slug of hit) {
+        const e = entities.get(slug);
+        const ffile = path.join(ont, "facts", `@${key}`, e.type, `${slug}.md`);
+        const line = `- [${type}] ${body.split("\n")[0]} (signal ${id.slice(0, 12)})`;
+        const prev = fs.existsSync(ffile) ? readDoc(ffile) : { fm: { entity: slug, type: e.type, audience_key: key }, body: "" };
+        if (!prev.body.includes(`signal ${id.slice(0, 12)}`)) {
+          writeDoc(ffile, prev.fm, [prev.body, line].filter(Boolean).join("\n"), a.dryRun);
+          report.facts_written++;
+        }
+        if (key === "company") {
+          e.fm.signal_count = String((parseInt(e.fm.signal_count || "0", 10) || 0) + 1);
+          e.fm.last_updated = now();
+          writeDoc(e.file, e.fm, "", a.dryRun);
+        }
+      }
+    }
+  }
+
+  if (!a.dryRun) {
+    if (index.length) {
+      const f = path.join(sig, "_index", `${today()}.json`);
+      const prev = fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, "utf8")) : [];
+      fs.mkdirSync(path.dirname(f), { recursive: true });
+      fs.writeFileSync(f, JSON.stringify([...prev, ...index], null, 2) + "\n");
+    }
+    if (rejected.length) {
+      const f = path.join(ont, "_rejected", `${today()}.jsonl`);
+      fs.mkdirSync(path.dirname(f), { recursive: true });
+      fs.appendFileSync(f, rejected.map(r => JSON.stringify(r)).join("\n") + "\n");
+    }
+    for (const file of moves) {
+      const rel = path.relative(path.dirname(path.dirname(file)), file); // {date}/{sha}.md
+      const dest = path.join(path.dirname(path.dirname(file)), "_done", rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.renameSync(file, dest);
+    }
+    if (report.candidates_processed > 0) {
+      fs.mkdirSync(ont, { recursive: true });
+      fs.writeFileSync(path.join(ont, ".last-run"), `${Date.now()}\n`);
+    }
+  }
+  if (a.json) console.log(JSON.stringify(report));
+  else console.log(`garden ${a.company}: +${report.entities_created} entities, ~${report.entities_updated} updated, +${report.signals_promoted} signals, +${report.facts_written} facts, ${report.rejected} rejected, ${report.candidates_processed} candidates${a.dryRun ? " (dry run)" : ""}`);
+}
+
+main();