docs: add public pages for the deepnote publish and sync CLI commands - #510

Stacked on #508 — base is worktree-sync-publish-coordination, so the diff here is docs only. Rebase onto main once #508 merges.

Why

Neither deepnote publish nor deepnote sync had public documentation. deepnote sync is also easy to confuse with the in-product Deepnote file sync feature: the names collide, and nothing on the existing page distinguished them.

What's here

docs/deepnote-cli-publish.md — deploying a build directory to a project. Covers authentication and token safety, finding a project ID (matching the URL convention already documented in data-apps.md), the _deepnote_static target and --path with its percent-encoded URLs, --api-access and why it is off by default, --prune, the local-validation-then-remote-mutation ordering, exit codes, and the canonical URL the server returns.

docs/deepnote-cli-sync.md — mirroring a workspace locally. Opens with the naming distinction, then covers the directory layout and .deepnote-sync.json, both sync directions and lost-update protection, --on-conflict including the non-TTY behavior, --all-files and the 100 MiB cap, the deletion rules in both directions, the safety rails (including why pruning is refused on a workspace mismatch), automation, and exit codes. Ends with a table for choosing between file sync, CLI sync, and publish.

docs/deepnote-file-sync.md — a callout at the top distinguishing the in-product Git-linked feature from the CLI command, plus a Related section. Surgical: the existing content is unchanged.

Both new pages cross-link each other and note that the two --prune flags share a name and point in opposite directions — remote for publish, local for sync.

One deviation from the brief, flagged

The brief asked to document the ownership rule as "sync --all-files ignores _deepnote_static/** after the conflict fix." That describes the exclusion approach (Option A) that was rejected in favour of "both work for both", and it is not what #508 does. Documenting it would have been wrong on the day it merged.

What the pages document instead, matching #508:

• deepnote publish writes the static root. It is the deploy command and the only one that should author those files; its source of truth is the local build directory.
• deepnote sync mirrors it and never silently overwrites it. The per-file divergence check applies there like anywhere else, so a site republished since the last sync is surfaced as a conflict rather than reverted to an older local copy.
• A publish inside a synced workspace keeps the mirror in step, so the next sync does not see the deploy as drift.

Same practical guidance — publish owns those files, sync will not clobber them — expressed as coordination rather than exclusion. Worth a look to confirm the framing reads the way you want before this leaves draft.

Deliberately untouched

• docs/deepnote-mcp.md — waiting on the released manifest.
• docs/creating-apps.md, docs/streamlit.md, and also docs/scheduling.md, docs/export-pdf.md, docs/export-project.md — the last three are in docs: refresh publishing and app delivery guidance #491's diff, so they are excluded too.
• No tool counts or unreleased capabilities. No plan-gating claims, since I could not verify them from the repo.

Checks

pnpm prettier:check and pnpm spell-check clean. Every /docs/<slug> link in the three files verified against an existing page.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive guidance for using deepnote publish, including authentication, project permissions, API access, options, failure behavior, and exit codes.
  • Added documentation for deepnote sync, covering workspace mirroring, bidirectional synchronization, conflicts, deletions, automation, and safety controls.
  • Clarified the difference between in-product file sync and the deepnote sync CLI command.
  • Added related resources for publishing, synchronization, file formats, and local setup.