Documents

A document is one kind of canvas object. The canvas is one graph of objects: documents, nodes, bash jobs, owners (a person, an app, a repo, a profile) and custom objects registered by outside services. Every object has an id and a name, and the same read verbs work on all of them: crtr canvas read, list, search, watch and edges. Documents are the objects you write; they are written with crtr doc write|edit|move|delete.

Documents shape a node without adding the same instructions to every prompt. A document says what it contains, who owns it, and when it should enter context. The result is durable guidance that can be discovered when relevant instead of a growing startup prompt.

There are two kinds. Knowledge is something an agent consults: a procedure, fact, or technical reference. A preference is behavior the agent should embody: a standing directive or correction. This is a use-based split. A procedure and a fact are both knowledge because the agent reads either one to answer a question; a preference changes how it acts.

Names and pointers

A document's full name is <owner-handle>/<path>, for example 3zl47w7d-…/plan for a node's document or crouter-sdk for a shipped one (path segments are letters, digits, _ and -, joined by /). Point at a document with [[name]]. Inside a document body, each [[link]] attaches the target's preview wherever the body is delivered in full, so a reader sees what the link is for before opening it. A bare name is looked up in the reader's own view first (its node, then its repos, profile and app), then the person's documents, then installed plugins, and the built-in crtr documents last; a <owner-handle>/<path> name is unambiguous. Moving or re-owning a document with crtr doc move keeps its id and every link.

Reading a document with crtr canvas read makes you a watcher: later edits to it are pushed to you, and if you are running they steer you. crtr canvas list and search record nothing. Each edit is a recorded revision with a rationale; an edit made from a stale revision is refused.

Owners

Every document has an owner, and an owner is itself an object.

An installed plugin is an app named after the plugin, and the documentation that ships with crouter is owned by the app crtr; both are public and read-only. Choose the narrowest owner that reaches the next agent who needs the document. For an application author, the profile is the usual owner for knowledge shared by that application's nodes across repositories.

Who may read

Each document is public (the default), friends or private. The person reads everything, a repo owns only public documents, and a reader that cannot see a document gets the same answer as for one that does not exist. A node's own owner space is open to it; an app's access to the person's documents is by privacy level and the scopes its grant holds (see Scopes and trust).

Delivery rules

A delivery rule is the delivery mechanism. A document is not loaded because of its name or because its preview resembles the task. Each rule names an activity — boot, workspace-open, file-read, document-read, command, pre-command or slash-command — and can match a path or command, carry an if on the node's shape (kind, mode, lifecycle, cwd, repo, profile, depth), and selects what to deliver: the name, the preview, or the full content. When several rules deliver the same document, the highest delivery wins (content over preview over name), and content delivery counts as a read. A document with no delivery rule stays in its listing until an agent deliberately finds or reads it.

The preview is delivered at the middle level, not a trigger. For example, a profile document can have a file-read rule that delivers its preview when an order record is opened. Its line — “When handling a refund request, read this because the eligibility window is not in the order record” — then tells the agent why an explicit full read is useful. The rule delivers the preview; the line helps the agent decide whether to read the body without pretending to replace it.

Documents therefore support progressive disclosure. You can record knowledge freely, but it costs future contexts only when a delivery rule delivers it. Read crtr doc write -h to write a document (and crtr doc write --rule -h and --owner -h for rules and owners) and crtr canvas read internal/memory-loading for the delivery mechanics.