Ontology (HQ-shared)

Read the active company's ontology — local first, the cloud gardener's output only as a fallback. Background on the gardener pipeline lives at core/knowledge/public/hq-core/ontology-gardener.md — read that ONCE per session if you need mechanism details; this skill is the runtime API.

When to use

Use this skill when an agent needs:

• Situational snapshot of a company → read company-brief.md (gardener-generated, ranked + token-budgeted)
• Entity context for a known person/project/company/concept → read ontology/entities/{type}/{slug}.md
• Activity signal — which entities are hot recently → sort by signal_count (frontmatter)
• Cross-references — what signals/sources mention an entity → entity's Relationships section
• Manual run — to refresh the brief or process new files immediately rather than waiting for the 4h tick

Do NOT use this for:

• Querying the indigo-signals-mcp MongoDB collections (that's a different store; use the MCP server / /indigo:signals skill)
• Triaging action items / commitments (use /indigo:signals or /indigo:action-items)
• Reading raw knowledge/, sources/, or signals/ files individually (slow + noisy — read the brief)

Step 0 — local brief first

Ontology is local-first (spec: core/knowledge/public/hq-core/ontology-local-spec.md). Resolve the company from bash core/scripts/hq-session.sh get company_slug, then render the brief from the local tree:

node core/scripts/ontology-brief.mjs --company {co}

It reads ontology/entities/, every ontology/facts/@*/, and every signal folder you have locally. Sync only delivers what you may read, so the brief shows exactly the facts and signals you were privy to; each line is tagged company or scoped. It writes nothing — never save a rendered brief into the company tree, because another reader may not be entitled to its scoped lines.

If it prints "no local ontology yet" and the company is cloud-backed with the cloud gardener still enabled, fall back to Step 1 below and say so in one line ("local ontology empty — reading the cloud brief"). Otherwise stop here.

Entity lookup (local): ontology/entities/{type}/{slug}.md for identity, and ontology/facts/@*/{type}/{slug}.md for what is known about it.

Step 0.5 — cloud fallback: resolve active company

The gardener output lives in the company's per-entity vault bucket. Resolve:

• Active company slug from session context (e.g. companies/manifest.yaml company anchor, ~/.hq/active-company, or ask the user if ambiguous)
• That company's vault bucket — look up via companies/{co}/manifest.yaml vault_bucket field OR derive from the gardener Lambda env (S3_BUCKET) if you operate the HQ cloud backend that runs the gardener
• That company's gardener Lambda — discover it (if deployed) via aws lambda list-functions --query "Functions[?contains(FunctionName,'OntologyGardener')].FunctionName" --output text

Announce: Ontology context: {company} · bucket {bucket} · gardener {fn-name}

If the active company has no gardener deployed yet (multi-tenant rollout still in progress), say so and stop — there's nothing to read.

Step 1 — Read the brief (default action)

aws s3 cp s3://{bucket}/company-brief.md - 2>&1

The brief is the first thing to read for any "what's going on" question. Sections in order:

1. ## Recent Signals — top N decisions/risks/questions (per brief.max_signals_per_type, default 5)
2. ## Source Channels — last-7d count per channel (meeting/email/slack/linear/notion)
3. Entity sections — top entities by signal_count

If the brief is empty / missing, the gardener has either never run or never had ≥3 entities. In that case, fall back to listing recent signals directly: aws s3 ls s3://{bucket}/signals/ --recursive | tail -20.

Step 2 — Targeted entity lookup

If the user asks about a specific person/project/company/concept:

# Find the entity slug — try canonical name → slug deterministically
SLUG=$(echo "{Name}" | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g' | sed 's/[^a-z0-9-]//g')

# Try each type until one resolves (or query the entity index if available)
for TYPE in person project company concept; do
  aws s3 cp "s3://{bucket}/ontology/entities/$TYPE/$SLUG.md" - 2>/dev/null && echo "found in $TYPE" && break
done

Read the frontmatter for signal_count, last_updated, first_seen. Read the body for description + Relationships section.

Step 3 — "What's hot recently"

Sort entities by signal_count:

aws s3 sync s3://{bucket}/ontology/entities/ /tmp/entities-{co}/ --quiet
for f in /tmp/entities-{co}/**/*.md; do
  count=$(grep -m1 '^signal_count:' "$f" | awk '{print $(2)}')
  echo "$count $f"
done | sort -rn | head -10

Returns the top-10 most-referenced entities. Useful for "who/what is dominating recent activity".

Step 4 — Manual gardener run

Trigger an ad-hoc gardener invocation (don't wait for the 4h tick):

GARDENER_FN=$(aws lambda list-functions \
  --query "Functions[?contains(FunctionName,'OntologyGardener')].FunctionName | [0]" \
  --output text)

aws lambda invoke --function-name "$GARDENER_FN" \
  --invocation-type RequestResponse --cli-binary-format raw-in-base64-out \
  --payload '{"version":"0","detail-type":"Scheduled Event","source":"aws.events","detail":{}}' \
  --log-type Tail /tmp/gardener-response.json 2>&1 | jq -r '.LogResult' | base64 -d | tail -20

Limitations:

• Uses AWS S3 Files mount at /mnt/s3-{company}/. Files PUT via aws s3 cp may not appear in the mount immediately. Production writers (signals-agent, transcript ingester, source-writer in infra/meeting-storage.ts) DO write through the mount and ARE immediately visible. Use those for end-to-end tests.
• One company per Lambda today. Multi-tenant rollout to other companies is a separate PRD.

Step 5 — Inspect cheap-path hit rate

The gardener emits SignalRefsResolved + SignalRefsUnresolved counters. High resolved/unresolved ratio = the signals agent is doing a good job of pre-linking entities (no LLM needed for ingestion).

NOW=$(date -u +%FT%TZ)
ONE_DAY_AGO=$(date -u -v-1d +%FT%TZ 2>/dev/null || date -u -d '1 day ago' +%FT%TZ)
GARDENER_NAMESPACE="<your-gardener-cloudwatch-namespace>"  # set to the namespace your HQ cloud backend publishes under

aws cloudwatch get-metric-statistics \
  --namespace "$GARDENER_NAMESPACE" \
  --metric-name SignalRefsResolved \
  --dimensions Name=CompanyId,Value={company} Name=Prefix,Value=signals \
  --start-time "$ONE_DAY_AGO" --end-time "$NOW" \
  --period 3600 --statistics Sum --output text

aws cloudwatch get-metric-statistics \
  --namespace "$GARDENER_NAMESPACE" \
  --metric-name SignalRefsUnresolved \
  --dimensions Name=CompanyId,Value={company} Name=Prefix,Value=signals \
  --start-time "$ONE_DAY_AGO" --end-time "$NOW" \
  --period 3600 --statistics Sum --output text

If unresolved >> resolved, either (a) the signals agent is producing signals for entities not yet in the graph (gardener will LLM-extract them on the next run, capped by signals.max_cost_usd), or (b) the entity files were renamed and entityIdFromPath no longer resolves the refs.

Step 6 — Inspect logs / metrics dashboards

• Logs: aws logs tail /aws/lambda/{GARDENER_FN} --follow --since 5m --format short
• Dashboard: CloudWatch HQ-OntologyGardener-{stage} — per-prefix invocation graphs, cheap-path hit rate, cost
• Cost alarms: ontology-signals-run-cost-{stage}, ontology-sources-run-cost-{stage}, ontology-daily-cost-ceiling-{stage}, ontology-stale-gardener-{stage}

Multi-tenant note

Today the gardener is single-tenant — there's one Lambda instance bound to a single company (COMPANY_ID={company}, mount /mnt/s3-{company}). For another company to benefit from this skill, the HQ cloud backend needs to provision a per-company Lambda OR rewrite the single Lambda to loop over companies. Track in a future PRD; until then this skill is single-company even though its design is multi-tenant.

Rules

• Read the brief FIRST. Don't iterate entity files until you've checked the ranked summary.
• Don't write to the vault from this skill — gardener writes are authoritative. To force a re-run, invoke the Lambda (Step 4), don't touch entity files directly.
• Don't synthesize signal_count or other counters — read the real values from the vault.
• Respect company isolation: the skill operates on the resolved active company's vault only. Never reach into another company's bucket.
• If a question can be answered without a gardener call (e.g. read company-brief.md directly), skip Step 4.