shard-wiki/research/260614-quip-deep-dive/findings.md

# Salesforce Quip — deep dive (findings)

**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T6 · **Subject:** Quip (Salesforce), a
collaborative-document SaaS.

## Why this dive

Notion (UC-57/58/59) gave us the closed-SaaS, external-REST-only, database-as-pages model.
Quip is the **enterprise document-collab** contrast: a **document+spreadsheet hybrid** where
a page is **prose interleaved with embedded live structured objects** (spreadsheets,
calendars, kanban "live apps"), reachable only through a REST API, gated by **Salesforce
identity**. The question: how does shard-wiki attach a shard whose "page" is a *mixed
prose+live-object document* behind enterprise auth?

## 1. The document + live-object model

- A Quip **document** is a real-time collaborative doc (concurrent editing). Its body is
  rich content — headings, lists, prose — **interleaved with embedded objects**:
  - **Spreadsheets** are *first-class, inline* — a doc can contain live spreadsheet sections
    with formulas, not just static tables.
  - **Live apps** (calendars, kanban boards, project trackers, polls) embed interactive
    structured widgets inside the document.
- **Folders** organize documents; **threads** (docs and chat are unified — every doc is also
  a conversation thread) carry **messages/comments** inline.
- So a Quip "page" is a **hybrid**: prose + embedded structured/live content in one
  document, with conversation attached. Not Markdown; a proprietary rich model.

## 2. The REST API (the only door)

Quip exposes a **REST API**: threads/documents (get, create, **edit-document** with an HTML
fragment + a location/section anchor), folders, messages, users, and spreadsheet cell
access. Content crosses the API as **HTML** (import and export) — there is **no native
Markdown** and no file/git access. Implications:

- **Import/export is HTML → lossy** to Markdown (like Notion's export, UC-59): embedded
  spreadsheets and live apps **do not round-trip** to Markdown cleanly — they degrade to
  tables or links.
- Editing is **section/anchor-scoped HTML splice** (`edit-document` targets a location) — a
  mid-granularity write (a section, not the whole doc, not a character).
- **Rate-limited** like any SaaS API; history is internal (revisions exist in-product, with
  limited API exposure).

## 3. Enterprise identity / permissions

Quip is tied to **Salesforce** (acquired 2016): authentication and access run through the
Salesforce org / Quip site; **folder and document sharing ACLs** govern visibility, with
enterprise SSO. So this is an **enterprise-ACL, authn-delegated** shard (UC-06) — shard-wiki
honors Salesforce-side permissions and never bypasses them.

## 4. Capability profile

| Dimension (synthesis spectrum) | Quip |
|--------------------------------|------|
| Attachment mode | **external-API** (REST; HTML import/export) — closed SaaS |
| Addressing granularity | document; **section/anchor** for edits; spreadsheet cell |
| Content identity | Quip thread/document ID (opaque) |
| Identity vs placement | API-id identity; folder placement separate |
| Structure | **hybrid doc**: prose + embedded spreadsheets + live apps + thread |
| History | **internal** revisions (limited API exposure) |
| Merge model | server-side real-time collab (OT-like); no external merge |
| Native query | none exposed (spreadsheet formulas internal) |
| Translation | **HTML** in/out → **lossy** to Markdown (spreadsheets/apps degrade) |
| Write granularity | **section/anchor HTML splice** (mid) |
| Operational envelope | rate-limited SaaS REST |
| Access grant | **Salesforce identity + folder/doc ACL** (enterprise SSO) |
| Content opacity | proprietary rich model; not E2EE but not transparent files |
| Provenance | author/edit metadata in-product; API-limited |

## 5. INTENT mapping

### Reinforcements

- **External-API attachment** (UC-57): Quip is a second concrete instance beside Notion of
  the closed-SaaS REST-only shard — generalizes the external-API mode (REST + HTML payload,
  vs Notion's REST + block-JSON, vs Wiki.js GraphQL).
- **Union without erasure / no silent flatten**: embedded spreadsheets and live apps must be
  **surfaced as what they are** with provenance, and the **HTML→Markdown lossiness made
  explicit** (UC-59) — never silently drop a live spreadsheet to a static table.
- **Authz-in-core, authn-delegated** (settled decision): Quip's Salesforce-tied ACL is the
  enterprise case — honor delegated identity and the shard's ACL (UC-06).
- **Graceful degradation**: with only a lossy HTML export, Quip is still usable as a
  read/projection/overlay-target/backup shard.

### Divergences (boundaries / notes)

- **Mixed prose+live-object page** is a content shape beyond "Markdown body + frontmatter":
  the page model must allow **embedded typed/live objects within a prose page** (not just a
  whole-page-is-a-record like Notion DB, but *inline* structured content) — feeds T12 and the
  non-Markdown-content question (UC-55).
- **HTML is the only interchange** — no Markdown, no files, no git. Content opacity is
  "proprietary-but-exportable": transparent-ish via lossy HTML, not via files (T11
  content-opacity tier between transparent-files and E2EE-opaque).
- **Write granularity = section-anchor HTML splice** — a mid tier (between whole-file and
  block/character) realized over an API, distinct from fedwiki's story-item op-log.

### What to keep

1. **External-API mode generalized** to carry an **HTML payload** variant (Quip) beside
   block-JSON (Notion) and GraphQL (Wiki.js) — capability/payload-format is part of the
   adapter profile (UC-57/UC-80).
2. **Inline embedded live/structured objects** as a page-model element (prose + embedded
   spreadsheet/app), with **explicit lossy projection** to Markdown (UC-55/UC-58/UC-59).
3. **Enterprise-ACL + delegated identity** honored, not bypassed (UC-06).

## 6. UC seed

| # | Seed | Disposition |
|---|------|-------------|
| UC-80 | Attach a **SaaS live-doc shard** whose pages **mix prose + embedded live structured objects** (spreadsheets / live apps) via **REST with lossy HTML import/export**, under **enterprise (Salesforce) identity** | **new** |
| — | external-API mode w/ HTML payload variant | enrich **UC-57** |
| — | inline embedded spreadsheet/live-app = non-Markdown content | enrich **UC-55** |
| — | embedded structured objects within a prose page | enrich **UC-58** |
| — | internal (API-limited) revision history | enrich **UC-36** |
| — | Salesforce-tied enterprise ACL + SSO | enrich **UC-06** |

## 7. Architecture notes for SHARD-WP-0002

- **T11 (capability / content opacity):** add a **payload-format** facet to external-API
  shards (HTML / block-JSON / GraphQL) and a **content-opacity tier** "proprietary but
  lossy-exportable" between transparent-files and E2EE-opaque. Write granularity =
  section-anchor splice.
- **T12 (page model):** support **inline embedded structured/live objects** within a prose
  page (not only whole-page-as-record) — with explicit lossy render to Markdown.
- **T14 (binding):** external-API binding with **HTML import/export**; honor Salesforce
  identity/ACL; default to read/projection/overlay given rate limits + lossy export.

## 8. Open questions

1. Does shard-wiki represent an **embedded live spreadsheet** as a typed sub-object with
   provenance (preferred) or flatten it to a static Markdown table (lossy) — and can overlays
   target a spreadsheet cell via the API, or only the prose?
2. Given **HTML-only, lossy** interchange and rate limits, is Quip ever a **write-through**
   shard, or read/projection/overlay/backup by default? (cf. Notion Q1, UC-57.)
3. How is **Salesforce identity** mapped to shard-wiki's delegated-authn model — pass-through
   token, service account, or per-user OAuth?

## 9. Sources

- Quip Automation API (REST) docs — quip.com / Salesforce developer docs (threads/documents,
  `edit-document`, folders, messages, spreadsheets)
- Salesforce Quip product docs (live apps, spreadsheets, sharing/permissions)
- prior: `research/260614-notion-deep-dive/` (closed-SaaS external-API contrast, UC-57/59)

## 10. Traceability

New UC **UC-80** carries the marker **◧** in the wikiengines column of
`spec/UseCaseCatalog.md`. Enriched: UC-57, UC-55, UC-58, UC-36, UC-06. Architecture
cross-refs: SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (inline objects), T14.