--- title: Spaces and Pages description: Write Markdown Pages, link them to projects, and work on them with agents. sidebar: order: 6 --- 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](/docs/using-carbon/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. ## Write Markdown 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: ```sh carbon pages list --project /path/to/project carbon pages search "release plan" carbon pages read carbon pages read --version 3 carbon pages update --revision 3 --file plan.md carbon pages history ``` 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.