---
kind: knowledge
when-and-why-to-read: When you hit a question about how the crtr runtime itself works or how to extend it — how nodes and the canvas behave, where state lives on disk, how to add plugins/commands/marketplaces to crtr, or how the primitives compose into real systems — this index should be read so runtime-sensitive work follows the canonical model instead of fragile inferences from scattered command help.
short-form: internal/ is the runtime's self- and developer-documentation — operational guides to nodes/canvas and the storage tiers, plugin/marketplace/command-plugin authoring, plus worked example compositions. Open it to understand how crtr works or to extend it.
system-prompt-visibility: preview
file-read-visibility: none
---

# internal/ — how the crtr runtime works, and how to extend it

This directory is the runtime's **self- and developer-documentation**: operational references covering how crtr behaves and how to extend or reconfigure it, so any agent operating under it can route to the canonical model rather than reconstruct it from scattered `-h` output. It ships with crtr.

Open this dir whenever a task turns on understanding the runtime itself or changing what it can do. Contents:

- **nodes-and-canvas** — the agent-runtime model: nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle (mode + lifecycle axes), and revive (manual + daemon auto-revive).
- **storage-tiers** — where every kind of state lives: the two tiers (scope root and canvas home) and their durability/ownership contracts.
- **agent-shaping** — the when-to-use-which layer over the four dials that shape a node: kinds (the builtin roster, sub-kinds, and custom personas), modes (base vs orchestrator), profiles, and the memory tiers (node/profile/project/user/builtin).
- **plugins** — authoring a crtr plugin: the plugin.json manifest, directory layout, scopes, install mechanics, versioning, command plugins (contributing top-level CLI commands via commands.json + one executable), and configured CLIs (contributing commands as definition + HTTP from a remote manifest, no executable).
- **marketplaces** — authoring a crtr marketplace: the marketplace.json index, plugin entries, symlink-based install, auto-bump CI, dual-publishing.
- **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.

Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on that `-h` surface so it surfaces exactly when you write.

Briefly: **plugins** (local command/doc packages), **marketplaces** (indexes that distribute plugins), and **configured CLIs** (remote-defined command surfaces fetched from a backend HTTP endpoint, stored locally, and rendered as native crtr commands — a simpler, non-executable alternative to command plugins for definition-only backends). All three discovery paths live on the **external-command** fallthrough, leaving the core fast-path untouched.

The individual files surface at `name` (their titles route; open the one the situation calls for); this index surfaces at `preview` so the dir announces when to come looking.