# Connect Chief Runtime to Slack

This step requires a desktop browser. Slack app creation and installation are
not supported reliably from a phone. The manifest is reusable and contains no
credentials.

## 1. Create the app from YAML

Open `https://api.slack.com/apps`, choose **Create an App**, then **From a
manifest**. Select the intended workspace, choose YAML, and paste this manifest:

```yaml
display_information:
  name: Chief Runtime
  description: Operator-controlled Chief Runtime for Slack
  background_color: "#2c2d30"
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: chief
    always_online: true
  slash_commands:
    - command: /chief
      description: Chief Runtime commands and maintenance conversation
      usage_hint: "help | status | doctor | request | lane | maintenance"
      should_escape: false
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - bookmarks:read
      - bookmarks:write
      - canvases:read
      - canvases:write
      - channels:history
      - channels:join
      - channels:read
      - chat:write
      - commands
      - emoji:read
      - files:read
      - files:write
      - groups:history
      - groups:read
      - im:history
      - im:read
      - im:write
      - lists:read
      - lists:write
      - mpim:history
      - mpim:read
      - pins:read
      - pins:write
      - reactions:read
      - reactions:write
      - search:read.files
      - search:read.public
      - search:read.users
      - team:read
      - usergroups:read
      - users.profile:read
      - users:read
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.channels
      - message.groups
      - message.im
      - message.mpim
      - reaction_added
  interactivity:
    is_enabled: true
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false
```

Review the generated summary, create the app, and install it to the selected
workspace. Reinstall after any later scope change.

The manifest enables App Home's Messages tab for two-way conversation and
intentionally supports ordinary reading and communication:
channel and DM history, files, canvases, lists, bookmarks, pins, reactions,
people lookup, search, message posting and editing, and joining public channels.
It deliberately omits workspace administration, billing, audit-log, retention,
identity/login, user-email, message-impersonation, private-channel management,
and blanket posting to public channels. Chief starts from first contact: invite
it to a channel or message/tag it; it is not licensed to broadcast into every
public channel.

## 2. Generate the Socket Mode token

In the app's **Basic Information** page, create one app-level token with only
the `connections:write` scope. This is the token Chief uses to open Socket
Mode. No public request URL is required.

The installed app also exposes its bot token under **OAuth & Permissions**.
Chief uses the bot token for the Web API. It never needs a user token. A test
driver may hold a user token outside the Chief machine, but do not put one in
Chief's config, environment, container, logs, or repository.

## 3. Establish first contact and record IDs

- Invite the bot to the reviewed control room.
- Open the bot's App Home and send it a message. Its Messages tab is enabled
  and writable by the manifest; this creates the operator DM without granting
  unsolicited reach.
- Record the operator user ID, bot user ID, control-room conversation ID,
  operator DM channel ID, and reviewed workspace URL. The control room may be
  a reviewed `C…` channel or the existing `D…` operator conversation with
  Chief. Channel and DM IDs appear in the
  corresponding Slack URL; user IDs are available from the person's profile.

Put the app-level and bot tokens in separate same-user files with mode `0600`.
Set the token-file paths and the recorded public IDs in Chief's config exactly
as shown in [the install guide](INSTALL.md). Never paste token values into the
TOML file.

## 4. Prove the connection

After the manual-mode review, select native services and apply setup:

```sh
chief setup --dry-run
chief setup
chief doctor --json
```

The final native setup opens the configured operator DM, sends one mechanical
welcome, and reads the exact message back. Re-running setup does not duplicate
it. Success ends with:

```text
HELLO\thello delivered to your DM — Chief is alive.
```

Hello failure is non-fatal to estate installation but is printed loudly with
Slack's exact error and a link back to this guide. Do not treat the install as
Slack-ready until the hello is visible and doctor reports Slack connected.