@@ -51,6 +51,15 @@ function run(...args: string[]) {
   return program.parseAsync(['node', 'deepnote', 'publish', ...args])
 }
 
+function captureStderr(): string[] {
+  const written: string[] = []
+  vi.spyOn(process.stderr, 'write').mockImplementation(chunk => {
+    written.push(String(chunk))
+    return true
+  })
+  return written
+}
+
 describe('deepnote publish', () => {
   it('trims whitespace from a pasted token', async () => {
     await fs.writeFile(join(tempDir, 'index.html'), '<h1>hello</h1>')
@@ -138,12 +147,14 @@ describe('deepnote publish', () => {
     const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
       throw new Error('exit')
     })
+    const stderr = captureStderr()
 
     await expect(run(tempDir, '--project-id', 'p1', '--token', 'tok', '--path', 'elsewhere/assets')).rejects.toThrow(
       'exit'
     )
 
     expect(exitSpy).toHaveBeenCalledWith(2)
+    expect(stderr.join('')).toContain('Target path must be _deepnote_static or a directory below it\n')
     expect(mockedGetProject).not.toHaveBeenCalled()
   })
 
@@ -626,12 +637,14 @@ describe('deepnote publish', () => {
       const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
         throw new Error('exit')
       })
+      const stderr = captureStderr()
 
       await expect(
         run(buildDir, '--project-id', 'p1', '--token', 'tok', '--sync-root', join(tempDir, 'Alpha'))
       ).rejects.toThrow('exit')
 
       expect(exitSpy).toHaveBeenCalledWith(2)
+      expect(stderr.join('')).toContain(`No .deepnote-sync.json found in ${join(tempDir, 'Alpha')}.\n`)
       expect(mockedGetProject).not.toHaveBeenCalled()
     })
 
@@ -642,12 +655,18 @@ describe('deepnote publish', () => {
       const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
         throw new Error('exit')
       })
+      const stderr = captureStderr()
 
       await expect(run(buildDir, '--project-id', 'p1', '--token', 'tok', '--sync-root', tempDir)).rejects.toThrow(
         'exit'
       )
 
       expect(exitSpy).toHaveBeenCalledWith(2)
+      expect(stderr.join('')).toContain(
+        `The sync manifest at ${join(tempDir, '.deepnote-sync.json')} tracks project p1 in Alpha, ` +
+          'but that directory does not exist. ' +
+          'Sync the workspace first, or pass --no-sync-root to publish without updating it.\n'
+      )
       expect(mockedUpload).not.toHaveBeenCalled()
     })
 
@@ -657,10 +676,16 @@ describe('deepnote publish', () => {
       const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
         throw new Error('exit')
       })
+      const stderr = captureStderr()
 
       await expect(run(buildDir, '--project-id', 'p1', '--token', 'tok')).rejects.toThrow('exit')
 
       expect(exitSpy).toHaveBeenCalledWith(2)
+      expect(stderr.join('')).toContain(
+        `The sync manifest at ${join(tempDir, '.deepnote-sync.json')} is not valid JSON. ` +
+          'Fix or delete it (deleting re-syncs everything from scratch). ' +
+          'Pass --no-sync-root to publish without updating the workspace.\n'
+      )
       expect(mockedGetProject).not.toHaveBeenCalled()
     })
 
@@ -670,12 +695,17 @@ describe('deepnote publish', () => {
       const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
         throw new Error('exit')
       })
+      const stderr = captureStderr()
 
       await expect(run(buildDir, '--project-id', 'p2', '--token', 'tok', '--sync-root', tempDir)).rejects.toThrow(
         'exit'
       )
 
       expect(exitSpy).toHaveBeenCalledWith(2)
+      expect(stderr.join('')).toContain(
+        `The sync manifest at ${join(tempDir, '.deepnote-sync.json')} does not track project p2. ` +
+          'Sync the workspace first, or pass --no-sync-root to publish without updating it.\n'
+      )
       expect(mockedUpload).not.toHaveBeenCalled()
     })
 
 
@@ -4,6 +4,8 @@ import {
   type PublishAppResult,
   PublishDivergedError,
   PublishError,
+  type PublishErrorCode,
+  type PublishErrorHint,
   publishApp,
   type SyncRootOption,
 } from '@deepnote/cloud-sync'
@@ -13,6 +15,7 @@ import dotenv from 'dotenv'
 import { ExitCode } from '../exit-codes'
 import { debug, getChalk, log, error as logError, warn } from '../output'
 import { MissingTokenError, resolveToken } from '../utils/auth'
+import { type CliFlag, cliFlagFor } from '../utils/option-hint'
 import { embeddedApiAccessNote } from '../utils/static-site-api-access'
 
 interface PublishOptions {
@@ -27,6 +30,18 @@ interface PublishOptions {
   force: boolean
 }
 
+const PUBLISH_ERROR_SENTENCES: { [C in PublishErrorCode]: (flag: CliFlag<PublishErrorHint<C>['option']>) => string } = {
+  'sync-root-unusable': flag => ` Pass ${flag} to publish without updating the workspace.`,
+  'project-not-in-sync-root': flag => ` Sync the workspace first, or pass ${flag} to publish without updating it.`,
+}
+
+function publishErrorSuffix(error: unknown): string {
+  if (!(error instanceof PublishError) || !error.code || !error.hint) {
+    return ''
+  }
+  return PUBLISH_ERROR_SENTENCES[error.code](cliFlagFor(error.hint))
+}
+
 export function createPublishAction(program: Command) {
   return async (dir: string, options: PublishOptions) => {
     const c = getChalk()
@@ -102,7 +117,7 @@ export function createPublishAction(program: Command) {
         onEvent: renderEvent,
       })
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
+      const message = (error instanceof Error ? error.message : String(error)) + publishErrorSuffix(error)
       if (error instanceof PublishDivergedError) {
         logError(
           `${message}. Run \`deepnote sync --all-files\` to bring the changes down, ` +
 
@@ -286,14 +286,15 @@ describe('deepnote sync events', () => {
       line: '⚠ skipped   Team/Alpha — modified both locally and in the cloud',
     },
     {
-      outcome: { ...outcome, action: 'pruned', detail: 'no longer in the cloud; removed locally (--prune)' },
+      outcome: { ...outcome, action: 'pruned', detail: 'no longer in the cloud; removed locally' },
       line: '✕ pruned    Team/Alpha — no longer in the cloud; removed locally (--prune)',
     },
     {
       outcome: {
         ...outcome,
         action: 'missing-in-cloud',
-        detail: 'no longer in the cloud; kept locally (use --prune to remove)',
+        detail: 'no longer in the cloud; kept locally',
+        hint: { option: 'prune', value: true },
       },
       line: '? missing   Team/Alpha — no longer in the cloud; kept locally (use --prune to remove)',
     },
@@ -311,6 +312,38 @@ describe('deepnote sync events', () => {
     }
   )
 
+  it('does not hint at --prune for a missing project whose path a current cloud project uses', async () => {
+    emitAll([
+      {
+        kind: 'project-outcome',
+        outcome: {
+          ...outcome,
+          action: 'missing-in-cloud',
+          detail: 'no longer in the cloud; kept local path used by a current cloud project',
+        },
+      },
+    ])
+
+    await sync('--prune')
+
+    expect(logged[0]).toBe(
+      '? missing   Team/Alpha — no longer in the cloud; kept local path used by a current cloud project'
+    )
+  })
+
+  it('adds no suffix to a missing project without a hint, though --prune was not passed', async () => {
+    emitAll([
+      {
+        kind: 'project-outcome',
+        outcome: { ...outcome, action: 'missing-in-cloud', detail: 'no longer in the cloud; kept locally' },
+      },
+    ])
+
+    await sync()
+
+    expect(logged[0]).toBe('? missing   Team/Alpha — no longer in the cloud; kept locally')
+  })
+
   it('suppresses the listing and outcome lines under -o json, leaving the JSON document alone on stdout', async () => {
     emitAll([
       { kind: 'listing-projects', baseUrl: 'https://api.example.com' },
@@ -340,6 +373,27 @@ describe('deepnote sync events', () => {
     expect(errored).toEqual(['Skipping file with unsafe path in "C": ../evil.csv'])
   })
 
+  it.each([[[]], [['-o', 'json']]])(
+    'adds the --prune hint to a kept-deleted-files warning on stderr (flags %j)',
+    async flags => {
+      emitAll([
+        {
+          kind: 'warning',
+          code: 'deleted-files-kept',
+          hint: { option: 'prune', value: true },
+          message: '2 files in "Alpha" deleted in Deepnote but kept locally: a.txt, b.txt.',
+        },
+      ])
+
+      await sync(...flags)
+
+      expect(errored).toEqual([
+        '2 files in "Alpha" deleted in Deepnote but kept locally: a.txt, b.txt. ' +
+          'Run sync --prune to remove them; pushing an edited copy restores that file in Deepnote.',
+      ])
+    }
+  )
+
   it('reports file transfers as debug output only', async () => {
     emitAll([
       { kind: 'file-transferred', direction: 'download', projectName: 'Alpha', path: 'data/a.csv', bytes: 12 },
@@ -538,6 +592,95 @@ describe('deepnote sync result handling', () => {
     ])
   })
 
+  describe('prune hints in the result', () => {
+    const outcome = { projectId: 'p1', name: 'Alpha', path: 'Team/Alpha' } as const
+    const missing = {
+      ...outcome,
+      action: 'missing-in-cloud',
+      detail: 'no longer in the cloud; kept locally',
+      hint: { option: 'prune', value: true },
+    } as const
+    const pruned = { ...outcome, action: 'pruned', detail: 'no longer in the cloud; removed locally' } as const
+    const keptForLiveProject = {
+      ...outcome,
+      action: 'missing-in-cloud',
+      detail: 'no longer in the cloud; kept local path used by a current cloud project',
+    } as const
+
+    function printedProjects(): { detail?: string }[] {
+      return JSON.parse(logged[logged.length - 1]).projects
+    }
+
+    it.each([
+      [
+        'a hinted missing project',
+        missing,
+        [],
+        {
+          ...outcome,
+          action: 'missing-in-cloud',
+          detail: 'no longer in the cloud; kept locally (use --prune to remove)',
+        },
+      ],
+      [
+        'a pruned project',
+        pruned,
+        ['--prune'],
+        { ...outcome, action: 'pruned', detail: 'no longer in the cloud; removed locally (--prune)' },
+      ],
+    ])('adds the flag to %s in the -o json document', async (_name, projectOutcome, flags, expected) => {
+      mockedSyncWorkspace.mockResolvedValue(resultOf({ projects: [projectOutcome] }))
+
+      await sync('-o', 'json', ...flags)
+
+      expect(printedProjects()).toEqual([expected])
+    })
+
+    it('keeps the hint out of the -o json document and the key order of the outcome', async () => {
+      mockedSyncWorkspace.mockResolvedValue(resultOf({ projects: [missing] }))
+
+      await sync('-o', 'json')
+
+      expect(Object.keys(printedProjects()[0])).toEqual(['projectId', 'name', 'path', 'action', 'detail'])
+    })
+
+    it('leaves the kept-for-a-live-project detail alone under --prune', async () => {
+      mockedSyncWorkspace.mockResolvedValue(resultOf({ projects: [keptForLiveProject] }))
+
+      await sync('-o', 'json', '--prune')
+
+      expect(printedProjects()).toEqual([keptForLiveProject])
+    })
+
+    it('leaves the details of other outcomes alone', async () => {
+      const projects = [
+        { ...outcome, action: 'pulled', detail: 'moved from Old/Alpha' },
+        { ...outcome, action: 'error', detail: 'boom' },
+        { ...outcome, action: 'unchanged' },
+      ] as const
+      mockedSyncWorkspace.mockResolvedValue(resultOf({ projects: [...projects] }))
+
+      await sync('-o', 'json')
+
+      expect(printedProjects()).toEqual(projects)
+    })
+
+    it('returns from runSync the same outcomes that -o json prints', async () => {
+      mockedSyncWorkspace.mockResolvedValue(resultOf({ projects: [missing] }))
+
+      const result = await runSync(tempDir, { token: 'tok' })
+
+      expect(result.projects).toEqual([
+        {
+          ...outcome,
+          action: 'missing-in-cloud',
+          detail: 'no longer in the cloud; kept locally (use --prune to remove)',
+        },
+      ])
+      expect(result.projects[0]).not.toHaveProperty('hint')
+    })
+  })
+
   it('still sets exit code 1 for an unsuccessful result under -o json', async () => {
     mockedSyncWorkspace.mockResolvedValue(failing)
 
 
@@ -16,6 +16,7 @@ import dotenv from 'dotenv'
 import { ExitCode } from '../exit-codes'
 import { debug, getChalk, log, outputJson, warn } from '../output'
 import { MissingTokenError, resolveToken } from '../utils/auth'
+import { cliFlagFor } from '../utils/option-hint'
 
 /**
  * `deepnote sync` — mirror the workspace's projects into a local directory and pull cloud edits down.
@@ -88,6 +89,22 @@ function describeConflict(conflict: SyncConflict): { question: string; overrideL
   }
 }
 
+const keptDeletedFilesHint = (flag: string) =>
+  ` Run sync ${flag} to remove them; pushing an edited copy restores that file in Deepnote.`
+
+function withFlagHint({ hint, ...outcome }: ProjectSyncOutcome): ProjectSyncOutcome {
+  if (outcome.detail === undefined) {
+    return outcome
+  }
+  if (hint) {
+    return { ...outcome, detail: `${outcome.detail} (use ${cliFlagFor(hint)} to remove)` }
+  }
+  if (outcome.action === 'pruned') {
+    return { ...outcome, detail: `${outcome.detail} (${cliFlagFor({ option: 'prune', value: true })})` }
+  }
+  return outcome
+}
+
 function promptForConflict(conflict: SyncConflict): Promise<SyncConflictDecision> {
   const { question, overrideLabel } = describeConflict(conflict)
   return select({
@@ -141,11 +158,15 @@ export async function runSync(dir: string | undefined, options: SyncOptions): Pr
         break
       case 'project-outcome':
         if (!isMachineOutput) {
-          log(renderOutcomeLine(event.outcome))
+          log(renderOutcomeLine(withFlagHint(event.outcome)))
         }
         break
       case 'warning':
-        warn(event.message)
+        warn(
+          event.code === 'deleted-files-kept'
+            ? event.message + keptDeletedFilesHint(cliFlagFor(event.hint))
+            : event.message
+        )
         break
       case 'file-transferred':
         debug(
@@ -157,7 +178,7 @@ export async function runSync(dir: string | undefined, options: SyncOptions): Pr
     }
   }
 
-  return syncWorkspace({
+  const result = await syncWorkspace({
     rootDir,
     baseUrl: options.url ?? DEFAULT_API_URL,
     token,
@@ -169,6 +190,7 @@ export async function runSync(dir: string | undefined, options: SyncOptions): Pr
     onConflict,
     onEvent,
   })
+  return { ...result, projects: result.projects.map(withFlagHint) }
 }
 
 function renderOutcomeLine(outcome: ProjectSyncOutcome): string {