Developers and machine interfaces

Data inventory and canonical boundaries

One machine-readable catalog describes all 11 collections, their sources, schemas, APIs, measured counts, and the boundary of every projection. /data/latest/inventory.json ·/data/latest/coverage.json ·/data/latest/case-lift.json ·/data/latest/coverage-backlog.json

Collections

Entities

176

Scenarios

Archetypes

124

Type	Count	Role	Source	API / schema
`observation` Observation	21	A directly observable trace left by the hiring process.	`data/{lang}/entities/observation/*.md`	REST · schema
`barrier` Barrier	16	A gate where the nominal hiring path can stop or diverge.	`data/{lang}/entities/barrier/*.md`	REST · schema
`mechanism` Mechanism	28	A causal force compatible with one or more observations and barriers.	`data/{lang}/entities/mechanism/*.md`	REST · schema
`pattern` Pattern	4	A recurring, rule-defined combination of observations and compatible mechanisms.	`data/{lang}/entities/pattern/*.md`	REST · schema
`loop` Loop	3	A validated reinforcing cycle among mechanisms.	`data/{lang}/entities/loop/*.md`	REST · schema
`intervention` Intervention	24	An actor-owned change aimed at a barrier, mechanism, pattern, or loop.	`data/{lang}/entities/intervention/*.md`	REST · schema
`actor` Actor	7	A decision seat with explicit controls, blind spots, and incentives.	`data/{lang}/entities/actor/*.md`	REST · schema
`process` Process	4	A state machine naming the subject, states, owners, transitions, and expected timing.	`data/{lang}/entities/process/*.md`	REST · schema
`era` Era	4	A sourced period of hiring economics: capital, hiring behavior, entry paths, and its ending.	`data/{lang}/entities/era/*.md`	REST · schema
`evidence` Evidence record	52	A language-neutral source supporting registry claims.	`data/evidence/*.md`	REST · schema
`record` Financial record	13	A durable budget, contract, funding, fee, payroll, subscription, or runway state with explicit flows.	`data/{lang}/entities/record/*.md`	REST · schema

composition

Validated scenarios · 16

Reusable situations composed from canonical entity IDs and explicit non-inferences.

Not for: A scenario is not an ontology entity or a claim that every case matches it.

presentation

Archetype overlays · 124

A nickname and grid placement for browsing every non-evidence ontology entry.

Not for: Archetypes are presentation, not evidence or canonical facts.

derived

Formal substrate

A four-primitive projection used for proofs, conservation checks, and cross-cutting queries.

Not for: Never edit the substrate as a second source of truth.

Choose the tool by situation

Understand one concept in context

Open the reader page; follow related entries and evidence.

Website

Fetch one known canonical ID

GET the collection item, run hoba show, or call get_node.

Static REST APICLIMCP server

Find concepts without knowing an ID

Search all 11 ontology collections by ID, title, and prose.

CLIMCP server

Start from a recurring real-world situation

Use a validated scenario, then inspect its explicit non-inferences.

WebsiteCLIMCP server

Separate observations from compatible causes

Run the H→O→B→A diagnostic protocol; do not jump from signal to motive.

CLIMCP serverWebsite

Load the entire ontology into a data system

Use registry.json for one snapshot or NDJSON for streaming.

Registry JSONNDJSON

Analyze causal/topological relationships

Use graph JSON/GraphML/CSV; remember it is the six-type finding projection.

Graph exports

Build a typed integration

Generate a client from OpenAPI and validate payloads with JSON Schema.

OpenAPIJSON SchemasStatic REST API

Give an agent exact registry access

Connect the MCP server so the model calls tools instead of guessing from copied prose.

MCP server

Add or change registry data

Edit authored data only, run strict validation and the build, then review generated drift.

Authored sourceValidation tools

Verify formal invariants

Regenerate the formal projection and run the Lean checks.

Validation toolsLean projection

Static REST API

Read-only JSON, generated at build time and served straight from the CDN. There is no database behind it. /openapi.json

Model Context Protocol (MCP) server stdio · local

Connect AI coding assistants and autonomous agents directly to the hoba knowledge graph.

// claude_desktop_config.json / .mcp.json — run from a local checkout
// (git clone … && pnpm install && pnpm build:packages)
{
  "mcpServers": {
    "hoba": {
      "command": "node",
      "args": ["/path/to/hoba.work/packages/mcp/dist/index.js", "--dir", "/path/to/hoba.work"]
    }
  }
}

Available tools: get_registry_info, get_data_inventory, search_registry, get_node, get_scenario, analyze_social_complaint, find_nearby_scenarios, explain_observation, find_compatible_mechanisms, get_diagnostic_probes, find_patterns, get_interventions, traverse_graph, get_methodology, detect_temporal_anomalies, calculate_runway, verify_flow_conservation, evaluate_pattern_emptiness, validate_entity_ids, validate_scenario, validate_analysis, validate_claim.

Methodology resources: hoba://methodology/core, hoba://methodology/epistemic-rules, hoba://methodology/agency, hoba://methodology/evidence, hoba://methodology/non-goals.

MCP returns canonical data, rules, and deterministic checks. Natural-language reasoning can remain in the client model.

The packages are not on npm yet; npx @hoba/mcp will work once they are.

Command line interface (CLI)

pnpm build:packages && node packages/cli/dist/cli.js --help

hoba search "reposted": Find entities that match a query
hoba registry inventory --json: Get the canonical catalog, measured counts, surfaces, and usage guidance
hoba explain obs.materially_similar_role_reposted_shortly_after_rejection --stage technical: Run the hoba protocol on an observation
hoba scenario scenario.application_silence: Read a validated scenario composed over the ontology
hoba show mech.genuine_technical_skill_shortfall: Print one node in full
hoba validate --strict: Check content, the barrier DAG, loop declarations and English/Ukrainian parity
hoba latency proc.the_hiring_funnel_end_to_end recruiter-queue 45: Diagnose a stage dwell-time anomaly
hoba runway 25000 3500: Calculate the financial runway horizon of a search

Add --json to any command for machine-readable output.

How to read the registry from code