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

# Slack

> How teams request governed work and review pending writes from Slack.

Slack is a conversational interface to the Polycore catalog. A teammate can ask
for an operational read in plain language, request a known action, and review a
pending write without receiving the credentials behind any of them.

<Info>
  Slack setup is part of assisted onboarding. Polycore provisions the
  installation, maps the workspace to your organization, and validates identity
  and approval behavior with your team.
</Info>

## Request flow

```mermaid theme={"system"}
sequenceDiagram
  participant U as Teammate in Slack
  participant S as Polycore Slack app
  participant C as Control plane and agent
  participant R as Customer-hosted runner

  U->>S: Mention Polycore in a channel or thread
  S->>C: Workspace, user, thread, and message
  C->>C: Resolve organization and connected catalog
  C->>R: Signed read dispatch
  R-->>C: Structured result
  C-->>S: Grounded response
  S-->>U: Reply in the Slack thread
```

The control plane resolves the Slack workspace and user before starting an
agent turn. The agent sees only the capabilities advertised by connected
runners in scope.

## Assisted setup

<Steps>
  <Step title="Connect the Slack workspace">
    We provision the Polycore Slack installation for the selected workspace and
    map its Slack team identity to your Polycore organization.
  </Step>

  <Step title="Map people and roles">
    We connect Slack identities to Polycore users and agree which people should
    be able to request work and review pending writes.
  </Step>

  <Step title="Choose channel scope">
    Your team decides where Polycore should be used, which channels may contain
    operational data, and whether the app should be invited only when needed.
  </Step>

  <Step title="Validate reads">
    A teammate asks a real question. We confirm project and environment routing,
    runner execution, a useful reply, and caller attribution.
  </Step>

  <Step title="Validate approval">
    A representative `write` action produces an approval card. We test approval,
    denial, stale decisions, and the final audit record.
  </Step>
</Steps>

## Reads

A Slack read can use a built-in query or a named read action.

```text theme={"system"}
@Polycore how many active accounts were created this week?
```

The agent may need several governed invocations to answer. For example, it can
inspect a Postgres schema, describe the relevant table, and then run an
aggregate query. Those invocations remain grouped under the one Slack request.

<Note>
  A read does not require human approval, so least-privilege datastore access
  matters. Limit the catalog and downstream identity to data that the intended
  Slack audience may retrieve.
</Note>

## Writes and approval cards

When the agent requests a capability marked `write`, the control plane stops
before runner execution and creates a pending approval.

An approval surface identifies:

* The requested capability.
* Project and environment.
* Schema-validated arguments.
* The requesting Slack user.
* The pending request id and current status.

A linked human with the required organization role can release the invocation.
The agent is not given an approval tool.

The card asks a specific human to decide. Because only a Slack mention notifies
anyone, it `@`-mentions owners and admins whose Slack account is linked to
Polycore, up to three, and counts the rest so a long admin list cannot become a
mass ping. An owner or admin with no linked Slack account is named on the card
but is not notified.

<Note>
  The current Slack path checks that the clicking human is an organization owner
  or admin. It does not require the approver to be a different person from the
  original requester, so an owner or admin may approve their own Slack-initiated
  write. When the requester can already approve, the card asks them to decide
  and notifies nobody else.
</Note>

Deciding leaves the card in place: the request, arguments, and any review link
stay readable, the buttons are removed so the decision cannot be replayed, and
the decision is recorded beneath it.

<Tabs>
  <Tab title="Approve">
    Polycore atomically records the decision, dispatches the exact pending
    invocation to the runner, and posts a plain-language summary of the outcome
    back to the request thread (falling back to a compact result preview if
    summarization is unavailable).
  </Tab>

  <Tab title="Deny">
    Polycore records the denial and closes the request without sending an
    executable write dispatch to the runner.
  </Tab>

  <Tab title="Already decided">
    A repeated click cannot execute the same invocation a second time. The
    approval store accepts one transition out of pending state.
  </Tab>
</Tabs>

## Conversation context

Polycore groups related Slack messages by thread. Prior request and answer pairs
can be supplied to later agent turns within a bounded context budget, so a
follow-up such as "and in production?" can retain the meaning of the previous
question.

<Warning>
  Treat Slack as a destination for operational data. Query results and agent
  answers may contain customer information even though execution credentials
  never reach Slack. Use appropriate channels and design capabilities to return
  only the fields people need.
</Warning>

## Failure behavior

The agent should not fabricate a result when:

* No runner is connected for the selected environment.
* A user or workspace is not mapped.
* A capability is unavailable.
* A datastore permission or index is missing.
* The runner or downstream system returns an error.
* A write is still pending or has been denied.

Polycore reports the blocking condition in the thread and records the failed or
pending invocation where applicable.

## Operational boundaries

<AccordionGroup>
  <Accordion title="Which Slack messages start an agent turn?" icon="at-sign">
    The app responds to its configured mention and thread flow. It is not meant
    to ingest every message in a workspace.
  </Accordion>

  <Accordion title="Can Slack receive a database credential?" icon="key-round">
    No. The credential is resolved on the runner host. Slack receives only the
    request, approval presentation, and final response chosen for that
    conversation.
  </Accordion>

  <Accordion title="Can the Slack agent approve its own write?" icon="bot-off">
    No. The catalog exposes operational capabilities to the agent, not an
    approve or deny capability.
  </Accordion>

  <Accordion title="Can one request touch more than one environment?" icon="split">
    The agent can make separate governed invocations when the request requires a
    comparison. Each invocation records its own target runner and environment
    under the same user-facing request.
  </Accordion>
</AccordionGroup>

## Production validation

<Check>
  Linked users can request reads and unlinked identities fail before agent
  execution.
</Check>

<Check>
  Default and explicitly named environments route to the intended runners.
</Check>

<Check>
  Follow-up messages in one thread retain bounded conversation context.
</Check>

<Check>
  A write cannot execute before a human decision and a denial causes no
  downstream change.
</Check>

<Check>
  Slack responses avoid fields your channel audience should not receive.
</Check>

<Check>
  Requests, capability invocations, and approval decisions are attributed in the
  shared audit model.
</Check>