Records, references and templates

Read this before persisting a new record or preparing an import. Store one record per Markdown file. Large transcripts/media are linked files, not giant frontmatter values. Credential values are not records: keep them in the host's protected credential storage.

Vocabulary

LOG historical event/report; RDT research; FDK exact feedback; TSK task; ART artifact collection; SRT variant; PIC/VID/AUD/FIL media; DOC specification, decision, glossary, handoff or verified documentation; SES session; MEM durable memory; MIL delivery evidence; IDE idea. Use relationships such as specification, research, decision, attachment, depends_on, task, evidence, collection and supersedes. Prefer returned UUIDs in links and human refs in prose.

Project-local refs use four-digit-minimum counters, e.g. TSK-0001, growing past 9999. Global workspaces prepend their unique 2–3-letter code, e.g. AB-TSK-0001. A variant is ART-0001-SRT-01, not a separate unrelated collection. Keep UUIDs/ref/type/workspace fixed on update. For several repositories in one companion, use global mode and unique codes; do not initialize independent histories for worktrees or silently renumber existing files after a collision.

Managed Markdown

The current frontmatter contract is schemaVersion=1, id UUID, ref, workspaceId UUID, type, title, status, tags[], links[{id,relation}], visibility, revision positive integer, createdAt/updatedAt ISO UTC, provenance{actor,source,sessionId?}, and data{}. The formatted Markdown body follows the frontmatter. Have the writer allocate metadata; do not paste this example as a new record with reused IDs.

Task data includes kind (feature/bug/improvement/research/documentation), priority (Low/Normal/High/Urgent), baseRef, acceptanceCriteria[], checkCommands[{file,args[]}], timezone and optional selected agent{provider,model,effort,mode}. Current companion checks accept node/npm/pnpm structured argument arrays, not arbitrary shell strings. Repository instructions may specify additional checks for the assigned agent to run directly.

Visibility and learning

Default private means eligible for selected-workspace private cloud synchronization. Local means no cloud copy, but local model access is possible. Never-copy means no agent/cloud use; do not quote it in another record, summary, transcript or brief. Public is a record value, not authorization to publish it on the portfolio. Redaction is best effort and cannot replace these scope/consent decisions.

FDK preserves the exact feedback body and context; create another FDK for a new prompt, rather than rewriting the original. Put the extracted lesson, confidence, applicability, scope and evidence in data/body sections as supported. FDK/MEM can remain proposed. Automatic application is bounded by the runtime, not by an agent declaring a lesson safe. Supersession retains history, source and rollback; never delete a conflicting memory to make it disappear.

Body patterns

Research: question; finding; claim/source/version/retrieved-date table; confidence; contradiction; unknowns; decision implications; next experiment.

Specification: problem/outcome; scope; settled decisions and glossary; behavior/interfaces; failure states/privacy; acceptance and verification; dependencies; unresolved decisions. Mark assumptions explicitly.

Task: outcome; brief/context; acceptance criteria; dependencies; allowed scope/worktree; selected artifact; verification; review report. A small slice demonstrates behavior, not merely a layer or folder.

Review LOG/DOC: task/spec refs; base/head and dirty diff; criterion/result/evidence table; actual commands, exits and output paths; changes; findings; limitations; proposed documentation changes; next owner action.

Memory: fact/preference; reason retained; applicability/scope; source/confidence; sensitive review state; supersedes/supersededBy. Handoff: destination; settled decisions; actual state; evidence; blockers; exact next action and context to load.

Working without the dashboard

An installed companion and MCP work without a website. Otherwise use node <installed-zen>/scripts/records.mjs --root <data-directory> <command> --input <request.json>. The standalone reference describes file-only initialization, writer locking, history, revision checks, recovery and companion adoption. It refuses existing managed SQLite directories. If the router/runtime is not installed with an individual mode, produce a labelled draft with no fabricated ID and request/install the common router only if persistence is needed.