René's URL Explorer Experiment

Title: docs(skill): add an app-models reference and fix the skill sync map by jamesbhobbs · Pull Request #509 · deepnote/deepnote · GitHub

Open Graph Title: docs(skill): add an app-models reference and fix the skill sync map by jamesbhobbs · Pull Request #509 · deepnote/deepnote

X Title: docs(skill): add an app-models reference and fix the skill sync map by jamesbhobbs · Pull Request #509 · deepnote/deepnote

Description: "Build me a Deepnote app" has five different answers, and the skill said which one to pick nowhere. An agent had to assemble the picture from cli-publish.md, examples/local-runner/cloud-app/README.md, examples/local-runner/run-app/README.md, and the local-runner package docs — and the only place that mentioned app tokens at all was the publish reference, describing the CLI flag rather than the boundary behind it. skills/deepnote/references/apps.md Five models, each with what it is made of, where it runs, who hosts it, and what credentials it gets: Data apps (notebook apps) — notebook blocks presented through Deepnote's app UI. Not deprecated, not a fallback; an agent contributes the notebook, not the app. Streamlit apps — a .py entrypoint on project hardware. Hosted MCP can activate an existing entrypoint but cannot upload or author the file, so a "build a Streamlit app from scratch in a hosted project" plan does not work. Published static sites — browser files below _deepnote_static/**, deployed by deepnote publish, which owns that namespace. Published browser apps with API access — the same, plus a viewer token. Local Node-backed apps (serveStatic) — a local server runtime, with the complete five-route contract documented. A decision table opens the file, keyed on the questions that change the plan: notebook blocks vs. custom HTML/JS vs. Python, browser-only vs. local Node server, viewer API access, project hardware, and whether an agent can create the underlying files with its current tools. The two boundaries worth the file Publishing ownership. publish owns _deepnote_static/**; the canonical URL comes from the API, never hand-assembled. The viewer token. A published app never carries the personal token used in local preview. The shell hands it a short-lived, project- and viewer-scoped token over an origin-pinned postMessage handshake, limited to: read the configured notebook's inputs and block metadata without source content, start a detached run, poll that viewer's own run by id, receive sanitized snapshotBlocks. Not notebook enumeration, not run-history enumeration, not arbitrary /v2. The failure mode is silent — the same code works locally with a personal token — which is why examples/local-runner/cloud-app guards on isEmbedded. AGENTS.md The sync section said MCP tool changes go in skills/deepnote/references/cli-*.md "(MCP mirrors CLI commands)". That is wrong in both directions: @deepnote/mcp has tools with no CLI equivalent, and the CLI has commands (publish, sync, install-skills) with no MCP tool. It routed local-MCP changes into the CLI references. Replaced with a map from each surface to its owning document, distinguishing three things that get conflated: local @deepnote/mcp, hosted MCP at deepnote.com/mcp, and the codex-plugin consumer of the hosted server. Scope Documentation only. cli-sync.md, cli-publish.md, CLI implementation, public docs, and MCP implementation are deliberately untouched — they are moving in #492, #508, and #491. Relationship to #508 No conflict, and no merge order. The two PRs touch disjoint files (#508 is CLI/cloud source plus cli-publish.md and cli-sync.md; this is AGENTS.md, SKILL.md, and the new reference), and apps.md no longer describes the publish/sync coordination as pending. Note that #508 resolves the overlap by sharing one baseline rather than excluding _deepnote_static from sync --all-files, so this file states only the part an app author needs — publish is the deploying writer for the static root — and defers the mechanism to the CLI references, which #508 owns. Validation pnpm test (3086 passed, 1 skipped), pnpm typecheck, pnpm biome:check, pnpm prettier:check, pnpm spell-check all clean. Biome reports 8 noConsole warnings in examples/local-runner/*/serve.mjs, all pre-existing and untouched here. Packaging verified end to end rather than assumed: pnpm build copies the new reference into packages/cli/dist/skills/deepnote/references/, and deepnote install-skills --agent "Claude Code" in a scratch directory installs apps.md alongside the rest. No skill validator (quick_validate.py) or skill-creator skill is present in this checkout, so that step could not be run. 🤖 Generated with Claude Code

Open Graph Description: "Build me a Deepnote app" has five different answers, and the skill said which one to pick nowhere. An agent had to assemble the picture from cli-publish.md, examples/local-runner/cloud-a...

X Description: "Build me a Deepnote app" has five different answers, and the skill said which one to pick nowhere. An agent had to assemble the picture from cli-publish.md, examples/local-runner...

Opengraph URL: https://github.com/deepnote/deepnote/pull/509

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width