Troubleshooting

Validation reports a missing layout path

Run threadpoint init for a new shared layout, then run validate and doctor again. If the project already has native agent files, inspect the doctor output before adopting them.

threadpoint init --root .
threadpoint validate --root .
threadpoint doctor --root .

Imports remain staged

Run promote in plan mode, review every staged import, and apply only when the shared guidance is ready. Do not prune native provider files while imports are unresolved.

threadpoint promote --root . --plan
threadpoint promote --root . --apply --yes

Prune refuses to remove native files

Treat a refusal as a safety signal. Rerun adopt and promote if native files changed after the backup, then retry prune in plan mode.

threadpoint adopt --root . --plan
threadpoint prune --root . --plan

License status is unconfigured

The current status command reads THREADGRID_LICENSE_KEY. If that variable is unset, the expected safe output is JSON status unconfigured. Do not paste license material into source files, shell history, support requests, or public issues.

threadgrid license status
{
  "status": "unconfigured"
}

License refresh is unavailable

License refresh requires THREADGRID_LICENSE_KEY. If it is unset, configure the key locally or activate with the key before refreshing.

THREADGRID_LICENSE_KEY=<redacted> threadgrid license refresh

License activation is delayed

If checkout completed but activation still reports inactive, retry refresh after confirming the Polar license key from the order email or customer portal is enabled for the lifetime benefit. Send only the request ID, UTC time, and safe status category to support; do not include customer IDs, order IDs, order details, license keys, or entitlement payloads.

License key email is missing

Open the customer portal from the license page and enter the local license key you have. The portal validates the key before opening Polar order and license details.

A paid workflow is not documented yet

Check the workflow guide first. Treat undocumented paid personal, private, cross-project, archive, curation, recall, review, publication, and license-aware workflows as unavailable unless the docs explicitly label them as shipped. Do not infer hidden support from product-planning language.

A threadgrid install channel is unavailable

Use the install page for current availability. The threadgrid installer and manual release archives are the v0 paths. Homebrew and package-manager channels remain planned until their release tasks are complete.