> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldflux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Edge cases, error messages, and the questions people email about most often.

## Setup

<AccordionGroup>
  <Accordion title="`worldflux init demo-box` says the directory exists.">
    Pick a different name, or pass `--force` if you mean to overwrite the generated WorldFlux files. `--force` does not delete files the recipe did not create.
  </Accordion>

  <Accordion title="The CLI cannot find a Python interpreter.">
    Install `uv` (`curl -LsSf https://astral.sh/uv/install.sh | sh`) and re-try. During beta, design partners install WorldFlux from a private checkout or private package index; public PyPI and `pipx` installation will be documented after the public package release.
  </Accordion>

  <Accordion title="`worldflux doctor` warns about the keyring.">
    On macOS, Keychain handles it. On Linux without `gnome-keyring` or `kwallet`, install one or pass `--allow-plaintext` to fall back to a config file. Plaintext is fine on machines only you can read; in CI, prefer `--token-env`.
  </Accordion>
</AccordionGroup>

## Sync

<AccordionGroup>
  <Accordion title="`worldflux sync` exits with `quota_exceeded`.">
    The workspace plan is at its run cap. Open `Settings → Billing` in the dashboard and upgrade, or wait for the cap to roll over. Plan status changes after the Stripe webhook is processed.
  </Accordion>

  <Accordion title="`login_required` after I just logged in.">
    The API key is scoped to one workspace. If `--workspace` on `login` did not match the one you are syncing into, log in again with the right slug.
  </Accordion>

  <Accordion title="The upload restarted from zero after a network blip.">
    `sync` is idempotent on `client_run_id`. The server discards re-uploads of artifact ids it already has, so the bytes you saw twice were not double-charged.
  </Accordion>

  <Accordion title="My API key leaked into shell history.">
    Rotate it immediately: `Settings → API keys → revoke`. The CLI keyring never echoes the key. The `printf` + `IFS= read -r -s` pattern in the quickstart keeps it off your history.
  </Accordion>
</AccordionGroup>

## Dashboard

<AccordionGroup>
  <Accordion title="The runs table is empty, but I just synced.">
    The Overview card shows whichever workspace the sidebar has selected. Switch it from the workspace switcher and the runs appear.
  </Accordion>

  <Accordion title="The metrics chart renders blank.">
    Recharts reads tokens at mount time. If the page mounted before the dark theme applied, the lines are drawn in fallback colors that happen to sit on top of the surface. Reload once.
  </Accordion>

  <Accordion title="The public share link is unavailable.">
    Revoked or expired shares return 410 and render an unavailable state. A deleted or unknown token can still return 404. There is no recovery path for a revoked share; the workspace owner must mint a new one.
  </Accordion>
</AccordionGroup>

## Recipes

<AccordionGroup>
  <Accordion title="MuJoCo recipes fail to import.">
    Run `uv sync --extra mujoco` first. The base install does not pull MuJoCo because the wheel is large and the suite is optional.
  </Accordion>

  <Accordion title="A V-JEPA recipe says VRAM is too low.">
    Drop to the `vjepa2_vitl` 0.3B variant in the catalog, or run on a host with more memory. The catalog's `minimumVramGb` is the observed floor for full-precision inference.
  </Accordion>

  <Accordion title="`worldflux compare` says the metrics shape differs.">
    The two recipes wrote different metric keys into the manifest. Compare reads the union and shows `n/a` for missing pairs. That is intentional. It lets you compare apples to oranges and read the gap.
  </Accordion>
</AccordionGroup>

## Privacy

<AccordionGroup>
  <Accordion title="What does the dashboard send to PostHog?">
    Opt-in page-view events with route names that redact object ids and share tokens, plus a hashed SHA-256 user identifier. No run content, no API keys, no email, and no original Cloud user identifier are sent by WorldFlux. The PostHog request can still include normal network metadata such as IP address, user-agent, and referrer as handled by the analytics provider. Autocapture and session replay are disabled. Opt out from `Settings → Profile → Analytics opt-in`.
  </Accordion>

  <Accordion title="How do I export my data?">
    `Settings → Profile → Request export`. WorldFlux Cloud queues a job and emails a download link when the bundle is ready.
  </Accordion>

  <Accordion title="How do I delete my account?">
    Same panel: tick the confirmation box, click `Schedule deletion`. The account is removed on day 30. Cancel any time before then with `Cancel deletion`.
  </Accordion>
</AccordionGroup>