Notion mode

Source of truth: skills/_shared/storage-resolution.md and the storage section of the config reference. Notion mode is a per-repo opt-in that stores Cadence’s artifacts in Notion instead of the local filesystem.

What Notion mode is

By default Cadence keeps brainstorm stubs, designs, and plans as markdown folders in your repo. Notion mode moves those three artifact types into two Notion databases instead: a Designs database and a Plans database, both under one Notion page you own. Every /c-* command then reads and writes its artifacts as Notion pages rather than files.

Source code and git commits are unaffected. Only the Cadence artifacts (the docs, their frontmatter, and their checkboxes) move to Notion. In Notion mode Notion is canonical: there is no on-disk copy of a design or plan, and plan progress shows live on a Notion board as /c-execute ticks tasks off.

Requires the official Notion MCP and an integration token

Notion mode runs on Notion’s official MCP (developers.notion.com/guides/mcp) for reads, queries, and property writes, and on a small bundled script that pushes doc bodies to Notion’s REST API using a NOTION_TOKEN environment variable you provide. Cadence stores no Notion token anywhere: the MCP holds its own credential, and NOTION_TOKEN lives only in your environment. It requires that specific MCP because it relies on the MCP’s documented block format to render callouts, cross-references, and diagrams as native Notion content; the MCP’s per-install server id is resolved at runtime, so nothing Notion-specific is pasted into config. If a repo is in Notion mode and the official Notion MCP is not found, or NOTION_TOKEN is unset when a doc write is needed, Cadence stops with an actionable message. It never silently falls back to the filesystem.

Setup

1. Install the official Notion MCP. Add Notion’s official MCP (developers.notion.com/guides/mcp) to your session if it isn’t already present. This is the specific MCP Notion mode requires.
2. Point at a root page. In .cadence/config.yaml, set storage.backend: notion and storage.notion.root_page to a Notion page URL or id you own. Leave storage.notion.designs_db and storage.notion.plans_db empty.
3. Share the page with the integration. In Notion, share that root page with the integration the official Notion MCP uses, so it can create databases and sub-pages under it. This grant is the one setup step Cadence cannot do for you.
4. Create an internal integration and export its token. Doc bodies are written by a bundled script over Notion’s REST API, authenticated separately from the MCP. Create an internal integration at notion.so/profile/integrations with content read/insert/update capabilities, share the same root page with it, and export its token as NOTION_TOKEN in the environment Claude Code runs in. The token never goes in config. To keep it out of plaintext files entirely, set NOTION_TOKEN_CMD instead: a command whose output is the token, such as a macOS Keychain lookup (security find-generic-password -s notion-pat -w) or a 1Password CLI op read. NOTION_TOKEN wins when both are set. Solo shortcut: a Notion personal access token also works as NOTION_TOKEN. It acts as you and inherits your own permissions, so it needs no sharing step on any page; internal integrations stay the recommended default for teams because they are workspace-owned and least-privilege.
5. Run any /c-* command. On the first Notion-mode run, Cadence creates the two databases under the root page, writes their ids back into the committed .cadence/config.yaml, and reminds you to commit so the whole team shares them.

See the storage config keys for the exact YAML. The entire storage block is team policy and belongs in the committed config, never in .cadence/config.local.yaml.

The two databases

Cadence creates and owns both databases under your root page, including their property schema and any future schema changes.

• Designs holds one row per brainstorm stub or design. Its frontmatter becomes properties: Title, Status (a Select), Created / Updated (Dates), Tags (a Multi-select), and a Slug (the stable, machine-owned handle Cadence uses to find the row again). Child docs hang off the row as sub-pages, keeping their NN prefix in the sub-page title so reading order stays legible.
• Plans holds one row per plan, with the same property shape plus a Base SHA. The design-to-plan link is a two-way Relation between the databases (a design’s Linked Plan and a plan’s Linked Design are the two ends of one relation), replacing the linked_plan / linked_design frontmatter fields.

Because designs and plans are database rows with real Status, Date, and Relation columns, Notion’s own status boards, filtered views, and roadmap timelines work over them at no extra cost.

How artifacts render in Notion

Cadence’s callout and cross-reference conventions are semantic, and each backend authors them in its own native syntax, so pages read as first-class Notion content rather than escaped text:

• Callouts (the [!summary], [!success], [!warning] set) are authored directly as native Notion callout blocks in Notion mode, each with a type-specific icon and background color — never as obsidian > [!type] syntax, which Notion would render as escaped literal text. A pre-send guard translates any obsidian-form callout that reaches a write anyway (for example, content drafted before the repo switched modes).
• Wikilinks ([[01-topic]]) become clickable Notion page mentions, resolved in a second pass once every page in the batch exists.
• Mermaid code fences render as native Notion diagrams; standard markdown (headings, lists, tables, code, checkboxes) passes straight through.

The mapping is defined in skills/_shared/notion-translation.md. Plan checkboxes are the load-bearing case: they become real Notion to-do blocks so /c-execute can tick them live.

Doc bodies are written by a script

Cadence writes every doc body with a bundled script (scripts/notion-write.js) that reads the content from a local file and pushes it to Notion’s REST markdown endpoints in a single request, of any size. The script refuses a body carrying untranslated obsidian callout syntax, polls Notion’s async task handling for large pages, retries rate limits, and verifies the read-back length before reporting success, so a clean exit is real evidence the page landed whole.

The reason for the script is client-side rather than anything about Notion. A large tool argument can be sheared while it streams, producing a call that succeeds while carrying a mangled tail (anthropics/claude-code#67765, still open). Earlier Cadence releases managed that risk by capping MCP content writes at roughly 8,000 characters, chunking longer docs, and checking every page by reading it back. The script removes the risk instead: the content travels from a file to Notion in a plain HTTP request and never rides in a streamed tool argument, so there is no cap, no chunking, and no session-poisoning failure mode. Interrupting a write is now harmless; the next write simply replaces the page wholesale.

Mockups stay on disk

Mockups are the one Cadence artifact Notion mode does not move. A design that opts into the 95-visual-contract slot writes its mockup HTML as local files on every backend: no attachment upload, no embedded preview, no download round-trip. The 95 doc in Notion stays the authority on which version is frozen and what the contract says, and records each version’s file:// URL beside its index row; the file itself lives on your machine and opens in a real browser.

Because there is no design folder on this backend to put them beside, /c-design asks once, before writing version 01, where mockups should live, and offers to persist your answer as mockups.dir. .cadence/config.local.yaml is the usual home for it, since that path is machine-specific.

A `file://` link clicked from Notion goes nowhere

Browsers refuse to follow a file:// link clicked from a web page, Notion included. That’s why the URL is recorded as plain text rather than a link: copy it into your address bar when clicking does nothing. It also means mockups don’t travel with the repo: a mockup:NN citation whose file is absent on this machine is reported as a normal missing-Reads: blocker, never guessed around.

What changes and what does not

Changes:

• Designs, plans, and stubs live as Notion pages, not markdown folders. They lose git diff, blame, and PR review of the artifacts themselves; Notion’s page history substitutes.
• /c-execute writes plan progress to Notion. The PM (your main session) is the sole writer, ticking each task’s to-do block and setting status and base_sha after the two-stage review. Notion mode requires network access (the MCP for reads and properties, Notion’s REST API for doc bodies); there is no offline path.

Does not change:

• Source code, tests, and git commits. Implementers and reviewers stay Notion-blind: they receive a task spec as plain text and write code and commits to git exactly as on the filesystem backend.
• The slug stays the human handle; Notion page ids hide behind resolution.
• Mockups. They are local HTML files on both backends, as described above.
• Filesystem repos. A repo that never sets storage.backend: notion behaves byte-for-byte as before. Existing on-disk artifacts in a repo that switches backends stay on disk: Notion mode applies to new artifacts (migrating old ones is out of scope).