# ALU Knowledge-Base Sheet Workflow

This is the one-page guide for everyone whose name shows up in the
"Data Provision Workplan" tab — Registrar, Wellness Center, SPD, Student Life,
Library, BEL, BSE, AO, FO, RO, ALUSIVE, Tech, FABLab, ALUSB, SOWC, CEL, CRA.

The Student Companion chatbot reads from the Google Sheet directly. You
edit the sheet, the chatbot reflects your edits — no developer in the loop.

## How updates flow

```
You edit a cell in the sheet
        │
        ▼
Apps Script onEdit trigger pings the chatbot backend
        │
        ▼
Backend re-fetches the sheet as JSON and updates its knowledge index
        │
        ▼
Within a few seconds, the next student question sees your update
```

A safety net poll also runs every 15 minutes. So worst case (e.g. the
backend was asleep when you edited), the change is live within 15 minutes.

## Editing rules

1. **Don't rename the tabs.** Tab names are wired into the backend. If you
   need a new tab, see "Adding a new tab" below.
2. **Don't change column headers.** The first row of each tab is read as the
   schema. Renaming `Resource` to `Resources` will silently drop those rows.
3. **One concept per row.** Each row becomes one citation in the chatbot's
   answer. A row that crams three policies together will be cited as one
   blob.
4. **Always include a link if you have one.** The `Link` column is what
   becomes the citation URL in the chatbot's answer. No link → no clickable
   citation.
5. **No student PII.** Names, emails, phone numbers of individual students
   must never appear in the sheet. Staff names/contacts that are already
   public (e.g. published on alueducation.com) are fine.
6. **Keep `Last Updated` honest** (when the column exists). It helps us
   audit which content is going stale.

## What the chatbot will and won't do

- ✅ Answer **from your row**, using the wording in the `Content` /
  `Description` cell.
- ✅ **Cite your `Link`** as a markdown link.
- ✅ **Refuse to answer** if your tab doesn't have the info — it will say
  "I don't have that" rather than invent a number, date, or policy.
- ❌ It does **not** add commentary or speculate beyond what's in the row.

So: if you want students to know something, write it plainly in the row.
If you want them sent to a specific page, put that page in the `Link` column.

## Verifying your edit landed

1. After saving an edit, wait 15 seconds.
2. Visit
   `https://<the-backend-space-url>/api/admin/sheet-status`
   in a browser. You'll see a JSON response with:
   - `last_result.fetched_at` — should be within the last minute
   - `by_department` — a count per department. If your department's
     count went up after you added a row, your edit landed.
3. Open the live chatbot and ask a question whose answer is in the row
   you just edited. It should answer from your row and cite your link.

If something looks wrong, ping the dev team with the row number — the
sheet syncer logs the row number alongside every entry it indexes.

## Adding a new tab

This is the only change that needs a small one-line edit by the dev team,
**but**: the change is in the Apps Script attached to the sheet, **not** in
the chatbot code. So it's still a 30-second change with no redeploy.

1. Create your tab in the sheet. First row = column headers.
2. Open **Extensions → Apps Script** in the sheet.
3. Find the `TAB_CONFIG` block near the top of `Code.gs`.
4. Add one line, e.g.:
   ```js
   "Wellness": {
     department: "Wellness Center",
     category: "Support",
     columns: { "topic": "title", "details": "content", "link": "source_url" }
   },
   ```
   The keys on the right (`title`, `content`, `source_url`, `category`,
   `last_updated`) are the semantic fields the chatbot understands. The keys
   on the left are **your** column headers, case-insensitive.
5. Save the Apps Script. Edit any cell to fire the onEdit trigger, or wait
   15 minutes for the poll.

## Removing a row

Delete the row in the sheet. On the next sync, the chatbot will drop that
entry from its index. (It detects this by diffing the current sheet against
what it had before.)

## Token rotation

The Apps Script ↔ backend ping is authenticated with a shared token,
stored in:

- **Apps Script:** Project Settings → Script Properties →
  `BACKEND_REFRESH_TOKEN`
- **Backend (HF Space):** the `SHEET_REFRESH_TOKEN` environment variable

If you rotate one, rotate both. (Until then, the 15-minute poll still
works — it doesn't need the token.)

## Who to ping

| Symptom                                                  | Contact      |
|----------------------------------------------------------|--------------|
| My row isn't showing up in chatbot answers               | Dev team     |
| The chatbot is citing an outdated link                   | Tab owner    |
| I need a new tab / column                                | Dev team     |
| The chatbot is hallucinating a policy that isn't in the sheet | Dev team — this is a regression to file |