---

frozen: true step: KN-DOCS-SYNC-a model: "Thinking (thinking-high)" date: 2026-08-17 branch: feat/kn-docs-sync-a status: thinking-freeze-2026-08-17 supersedes: "Freezes Knowtation-owned live Google Drive (then Notion) connectors. Reuses Calendar 1D OAuth primitives (PKCE S256, AES-256-GCM vault, hosted blob strong-consistency). Does not invent a Scooling vault, collect a provider key in Scooling, flip Scooling /connect Drive to Ready, or change the existing Hub folder gdrive importer. This freeze does not authorize KN-DOCS-SYNC-b Auto until freeze-review pass." evidence: "Scooling PRIMARY 2026-08-16 (ROADMAP F3i-kn; OVERSEER-HANDOVER NEXT). CONNECT-CATALOG-b BV pass sha256:6372219bce3ac96a10fe76db176ecf78cd0ffb6165178bb1d2265796845ef2e9. MEDIA-LIVE-READS smoke PASS. Hub lib/importers/gdrive.mjs is a Markdown-folder importer. Hub lib/importers/notion.mjs reads a Hub-only env name. Calendar 1D is the OAuth pattern."

KN-DOCS-SYNC — Knowtation-owned live Drive (then Notion) connector

Ground truth for KN-DOCS-SYNC-b Auto. Downstream Auto may treat this document as ground truth without re-deriving. It does not flip Scooling /connect Drive or Notion to Ready, collect a provider key in Scooling, invent a second vault, send Hub source_type gdrive or notion from Scooling, flip SCOOLING_MEDIA_*, invent Live on Patterns / Models / Studio / threads, open presence or pairing, or work Parentier.org.

phase: KN-DOCS-SYNC-a
outputs:
- id: kn-docs-sync
  path: docs/KN-DOCS-SYNC-FREEZE.md
  frozen: true
  notes: Drive readonly OAuth + encrypted refresh-material vault in Knowtation only; list/import as notes through Review-before-write; optional sync_cursor; Notion stays Hub-key. No Scooling Ready flip in this tip.
frozen_inputs:
- id: connect-and-open-range
  path: ~/scooling/docs/CONNECT-AND-OPEN-RANGE.md
  notes: KN-DOCS-SYNC steps; Scooling never collects the key; Drive honestly disabled until this lands
- id: connect-catalog
  path: ~/scooling/docs/reviews/2026-08-16-connect-catalog.md
  notes: Wave 2 freeze; Drive/Notion stay not_wired; denied Hub types include gdrive and notion
- id: connect-catalog-bv
  path: ~/scooling/docs/reviews/2026-08-16-connect-catalog-bv-round1-pass.md
  notes: CONNECT-CATALOG-b BV pass; digest sha256:6372219bce3ac96a10fe76db176ecf78cd0ffb6165178bb1d2265796845ef2e9
- id: bring-in-connect
  path: ~/scooling/docs/reviews/2026-08-16-bring-in-connect.md
  notes: docs_drive_live and docs_notion not_wired; calendar-1D pattern named for KN-DOCS-SYNC
- id: calendar-1d
  path: docs/CALENDAR-OAUTH-CONNECTOR-1D-SPEC.md
  notes: Confidential web client + PKCE S256; encrypted vault; redirect allowlist; Scooling never holds material
- id: gdrive-folder-importer
  path: lib/importers/gdrive.mjs
  notes: Folder of Markdown only — not Drive API. Unchanged by this Auto.
- id: notion-hub-importer
  path: lib/importers/notion.mjs
  notes: Hub-only env name; CLI / POST import path. Live hosted path is new Review-before-write routes.
- id: oauth-pkce
  path: lib/companion-oauth-pkce.mjs
  notes: S256-only; constant-time state; fail-closed. Reuse; do not fork a second PKCE core.
- id: calendar-token-vault
  path: lib/calendar/oauth-token-vault.mjs
  notes: AES-256-GCM + scrypt primitive to copy. Do not write Drive blobs into calendar_oauth.
- id: calendar-blob
  path: hub/bridge/calendar-blob-store.mjs
  notes: Hosted strong-consistency hydrate for pending OAuth state. Copy the pattern into a docs blob store.
- id: proposals-store
  path: hub/proposals-store.mjs
  notes: createProposal is the Review-before-write write path for imported notes.
- id: import-source-types
  path: lib/import-source-types.mjs
  notes: gdrive and notion remain import types. Live Drive does not POST those types from Scooling.
- id: scooling-roadmap-f3i-kn
  path: ~/scooling/docs/ROADMAP.md
  notes: F3i-kn owns this build; CONNECT-DRIVE-READY is a later Scooling Auto
review_stamp:
  reviewed_at: '2026-08-17T11:13:54Z'
  verdict: pass
  reviewer_mode: agent
  reviewer_model: thinking-high
  reviewer_provider: local
  kit_version: 0.1.0
  artifact_digest: sha256:cebd3d9d53f1c7dadcad2a5c7a09fbd280678f957fb66b1d364997622d623d96
downstream:
- id: KN-DOCS-SYNC-b
  model: Auto
  consumes_as_ground_truth: true
  notes: Implement Drive OAuth + vault + list + Review import + optional sync_cursor + Notion Hub-key list/import (inert gates). Starts only after freeze-review pass. Auto does not edit Scooling. Auto does not flip compile-time gates to true.
- id: CONNECT-DRIVE-READY
  model: Auto
  consumes_as_ground_truth: true
  notes: Later Scooling tip. Flip /connect Drive (then Notion) only after this Auto lands and Drive gate is operator-authorized. Not this Knowtation tip.
tier3_gates:
- T1 Muse main or muse-mirror to GitHub main (SD-14) outside SD-21 land hygiene
- T2 Setting DOCS_OAUTH_GOOGLE_AUTHORIZED or DOCS_NOTION_HUB_KEY_AUTHORIZED to the enabled literal in source or live env
- T3 Writing Google Drive client credentials or the docs vault wrapping secret into git
- T4 Pasting a Notion integration value into Scooling, a Scooling env, or a Scooling adapter
- T5 Flipping Scooling /connect docs_drive_live or docs_notion off not_wired (CONNECT-DRIVE-READY)
- T6 Any SCOOLING_MEDIA, SCOOLING_STUDIO, or SCOOLING_TASK_LOOP enabled assign
- T7 Live Google or Notion network from CI
- T8 Feature to GitHub main / non-muse-mirror head

Auto must not build until freeze review pass. This Thinking tip does not implement routes. This Thinking tip does not flip any env.

Review record

Round	Reviewer	Verdict	Resolution
0	Thinking (this session)	draft	Freeze authored from CONNECT-AND-OPEN-RANGE + CONNECT-CATALOG-b BV pass + Calendar 1D + Hub gdrive/notion importers
1	Freeze-review loop (thinking)	findings	R1-F1–F5 fixed below. CLI dry-run was already pass.
2	Freeze-review loop (thinking) + ok review --freeze	pass	R1 holds. No new cited findings. CLI C checklist clean. Cleared for KN-DOCS-SYNC-b Auto. Auto must not edit Scooling, flip gates, or writeNote on live routes. No human escalation.

Round 1 findings (cited — file+line)

ID	Sev	Cat	Citation	Finding	Fix
R1-F1	MAJOR	completeness	docs/KN-DOCS-SYNC-FREEZE.md:160 (prior D10)	D10 said Hub-key only but did not say the existing env is process-wide. Auto could invent per-vault Notion material.	D10 now locks process-wide env, no per-connector copy, connected = env present.
R1-F2	MAJOR	security	docs/KN-DOCS-SYNC-FREEZE.md:191 (prior q name-contains)	List q was “name contains, ≤ 128” with no charset lock — Drive query injection.	q MUST match ^[A-Za-z0-9 ._-]{1,128}$ or 400; no raw q= build. Security tier covers it.
R1-F3	MINOR	consistency	docs/KN-DOCS-SYNC-FREEZE.md:227 (prior)	auto_approvable is not a hub/proposals-store.mjs field (createProposal at :204-215 has no such column).	Omitted. Admission lock is no T5 fingerprint + human approve.
R1-F4	MINOR	completeness	docs/KN-DOCS-SYNC-FREEZE.md:166 (prior D16)	Per-file cap only; CONNECT-CATALOG batch cap 80_000_000 unbound.	D16 adds 80_000_000 bytes per import batch.
R1-F5	MINOR	completeness	docs/KN-DOCS-SYNC-FREEZE.md §12 (prior)	“Hub UI or Scooling” in §4.3 left Hub chrome in Auto scope.	§12 excludes Hub wizard chrome; REST + tests only.

Citation discipline

Every freeze-review finding MUST cite file+line (OVERSEER-KIT-SPEC §6). Do not trust uncited review output. HTTP routes in this doc omit the leading slash (api/v1/…) so the freeze mechanical gate does not treat them as absolute machine paths. Cross-repo paths use ~/scooling/…. Never leading-slash absolute paths.

---

0. Job (lock)

People can already bring downloaded files into Knowtation from Scooling /connect after Review. Live Google Drive and Notion are honestly off on that page. This freeze writes the Knowtation-owned connector so a later Scooling tip can turn the Drive card on without ever holding a key.

Knowtation owns the Google consent, the stored refresh material, the file list, and the note proposals. Scooling may later start consent and show status only. Scooling never collects the key.

---

1. What stays frozen (do not reopen)

Lock	Source	This Auto
Knowtation is the only canonical store	CROSS-REPO-COORDINATION; ADAPTER-CONTRACTS	Unchanged
Review-before-write for durable notes	PROPOSAL-LIFECYCLE; BRING-IN-CONNECT §5.4	Holds — live import creates proposals; apply writes notes
Hub folder gdrive importer	lib/importers/gdrive.mjs	Unchanged — still a folder of Markdown, not Drive API
Hub notion CLI / POST import	lib/importers/notion.mjs	Unchanged for admin CLI / POST import. Live hosted path is new routes
Scooling denied Hub types	CONNECT-CATALOG §6.2	Holds — Scooling still never sends gdrive or notion
Scooling /connect Drive / Notion cards	BRING-IN-CONNECT §2.3	Stay not_wired — CONNECT-DRIVE-READY is a later Scooling Auto
Calendar 1D OAuth	docs/CALENDAR-OAUTH-CONNECTOR-1D-SPEC.md	Reuse primitives — do not share the calendar vault directory or calendar client id
Media connector id gdrive	MEDIA-WRITE-SURFACES (opaque ref, no fetch)	Unrelated — do not reuse media import-consent for this path
MEDIA hosted reads	MEDIA-LIVE-READS smoke PASS	Do not flip SCOOLING_MEDIA_*
Sheets / chat inbox / Slack workplace	CONNECT-AND-OPEN-RANGE	Out of scope
Eight venue words / Home chat	SITE-FINISH / BRING-IN-CONNECT	Unchanged

---

2. Hub ground truth (verified this session — do not re-derive)

Fact	Citation	Consequence
Hub gdrive is a folder of .md files	lib/importers/gdrive.mjs:1-24	Live Drive is a new connector, not an extension of POST import gdrive
Hub notion reads a Hub-only env name and writes notes directly	lib/importers/notion.mjs:20-66	Live Notion uses the same Hub-only env name and a new Review path
IMPORT_SOURCE_TYPES includes gdrive and notion	lib/import-source-types.mjs:7-30	Those strings stay for folder / CLI import. Scooling still must not send them
Calendar OAuth is confidential web + PKCE S256, vault under calendar_oauth	docs/CALENDAR-OAUTH-CONNECTOR-1D-SPEC.md:39-44; lib/calendar/oauth-token-vault.mjs:79-83	Copy the primitive; new directory docs_oauth
Calendar hosted callback needs strong blob consistency	hub/bridge/calendar-blob-store.mjs:7-11	Docs OAuth pending state uses the same strong-consistency rule
Scooling Drive / Notion cards are not_wired	~/scooling/docs/reviews/2026-08-16-bring-in-connect.md:193-201	This tip does not flip them
CONNECT-CATALOG-b BV pass	~/scooling/docs/reviews/2026-08-16-connect-catalog-bv-round1-pass.md:13	Wave 2 file cards are done; live Drive was out of that Auto
Scooling never stores a sync cursor	~/scooling/docs/reviews/2026-08-16-bring-in-connect.md:213	sync_cursor lives in Knowtation only

---

3. Design decisions (frozen)

#	Decision	Frozen value	Rationale
D1	OAuth client type (Drive)	Confidential web application + PKCE S256	Same as Calendar 1D D1. Client credential stays on the Knowtation server.
D2	Drive scopes	openid and https://www.googleapis.com/auth/drive.readonly only	Read-only Drive + stable sub. No email / profile. No write scope. No drive.file (too narrow for folder list). No Sheets scope.
D3	Refresh-material acquisition	access_type=offline and prompt=consent	Background list / sync without re-login.
D4	Vault	AES-256-GCM + scrypt, copied from lib/calendar/oauth-token-vault.mjs, stored under data/docs_oauth/{connector_id}.enc	Do not write into calendar_oauth. Separate wrapping secret. Access material is in-memory only during a list / import / sync run.
D5	Client registration	Separate Google Cloud client from Calendar	Drive scopes are Restricted; blast radius and verification stay separate.
D6	Note write path	createProposal then approve / apply	Review-before-write. Live path MUST NOT call writeNote or POST import.
D7	Frontmatter source	Live Drive notes use source: google-drive and source_id = Drive file id	Distinct from folder-import source: gdrive. Dedup by (source, source_id).
D8	Revoke vs notes	Revoke deletes vault blob + Google revoke (best-effort). Vault notes stay	Notes are reviewed canonical content. Calendar events were copies in a calendar store; that purge rule does not apply.
D9	Sync cursor	Optional opaque sync_cursor on the connector (Drive Changes startPageToken / newStartPageToken)	Knowtation-only. Sync creates proposals for new or changed allowlisted files; never silent note writes. 410 → full re-list.
D10	Notion auth	Hub-key only (existing process-wide env name). No Notion OAuth. No per-vault or per-connector copy of that value	CONNECT-AND-OPEN-RANGE: Notion stays Hub-key; never pasted into Scooling. Hosted Hub already has one integration value. connected means the env is present. List/import sees only pages that integration can access. Per-user Notion login is a later freeze.
D11	Google verification posture	v0 in Google testing mode with allowlisted test users	drive.readonly is Restricted. Public launch is a later operator / legal gate.
D12	Compile-time gates	DOCS_OAUTH_GOOGLE_AUTHORIZED and DOCS_NOTION_HUB_KEY_AUTHORIZED hard-coded false in source	Operator Tier 3 to enable. Tests inject authorizedOverride.
D13	Scooling role	Initiate + status only (later CONNECT-DRIVE-READY)	Scooling never holds refresh material, never calls Google or Notion, never stores sync_cursor.
D14	Auto b DONE bar	Drive connector + Notion Hub-key connector both land inert	Drive is the first live flip. Notion code ships gated false so Scooling does not need a second Knowtation freeze.
D15	MIME allowlist (Drive)	Google Docs, text/markdown, text/plain, application/pdf, Word docx	Sheets, Slides, folders-as-notes, audio, video, and other MIME → unsupported_mime.
D16	Caps	20 file ids per import; 25_000_000 bytes per file; 80_000_000 bytes per import batch; list page size 50; sync rate-limit 60s per connector	Aligns with CONNECT-CATALOG / BRING-IN-CONNECT file caps.
D17	Hosted persistence	New docs blob store, strong consistency for pending OAuth state	Same failure that calendar fixed (callback on a different lambda).

---

4. WHAT — surfaces

4.1 Providers

provider	Auth	This Auto
google-drive	Google OAuth (D1–D5)	Required
notion	Hub-key (D10)	Required, inert until T2

No Microsoft, Slack, Discord, Telegram, WhatsApp, Sheets, or chat-inbox provider.

4.2 Routes (self-hosted Hub + hosted gateway → bridge)

All routes except the Google callback sit behind existing JWT + vault access (same middleware class as api/v1/calendar/...). Gate off → 501 { code: 'NOT_AUTHORIZED' } and no network, no vault I/O.

Method / route	Role	Request	Response (no secrets)
POST api/v1/docs/connectors	editor, admin	{ provider, display_name?, return_url? }	Drive: { connector_id, authorization_url, expires_at }. Notion: { connector_id, status } (connected if Hub-key present, else needs_reauth)
GET api/v1/docs/connectors/callback	state-authenticated	code + state query	302 to allowlisted return_url. Failure 302 return_url with connect=error and reason enum only
GET api/v1/docs/connectors	viewer+	—	{ schema: 'knowtation.docs_connectors/v0', connectors:[{ connector_id, provider, display_name, status, last_sync_at, last_sync_error, file_count }] }
GET api/v1/docs/connectors/:id/files	viewer+	page_token?, q?	{ files:[{ file_id, name, mime, modified, size, importable }], next_page_token? } — no bodies, no emails, no owners. q MUST match ^[A-Za-z0-9 ._-]{1,128}$ or the route returns 400 BAD_REQUEST (no Drive q= string built from raw input).
POST api/v1/docs/connectors/:id/import	editor, admin	{ file_ids: string[] }	{ proposed, skipped, proposal_ids } — creates proposals only
POST api/v1/docs/connectors/:id/sync	editor, admin	—	{ proposed, skipped, last_sync_at } — optional cursor; rate-limited ≥60s
DELETE api/v1/docs/connectors/:id	editor, admin	—	{ revoked: true } — blob gone; notes kept

status enum: pending, connected, needs_reauth, revoked.

last_sync_error enum only: auth_expired, rate_limited, provider_error, network_error, none. No provider text.

Notion POST ignore return_url. Notion has no callback route. Notion sync uses Notion next_cursor stored as sync_cursor.

4.3 OAuth flow (Drive only)

Later Scooling (CONNECT-DRIVE-READY) or Hub UI
   POST api/v1/docs/connectors  { provider: 'google-drive', return_url }
   Knowtation: PENDING connector; PKCE S256 + state (CSPRNG, TTL 10m,
   bound to vault_id + connector_id + return_url); persist verifier+state server-side
   → { connector_id, authorization_url, expires_at }
Browser opens authorization_url
Google consent (readonly + offline)
GET api/v1/docs/connectors/callback  (code + state)
   validate state (constant-time, single-use, not expired)
   exchange code + code_verifier + client credential at Google (server TLS)
   encrypt refresh material → oauth_ref; discard plaintext; access material in memory
   store account_sub (OpenID sub, never email)
   302 allowlisted return_url  (no code, no material in the redirect)

Redirect URI and return_url are exact-match allowlisted (env names in §8). Open redirects fail closed.

4.4 List → Review import (both providers)

1. List returns metadata only (importable true iff MIME / Notion type is allowlisted).
2. Import accepts 1–20 ids. Unknown / not importable / oversize / empty convert → skipped with bounded reason (unsupported_mime, too_large, not_found, already_pending, empty_extract).
3. Server fetches content (Drive export / download, or Notion markdown). Converts to one Markdown note per id.
4. Server calls createProposal with source: import, review_queue: docs-sync, and intent a fixed prefix plus the untrusted file name (truncated ≤ 128). Do not invent an auto_approvable field on the note store (hub/proposals-store.mjs has no such column). The admission lock is §4.4 step 9.
5. Path: imports/google-drive/{safe_id}.md or imports/notion/{safe_id}.md. safe_id is the provider id with non [A-Za-z0-9_-] stripped, ≤ 64 chars.
6. Frontmatter (Drive): source: google-drive, source_id, connector_id, imported_at. Notion: source: notion, source_id (page id), connector_id, imported_at.
7. If a live note already exists with the same (source, source_id), create an edit proposal with base_state_id — do not mint a second path.
8. Approve / apply uses the existing note-proposal apply path (self-hosted createProposal + apply; hosted gateway / canister propose + apply-approved). Auto MUST NOT add a new after-approve hook.
9. docs-sync proposals are not admitted to personal self-apply. Do not add a T5 fingerprint. Human approve only.

File / page name and body are untrusted. Existing proposal injection labels apply. Never interpret name as a command.

4.5 Optional sync

POST …/sync is optional. When sync_cursor is absent, perform a first page list and store the new cursor. When present, Drive uses Changes list; Notion uses search / database iterate with next_cursor. New or changed allowlisted items become proposals (same as import). Unchanged ids are no-ops. Sync never writes notes directly. Concurrent sync on the same connector → 429 RATE_LIMITED.

4.6 Revoke

1. Drive: decrypt oauth_ref; POST Google revoke (best-effort; network failure does not block local purge). Notion: no remote revoke API required.
2. Delete the encrypted blob (Drive) / clear Hub-key handle from the connector record (Notion never copies the Hub env into the record).
3. Set revoked_at, status: revoked; keep a material-free tombstone.
4. Do not delete imported notes.

invalid_grant on Drive refresh → needs_reauth, last_sync_error: auth_expired, stop sync. Notes stay. Hard DELETE is required to drop the connector.

---

5. HOW — modules and data

5.1 New modules (suggested paths)

Path	Role
lib/docs/oauth-token-vault.mjs	Copy calendar vault primitive; path root docs_oauth; connector id ^conn_[A-Za-z0-9_-]{8,64}$
lib/docs/google-drive-connector.mjs	PKCE begin, callback, list, export/download, sync, revoke. Injected Google client in tests
lib/docs/google-drive-normalizer.mjs	Pure MIME → markdown / skip. No network
lib/docs/notion-hub-connector.mjs	List + fetch using Hub env name; no OAuth
lib/docs/docs-connector-store.mjs	Connector records (no secrets); sync_cursor; tombstones
lib/docs/docs-import-propose.mjs	Build proposal input; dedup; caps
hub/bridge/docs-blob-store.mjs	Hosted hydrate/persist; strong consistency for pending OAuth
hub/bridge/docs-routes.mjs	Bridge route registration (mirror calendar)

Gateway mounts the same path prefixes and proxies to the bridge (mirror hub/gateway/server.mjs calendar block). Self-hosted hub/server.mjs mounts the same routes.

5.2 Connector record (client-visible)

Field	Client?	Notes
connector_id	yes	conn_…
provider	yes	google-drive | notion
display_name	yes	Untrusted; ≤ 128
status	yes	enum §4.2
account_sub	no	Drive OpenID sub only; never email
oauth_ref	no	Opaque handle to the enc blob
sync_cursor	no	Opaque provider cursor
last_sync_at	yes	ISO8601 or null
last_sync_error	yes	enum
file_count	yes	Last successful list count (0 if none)
revoked_at	yes	ISO8601 or null

Vault payload (Drive, never returned): refresh material, granted scope string, token type, obtained_at, account_sub. Client id / client credential are env only, never written to the blob.

5.3 Drive conversion

MIME	Action
application/vnd.google-apps.document	files.export as text/markdown; if empty, text/plain
text/markdown	download bytes as UTF-8 body
text/plain	download bytes as UTF-8 body
application/pdf	download bytes; convert with a new exported pdfBytesToMarkdown(buf) extracted from lib/importers/pdf.mjs (unpdf + normalizeExtractedText). CLI importPdf keeps writeNote. Live path MUST NOT call importPdf / writeNote. Empty or image-only extract → skip empty_extract
application/vnd.openxmlformats-officedocument.wordprocessingml.document	download bytes; convert with a new exported docxBytesToMarkdown(buf) extracted from lib/importers/docx.mjs (mammoth + normalizeMarkdownBody). CLI importDocx keeps writeNote. Live path MUST NOT call importDocx / writeNote. Empty convert → skip empty_extract
application/vnd.google-apps.folder	list children only; not importable as a note
other	importable: false, skip unsupported_mime

Google Docs export failure → skip provider_error for that id; do not fail the whole batch.

5.4 Notion conversion

Reuse the Hub markdown fetch already in lib/importers/notion.mjs as a called helper or extracted function, but the live route MUST go through docs-import-propose (proposals), not writeNote. List uses Notion search (pages the integration can see). Databases are listed as containers; import targets pages. Skip unsupported block types by omitting them (do not fail the page).

The Hub env name stays server-side. Connector records store no copy of that value.

---

6. Security invariants (enforced, not documented-only)

• No secret egress. Refresh material, client credential, authorization codes, code_verifier, state, Hub Notion value, and sync_cursor never appear in responses, redirects, logs, error messages, provenance, projections, MCP resources, or Scooling adapters.
• State / CSRF. state is CSPRNG, single-use, TTL 10m, bound to vault_id + connector_id + return_url, compared constant-time via lib/companion-oauth-pkce.mjs. Replay, tamper, expiry → deny.
• PKCE S256 only. plain rejected everywhere.
• Redirect allowlist. Exact match; no open redirect.
• Read-only Drive scopes (D2). Any write scope is a later freeze.
• Scooling never collects the key. No Scooling env, form field, adapter argument, or localStorage for Google or Notion material.
• Untrusted content. Names and bodies are untrusted prompt content.
• Least data. List omits owners, permissions, emails, sharing ACLs.
• Server-only provider calls. Agents never call Google or Notion. MCP may list connector status (token-free) but MUST NOT expose file bodies until a note exists via Review.
• Backoff. Honor 429 / Retry-After. Bounded retries (max 3) then rate_limited.
• Gate off = inert. False gates → 501, no network, no vault I/O.
• Namespace isolation. Docs vault directory ≠ calendar_oauth. Docs blob keys ≠ calendar/oauth/….
• Id injection. file_ids / page ids must match ^[A-Za-z0-9_-]{1,128}$ (Drive) or Notion UUID-with-optional-hyphens ≤ 64. Else 400 BAD_REQUEST.

---

7. Fail-closed rules

Code	When
NOT_AUTHORIZED	Gate false
NOT_CONFIGURED	Drive env incomplete on a begin/callback while gate is true
STATE_INVALID	Missing / replay / tamper / expiry / vault mismatch
RETURN_URL_DENIED	return_url not exact-allowlisted
PROVIDER_DENIED	Unknown provider
CONNECTOR_NOT_FOUND	Unknown or revoked id on mutating routes
NEEDS_REAUTH	Import / sync / list while needs_reauth
RATE_LIMITED	Sync < 60s or provider 429 exhausted
BAD_REQUEST	Cap exceeded, bad ids, unknown fields
SOURCE_TYPE_DENIED	Any attempt to treat this path as POST import gdrive / notion from a Scooling adapter in this tip (there is no Scooling adapter in this tip; regression test still asserts Hub does not accept a Scooling-shaped import body on these routes)

Callback failures redirect with reason in { state_invalid, denied, provider_error, not_configured } only.

---

8. Environment (never committed)

Names only — values are operator-set, never written in this artifact.

Name	Purpose
DOCS_OAUTH_GOOGLE_AUTHORIZED	Tier 3 Drive gate; source default false
DOCS_NOTION_HUB_KEY_AUTHORIZED	Tier 3 Notion gate; source default false
GOOGLE_DRIVE_OAUTH_CLIENT_ID	Drive OAuth client id (server)
GOOGLE_DRIVE_OAUTH_CLIENT_SECRET	Drive OAuth client credential (server-only)
KNOWTATION_DOCS_OAUTH_SECRET	Vault wrapping secret (≥ 32 chars)
DOCS_OAUTH_REDIRECT_URI	Exact Google-registered callback URL
SCOOLING_RETURN_URL_ALLOWLIST	Reuse the existing Calendar allowlist (exact URLs)
NOTION_API_KEY	Existing Hub-only Notion value; never copied to Scooling

.gitignore already excludes data/. .museignore must keep data/ excluded. Auto adds docs_oauth/ to any ignore file that currently names calendar_oauth/ explicitly; if only data/ is ignored, no ignore edit is required.

.env.example may list the names above with empty placeholders. Auto MUST NOT commit a real value.

---

9. Scooling consumer contract (not implemented here)

Frozen so CONNECT-DRIVE-READY cannot invent a second design. This Knowtation Auto must not edit the Scooling repo.

Later Scooling may	Later Scooling must not
POST api/v1/docs/connectors with provider: 'google-drive' and an allowlisted return_url	Collect, store, or log refresh material
Open authorization_url in the browser	Call Google or Notion
GET connector status (token-free)	Send Hub source_type gdrive or notion
After Ready flip, let a person pick listed file_ids and POST import	Store sync_cursor
Flip docs_drive_live to Ready only after this Auto lands and Drive gate is operator-authorized	Flip Ready in the Knowtation tip

Notion Ready on /connect is after Drive Ready (CONNECT-AND-OPEN-RANGE “then Notion”). Same rule: no key in Scooling.

---

10. Test matrix (seven-tier) — KN-DOCS-SYNC-b consumes this

All provider network is faked via an injected Google client and Notion client. No live Google or Notion call in CI. Live smoke is operator-run behind T2.

Tier	File	Coverage
unit	test/docs-oauth-connector-unit.test.mjs	PKCE/state build+validate; docs vault encrypt/decrypt + tamper fail; MIME allow/deny; id regex; path safe_id; gate false short-circuit
integration	test/docs-oauth-connector-integration.test.mjs	Drive begin → callback → list → import proposals → sync cursor → DELETE. Notion Hub-key list → import proposals. Dedup edit proposal
e2e	test/docs-oauth-connector-e2e.test.mjs	Hub/bridge route walkthrough with fakes: connect, list metadata only, import creates docs-sync proposals, approve apply writes one note, revoke keeps the note
stress	test/docs-oauth-connector-stress.test.mjs	Paginated list; 20-id cap; concurrent sync 429; Changes 410 full re-list without duplicate proposals
data-integrity	test/docs-oauth-connector-data-integrity.test.mjs	Dedup by source+source_id; vault blob survives restart; revoke deletes blob; notes remain; cursor opaque and not in GET connectors
performance	test/docs-oauth-connector-performance.test.mjs	List 50 + import 20 within local budget; vault decrypt overhead bounded
security	test/docs-oauth-connector-security.test.mjs	No material in responses/redirects/logs; state replay/tamper/expiry deny; PKCE plain rejected; redirect allowlist; gate off → 501 no network; Scooling-shaped POST import gdrive/notion not used; file_ids injection fixtures; list q reject quotes/operators; Notion value absent from connector JSON; calendar_oauth namespace unused; no T5 fingerprint for docs-sync

Test command: node --test test/docs-oauth-connector-*.test.mjs.

Security tier MUST fail against a pre-fix stub that returns refresh material on GET connectors or writes notes from import without a proposal.

---

11. Auto file allowlist (KN-DOCS-SYNC-b)

Path	Why
lib/docs/**	New connector / vault / normalizer / propose
hub/bridge/docs-blob-store.mjs	Hosted persistence
hub/bridge/docs-routes.mjs	Bridge routes
hub/bridge/server.mjs	Register docs routes + blob wrap
hub/gateway/server.mjs	Proxy the §4.2 prefixes
hub/server.mjs	Self-hosted mounts
lib/importers/notion.mjs	Extract fetch helper only; keep CLI writeNote behavior
lib/importers/pdf.mjs	Export pdfBytesToMarkdown only; CLI importPdf behavior unchanged
lib/importers/docx.mjs	Export docxBytesToMarkdown only; CLI importDocx behavior unchanged
docs/HUB-API.md	Honesty — live routes + “folder gdrive is not Drive OAuth”
docs/openapi.yaml	Route shapes
docs/PROPOSAL-LIFECYCLE.md	docs-sync queue note
docs/ROADMAP.md	Status
docs/OVERSEER-HANDOVER.md	NEXT
test/docs-oauth-connector-*.test.mjs	Seven-tier
.env.example	Names only, if the file exists on the tip
.gitignore / .museignore	Only if calendar_oauth is named and docs_oauth must join it

Forbidden in this Auto

• Any path under ~/scooling/
• lib/importers/gdrive.mjs behavior change
• lib/calendar/** writes (read/reuse only)
• Compile-time gate flipped to true
• SCOOLING_* or MEDIA_* env assigns
• New Hub source_type string
• Sheets / chat-inbox / Slack connectors
• Notion OAuth
• Direct writeNote on the live Drive / live Notion routes

---

12. Out of scope

• Scooling CONNECT-DRIVE-READY Ready flip
• Google Sheets live (docs_sheets stays not_wired)
• Chat inbox / Slack / Discord / Telegram / WhatsApp as workplace
• Drive write-back (create/edit Google files)
• Notion OAuth
• Google app public verification
• MCP/CLI parity for the new routes (after Hub REST is proven)
• Deleting vault notes on revoke
• OpenClaw Hub importer
• Hub UI chrome / new Hub wizard (REST + seven-tier only; learner UI is later Scooling CONNECT-DRIVE-READY)
• Presence, pairing, Parentier.org, Home chat

---

13. Definition of Done (KN-DOCS-SYNC-b)

• [ ] Freeze-review pass before Auto starts
• [ ] D1–D17 implemented; gates hard-coded false
• [ ] Seven-tier test/docs-oauth-connector-*.test.mjs green locally
• [ ] Build verification pass before ROADMAP → DONE
• [ ] Folder gdrive importer unchanged
• [ ] No Scooling file edits
• [ ] No secrets committed
• [ ] Both governance docs updated together
• [ ] Feature-branch hygiene; merge remains Tier 3 (or SD-21 land with no live flip)

13.1 Before Auto may start

• This artifact frozen: true
• /freeze-review-loop or /freeze-review verdict pass
• ok review --freeze docs/KN-DOCS-SYNC-FREEZE.md pass

13.2 Auto must not

• Flip Scooling Drive / Notion cards
• Collect a key in Scooling
• Enable the compile-time gates
• Call live Google or Notion from CI
• Treat Hub POST import gdrive as this feature