API And Public Surfaces

Documentation Map

• Overview

• Quick Start

• Installation

• Configuration

• Operations

• Troubleshooting

• Release Notes

• Compatibility

• Architecture

• API Reference

• Security

• Integrations

• Capabilities

• Roadmap

• Contract Governance

• OSS Inventory

• Channel: latest

• Source repo: JaddaHelpifyr/jhf-bobbin

API And Public Surfaces

Tool / Contract Summary

jhf-bobbin does not expose a resident Bobbin-owned HTTP API, webhook endpoint, or MCP service. Its public and testable surfaces are CLI scripts, file contracts, machine-readable manifests, packaging artifacts, and validator outputs.

Business Value

• gives operators and QA a clear inventory of what can be called or validated
• prevents README and integration docs from becoming an unstructured endpoint dump
• makes it explicit which runtime APIs are consumed from other systems instead of owned locally

Current Verified State

Available and repo-validated surfaces include:

• Python and shell CLI entrypoints in scripts/
• machine-readable manifests and config contracts
• package build/publish/verify scripts
• repo-local and optional live runtime verification paths

Available Now

Exposed Repo-Owned CLI Surfaces

Surface	Type	Purpose
bash scripts/bootstrap.sh	shell	bootstrap installer configuration
bash scripts/install_jhf_memory.sh	shell	install or re-materialize the Bobbin runtime stack
bash scripts/reapply_after_openclaw_update.sh	shell	restore Bobbin state after OpenClaw updates
bash scripts/plugin_smoke_test.sh	shell	bounded runtime smoke validation
bash scripts/qdrant_checks.sh	shell	Qdrant collection and search verification
bash scripts/fabric-selfcheck.sh	shell	repo-local contract and documentation selfcheck
python3 scripts/check_live_runtime_contract.py	python CLI	fail-closed live runtime verification
python3 scripts/export_host_runtime_snapshot.py	python CLI	read-only runtime snapshot export
python3 scripts/check_runtime_materialization_drift.py	python CLI	cross-layer runtime materialization drift verification
python3 scripts/export-fabric-metadata.py	python CLI	metadata export for downstream consumers
python3 scripts/export_fabric_status_bundle.py	python CLI	status bundle export for read-only consumers

Exposed File And Artifact Surfaces

Surface	Type	Purpose
fabric-manifest.json	manifest	canonical Bobbin identity, capabilities, dependencies, and consumed surfaces
configs/stack-contract.json	contract	canonical stack, ports, volumes, and startup/verify truth
docs/MODULE_FEATURES.md	contract	machine-readable QA feature registry
dist/package-metadata.json	artifact metadata	package delivery contract after build/publish

Optional / Extended

• live readback checks using --check-live variants for Fabric and runtime validators
• package publishing via Gitea Generic Packages
• host snapshot validation and operator-run evidence export

Planned / Not in Current Scope

• no resident Bobbin-owned REST API
• no Bobbin-owned inbound webhook contract
• no Bobbin-owned queue consumer surface
• no Bobbin-owned MCP runtime service

Public Surfaces

Resident Service Surfaces

• none

Consumed Runtime APIs

Upstream Surface	Purpose	Ownership
GET /readyz on LocalAI	readiness confirmation	target runtime
GET /v1/models on LocalAI	model presence verification	target runtime
POST /v1/embeddings on LocalAI	embedding generation	target runtime
Qdrant collection/search endpoints	vector store bootstrap and recall verification	target runtime
Fabric contract/readiness endpoints	governance and claims truth consumption	jhf-fabric

Contract Families

Fabric-owned families consumed read-only are documented in:

• Fabric Tool Profile (docs/FABRIC_TOOL_PROFILE.md)
• Memory Policy and Claims Consumption (docs/MEMORY_POLICY_AND_CLAIMS_CONSUMPTION.md)
• Integrations

Producer-/Consumer-Zuordnung

• Bobbin produces:
  • CLI outputs
  • validation results
  • exported metadata/status artifacts
  • package metadata
• Bobbin consumes:
  • OpenClaw runtime configuration
  • LocalAI and Qdrant runtime APIs
  • Fabric governance/claims/readiness surfaces

Compatibility Window

• version truth: tag v0.x.y or derived 0.0.0+<shortsha>
• interface stability: stable for documented CLI/contract surfaces, operator-bounded for live host flows

Lifecycle Status

• repo-owned public surfaces: active
• resident service API: intentionally absent

Readiness / Drift / Monitoring

• use Operations for operational verify paths
• use Feature Registry (docs/MODULE_FEATURES.md) for QA-oriented test paths
• use Stack Container Contract (docs/STACK_CONTAINER_CONTRACT.md) for canonical stack truth

Deployment / Verify

bash scripts/fabric-selfcheck.sh
python3 scripts/check_docs_contract.py
python3 scripts/check_module_features_contract.py
python3 -m unittest -q tests/test_contracts.py

Known Limits

• CLI and file surfaces are repo-owned; runtime APIs are mostly upstream-owned
• host verification depends on operator access and running services

Related Issues

• JaddaHelpifyr/jhf-bobbin#59
• JaddaHelpifyr/jhf-bobbin#60
• JaddaHelpifyr/jhf-bobbin#74

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.