Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ in this repository. `CLAUDE.md` is a symlink to it.

`README.md` is for the person *using* the toolkit, who is not technical and
runs it from Goose or Claude Desktop. Keep it in plain words: what to ask for,
what is safe, how to set up once using what AAIF already has. Engine detail,
first-time setup (creating the Google client, Slack app and Luma key), adding
the next person and the standalone-zip list belong in `MAINTAINING.md`. `CONTRIBUTING.md` covers skill
what is safe, how to set up once, including creating their own Google connection
file and Slack and Luma keys. Engine detail, first-time setup (creating the Slack
app), adding the next person and the standalone-zip list belong in `MAINTAINING.md`. `CONTRIBUTING.md` covers skill
authoring; `DESIGN.md` covers how anything this repo renders for a human is
styled. This file is what those don't say.

Expand Down
8 changes: 5 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,11 @@ plugin version is mirrored in root `plugin.json` and `.claude-plugin/plugin.json
detail and the standalone-zip list moved to `MAINTAINING.md`
(`check_portable_skills.py` reads it there).
- **Setup instructions for both kinds of setup.** `MAINTAINING.md` walks the
first person through creating the Google client, Slack app and Luma key, and
lists what to do for each person after that. The README takes that next
person through everything else without a helper. `aaif-check-setup` now
first person through creating the Slack app, and lists what to do for each
person after that. The README takes that next person through everything else
without a helper, including creating their own Google connection file and
Slack and Luma keys, because operators can be in different organizations and a
Slack user token acts as whoever generated it. `aaif-check-setup` now
reports a missing Google connection file instead of recommending a sign-in
that cannot work.
- **`aaif-check-setup`** — "check my setup" runs a read-only ✅/❌ check of
Expand Down
111 changes: 51 additions & 60 deletions MAINTAINING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
[README.md](README.md) is for the person who *uses* the toolkit, written for
someone who is not technical. This file is for whoever keeps it running: how it
is built, what each engine does, how Google access is wired, and the setup that
happens once per organization, before anyone can follow the README.
happens once, before anyone can follow the README.

Packaged as a portable [Agent Plugin](https://agent-plugins.org) with plain
[Agent Skills](https://agentskills.io) so the same checkout works across Goose,
Expand All @@ -16,47 +16,19 @@ manifest is the root `plugin.json`. See [Using in other tools](#using-in-other-t

## First-time setup

Do this once per organization. It creates the three things every later operator
reuses: a Google connection file, a Slack token and a Luma key. Keep them in a
password manager, then follow the README's *Set up once* for yourself.

### Google connection file

Use the Google account that owns the toolkit. With `gcloud` installed,
`gws auth setup` can help with parts 1 and 2. It points you at External, so
still make the choice in part 3.

1. [Create a Google Cloud project](https://console.cloud.google.com/projectcreate)
named `aaif-toolkit`.
2. [Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com,sheets.googleapis.com,docs.googleapis.com,slides.googleapis.com,forms.googleapis.com):
Drive, Sheets, Docs, Slides and Forms.
3. [Set up the consent screen](https://console.cloud.google.com/auth/overview)
with the app name `AAIF Toolkit`. Choose **Internal** if every operator's
account is in this Workspace. Otherwise choose **External**, leave it in
testing mode, and add each operator under
[Audience → Test users](https://console.cloud.google.com/auth/audience).
Google [expires an External testing app's refresh tokens after 7
days](https://developers.google.com/identity/protocols/oauth2), so those
operators sign in again weekly.
4. [Create a client](https://console.cloud.google.com/auth/clients) of type
**Desktop app** and download its JSON. That file is the connection file. Keep
its name, because the README's move command looks for `client_secret*.json`.

| Google says | Cause |
|---|---|
| Access blocked | The account is not a test user on an External app |
| `redirect_uri_mismatch` | The client is not a **Desktop app**; make a new one |
| `accessNotConfigured` | An API in part 2 is not enabled |
Do this once. It creates the Slack app every operator gets their token from, and
checks the Luma calendar is ready. Then follow the README's *Set up once* for
yourself. Each person creates their own Google connection file and their own
Slack and Luma keys there.

### Slack token
### Slack app

It is a **user** token (`xoxp-`), not a bot token, because the creator of a
Each operator's token is a **user** token (`xoxp-`), not a bot token, because the creator of a
channel joins it and a bot would sit in every chapter room. So the token acts as
whoever installs the app: it sees what they see, and every room it creates adds
them. Its `search:read` scope also lets anyone holding it search that person's
DMs and private rooms, and its `chat:write` scope lets them post as that person.
So install it from a dedicated account with no personal DMs or private rooms if
you can.
So each person generates their own and never shares it.

1. Open [Slack's app page](https://api.slack.com/apps?new_app=1), choose
**From a manifest**, and pick the community workspace.
Expand Down Expand Up @@ -85,17 +57,15 @@ you can.
```

3. **Install to Workspace**, then **Allow**. A workspace may need an admin to
approve it first.
4. Under **OAuth & Permissions**, copy the **User OAuth Token**.
approve it first, under **Requested apps**. A custom app has no marketplace
listing, so its marketplace link shows an error.
4. Under **OAuth & Permissions**, copy your **User OAuth Token**.

`channels:join` is deliberately absent: Slack offers it to bot tokens only, and
a user token joins with `channels:write`. The write token runs both the audits
and the write steps; a token stored as `aaif-slack-read-token` alone runs the
audits but not provision, invite or the directory posts.

**Everyone shares this one token.** The next person gets it from an admin and
creates nothing.

**A personal, read-only alternative is the Slack CLI's own login.** Install the
[Slack CLI](https://docs.slack.dev/tools/slack-cli/), run `slack login`, paste
the `/slackauthticket ...` line it prints into any conversation in the workspace,
Expand All @@ -106,47 +76,68 @@ audits but not the activity or spam audits, or any write step. It has expired on
us before, and `aaif-check-setup` does not look there, so its Slack line stays
⚪ even when this token works. To replace an expired one, run `slack login` again.

### Luma key
### Luma calendar

The calendar needs Luma Plus, and keys are per calendar. In
[Luma](https://luma.com/home/calendars), open the calendar, then **Settings →
Developer → API Keys → Create**. Copy the key straight away, because Luma shows
it only once.
The calendar needs Luma Plus, and keys are per calendar. Each person creates their
own under **Settings → Developer → API Keys**.

## Adding the next person

The README's *Set up once* is written for this person, who doesn't need to be
technical. The request text in its step 3 is public, so a request proves nothing.
technical. The request text in its step 5 is public, so a request proves nothing.
When you get one:

1. **Confirm who is asking**, through a channel you already know, and that AAIF
has approved them as an operator.
2. **Share the Chapters folder and the Community Intake Ops sheet** with their
Google address, as an editor.
3. **External consent screen only:** add them as a test user.
4. **Send the connection file, Slack token and Luma key** through a password
manager or another private channel, never the assistant chat. Leave out
whatever they won't use.
Google address, as an editor. Across organizations, have them open both links,
because Workspace settings on either side can block the share.
3. **Add them as a collaborator on the Slack app**: on
[Slack's app page](https://api.slack.com/apps), choose the app, then
**Collaborators**. They must already be in the workspace. A collaborator can
change the app's settings, so add only approved operators.
4. **Add them to the private organizer rooms**, if they'll run the sync or the
Slack audits, and add an `Ops staff email` row for them on the `Slack Config`
tab so later provisioning runs seed them into new rooms. A user token only
sees private rooms its owner is in. Without this, the setup check shows ✅ but
those rooms read as missing: the audit aborts, invites skip them, and
provisioning plans creates that fail with `name_taken`.
5. **Add them as an admin of the Luma calendar.**

Leave out whatever they won't use.

They can then finish alone. `aaif-check-setup` ("check my setup") tells them
what is still missing.

## Removing a person

Everyone shares the same token and key, so the person keeps working access until
you replace them:

1. Remove their Drive shares and, on an External consent screen, their test user.
2. Under the Slack app's **OAuth & Permissions**, revoke the token and reinstall
the app. In Luma, delete the key and create a new one.
3. Send the new token and key to everyone who remains. They update the same
Keychain items.
1. Remove their Drive shares.
2. Remove them from the Slack app's **Collaborators**, then end their token. It
stays live until someone does, because only they hold it:
- Ask them to revoke it, if you trust them to.
- If they're leaving the workspace, removing them ends it.
- Otherwise revoke all of the app's tokens on the app's settings page. Every
operator then creates a new one (README step 5).
3. Remove their `Ops staff email` row and take them out of the private organizer
rooms.
4. Remove them from the Luma calendar and delete the key named after them under
**Settings → Developer → API Keys**.

Also replace any token or key they received from someone else. A token that was
ever passed around still acts as whoever created it.

## What setup relies on

- **`gws` must be installed before the assistant app opens**, or its shell will
not see the binary (`aaif-check-setup` says "installed but this app cannot see
it").
- **Each person creates their own connection file** because an Internal client
only works inside one organization, and an External one in testing mode needs
every user added and
[expires refresh tokens after 7 days](https://developers.google.com/identity/protocols/oauth2).
With `gcloud` installed, `gws auth setup` can help with the project and
services, but it points at External. The README's move command looks for
`client_secret*.json`, so the file keeps its downloaded name.
- **The connection file lives at `~/.config/gws/client_secret.json`.** Without
it and without a sign-in, a Drive call answers 401 on a clean machine, and
"insufficient authentication scopes" where gcloud credentials exist. Both look
Expand Down
109 changes: 80 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,9 +98,9 @@ message about a sign-in, token, key or missing tool.

## Set up once

AAIF's Google connection, Slack app and Luma key already exist, so you only
connect to them. This takes about 20 minutes and you don't need to be technical.
If nobody at your organization has set the toolkit up yet, start with
This takes about 30 minutes and you don't need to be technical. You create your
own Google connection and your own Slack and Luma keys. AAIF's Slack app already
exists. If nobody has set it up yet, start with
[first-time setup](MAINTAINING.md#first-time-setup).

To write posts, bios, invites and recaps, you only need steps 1 and 2.
Expand Down Expand Up @@ -136,18 +136,24 @@ toolkit updates itself from then on.
click **Sync**.
4. Under **Discover**, find **aaif-events** and click **Add**.

### 3. Ask AAIF for your access

Only AAIF can give you these, and you only ask once. Send this to an AAIF admin,
outside the assistant chat:

> I'm setting up the AAIF toolkit. My Google address is ___. Please send me the
> Google connection file, the Slack token and the Luma key privately, and give
> me edit access to the Chapters folder and the Community Intake Ops sheet.

Leave out Slack or Luma if you won't use them. You need the Slack token to run
the sync, the Slack audit or the community update. Without a Luma key, the
toolkit gives you event-page text to paste into Luma by hand.
### 3. Create your Google connection file

Sign in to Google with your AAIF account first. Each person makes their own file,
because it can be limited to one organization.

1. [Create a project](https://console.cloud.google.com/projectcreate) named
`aaif-toolkit`. It's free. If Google won't let you, ask your organization's
Google admin to allow it.
2. [Turn on the Google services](https://console.cloud.google.com/flows/enableapi?apiid=drive.googleapis.com,sheets.googleapis.com,docs.googleapis.com,slides.googleapis.com,forms.googleapis.com)
the toolkit uses. Check that `aaif-toolkit` is the selected project.
3. [Set up the sign-in screen](https://console.cloud.google.com/auth/overview):
name it `AAIF Toolkit`, use your own email address, and choose **Internal**.
If Internal isn't offered, choose **External** and add yourself as a test user
on the [Audience page](https://console.cloud.google.com/auth/audience). With
External, Google asks you to sign in again about every 7 days.
4. [Create a client](https://console.cloud.google.com/auth/clients), choose
**Desktop app**, then **Download JSON**. Leave the file in Downloads and don't
rename it. Keep it private.

### 4. Connect Google

Expand All @@ -163,9 +169,8 @@ by a third party, not by Google or AAIF.
If Terminal says `command not found: brew`, go to [brew.sh](https://brew.sh),
paste the line on that page into Terminal, and follow the "Next steps" it
prints at the end. Then run the line above again.
2. Take the Google connection file only from the admin you asked in step 3, and
save it to your **Downloads** folder without renaming it. Then run this in
Terminal:
2. Move your Google connection file into place by running this in Terminal. Only
use a file you downloaded yourself in step 3, never one someone sends you.

```bash
mkdir -p ~/.config/gws && mv ~/Downloads/client_secret*.json ~/.config/gws/client_secret.json && chmod 600 ~/.config/gws/client_secret.json && echo Done
Expand All @@ -179,16 +184,49 @@ by a third party, not by Google or AAIF.
3. Quit your assistant completely (⌘-Q), open it again, and ask it to *"check
my setup and sign me in to Google"*. A browser window opens. Sign in with
your AAIF Google account. If Google warns that the app isn't verified, click
**Advanced**, then continue. The screen must name **AAIF Toolkit**. If it
names anything else, stop and tell an AAIF admin. Otherwise, allow everything
it asks for.
**Advanced**, then continue. The screen must name **AAIF Toolkit**, the name
you gave it in step 3. If it names anything else, stop and ask an AAIF admin.
Otherwise, allow everything it asks for. If the check then says this account
can't open the Community Intake sheet, that's expected until you finish step 5,
so don't sign in again.

Only approve a Google sign-in that you started from your assistant, whoever
sends you a link.

### 5. Save your Slack and Luma keys
### 5. Get your access and create your keys

Only AAIF can give you access, and you only ask once. Send this to an AAIF admin:

> I'm setting up the AAIF toolkit. My Google address is ___. Please give me edit
> access to the Chapters folder and the Community Intake Ops sheet, add me as a
> collaborator on the AAIF Slack app and to the private organizer rooms, and give
> me admin access to the AAIF Luma calendar.

Leave out Slack or Luma if you won't use them. You need a Slack token to run the
sync, the Slack audit or the community update. Without a Luma key, the toolkit
gives you event-page text to paste into Luma by hand.

Save each key in your Mac's Keychain, *not* in the assistant chat, because the
**Create your Slack token.** It acts as you and can read what you can, including
your DMs, so keep it to yourself.

1. Open [Slack's app page](https://api.slack.com/apps) and choose the AAIF app.
2. Open **OAuth & Permissions**, click **Install to Workspace** or **Reinstall to
Workspace**, then **Allow**.
3. Copy the **User OAuth Token**. It starts with `xoxp-`.

Your token only sees private rooms you're in. If the sync or a Slack audit says
organizer rooms are missing, don't approve creating them. Ask an AAIF admin to
add you to those rooms, then run it again.

**Create your Luma key.**

1. On your [calendars page](https://luma.com/home/calendars), open the AAIF
calendar.
2. Open **Settings → Developer**. Under **API Keys**, click **Create** and name it
after yourself.
3. Copy the key straight away, because Luma shows it only once.

**Save each key** in your Mac's Keychain, *not* in the assistant chat, because the
chat keeps everything you type.

1. Open **Keychain Access**. Press ⌘-Space and type "Keychain Access".
Expand All @@ -203,6 +241,10 @@ chat keeps everything you type.
4. Click **Add**. The first time a job uses the key, your Mac asks whether
to allow it. Click **Always Allow**.

To replace a key later, don't add a second item with the same name. Double-click
the existing item in Keychain Access, tick **Show password**, paste the new key
and click **Save Changes**.

### 6. Check it

Ask your assistant to **"check my setup"**. Each ❌ line comes with what to do
Expand All @@ -221,17 +263,26 @@ does too.
or a sign-in that can't be read): say *"sign me in to Google again"*. The
setup check has given the assistant the exact sign-in to use. A browser
opens; sign in with your AAIF Google account and allow everything it asks
for. Then check your setup again. If the line says the connection file is
missing, signing in can't work yet, so do step 4 of *Set up once* instead.
for. Then check your setup again. If the line says this account can't open
the Community Intake sheet and you haven't finished step 5, do that first. If
the line says the connection file is
missing, signing in can't work yet, so do steps 3 and 4 of *Set up once*
instead.
3. **"Installed but this app cannot see it":** quit the assistant
completely (⌘-Q) and open it again.
4. **The assistant seems to be guessing or doing it differently each time:**
name the job, e.g. *"use the aaif-recap-post skill"*. Typing `/` in
Claude Desktop lists every skill.
5. **Google says "Access blocked" when you sign in:** ask an AAIF admin to add
your address as a test user.
6. **Google asks you to sign in again about once a week:** that can be normal
for AAIF's connection. Say *"sign me in to Google again"*.
5. **Google shows an error:**
- *"Access blocked" when you sign in:* if you chose Internal, sign in with the
account that created the file. If you chose External, add yourself as a test
user (step 3, part 3).
- *`redirect_uri_mismatch` when you sign in:* your client isn't a **Desktop
app**. Create a new one and move it into place (step 3, part 4, and step 4).
- *The setup check says a Google service is turned off:* turn them on (step 3,
part 2). Signing in again won't fix this.
6. **Google asks you to sign in again about once a week:** that's normal if you
chose External in step 3. Say *"sign me in to Google again"*.
7. **Still stuck:** copy the last message the assistant showed you (it never
includes your keys) and send it to an AAIF admin.

Expand Down
Loading
Loading