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

# FAQ & Troubleshooting

> Answers to the most common questions and step-by-step fixes for known issues.

# FAQ & Troubleshooting

***

## Setup & Permissions

<AccordionGroup>
  <Accordion title="Why can't WardForge create the Guardian-Quarantine role?">
    This happens when WardForge's own role is **below** the position it needs to manage. Discord
    requires a bot's role to be **higher in the hierarchy** than any role it creates or assigns.

    **Fix:**

    1. Go to **Server Settings → Roles**
    2. Drag the **WardForge** role to the **top of the list** (or at least above all roles
       it needs to manage)
    3. Run `/guardian doctor` — it will confirm the hierarchy is correct

    <Warning>
      Even with Administrator permission, Discord enforces role hierarchy for role management.
      Administrator does not bypass this restriction.
    </Warning>
  </Accordion>

  <Accordion title="WardForge says it's missing the 'Ban Members' permission but I gave it Administrator.">
    This is usually a **channel-level permission override** that's blocking WardForge in a specific
    channel. Administrator grants server-wide permissions, but individual channel overrides can
    deny permissions even for admins.

    **Fix:**

    1. Go to the channel where WardForge is being blocked
    2. Open **Channel Settings → Permissions**
    3. Find WardForge's role and remove any explicit **Deny** overrides
    4. Run `/guardian doctor` again
  </Accordion>

  <Accordion title="The /setup command never completes — it just shows 'thinking...'">
    WardForge timed out, usually because:

    * It lacks permission to create channels or roles
    * The Discord API is slow (retry in a few minutes)
    * A name conflict exists (a role named `Guardian-Quarantine` already exists with wrong settings)

    **Fix:**

    1. Delete any existing `Guardian-Quarantine` role and `#guardian-logs` channel if they exist
    2. Confirm WardForge has **Administrator** permission
    3. Try `/setup` again
  </Accordion>
</AccordionGroup>

***

## Anti-Raid & Quarantine

<AccordionGroup>
  <Accordion title="A legitimate new member was quarantined — how do I release them quickly?">
    Open `#guardian-logs` (or your configured log channel). The quarantine notification embed has a
    **"✅ Release Quarantine"** button — click it to immediately remove the quarantine role.

    Alternatively, any staff member with **Manage Roles** can run:

    ```
    /quarantine release @member
    ```

    <Tip>
      Consider pinning a message in your general channel explaining that accounts less than 24 hours
      old will briefly be in quarantine. This reduces confusion for legitimate new users.
    </Tip>
  </Accordion>

  <Accordion title="My server had a giveaway and WardForge locked it during the surge of new members.">
    Events that attract many new members (giveaways, collaborations, going viral) can trigger raid
    detection. To prevent this:

    **Before the event:**

    ```
    /antiraid mode monitor
    ```

    This keeps all detection and logging active but **never auto-locks** — staff are alerted but
    the server stays open.

    **After the event:**

    ```
    /antiraid mode auto
    ```

    Restore full automatic protection once the influx normalizes.
  </Accordion>

  <Accordion title="The Guardian-Quarantine role exists but quarantine isn't working.">
    Two common causes:

    1. **Role hierarchy** — `Guardian-Quarantine` must be **above** your default member role so it
       can override channel access. If it's below `@everyone`, it has no effect.
    2. **Channel permission overrides** — if channels explicitly grant `@everyone` permission to
       view/send, the quarantine role can't override it.

    Run `/guardian doctor` for an automatic diagnosis and specific fix instructions.
  </Accordion>
</AccordionGroup>

***

## Anti-Phishing & /report

<AccordionGroup>
  <Accordion title="I submitted a /report but nothing happened.">
    Check the following:

    1. **TrustScore** — you need a minimum score of 20 to submit reports. Run `/trustscore @yourself`
       to check your score.
    2. **Cooldown** — there's a 10-minute cooldown between reports. Wait and try again.
    3. **Already blacklisted** — if the target is already in the Global Blacklist, you'll see the
       existing record instead of a new report being created. This is expected behavior.
    4. **No report channel configured** — if `/report-config set-channel` was never run, reports
       go to `#guardian-logs` by default. Check that channel.
  </Accordion>

  <Accordion title="WardForge deleted a legitimate link posted by a member.">
    WardForge may have flagged the domain as phishing in one of the three databases. To whitelist it:

    ```
    /antiphishing whitelist add your-domain.com
    ```

    If you believe this is a **false positive in the database itself**, you can report it directly
    to [PhishTank](https://phishtank.org) or [Google Safe Browsing](https://safebrowsing.google.com/safebrowsing/report_error/).

    <Note>
      WardForge respects the whitelist immediately — no restart required.
    </Note>
  </Accordion>

  <Accordion title="Can a member abuse /report to target someone?">
    WardForge has multiple layers of anti-abuse protection:

    * **TrustScore ≥ 20** — new or low-trust accounts can't submit reports
    * **10-minute cooldown** — prevents rapid-fire false reports
    * **Link scan requirement** — auto-bans only trigger when a link is **confirmed in a phishing
      database**, not on user accusation alone
    * **Staff review** — unconfirmed reports always go to staff; WardForge never auto-bans based
      solely on a member's text description

    A member cannot get someone banned simply by reporting them — there must be a confirmed
    malicious link or staff authorization.
  </Accordion>
</AccordionGroup>

***

## Backup & Restore

<AccordionGroup>
  <Accordion title="How do I restore a channel that was deleted by a compromised admin?">
    If WardForge detected the channel deletion, a **selective restore button** was automatically
    posted to `#guardian-logs` within seconds of the deletion. Click **"Restore Channels"** in
    that embed.

    If the automatic restore button is no longer available (more than 60 minutes have passed):

    ```
    /backup list           # Find the most recent snapshot before the deletion
    /backup restore <id>   # Restore from that snapshot
    ```

    <Warning>
      Restoring a full backup will recreate channels and roles from the snapshot. **Messages are not
      restored** — only the server structure (channels, categories, roles, permissions).
    </Warning>
  </Accordion>

  <Accordion title="I don't see /backup create — only /backup list.">
    You need **Administrator** permission to create backups. `/backup list` is available to anyone
    with **Manage Guild**. Check your role permissions.
  </Accordion>

  <Accordion title="How often should I create backups?">
    WardForge does not create automatic scheduled backups — you control when snapshots are taken.
    We recommend:

    * **After any major role/channel restructure** — create a labeled snapshot
    * **Before giving a new admin elevated permissions** — safety net in case of compromise
    * **Weekly** for active communities

    Free accounts have **3 backup slots**. Pro accounts have unlimited storage.
  </Accordion>
</AccordionGroup>

***

## Self-Hosting

<AccordionGroup>
  <Accordion title="Redis is failing its healthcheck after I set REDIS_PASSWORD.">
    The Docker healthcheck must authenticate with Redis. Confirm your `docker-compose.yml` uses:

    ```yaml theme={null}
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
    ```

    If it still uses `redis-cli ping` without `-a`, the check will fail because `requirepass` is
    enabled. Update your compose file and restart the Redis service:

    ```bash theme={null}
    docker compose restart redis
    ```
  </Accordion>

  <Accordion title="The bot starts but /setup fails with 'database not ready'.">
    PostgreSQL hasn't finished initializing when the bot starts. The `depends_on: condition: service_healthy`
    in `docker-compose.yml` should handle this, but if you're starting for the first time on a slow
    machine:

    ```bash theme={null}
    docker compose up db redis -d    # Start dependencies first
    sleep 10                         # Wait for PostgreSQL to initialize
    docker compose up guardian-bot -d
    ```
  </Accordion>

  <Accordion title="I changed .env but the bot isn't picking up the new values.">
    Docker Compose doesn't hot-reload `.env` changes. Restart the affected service:

    ```bash theme={null}
    docker compose up -d --force-recreate guardian-bot
    ```
  </Accordion>
</AccordionGroup>

***

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Discord Support Server" icon="discord" href="https://discord.gg/wardforge">
    Join our support server for real-time help from the team and the community.
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/your-org/wardforge/issues">
    Report bugs or request features on GitHub.
  </Card>
</CardGroup>