# Sograyim for Google Docs — limited beta (pre-Marketplace)

**Status: invite-only beta. Not available as a public install link.** There is no Google
Workspace Marketplace listing yet, and this document does not create one — it describes the
strongest safe path that already exists today, confirmed against the real project configuration
(`addin/google-docs/.clasp.json`, `appsscript/appsscript.json`): a standalone Apps Script project
(script ID `1LltNsUogPYSIDJKRsMjCHvmyTraxjODb75-FbhwsaWSpbrjlOKpthD4U`) with two narrow OAuth
scopes (`documents.currentonly`, `script.container.ui` — it can only read/write the one document
the user is actively working in, and show its own sidebar; nothing broader).

## The one real option before Marketplace publication: a Google-supported *test deployment*

Apps Script supports adding specific Google accounts as testers on a **test deployment**, without
publishing anywhere public. A tester:

- Needs **no developer tools** — no `clasp`, no Node, no source code, no Apps Script editor access.
- Opens the add-on the same way a published add-on would open, once added as a tester and once
  they've accepted the project's OAuth consent screen (which will show as "unverified app" until a
  real Marketplace review happens — expected and safe for a small, known beta list, but it is the
  one thing that will look alarming to a non-technical tester if nobody warns them first).

This is categorically different from, and safer than, giving someone `clasp clone` + editor access
to the script project — **editor access exposes the full source code** of `core/` (shared with the
Word add-in) and must never be handed to an ordinary tester. If a different collaborator genuinely
needs to *edit* the project, that is a separate, explicit decision — not something this beta process
grants by default.

## Owner checklist — onboarding one tester

1. Open the Apps Script project: `clasp open` (from `addin/google-docs/`, with your own
   authenticated `clasp login` — this step is for the project owner only).
2. In the Apps Script editor: **Deploy → Test deployments**.
3. Under "Testers," add the tester's Google account email address (a personal Gmail address or a
   Google Workspace account both work — see the compatibility note below).
4. Send the tester:
   - A link to open **any Google Doc** they own or can edit.
   - The instructions below (copy as-is or link to this file).
5. Confirm with the tester, on their first real use, that the sidebar actually opens and a known
   test citation (e.g. `{דברים י,יב}`) resolves — this is the one thing that can't be verified from
   the owner's side alone, since the add-on runs in the tester's own Google account context.
6. Record who was added as a tester and when (there is no existing tracking mechanism for this in
   the repo — a simple dated list in this file, appended as testers are onboarded, is enough).

## Tester instructions (send as-is)

1. Open any Google Doc.
2. **Extensions → Add-ons → Get add-ons** will not show this add-on (it isn't published) — instead,
   it should already appear directly under **Extensions** once you've been added as a tester and
   opened the document at least once since. If it does not appear, tell the project owner — you may
   need to be re-added or the deployment may need refreshing.
3. The first time, Google will show a permissions screen naming this project and its two scopes
   (read/write the current document; show a sidebar). It will likely say **"unverified"** — that is
   expected for a pre-Marketplace beta, not a sign something is wrong. Approve it to continue.
4. A menu item opens the sidebar. Type a source reference like `{דברים י,יב}` in the document and
   use the sidebar's scan/insert flow, exactly as in the Word add-in.
5. License activation and AI-provider setup work the same way as the Word add-in (same shared
   licensing client) — see `customer-installation-guide.he.md` / `.en.md` for that part.

## Google account / domain compatibility

- Works with a personal Google account or a Workspace account, **provided the tester's own
  Workspace admin hasn't blocked installing/running unverified/unpublished Apps Script add-ons** —
  some managed Workspace domains restrict this by policy. If a tester's add-on never appears or the
  consent screen is blocked outright with an admin-policy message, that is their domain's add-on
  policy, not a bug in this project — there is no workaround available to us, and it's required
  reading for anyone trying to onboard a tester on a managed work account.

## Updating and retesting

- Any code change: `cd addin/google-docs && npm run push` (builds, then `clasp push`) updates the
  live script project immediately — the next time any tester opens the sidebar, they get the new
  version with no reinstall, exactly as documented in `docs/how-updates-work.md`.
- A **new OAuth scope** (if `appsscript.json`'s `oauthScopes` ever grows) requires every tester to
  re-approve a new consent screen the next time they open the add-on — not a reinstall, but worth
  warning testers about in advance so it doesn't look like a problem.

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| Add-on doesn't appear under Extensions at all | Tester wasn't added under Deploy → Test deployments, or hasn't reopened a document since being added |
| Consent screen blocked by the account's admin | Workspace domain policy blocks unverified/unpublished add-ons — ask the tester's admin, not fixable from this project |
| Sidebar opens but citations never resolve | Same Sefaria/AI/licensing issue classes as the Word add-in — see the shared troubleshooting in `customer-installation-guide.he.md` |

## Removal

Remove the tester's email from Deploy → Test deployments → Testers. There is nothing to uninstall
on the tester's side beyond that — Apps Script add-ons aren't installed into the browser or Google
account the way a browser extension is; removing test-deployment access simply stops it from
appearing in Extensions on their next document open.

## What this is *not*

- Not a public install link. Do not share the script ID, the `clasp open` editor URL, or this
  document's existence outside a short, known beta list.
- Not a Marketplace submission, OAuth-verification change, or account-ownership change — none of
  those happen as part of this beta process.
- Not equivalent to the Word add-in's "upload a manifest file" path — there is no file for a Google
  Docs tester to download and install; access is granted entirely through the tester-email step
  above.