Two strands, both about the same confusion: which command owns a project's files, and which app model a given deliverable actually is.

1. packages/ — sync and publish stop overwriting each other's writes to the project file store.
2. skills/ — a canonical reference for Deepnote's app models, and a corrected skill sync map in AGENTS.md.
3. deepnote static-site access — change a published site's sharing and viewer API access without republishing (section at the end).

1. Sync and publish share one baseline

The conflict

deepnote publish deploys into _deepnote_static/**, which is a subtree of the project file store that deepnote sync --all-files mirrors. Neither command knew the other existed — STATIC_ROOT was a private const in publish.ts, and sync claimed the entire inventory. Four consequences:

1. Guaranteed churn. Publish never touched sync's manifest, so after every publish the whole static subtree looked changed and the next sync --all-files re-downloaded the built site into .files/.
2. Push could regress a live site. uploadProjectFiles never fetched the inventory at all — it was documented "last-write-wins, no staleness check", with no equivalent of the baseModifiedAt/baseContentHash protection the notebook path gets.
3. --prune produced ghosts. publish --prune removed a remote asset; sync's local copy still hash-matched the manifest so push skipped it, leaving it on disk forever and resurrecting it in the cloud on the next edit.
4. Round-trip loop. dist/ → publish → cloud → sync pull → .files/ → git → sync push → cloud.

The fix

Coordination, not partition — both commands keep writing the same paths.

Sync gains per-file lost-update protection on push. Every candidate is now checked against the cloud inventory, and a file that moved since the manifest baseline goes through the existing --on-conflict override-or-skip choice instead of being overwritten. Reported as N file(s) kept from Deepnote / filesSkipped. This is the load-bearing part: publish often runs from CI where no manifest exists, and the Deepnote app can write these paths too. It also fixes the same silent overwrite for ordinary working files (requirements.txt edited in the app was clobbered before).

Publish updates the sync mirror when the published directory sits inside a synced workspace: it writes each file into the project's .files/ mirror and records size, hash, and server updatedAt, exactly as a sync download would. Manifest, mirror, and cloud then agree, so sync sees the deploy as already in step. --prune drops pruned paths from both. --sync-root <dir> / --no-sync-root control discovery, which otherwise walks up from the published directory.

Publish stops before mutating anything if a path it would write has moved on in Deepnote since that workspace last synced — the mirror holds no copy of that content. --force overrides. Its check is deliberately narrower than sync's: sync is a mirror where both sides are authoritative, publish is a deploy where the local build is authoritative, so a path with no baseline is not flagged (that's the normal state of a static root written by earlier publishes, and flagging it would break the first publish in every workspace).

PROJECT_STATIC_ROOT moves to @deepnote/cloud so every writer agrees on where the boundary is.

Edge cases handled

• A pending replacement is exempt from the conflict check — that missing cloud copy is sync's own unfinished delete, not another writer's deletion. Without this, every interrupted upload would become a false conflict.
• The mirror is only updated when the tracked project directory already exists. Creating it would flip readLocalNotebookFiles from null to [], which sync reads as "every notebook was deleted locally" and pushes. Leaving the baseline stale is safe: the next sync pulls once and converges.
• A record written before updatedAt was tracked has no baseline to compare, so it still overwrites (rather than manufacturing conflicts for existing users) and becomes verifiable after the next pull.
• Mirror failures are warnings, not errors — the deploy already succeeded, and a stale manifest is safe because the next sync brings the mirror back in step (a pull re-downloads the published files, a push surfaces them as a conflict).
• Push hashes files in one pass and re-reads them at upload time, so one prompt can cover a whole project without buffering every file in memory.

Known limitation

The file API has no conditional write (POST /v2/files refuses to overwrite at all, which is why writes are delete-then-upload), so this is optimistic concurrency over the inventory: a small time-of-check/time-of-use window remains, and each replaced file has a brief 404 window on the live site. Both need a server-side atomic replace to close, tracked separately.

Review rounds (takeover, 2026-09-03)

Live-tested against the real CLI with a mock server (--contract strict|echo) and re-reviewed in five rounds. Changes on top of the original design:

• Server dependency made explicit. The per-file updatedAt baseline that publish records comes from the upload response, which the server only started echoing in deepnote-internal#20773 (in production since v0.16.997, 2026-09-03). On servers without it — self-hosted or older — publish-written baselines are unverifiable; the docs say so, and the CLI degrades to the pre-baseline overwrite rather than failing.
• The publish stop needs a usable baseline. Only an entry carrying the server's updatedAt is compared: --all-files syncs always record one, publishes do since #20773. A path without one is overwritten like any deploy. A per-path warning for that case was tried and removed — its only remedy, a pull, records the cloud copy as the baseline so the next publish passes the stop anyway.
• Pull keeps the baseline of a cloud-deleted file that stays on disk (no --prune), and warns. Previously the record was dropped, so an edited copy silently resurrected a file someone had removed (e.g. via publish --prune). An edited push now surfaces the deletion as a conflict; --prune still removes file and record together.
• Pending uploads. Publish clears a path from pendingFileUploads when it writes or prunes it, so an interrupted sync replacement that publish already settled cannot brick later syncs. A pending path whose cloud copy exists again is a conflict ("re-created in Deepnote after an interrupted upload"), not a silent retry — the "our own unfinished delete" premise is disproven when the copy is back. Sync persists each settled upload immediately, so a run interrupted later cannot leave its own upload looking pending; if a kept re-created conflict does occur, skipping it drops the retry so the next pull resolves it instead of the conflict sticking.
• Explicit --sync-root failures are exit 2 consistently, including a tracked project directory that is missing; a manifest that exists but cannot be read (or is a symlink) also exits 2 with a pointer at --no-sync-root.
• Kept-files warning is honest about pull: it says pulling replaces the local copies; the download-side dirty check itself is a follow-up.
• Token handling unified: every command resolves --token/DEEPNOTE_TOKEN through one trimming helper (a pasted token with a stray space used to fail only in publish).
• Dry run honours an explicit --on-conflict instead of always reporting a skip; the upload loop re-checks the 100 MiB cap on the bytes it actually uploads.
• Shared sha256/baselineDiverged helpers so publish and sync cannot drift on what "changed" means; apps.md states the static site's URL-to-file mapping.

Gates at head: pnpm test 3147 passed, typecheck, biome, prettier, spell-check clean; CI green including codecov patch/project.

2. App models reference (#509)

The skill had no canonical account of Deepnote's app models, so an agent choosing between them had to infer the differences from cli-publish.md, two example READMEs, and the local-runner package docs — and the one place that mentioned app tokens covered only the CLI flag.

skills/deepnote/references/apps.md states the five models, what each is made of, where it runs, and which credentials it gets: data apps, Streamlit apps, published static sites, published browser apps with viewer API access, and local Node-backed serveStatic apps. It leads with a decision table keyed on the questions that actually change the plan — including whether an agent can create the underlying files at all, which is where hosted-only workflows quietly fail.

It also records the failure mode worth knowing before it bites: code developed against a local preview with a personal token keeps working there and does nothing once embedded, with no error, because the viewer token is limited to one run loop.

AGENTS.md — the skill sync map claimed MCP tools mirror the CLI and should be recorded in cli-*.md. They do not: @deepnote/mcp (local files), hosted MCP at deepnote.com/mcp, and the codex-plugin consumer are three separate surfaces. The map now routes each to its own home and adds a row for app models, publishing ownership, and token boundaries.

skills/deepnote/SKILL.md — an Apps section pointing at the new reference.

Ownership documented consistently

Both strands land the same rule, which is why they read better together than apart. apps.md states it for agents and the cli-*.md references carry the mechanics:

• deepnote publish is the deploying writer for _deepnote_static/** — build output goes through publish, not through a synced workspace.
• The two commands share one baseline rather than splitting the namespace: sync mirrors those paths and surfaces a republished site as a conflict instead of reverting it.
• Publish updates a surrounding workspace's mirror unless told not to (--no-sync-root, which is what CI wants), and exits 1 without touching the project when Deepnote holds unsynced changes.

A follow-up commit on this branch dropped an earlier "publish owns the namespace" line from apps.md, which read as a split now that the implementation deliberately shares a baseline.

Branch history

• docs(skill): add an app-models reference and fix the skill sync map #509 was merged into this branch (its base was worktree-sync-publish-coordination), bringing apps.md, the AGENTS.md map fix, and the SKILL.md pointer.
• main was merged in to pick up chore: ignore local worktrees under .claude/worktrees #507. That is why chore: ignore local worktrees under .claude/worktrees #507 appears in this branch's log but not in the diff — it is already on main.
• One follow-up commit states the publish/sync coordination in apps.md now that the mechanism ships in this PR.

Testing

The merged commits touch only AGENTS.md, SKILL.md, and skills/deepnote/references/apps.md — no code, so the gate results for the implementation still stand: pnpm test (3127 passed, 1 skipped), pnpm typecheck, pnpm biome:check, pnpm prettier:check, pnpm spell-check all clean.

New test coverage in this PR:

• publish.test.ts — mirror writes and manifest records, the divergence stop and --force, --prune clearing the mirror, --no-sync-root, both --sync-root error cases, the missing-project-directory case, and the warn-not-fail mirror failure.
• sync.test.ts — a diverged cloud copy kept vs. overridden, a deleted cloud copy treated as a conflict, an unchanged copy not flagged, a pending retry finishing when the cloud copy is gone, plus unit coverage of describeCloudFileDivergence.
• publish-mirror.test.ts — findDivergedPublishPaths (including the deliberate mirror/deploy asymmetry) and resolvePublishMirror discovery.

Docs updated per AGENTS.md: packages/cli/README.md, skills/deepnote/references/cli-publish.md, skills/deepnote/references/cli-sync.md, and both commands' --help.

Stacked on this

#510 adds the public docs/ pages for deepnote publish and deepnote sync, and distinguishes the CLI deepnote sync command from the in-product "Deepnote file sync" feature. It is based on this branch and will retarget to main when this merges.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added static-site access to manage published-site sharing and viewer API access without republishing.
  • publish now supports sync-workspace coordination, conflict detection, pruning, and force overrides.
  • Sync now detects changed, deleted, or recreated cloud files and reports uploaded and skipped files more clearly.

• Bug Fixes

  • Prevented publishing and syncing from silently overwriting newer or deleted cloud files.
  • Improved validation for workspaces, paths, authentication, and mirror updates.

• Documentation

  • Expanded guidance for apps, publishing, syncing, access controls, and MCP surfaces.

Static-site access lifecycle

This draft now also adds deepnote static-site access, a settings-only command that reuses the existing PATCH /v2/projects/{projectId} contract. It can disable or re-enable sharing and change viewer API access without uploading or deleting _deepnote_static/**. Disabling sharing also disables viewer API access; re-enabling serves the retained files again.

The CLI README, cli-publish.md, apps.md, and the installed Deepnote skill describe the same publish → change access lifecycle. Six command tests cover combined settings, sharing-only and API-only updates, invalid empty/contradictory requests, and API failures.

Latest local verification: pnpm typecheck, pnpm biome:check, pnpm prettier:check, pnpm spell-check, and pnpm test (3133 passed, 1 skipped).