Spaces and Pages

Write Markdown Pages, link them to projects, and work on them with agents.

Spaces and Pages are currently behind a feature flag and off by default. The instructions below apply when Pages is enabled for testing. Profiles remains available.

Open Spaces from the sidebar or press ⌘P. Spaces is Carbon’s document workspace. Its documents are called Pages.

Project and session grouping is now called Profiles. Existing groups and settings are kept.

Create and organize Pages

Click Create to write a Page. Use Link project to associate it with one or several projects. Every project link points to the same document. A Page can also stand on its own.

Search finds words in titles and document bodies. Use Favorites, Recent, project filters, or the list and grid controls to find your work. Trash keeps deleted Pages available to restore.

Pages belong to their Carbon server. A remote Page remains on its server; linking it to a project does not copy it into a repository or worktree.

The rich editor supports headings, formatting, nested lists and checklists, links, images, tables, code blocks, and formulas. Type / to insert a block. Select text to format it. Code blocks retain their language, including Mermaid diagram source.

Use Markdown source to edit the underlying text and Preview Page to read it. Source mode preserves constructs outside the rich editor’s schema, including HTML, frontmatter, footnotes, reference links, and callouts. Pages larger than 32 KiB open in source mode to keep editing responsive. A Page body can hold up to 256 KiB.

Changes save automatically. ⌘S saves immediately. If another writer changes the Page, Carbon keeps your draft and offers a comparison. Saving your version requires the revision you reviewed; another intervening edit raises another conflict.

History and references

Open Version history to inspect earlier revisions. Restore writes a new revision and retains the Page’s current project links, favorite, and Trash state.

Use in task adds a saved Page reference to the composer. You can also choose Reference a Page from the composer’s context menu. Conversation references cite a specific revision. Opening one shows that saved content, with an action to open the current Page.

Use Link another Page inside a document for a live link. Linked from lists Pages that refer to the document.

Attachments and previews

Attach files from the Page toolbar. Images can appear inline; file links open a preview where the file type supports it. Preview renders formulas and Mermaid diagrams. Attachments can be up to 20 MiB and stay available independently of sessions and worktrees.

Agent access

Agents use the same managed documents and revision checks as the editor:

carbon pages list --project /path/to/project
carbon pages search "release plan"
carbon pages read <page-id>
carbon pages read <page-id> --version 3
carbon pages update <page-id> --revision 3 --file plan.md
carbon pages history <page-id>

Use carbon pages --help for attachment, backlink, history, and sync commands. Reads return the revision needed by a write. A stale write leaves the document unchanged.

Linear documents

Choose Create → Import from Linear to link a Linear document as a Page. The Page’s source controls show its sync status and let you open the original or unlink it while retaining the Carbon Page.

Linked documents sync in both directions. Page links and attachments stay in Carbon; syncing their Markdown does not upload their files to Linear. If both sides changed, Carbon preserves both versions and asks which to keep. Linear does not provide an atomic conditional document update, so a write checks the remote version immediately before sending; this cannot eliminate a remote edit in the narrow interval between that check and the update.