Troubleshooting and FAQ

Troubleshooting and FAQ

This page is explanatory. Canonical operational details live in INSTALL.md, SECURITY.md, and the relevant documents under docs/.

Bootstrap completed, but a profile does not respond

Start with offline validation and then run the smoke test. If only online mode fails, the likely issue is provider/model configuration rather than repo structure.

What is the difference between offline validation and online smoke test?

Offline validation checks repository structure and expected public artifacts. Online smoke testing sends a real question to each profile and therefore depends on provider/model credentials.

The wiki or repository does not accept push

For the main repository, check token scope, remote URL, and whether the branch is behind origin/main.

For the wiki, remember it is a separate Git repository. If https://github.com/<owner>/<repo>.wiki.git returns Repository not found, the wiki backend may not be materialized yet.

Provider/model is not configured

Run the bootstrap/setup flow again or configure Hermes separately, then repeat the smoke test.

An optional dependency is missing

Consult docs/dependencies-and-configuration.md to decide whether the missing tool is required for your engagement type.

Headroom became a noop

If selective retrieval stops producing useful packs, fall back to raw-authoritative review and verify whether the current artifact type or hypothesis still benefits from selection-first retrieval.

KAG did not return enough evidence

Lack of evidence in a retrieval pack is not proof of absence in the source artifact. Escalate to raw review when the decision depends on missing slices.

An engagement ended in RESEARCH

That means the current evidence is not sufficient for a stronger conclusion. The correct next step is an evidence-collection or impact-validation plan, not a forced final claim.

A finding was blocked by QA

That is a feature of the workflow, not necessarily a failure of the engagement. QA may reject a claim because scope is unclear, impact is inferred, evidence is weak, or the narrative overstates what was shown.

How do I update without publishing private state?

Use the safe self-update path only for allowlisted, non-secret artifacts and review the diff before commit/push.