# Troubleshooting and FAQ



## It isn't responding [#it-isnt-responding]

| Symptom                                                   | Cause                                                                        | Fix                                                                                            |
| --------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| No 👀, no reply, nothing                                  | It isn't in the channel                                                      | `/invite @Surface Marketing Agent`                                                             |
| 👀 appears, then a Connect card                           | Surface isn't connected, or the grant expired                                | Click **Connect Surface**. `/surface status` confirms                                          |
| *"In this channel I only take questions from the … team"* | A [Slack Connect channel](/docs/sam/shared-channels) that hasn't been opened | Someone at the installing workspace runs `/surface shared open`, or ask in an internal channel |
| *"This workspace has hit today's question limit"*         | 200 questions in 24 hours                                                    | Wait for the rolling window, or ask a Surface admin to raise it                                |
| 👀 but silence on a thread reply                          | It judged the message wasn't for it                                          | Working as designed. @-mention it to be sure                                                   |

## The answer wasn't what I wanted [#the-answer-wasnt-what-i-wanted]

| Symptom                                      | What's going on                                                | Fix                                                                                           |
| -------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| The draft reads generic                      | It found no voice rules, and it will have said so in one line  | Tell it your voice rules once (*"remember: …"*), or point it at a Vault doc, then re-ask |
| It ranked on pageviews, you wanted pipeline  | Sometimes the pipeline metric really is flat, and it'll say so | Ask for the metric by name: *"rank by meetings booked"*                                  |
| It asked which form you meant                | No form matches the name you used                              | Use the exact name from Surface, or pick from the list it offered                             |
| It gave totals, you wanted a rate or a trend | It answers what was asked, literally                           | Ask for *"the rate, and the week-over-week change"*                                      |
| It stopped halfway through something big     | Hit the step or cost ceiling                                   | Click **Run it in the background**, or narrow the range                                       |
| It's off down the wrong path and still going | A turn that has gone somewhere nobody wants                    | Hit **Stop** on the status line. Nothing is changed by a stopped turn                         |
| It got something wrong                       | It happens                                                     | Correct it in the thread. Corrections are saved to [memory](/docs/sam/memory)                 |

## Files [#files]

* **"Couldn't read \[file]"**: it names what it skipped and why. `.xlsx`, PDFs
  and Slack Lists aren't readable; export to CSV.
* **More than 8 images**: it reads 8 and names the rest. Split into two
  messages.
* **A file from earlier in the thread**: still works. Just refer to it.

## FAQ [#faq]

<AccordionGroup>
  <Accordion title="Can it see all our Slack messages?">
    It reads the thread you're in, or the current channel's recent history if
    you ask it to. It is not indexing your Slack.
  </Accordion>

  <Accordion title="Does everyone in the workspace share one memory?">
    Yes, that's the point. Channel-scoped notes exist for project-specific
    context.
  </Accordion>

  <Accordion title="Can it change our data without asking?">
    No. Every change is an approval card. Background jobs are read-only
    entirely.
  </Accordion>

  <Accordion title="Who can approve a change?">
    Whoever asked for it, or any Slack workspace admin.
  </Accordion>

  <Accordion title="Why is it asking me to rate an answer?">
    Roughly one answer in five carries 👍 / 👎 and a *saved 5m · 30m · 2h* row.
    It's sampled deliberately, because buttons under every answer read as being
    asked to rate a conversation.
  </Accordion>

  <Accordion title="How do I keep a good answer?">
    If it's a document rather than a number, a **Save in Vault** button appears
    under it. One click files it in your Surface Vault as a dated Markdown doc
    under `slack/`, and it reads its own Vault before drafting, so saving
    compounds. Anyone in the workspace can click it; it only ever creates, never
    overwrites.
  </Accordion>

  <Accordion title="Why does it write so little?">
    60 words by default, on purpose. Drafts, digests and scheduled posts are
    exempt: ask it to write something and it writes the whole thing.
  </Accordion>

  <Accordion title="Can we point it at a different Surface environment?">
    `/surface disconnect`, then connect again and pick.
  </Accordion>

  <Accordion title="Does it work in private channels?">
    Yes. Invite it.
  </Accordion>

  <Accordion title="What happens if we uninstall?">
    It stops immediately. Install history is kept for support; reinstalling
    restores the workspace.
  </Accordion>
</AccordionGroup>