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 text blocks attached to your Application node. These blocks 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 block simultaneously and their changes merge correctly. No data loss. No last-write-wins collision.

 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.

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 multiple app-content blocks, each identified by a name or a stable node ID. The 

 observable fires immediately with the current content, then again on every change — from any source.

// Single block (default)
const text = await window.charmiq.appContent.get();

// Named block
const code = await window.charmiq.appContent.get("[name='editor']");

// By stable node ID (most reliable across renames)
const text = await window.charmiq.appContent.get("[id='kRP9xNbCmQ']");

// Watch the default block
window.charmiq.appContent.onChange$().subscribe(change => {
  console.log(change.content); // current text
  console.log(change.id);      // stable node ID
  console.log(change.name);    // name attribute (if set)
});

// Watch all blocks — fires once per block on init, then on add/remove/change
window.charmiq.appContent.onChange$().subscribe(change => {
  if (change.deleted) {
    // Block was removed
  } else {
    // Block was added or updated
  }
});

 replaces the full content of a block. It creates a new block if the selector doesn't match anything.

// Replace entire content
await window.charmiq.appContent.set('Hello, world!');

// Replace a named block
await window.charmiq.appContent.set(newText, "[name='output']");

// Create a new named block
await window.charmiq.appContent.set('', "[name='log']", 'Log');

 sends incremental edits through the OT pipeline. Use this for editor-like Applications where the user is actively typing — it produces minimal diffs that merge better with concurrent edits.

await window.charmiq.appContent.applyChanges([
  { from: 0, to: 5, insert: 'Goodbye' },  // Replace chars 0–5
  { from: 20, to: 20, insert: ' world' }  // Insert at position 20
]);

await window.charmiq.appContent.remove("[name='log']");

When your Application writes to app-content, the change comes back through 

. Without a guard, you create an infinite loop: write → notification → write → ...

let updating = false;

window.charmiq.appContent.onChange$().subscribe(change => {
  if (updating) return;
  updating = true;
  editor.setValue(change.content);
  updating = false;
});

editor.on('change', () => {
  if (updating) return;
  window.charmiq.appContent.applyChanges(computeDiff(editor));
});

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.

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

App-content blocks 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 block 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)	First/default app-content block
`[id='kRP9xNbCmQ']`	Block by stable document node ID
`[name='editor']`	Block by name attribute
`[0]`, `[1]`	Block by position (zero-indexed)

Developer | App-Content and App-State

The Two Channels

App-Content

Reading Content

Watching for Changes

Writing Content

Deleting a Block

The Update Loop

Multi-Block Pattern

App-State

Selectors Reference

External Access

Next Steps