Skip to main content

Troubleshooting

Documentation Map​

Troubleshooting

Use this page as the short-entry runbook. Deeper operator procedures remain in the existing runbooks and product docs.

Primary References​

  • Operations
  • Runbook
  • Stack Contract (docs/STACK_CONTRACT.md)
  • Integrations (docs/INTEGRATIONS.md)
  • MCP Operations (docs/MCP_OPERATIONS.md)

Runtime / Compose / Drift Problems​

Run this check:

python infra/scripts/verify_stack_contract.py --check-running
python infra/scripts/verify_runtime_materialization.py --output artifacts/evidence/runtime-materialization.json
python maintenance/verify_oss_inventory_version_truth.py --check-live --ssh-target <internal-runtime-redacted><internal-runtime-redacted> --output artifacts/evidence/oss-version-truth.live.json

MCP / Operator Gateway Problems​

Run this check:

python infra/scripts/verify_authenticated_mcp_demo_action.py --ssh-target <internal-runtime-redacted><internal-runtime-redacted> --host-repo-path /home/administrator/jhf-spindle --output artifacts/evidence/mcp-authenticated-demo-action-live.json
python infra/scripts/mcp-call.py --help

Callback / Approval / Dispatch Problems​

Run this check:

python infra/scripts/check_callback_transport.py --output artifacts/callback-transport.json
bash infra/scripts/contract-smoke.sh
python -m pytest -q apps/jhf_spindle_core/tests/test_approval_packets.py apps/jhf_spindle_core/tests/test_document_dispatch.py

Support / Zammad Problems​

Run this check:

bash infra/scripts/zammad-smoke.sh
python infra/scripts/run_zammad_erp_corner_cases.py
python infra/scripts/support_case_smoke.py

Release / Contract Drift Problems​

Run this check:

python infra/scripts/check_markdown_compliance.py
python infra/scripts/check_compatibility_contracts.py --check
python infra/scripts/export_fabric_metadata.py --check
python infra/scripts/openclaw_plus_acceptance.py

License notice: AGPLv3 (GNU Affero General Public License v3.0)
Website: https://helpifyr.com