Every Application node in a CharmIQ document has two built-in storage channels. They serve different purposes and behave differently under concurrent access. Choosing the right one matters.

 is one or more named texts attached to your Application node, each an app-content. They are managed by CharmIQ's Operational Transform (OT) system — the same system that handles collaborative text editing in the rest of the document. Multiple writers (users, Charms, other Applications, MCP clients) can write to the same app-content. See 

 is a single JSON blob attached to your Application node. It uses last-write-wins semantics: the most recent write replaces the previous value entirely. There's no merge — just replacement.

Both are your Application's own: reading and writing them needs no declaration and no permission.

The rule of thumb: if two people or processes might write to the same data at the same time, use app-content. If you're storing configuration that one writer controls at a time, use app-state.

An Application can have several app-contents, each named or identified by a stable node ID. It reads and writes each one as it stands: its text, with the writes measured on it.

// the Application's app-content (its first), kept current: null while there is none
window.charmiq.appContent.content$().subscribe(content => {
  show(content ? content.text : 'Nothing yet');
});

// a named app-content
window.charmiq.appContent.content$("[name='editor']").subscribe(content => { /* … */ });

 gives the app-content as it stands now, then again every time anyone changes it, your own writes included. It is 

 while no app-content matches, and becomes 

 the moment the app-content is removed: the Platform knows exactly when, so there is nothing to check. Once an app-content is removed, the next app-content the selector names is followed. A read that fails errors the stream with its 

 (the text as lines, without the line break that ends each).

Every write is made through the app-content you were given, and measured on it. If the app-content has changed since, the write is refused whole with 

 and nothing is written, so a write never lands on text it wasn't measured on.

await content.appendLine('Jam');          // adds a line after the last
await content.removeLine(0);              // removes the first line, with its line break
await content.replaceLine(1, 'Tea');      // replaces the text of a line
await content.setLines(['Milk', 'Tea']);  // makes the app-content these lines, writing only the runs that differ
await content.edit([{ from: 0, to: 4, insert: 'Oat milk' }]);  // any range, each edit measured after the ones before it

 puts a line break first when the last line has none, and if another writer got there first it is measured again and sent again on its own: adding a line never depends on what the app-content held. Every other write is the caller's to retry, because only it knows whether its intent still holds. 

 writes only the runs of lines that differ, so another writer's change to a line you kept stays; when the lines differ too much to tell which stayed the same, it is refused (

) and nothing is written — change them with 

 instead. Every edit must lie inside the app-content; an edit outside it is refused (

const log = await window.charmiq.appContent.create('', 'log');  // the app-content named log: a new one, or the one already there
await log.remove();  // refused if it changed since

 never writes an app-content that exists, empty or not: when one of that name is there, it is returned with its text. Two collaborators creating one at the same moment each make one; 

 replaces an app-content's whole text (and creates one when the selector matches none): anything another writer changed meanwhile is lost, so use it only to replace everything on purpose.

You are never the only writer. A user in another tab, a Charm, another Application or an MCP client can change an app-content while you do. Because every write is measured on the app-content it is called on, none lands on text it wasn't measured on. Two rules keep everyone's work:

On a refusal, decide again from the app-content as it is now. A removal or a replacement was the user's choice about a line that may have moved, so show the list again and let them choose.

The guard is narrow. Your writes never land on text they weren't measured on, but it is not a lock: two writers' writes can both apply, each to the text it saw, and the document merges them as it merges any edits. A resolved write means the editor applied your edit, not that it has been saved yet.

A page loaded by an older Platform has no 

: ask the user to reload rather than writing another way.

A live text editor sends a change on every keystroke, and the user keeps typing before the last one is confirmed. A snapshot cannot say which of the editor's own edits a new revision holds, or where its unconfirmed typing belongs in another writer's change. Comparing texts is a guess, and a guess drops or duplicates text. For this case the Platform adds two things:

The editor keeps three things apart: the text the document has confirmed, the batch it has sent, and what the user typed since. Each change from someone else rebases the last two over it. That is a collaborative editing model's job, never a comparison of snapshots. The CodeMirror Editor (

 in the CharmIQ Applications repository) is the worked example: it runs CodeMirror's collaboration library over these, and its Charm command waits for its write.

 When the text can no longer be saved (the app-content was removed, a write was refused, an edit was missed, or the page cannot follow edits), keep every character in the editor, read-only, and say why. Offer to copy the text and reload; never discard it, and never send a write again when its result is unknown.

// every app-content, each one you can write through
window.charmiq.appContent.contents$().subscribe(contents => renderTabs(contents));

// every app-content of a name: a second one is visible, never hidden behind the first
window.charmiq.appContent.contents$("[name='model']").subscribe(models => {
  if (models.length > 1) say('This document has two models.');
});

 are built over primitives that stay for what they do not cover: 

 (each change; with no selector, every app-content; its 

 notice is a reason to check, not proof), 

 (guarded edits: the guard is a snapshot's 

 and the write tag (for a live text editor), and 

App-state is a single JSON object. The entire object is replaced on each write — there's no patch or merge.

// Read current state
const config = await window.charmiq.appState.get();
// → { theme: 'dark', language: 'javascript', fontSize: 14 }

// Watch for changes (fires immediately with current state)
window.charmiq.appState.onChange$().subscribe(state => {
  applyTheme(state?.theme ?? 'light');
});

// Write (replaces the entire object)
await window.charmiq.appState.set({
  theme: 'light',
  language: 'python',
  fontSize: 16,
});

If two users change app-state simultaneously, the last write wins. The other write is lost. This is fine for settings panels where one user is in control — it's not fine for data that accumulates or that multiple processes write concurrently. Use app-content for that. Rule 1 still holds: show what 

Node IDs are stable across sessions and renames. Names can change. If you need a reliable reference to a specific app-content, use its ID.

 always act on your own Application, in this instance, and on nothing else. Two copies of the same Application in one document each keep their own. To work with another Application, use what it advertises: see 

. Another Application reaches your data only the way any tool does: through authorized Platform APIs, including Commands and MCP, with the User's consent.

App-contents are visible to external tools via MCP. Any MCP client with write access — Claude Code, a VS Code extension, a Zapier workflow — can append to or replace an app-content in your Application. This is how external data pipelines feed into Applications: the external tool writes structured records (JSONL works well) and your Application watches for changes.

App-state is also readable and writable via MCP.

 API reference including appContent, appState, OAuth, and MCP.

 — How Applications share data with each other inside a document.

The two storage channels every Application has — when to use each and how to avoid the pitfalls.

Use Case	Channel	Why
Editor content	`appContent`	Multiple users may edit simultaneously
Form data that accumulates	`appContent`	Append-safe with OT
JSONL records from an external source	`appContent`	External tools can append via MCP
Theme or language preference	`appState`	Simple config, last-write-wins is fine
Toggle states, layout settings	`appState`	Non-collaborative settings
Active tab, selected item	`appState`	UI state, single writer

Selector	Matches
(none)	`content$()`, `get()`, `set()`, `applyChanges()`, `remove()`: the first app-content. `contents$()`, `onChange$()`: every app-content
`[id='kRP9xNbCmQ']`	App-content by stable document node ID
`[name='editor']`	App-content by name attribute
`[0]`, `[1]`	App-content by position (zero-indexed)

Developer | App-Content and App-State

The Two Channels

App-Content

Reading an App-Content

Writing an App-Content

Creating and Deleting an App-Content

Collaborating

A Live Text Editor

Several App-Contents

The Primitives

App-State

Selectors Reference

Whose Data

External Access

Next Steps