Cuaderno

Cuaderno (cdno) is a command-line vault manager for the Research Logbook Method (RLM) — a way of running long-horizon knowledge work out of a folder of plain Markdown files. It is built for researchers and other deep-work practitioners, and is deliberately friendly to ADHD working styles: it leads with what is there, not what is missing — no guilt counters, no angry overdue badges, explicit permission to park or drop work.

You drive it from a terminal, and an AI assistant (Claude and other MCP clients) can drive it too, through the bundled MCP server.

What it gives you

• A dated, append-only log as the single source of truth for what you did.
• Projects with a current state, next actions, milestones, and waiting-on items — capped at five active at a time so you can’t overcommit.
• Evidence portfolios: per-question dossiers that accumulate papers, experiment results, and notes over months and years.
• Important questions kept front-and-centre and re-read often.
• Stewardships: small, bounded, long-haul responsibilities (health, finances) with optional habit tracking.
• A commitments register — promises with dates, aggregated from everywhere they live.
• Full-text search, frontmatter linting, and a JSON mode so every read and write verb is scriptable.

Two ways to use it

Both operate on the same Markdown vault — the files on disk are always the source of truth (the SQLite index is just a rebuildable cache).

How this guide is organised

• Getting started — install, create a vault, run the daily loop, and wire up Claude.
• Concepts — the mental model: the method, the twelve note types, the vault layout, and the rules the tool enforces.
• Tutorials — task-oriented walkthroughs of each workflow.
• CLI reference — every command, flag, and example.
• MCP server reference — every tool exposed to AI clients.
• Appendix — JSON shapes, frontmatter fields, the full config file, recurrence syntax, and troubleshooting.

This guide documents the shipped behaviour of Cuaderno. New to it? Read The Research Logbook Method for the why, then jump to the Quickstart for the how.

Installation

Cuaderno ships two binaries:

• cdno — the command-line tool for the daily loop.
• cdno-mcp — the MCP server that lets Claude (and other MCP clients) read and write your vault.

Both are installed together.

Homebrew (macOS and Linux)

The recommended path. Pre-built bottles exist for macOS (Apple Silicon + Intel) and Linux (x86_64 + aarch64).

brew install agustinvalencia/tap/cuaderno

Verify:

cdno --version      # -> cdno 0.1.24 (or newer)
cdno-mcp --version

To upgrade later:

brew upgrade cuaderno

From source

Use this on platforms without a bottle, or to track the latest main. You need a Rust toolchain.

git clone https://github.com/agustinvalencia/cuaderno
cd cuaderno
cargo build --release --bins
# Binaries land at target/release/cdno and target/release/cdno-mcp

Put them on your PATH — for example:

ln -s "$PWD/target/release/cdno"     /usr/local/bin/cdno
ln -s "$PWD/target/release/cdno-mcp" /usr/local/bin/cdno-mcp

Shell completions (optional)

cdno can print a completion script for your shell, with vault-aware suggestions (it completes project, portfolio, and stewardship slugs by re-invoking the binary on TAB):

# zsh — add to your ~/.zshrc:
source <(cdno completions zsh)

Supported shells: bash, zsh, fish, elvish, powershell. See completions for per-shell setup.

Uninstall

brew uninstall cuaderno          # if installed via Homebrew
# or, for a source build, remove the symlinks you created:
rm -f /usr/local/bin/cdno /usr/local/bin/cdno-mcp

Uninstalling the binaries never touches your vault — it’s just Markdown files on disk. Delete the vault directory yourself if you want it gone.

Next step

Create your vault: Initialise a vault.

Initialise a vault

A vault is just a directory of Markdown files with a .cuaderno/ config folder at its root. Create one with cdno init:

cdno init ~/notebook
cd ~/notebook

This scaffolds the full folder tree, writes a default .cuaderno/config.toml (which declares the concept type), and writes two starter templates into .cuaderno/templates/: daily.md and concept.md. Every other note type renders from its built-in template until you add a file for it there. What you get:

~/notebook/
├── journal/          # daily + weekly notes, partitioned by year
│   └── 2026/         #   e.g. journal/2026/daily/2026-04-25.md, journal/2026/weekly/2026-W17.md
├── projects/         # project maps (max 5 active)
│   ├── _parked/      # inactive projects
│   └── _done/        # closed projects, partitioned by year
├── actions/          # manifest action notes (the heavy form)
│   └── _done/        # completed actions, partitioned by year
├── portfolios/       # evidence dossiers, one folder per question
├── stewardships/     # long-haul responsibilities (flat file or folder)
├── commitments/      # standalone promises with deadlines
│   └── _done/        # fulfilled commitments
├── questions/
│   ├── research/
│   └── life/
├── inbox/            # quick captures awaiting triage
├── concepts/         # the concept library (a custom type init declares)
└── .cuaderno/
    ├── config.toml   # vault configuration
    └── templates/    # note templates (override the built-ins here)

See Vault structure for what each folder holds.

Running cdno from anywhere

You rarely need to be at the vault root. cdno finds the vault by walking up from your current directory until it sees a .cuaderno/ folder — so commands work from any subdirectory.

When you’re outside any vault, two fallbacks apply, in order:

1. The --vault <PATH> flag (highest priority — overrides everything).
2. The CUADERNO_VAULT_PATH environment variable.

# From anywhere, target a specific vault:
cdno --vault ~/notebook log "spotted a bug in the sampler"

# Or set it once for the shell session:
export CUADERNO_VAULT_PATH=~/notebook
cdno log "spotted a bug in the sampler"

If you’re standing inside vault A while CUADERNO_VAULT_PATH points at vault B, the directory you are in wins — writes land in A. The env var is only a fallback for when discovery finds nothing.

Upgrading an older vault

cdno init refuses to run on a vault that already exists: re-initialising is destructive, so it is never done for you. When a newer cdno ships a note type that init now declares, add it to your existing vault instead:

cdno config note-type install --list             # what ships, and whether this vault has it
cdno config note-type install --name concept

It writes the type’s template, its folder and its declaration, each only when absent. A declaration you already have, or a template you have edited, is kept and reported, never overwritten, so the command is safe to re-run; it ends with concept: already installed, nothing to do when there is nothing left to write. Add --dry-run to see exactly what it would write first. See Installing a bundled note type.

Back up your vault

A vault is just Markdown files (the SQLite index in .cuaderno/index.db is a rebuildable cache — see Business rules). The simplest, most durable backup is version control: git init the vault and commit as you go, or keep it in a synced folder.

cd ~/notebook
git init && git add . && git commit -m "Initial vault"
# The index is regenerated on demand, so it's safe to ignore:
echo ".cuaderno/index.db" >> .gitignore

Because the Markdown is the source of truth, your history is just your commits — nothing is locked inside a proprietary store.

Next step

Run your first daily loop: Quickstart.

Quickstart: the daily loop

This is Cuaderno in five commands. It assumes you’ve installed cdno and created a vault. Run these from inside the vault (or with --vault).

# 1. Start a project (capped at 5 active).
cdno project create --title "Surrogate model" --context work

# 2. Give it a next action, tagged by the energy it needs.
cdno action add --project surrogate-model \
                --title "Run feature set B on the full mesh" \
                --energy deep

# 3. Record a promise with a deadline.
cdno commit create --title "Pay rent" --due 2026-06-01 --context personal

# 4. Each morning: see what's due, your active projects, and a suggested start.
cdno orient --energy deep

# 5. Mark the action done when it's finished (substring match on the bullet).
cdno action complete --project surrogate-model --query "feature set B"

Throughout the day, the two verbs you’ll reach for most:

cdno log "scaled the mesh to 2M cells; runtime 4x, still stable"   # append to today's log
cdno capture "check whether Chen 2025 used the same preconditioner" # drop a thought into the inbox

Interactive vs. scripted

Every write command follows the same convention (see CLI overview):

• In a terminal, omit a required flag and cdno prompts you for it, then asks you to confirm before writing.
• In a script, pipe, or with --no-interactive, a missing required flag is an error instead — so automation never blocks on a prompt.

# Interactive: cdno asks for the title and context.
cdno project create

# Scripted: everything supplied, no prompts.
cdno project create --title "Surrogate model" --context work --no-interactive

Machine-readable output

Add --json to any read or write verb to get structured output instead of a formatted table. Read verbs emit their listing/detail; write verbs emit a { "path": ..., "message": ... } result and run non-interactively. Great for scripts and for piping into jq.

cdno project list --json | jq '.[].slug'
cdno project create --title "Surrogate model" --context work --json
# -> { "path": "projects/surrogate-model.md", "message": "Created projects/surrogate-model.md" }

See JSON output for the full shapes.

Where to go next

• Understand the model: The Research Logbook Method.
• Work through each workflow: Tutorials.
• Let Claude drive: Connect to Claude.

Connect to Claude (MCP)

Cuaderno ships an MCP server, cdno-mcp, that exposes your vault to AI clients — Claude Desktop, Claude Code, Kiro, Gemini CLI, and anything else that speaks MCP. The assistant can then read context (your orientation, a project, a portfolio) and make writes (append to the log, file evidence, complete an action) on your behalf.

It’s the same engine as the CLI — the files on disk stay the source of truth.

Register the server

Add cdno-mcp to your client’s MCP configuration. For Claude Desktop, edit ~/.claude/claude_desktop_config.json (Claude Code: ~/.claude.json or per-project .mcp.json):

{
  "mcpServers": {
    "cuaderno": {
      "command": "cdno-mcp",
      "env": { "CUADERNO_VAULT_PATH": "/Users/you/notebook" }
    }
  }
}

• command must resolve on the client’s PATH. If it doesn’t, use the absolute path (e.g. /opt/homebrew/bin/cdno-mcp, or target/release/cdno-mcp for a source build).
• CUADERNO_VAULT_PATH tells the server which vault to open. You can omit it; the server then opens whichever vault its working directory belongs to (the same discovery rule as the CLI).

Restart the client. Cuaderno’s tools then appear in the client’s tool list.

What the assistant can do

The server advertises 66 tools, grouped by purpose:

• Context-gathering reads — get_orientation, get_project_context, get_portfolio_contents, get_weekly_context, search_notes, read_daily_note, and more.
• Writes — append_to_log, file_to_portfolio, update_project_state, add_action, complete_action, create_commitment, create_tracking_entry, the daily/weekly section writers, and others.
• Creation and lifecycle — create_project, create_portfolio, create_question, create_stewardship, park_project, activate_project, set_question_status, and so on.

The full catalogue, with each tool’s inputs and output shape, is in the MCP server reference.

Skills

You can wrap common multi-step flows as Claude skills that call these tools — e.g. a daily orientation that reads get_orientation and writes your intention with upsert_daily_section. The repo ships worked examples under examples/skills/; see Using with Claude skills.

Next step

Learn the model behind it all: The Research Logbook Method.

The Research Logbook Method

The Research Logbook Method (RLM) is the practice Cuaderno implements. It distils habits common to prolific researchers — Faraday’s notebooks, Darwin’s dated entries, Hamming’s “important problems,” Knuth’s and Tao’s working logs — into eight concrete practices across two tracks (seven in RLM 1.0; see Method version). Each maps onto one or more note types the tool manages.

Two tracks

Research is two jobs at once. Inquiry is open-ended, driven by questions and evidence. Operations is delivery — deadlines, collaborators, promises. Most systems handle one and force the other into its shape. The RLM keeps them separate and lets them share a substrate: the daily log, the weekly review, and one set of projects that bridges the two.

Track 1 — Inquiry: how you investigate

1. A chronological log (Faraday). A single append-only stream of what you did, observed and thought, in the order it happened. Past entries are never edited; a change of mind is a new entry referencing the old one. The one exception is an address: when a page is renamed, every reference to it is corrected to the new name, the old name is kept on the page, and the rename is itself an entry. It removes the “where do I put this?” decision, preserves the reasoning and not just the result, and keeps you honest against hindsight. Unified across contexts — the regularisation weight and the plumber go in the same day.
2. Evidence portfolios (Darwin). One folder per active question, accumulating whatever is relevant. The log interleaves many questions; the portfolio aggregates one. Name the folder practically, but phrase the question at the top of its index: “sparse models” names a topic, “does the sparse variant outperform the dense baseline out of distribution?” tells you when you are done. Don’t organise inside — accumulate, and file as things arise, while your reaction is still the most valuable part.
3. Important questions (Hamming). The few questions that would genuinely change your situation if answered. Not tasks — questions. They sit above projects: one question may spawn several over time and persists as they finish or get shelved. Two short lists, research and life, reviewed monthly: are these still the right questions?

Track 2 — Operations: how you deliver

A question and a project are not the same thing. A question is open-ended and may branch or turn out to be the wrong question. A project is bounded — a deliverable, a deadline, people counting on you. One question can span several projects; a project can draw on several portfolios; either can exist without the other. Keeping them apart stops deadline pressure polluting open-ended inquiry, and stops open-ended inquiry dissolving operational commitments.

4. Project maps (Knuth). A mutable one-pager per piece of finite work — the page you open after a two-week gap. It answers: where was I, what do I believe and what would change my mind, what are my next actions, what is time-sensitive, where is everything. Tasks live here, embedded in the project that gives them meaning. Maximum five active projects, at most three next actions each — fifteen tasks as a ceiling, not a backlog. A project map is not a history (the log is), not a long checkbox list (eighteen unchecked boxes reads as failure), and not a timeline.

   Parking, clarified (1.1). A parked project map is a complete map. Parking changes two things only: the project does not count against the five, and it is read at the monthly review rather than daily. Everything else a map does, it keeps. You may write next actions on a parked map, update its state, note a milestone, note who you are waiting on. A hard-dated milestone on a parked map, or a dated action on it, is still a promise and stays in the commitments register.

   A map you start work on is a map that counts: being in the middle of something is the strongest sign you are moving it yourself. If you find yourself working on a parked map, or picking up work you had set down on it, it is not parked; activate it, parking another if you must.

   On adopting this clarification, read the parked maps once: every stale date on them is dropped, with its entry in the log, or re-dated.

5. Stewardships. Dashboards for perpetual responsibilities — health, finances, household — that never finish. The critical distinction: projects end, stewardships do not. If health and finances occupy project slots you permanently lose two of five to things that cannot complete. They run in the background with periodic commitments and get a scan at the weekly review, without competing for slots.

6. A commitments register. One flat, date-sorted list of everything with a hard external deadline, whichever project or stewardship it came from. This is not a to-do list, and the distinction matters: a to-do is something you decided to do, a commitment is something someone else is counting on. Mixed together, the commitments drown and you break promises you meant to keep.

7. Energy-matched scheduling (Tao, Wolfram). Tag work deep, medium or light and match it to your current cognitive state. Forcing deep work when your brain wants something mechanical is not discipline, it is waste — the alternative to deep work on a low day is usually paralysis, not virtue. The exception: if you never have deep days, that is environmental, and the fix is protecting blocks rather than trying harder.

8. Handing off (1.1). A project map answers: where was I, what do I believe and what would change my mind, what are my next actions, what is time-sensitive, where is everything. It gains one more question: whose move is it?

   A project you have handed to someone else carries their name at the top of its map: held by: the harbour office, held by: a colleague, held by: the contractor who has the hull. The holder is whoever you could write in Waiting On. A map with no name on it is yours; a map that names you is yours. The page stays where it is; only the name changes.

   Why: if a project someone else is moving holds one of your five, the cap counts their attention as yours, and you will either raise the number or stop writing such work down. Both are worse than a name on a page.

   The count. Count the maps that are neither parked nor handed off. A handed-off project is still open: it keeps its map, keeps logging, keeps its dates in the register, and is still read at the weekly review, and at the daily orientation when something has come back. It is not a sixth slot; it is a project that is not a unit of your attention this week.

   The review. Yours: did it move? Handed off: what came back, and what is waiting on your decision? The second is asked in a week when the map changed.

   The log. Handing off and taking back are dated entries in the chronological log naming the project and the holder; taking back strikes the name. Taking back a parked map only strikes the name; to work on it, activate it as well, as its own entry.

   The cap is checked whenever a map that did not count begins to count: activating a map nobody else holds, or taking back an active one.

   Three guards. If you cannot name who has it, it is yours. A handed-off map says what you are waiting for; a name over an empty Waiting On is a parked map wearing a name, and the weekly review parks it or takes it back. And handing off is never the answer to “the cap is full”: doing a thing on a handed-off map does not make it yours, doing most of its work does; at the weekly review, a handed-off map you worked on yourself on two or more days is taken back, or its name changed to who really has it. You do not hand off a map while you are in the middle of its work.

   The asymmetry. Parking is your decision about now, so starting work on a parked map undoes it at once; a holder is a fact about someone else, which one afternoon’s work on the map does not change.

   The map already has a Waiting On section for single items. Handing off is Waiting On lifted to the whole project, which is why the method already half-had it. Its ancestry is GTD’s Waiting For, kept per project rather than as a separate list.

The bridge

The log feeds both tracks: an observation becomes evidence in a portfolio, a realisation that something must be rerun before a deadline becomes a next action on a project map. The weekly review governs both — retrospective and forward scan. Projects reference the portfolios they draw on, and commitments decompose into milestones that surface as next actions at the right time.

The daily orientation is where the tracks meet: check what is urgent, glance at what is important, check your energy, and pick one thing.

Actions, not tasks

The RLM speaks of actions, not “tasks,” on purpose. The default form of an action is a single inline bullet on a project map — not a heavyweight per-item note. You only “promote” an action to its own note when it grows into an investigation spanning multiple days and evidence artefacts. This keeps the friction of capturing the next step near zero. See Actions.

Designed for ADHD working styles

The method is deliberately shaped to be sustainable when executive function is unreliable:

• Leads with what is there, not what is missing — no guilt engine, no red overdue counts.

• Permission to park or drop. Projects park, complete or drop, questions retire, actions and milestones drop, commitments get fulfilled or dropped — all first-class, and none of it is a failure state.

  “Reversible” is worth stating precisely, because it means less than it might sound like. Parking is genuinely two-way: a parked project activates again, and a retired question does too. Dropping is not — there is no un-drop verb for an action, a milestone or a commitment, and none is planned. It is re-decided rather than undone: if a dropped thing turns out to matter, make it again, and the record honestly shows two decisions rather than pretending the first never happened. That is the same reason a drop is logged as a drop and not as a completion.

  Projects are the one named exception. A dropped project keeps its slug, its map and its history, so cdno project activate brings it back, and a project dropped in error can later be completed, or the reverse. Each is still a new decision with its own log line, never an erasure of the first.

  What a drop does preserve is the note. A dropped action or commitment keeps its file, its body and its created date, archived under _done/<year>/ — so the context you wrote survives even though the plan did not. A milestone is only a bullet, with no note behind it, so dropping one leaves just the log entry naming it — including when it had sub-bullets, which is the one place this guarantee does not yet hold (#574).

• Minimal maintenance. If keeping the system running costs more than a few minutes a day outside the weekly review, something is wrong.

• One obvious next step. cdno orient answers “what should I do now?” with a single suggestion, biased to your current energy.

The rhythm

The method runs on a few interlocking loops:

• Daily — orient in the morning, log and act through the day, a light close at the end. See The daily loop.
• Weekly — a short retrospective (wins, challenges, one improvement) and a single goal for next week. See Weekly review.
• Monthly — the parked maps (“is it time?”) and the questions (“still the right questions?”).
• Occasional — file evidence as you find it, triage the inbox, prune questions and projects.

Method version

The version tracks the method’s text, not any tool. A change is minor if every page of an existing logbook can be read under it without being rewritten, moved, or given a line it lacks; a minor version may ask for a one-time read-through of existing pages. A change is major if any page must be rewritten or moved, and it comes with instructions for doing so (in a tool, a migration). A logbook records on its first page, dated, the version it follows and the day it moved to a newer one; the published method keeps a changelog of practices.

Changelog of practices

• 1.0 — the seven practices: the chronological log, evidence portfolios, important questions, project maps, stewardships, the commitments register, and energy-matched scheduling.
• 1.1 — parking clarified (under practice 4), practice 8 (handing off), and the monthly loop in the rhythm. Additive: every 1.0 logbook is a valid 1.1 logbook. On adopting 1.1 a paper user does two things: a dated line on the first page, and one pass over the parked pages’ dates.
• 1.2 — practice 1 gains its one exception: a renamed page’s references are corrected, the old name is kept on the page, and the rename is itself an entry. Additive: every 1.1 logbook is a valid 1.2 logbook. On adopting 1.2 a paper user does one thing: a dated line on the first page; there is nothing to read through.

How it maps to the tool

Read on: Note types.

Note types

Every note in a vault has a type: in its frontmatter. Cuaderno parses that frontmatter into a typed structure — if it parses, it’s valid. There are twelve note types.

Plus the inbox: raw, untyped captures in inbox/ awaiting triage.

The journal: daily, weekly, and monthly

The chronological backbone. Daily notes collect timestamped log lines plus structured sections (Intention, Agenda, Standup, Meeting), and a ## Notes section for worked-out substance that the log points at (see The concept library). Weekly notes hold the review (Wins, Challenges, One Improvement) and the week’s single goal. Monthly notes hold the higher-altitude review (Wins, Themes, Next Month’s Focus) and a ## Weeks block that links the month’s weekly notes rather than copying them, so the weeks stay the source of truth. All three are append-only — the historical record only grows.

project — the one mutable map

Projects are the only freely-mutable note type. A project carries a Current State, a list of next actions (inline bullets by default), milestones, and waiting-on items. When you update the Current State, the previous state is auto-logged to today’s daily note first, so history is never lost (see Business rules). At most five projects are active at once; the rest live parked in projects/_parked/, and a completed or dropped project moves to projects/_done/<year>/.

action — inline by default, a note when it grows

An action’s default form is a checkbox bullet on its project map. That’s usually all you need. When a single action becomes an investigation spanning days and artefacts, you promote it to a manifest action note (heavier: status, energy, criteria, links). Completing an action removes the bullet, logs it, and — if it had a note — archives that note to actions/_done/<year>/. See Actions.

portfolio + evidence — dossiers per question

A portfolio is a folder named for a question, with an _index.md (the portfolio note) and a set of evidence notes filed into it over time. Each evidence note records a source and an origin (a wikilink to whatever produced it). Evidence is append-only — a portfolio is a growing record. See Research and evidence.

stewardship + tracking — long-haul responsibilities

A stewardship is a dashboard for something you tend indefinitely. It can be flat (a single stewardships/<slug>.md) or expanded (a stewardships/<slug>/ folder with _index.md, a tracking/ subfolder for time-series entries, and a routines/ subfolder for reference docs). Expanded stewardships accept tracking notes via cdno track. See Stewardships and tracking.

question — important questions, kept visible

A question note has a domain (research or life) and a status (active, parked, answered, retired). Questions anchor portfolios and projects (via the core_question link). List the active ones any time with cdno questions.

commitment — dated promises

A standalone promise with a hard due: date and a context. It moves to commitments/_done/<year>/ when it ends — stamped completed if it was kept, dropped if it was cancelled or overtaken. Both are terminal; the frontmatter says which. Standalone commitments are one of four sources feeding the aggregated commitments view.

These twelve are a closed set with built-in behaviour. For an entity they don’t cover (people, books, clients), you can declare a schema-only custom note type in config.toml — a folder, field rules, and a template, with no recompile (see the worked Tracking people recipe).

One custom type comes declared for you: cdno init writes a concept type (concepts/, mutable, refined in place) into a new vault’s config, for understanding you will reuse — a theorem, a technique, a procedure. It is an ordinary custom type you may delete. See The concept library.

For the exact frontmatter fields of each type, see Frontmatter fields. Next: The concept library.

Which notes can be renamed

cdno note rename takes:

Not renamable: daily, weekly and monthly (the journal is addressed by date), archived action notes, commitment, stewardship, evidence, tracking, inbox items, folder notes (other than a portfolio’s) and a note with no type. They are refused with note_not_renamable, and nothing is written. A rename corrects references, which is the one exception to the append-only rule; see the method page.

The concept library

Some of what you work out is neither evidence nor work. What the Woodbury identity buys you when you invert a low-rank update. How to do a rolling restart of a StatefulSet without losing quorum. It answers no open question, so it is not evidence. It has no deliverable and never completes, so it is not a project or an action. It belongs to no perpetual responsibility, so it is not a stewardship routine. Left in the daily log, it is findable but scattered: three partial versions across three days, and the one you find first is not necessarily the best.

The cost of that is re-derivation — working the same thing out again because the last time is buried, or because the half-versions disagree. A concept note is the fix: the single, current, best account of one piece of understanding you expect to reuse. Concept notes together form a library of concepts in a flat concepts/ folder, organised by tags and links rather than by folders.

A concept note is refined in place as your understanding improves, and each refinement leaves a one-line trace in the daily log. It has no lifecycle, no staleness, no review obligation and no cap.

A custom type, declared for you

concept is not a thirteenth built-in note type. It is an ordinary custom note type that cdno init declares in a new vault’s .cuaderno/config.toml, with its template installed as .cuaderno/templates/concept.md:

# A declared custom type: the concept library (RFC 0002). Delete this block (and
# any notes under concepts/) if you do not want one; nothing else depends on it.
[note_types.concept]
folder = "concepts"
required = ["created"]
optional = ["tags", "origin"]
template = "concept.md"

If you do not want a library, delete the block. A vault created before the type existed gets the declaration, the template and the folder with one command, which writes only what is absent and never changes a declaration you already have (see Installing a bundled note type):

cdno config note-type install --name concept

A concept note looks like this:

---
type: concept
created: 2026-09-25
tags: [linear-algebra, optimisation]
origin: "[[journal/2026/daily/2026-09-02#Woodbury identity]] [[journal/2026/daily/2026-09-24#Low-rank refit]]"
---

# Woodbury identity

## Statement
…

## Why it matters
…

## See also
- [[concepts/sherman-morrison]]

The title is the H1. tags is your subject vocabulary: open, indexed, and needing no configuration. origin, written only when you supply it at creation, holds wikilinks to the daily-note entries the concept came from. The body is free-form: Statement / Why it matters / See also is the template’s default, and a procedure or a definition simply uses its own headings.

One concept per note. If a note needs two headings that could each be cited on their own, it is usually two notes, linked. A single derivation that does not split can stay one note, with its sections cited by heading link ([[concepts/woodbury-identity#Statement]]).

The filing test

Before you keep something, ask what is it?

1. A dated observation, result or source that bears on an open question → evidence in a portfolio.
2. The answer to a question you weighed evidence for → the question note, with status: answered. Its ## Current Thinking may be promoted into a concept that the question links to; the question keeps the record of how it was answered.
3. A prescribed practice belonging to one stewardship (a workout plan, a care routine) → a stewardship routine.
4. Understanding you will reuse, independent of any deliverable — a theorem, a definition, a technique, a procedure, an idea → a concept note.
5. Not yet settled → an entry in the day’s ## Notes, until you promote it.

And the things that are none of these stay where they already go: something to do is an action on a project map; finite work with a deliverable is a project.

A benchmark result is evidence. What the benchmark taught you about the technique is a concept. The command that ran it belongs in the evidence note — and may also become a concept, if you will run it again.

The provenance rule

Evidence never depends on the current text of a concept note. An evidence note records what was done and observed inline — the exact invocation, the version, the parameters — and may link to a concept only as see also. A concept is never the origin: of an evidence note. Concepts describe your understanding now; evidence records what happened then. That separation is what lets you refine a concept freely without rewriting the past.

Substance in the day, pointers in the log

## Logs is the day’s sequence: one line per event. Substance — a derivation, a worked procedure, a page of reasoning — does not belong there, because a block of text turns a sequence into a wall. It goes in the daily note’s ## Notes section instead, one ### <heading> entry per piece, while the log gets a one-line pointer to it:

## Notes
### Woodbury identity
(A + UCV)^-1 = A^-1 - A^-1 U (C^-1 + V A^-1 U)^-1 V A^-1.

Cheap when A^-1 is already known and the update is low-rank: today's use was the
k=3 refit on [[surrogate-model]]. #concept

## Logs
- **14:32**: noted [[journal/2026/daily/2026-09-02#Woodbury identity]] ([[surrogate-model]])

cdno log note (or the note_to_daily MCP tool) writes both halves in one go: the entry under ## Notes, which it creates just above ## Logs if the day does not have one yet, and the noted [[…#Heading]] pointer line in ## Logs, followed by the entry’s own wikilinks in parentheses. So the day’s sequence shows that a derivation happened and what it touched, while the derivation itself stays out of the way. Like ## Logs, ## Notes is append-only.

Each entry’s heading is its address, so the tool holds it to a few rules: unique within the day, never a daily section name (Standup, Intention, Agenda, Meeting, Notes, Logs), no [, ], |, # or inline markup, and not starting with ^. Headings inside the entry must be level 3 or deeper. If you write an entry by hand, follow the same convention.

Mark candidates. End an entry you might reuse beyond today with the tag #concept on its last line. That is how you — or an assistant — find promotion candidates later.

## Notes is not read by the project, weekly or monthly context: those read ## Logs. An entry about a project reaches that project through the pointer line’s wikilinks and the entry’s own links (which become backlinks once the index is rebuilt; see Promotion), so a review sees that you worked something out, not the working itself.

Promotion

Write a concept note straight away when you already know you will reuse the thing. When you are not sure, note it in the day and promote it the second time it comes up.

Promotion is simply creating a concept note with origin pointing at the entries it came from. There is no separate promote operation, no counter, and no promoted to line:

cdno note create concept --title "Woodbury identity" --body-file woodbury.md \
  --origin "[[journal/2026/daily/2026-09-02#Woodbury identity]] [[journal/2026/daily/2026-09-24#Low-rank refit]]"

Creation is logged for you, to today’s daily note, as concept created [[concepts/<slug>]] — <title>, and origin records where the concept came from. Over MCP the same step is create_custom_note with body and origin.

The ## Notes entries stay as they were — the day’s record is append-only — and their daily notes have a backlink from the concept. Every write through cdno indexes the links it writes, so links from cdno log note, cdno note create or cdno note revise are in the backlinks at once.

Search before you create. A second note on a subject the library already covers is the duplicate this whole method exists to avoid. cdno search <word> --type concept first; if the concept exists, refine it rather than minting another. (Nothing refuses a second note with the same title: it is created as <slug>-2.)

An assistant connected over MCP follows the same habit. Its tool descriptions tell it to search the library before drafting an explanation, and to offer promotion when it finds #concept entries on the same subject on two or more dates.

Finding candidates, and the current limitation

Search matches words, not tags. Searching concept across daily notes finds the entries tagged #concept, but also — by stemming — any day that merely created, revised or linked a concept note, since those log lines contain concepts/. The snippet rarely shows the entry’s subject either, so open each hit and look for ## Notes entries whose last line carries #concept:

cdno search concept --type daily

A search that filters by tag is planned but not shipped.

Refinement

A concept note is mutable in place. A better explanation replaces the worse one; a correction replaces the error. The note is always the current best account — correct it rather than annotate it.

Refine through the tool, so the change leaves a trace:

cdno note revise woodbury-identity --section "Why it matters" --content-file why.md \
  --reason "added the cost comparison"

Each revision that changes the text writes one line to today’s daily log:

- **14:32**: revised [[concepts/woodbury-identity#Why it matters]] — added the cost comparison

• The reason is required. It is the part of the history worth keeping, so say briefly why.
• The #Section anchor is present when you revised one section, and absent for a whole-body rewrite.
• There is no was: / now: block, unlike a project’s state change. The log records when and why; git records what.
• Text identical to what is already there writes and logs nothing.

You can replace the whole body (--body-file, or your editor when run interactively with no file) or upsert one section (--section with --content-file). A section that exists is replaced together with its sub-sections; one that does not is appended as ## <section>. There is no append operation for a concept — refinement means rewriting what is there.

The hash guard. cdno note revise reads the note first and remembers a hash of what it read. If the file changes on disk before the revision is written — say you saved it in your editor while the revise editor was open — the revision is refused rather than overwriting that change: read the note again and redo it. Over MCP, read_note returns that content_hash and a whole-body revise_note must pass it back as expected_hash.

Edits you make directly in an editor are legitimate — the Markdown is the source of truth — but they leave no log line. That is a known limit of the history, not something cdno lint polices.

Only mutable custom types can be revised this way. Built-in types (a project’s sections belong to its own commands) and custom types declared append_only = true are refused.

No staleness

Understanding does not go stale. A theorem is as true after two untouched years as on the day you wrote it down, and an explanation you have not changed is one you were happy with. So concept notes have no verified date, no age signal, no staleness lint and no review chore. They never appear in cdno orient, the weekly or monthly context, or any review list.

The history lives in the daily log instead: every creation and revision is a dated line there, so “how has my understanding of this evolved?” is a search, not a field.

Usefulness is a question you can ask, not a metric that is kept: the note’s backlinks (which notes link to it) are one read_note away over MCP, and whether it has been mentioned in the log is a search. An unreferenced concept costs nothing and is left alone. A procedure that depends on a version can say “last run on 2026-09 against v1.4” in its own body if that matters; there is no field for it.

Structure by links, not folders

concepts/ is flat. A concept usually belongs to several subjects at once — a theorem is both linear algebra and optimisation — so a folder is the wrong axis. Tags carry membership, and wikilinks carry relationships.

Hub notes carry navigation. When a cluster is real, write a concept note that is mostly links — concepts/linear-algebra.md listing the theorems, the notation sheet, the techniques. It is an ordinary concept note, written by hand when you need it, never a folder decided in advance. By convention its slug is the tag it maps. It plays the part a portfolio’s _index.md plays for evidence.

If the folder grows past a few hundred files and you browse it on disk, one coarse subfolder level (concepts/maths/) is tolerated. The tool is blind to it: it never asks for a subfolder, and [[concepts/<slug>]] still resolves after you move a file by hand.

Summary

Walk one promotion end to end in Building a concept library.

Next: Vault structure.

Vault structure

A vault is a directory tree of Markdown files plus a .cuaderno/ config folder. cdno init creates the whole layout; here’s what each part holds.

vault/
├── journal/
│   └── 2026/                      # partitioned by (ISO) year
│       ├── daily/
│       │   └── 2026-04-25.md      # type: daily (append-only)
│       └── weekly/
│           └── 2026-W17.md       # type: weekly (append-only)
│
├── projects/
│   ├── surrogate-model.md        # type: project (mutable)
│   ├── _parked/                  # parked projects: complete maps that don't count
│   │   └── bayesian-opt.md
│   └── _done/
│       └── 2025/                 # closed projects: completed or dropped
│           └── thesis-chapter-2.md
│
├── actions/
│   ├── characterise-sampler.md   # type: action (manifest form)
│   └── _done/
│       └── 2026/                 # completed actions, partitioned by year
│           └── run-ablation.md
│
├── portfolios/
│   └── sparse-vs-dense-ood/
│       ├── _index.md             # type: portfolio
│       ├── 2026-03-15-chen-2025.md   # type: evidence (append-only)
│       └── 2026-04-01-ablation-b.md
│
├── stewardships/
│   ├── finances.md               # type: stewardship (flat)
│   └── health/                   # expanded variant
│       ├── _index.md             # type: stewardship
│       ├── tracking/             # type: tracking entries (append-only)
│       │   └── 2026-04-06-gym.md
│       └── routines/             # reference docs, not logs
│           └── upper-body-a.md
│
├── commitments/
│   ├── pay-rent.md               # type: commitment
│   └── _done/
│       └── 2026/                 # fulfilled commitments
│
├── questions/
│   ├── research/
│   │   └── surrogate-cost.md     # type: question (domain: research)
│   └── life/
│       └── apartment-as-home.md  # type: question (domain: life)
│
├── concepts/                     # the concept library (a custom type `cdno init` declares)
│   ├── woodbury-identity.md      # type: concept (mutable, refined in place)
│   └── linear-algebra.md         # a hub note: mostly links
│
├── inbox/                        # raw captures awaiting triage
│
└── .cuaderno/
    ├── config.toml               # vault configuration
    ├── index.db                  # SQLite index cache (auto-created, rebuildable)
    └── templates/                # note templates (override the built-ins)

Conventions worth knowing

• _parked/ (projects) and _done/ (projects, actions, commitments) prefix folders hold inactive or finished notes. The underscore keeps them sorted out of the way and signals “not the active set.” _done/ is partitioned by year so the active folders stay scannable.
• projects/_parked/ holds complete maps that are set aside: they take every plan write (actions, state, milestones, waiting-on), keep their hard dates in the commitments register, and do not count toward the cap. You read them at the monthly review. A handed-off project (held_by: in its frontmatter) stays in whichever folder it was in; only the name changes. See Business rules.
• _index.md is the identity note of a folder — the portfolio note inside a portfolio folder, the stewardship note inside an expanded stewardship folder.
• tracking/ inside a stewardship holds time-series entries; routines/ holds prescriptive reference documents (a workout plan, a checklist) — those are not logs.
• concepts/ is flat by design: tags and links, including hand-written hub notes, give it structure. See The concept library.
• Stewardships have two shapes: a flat stewardships/<slug>.md, or an expanded stewardships/<slug>/ folder. Only expanded ones can hold tracking entries.

.cuaderno/

• config.toml — vault settings: the method version the vault follows ([vault] method_version), the project cap, the holder deny-list ([projects] holder_sentinels), ignore globs, template behaviour, schema extensions, variables. See Configuration.
• index.db — a SQLite cache of the vault, used for fast search, linting, and link queries. It is rebuilt automatically when it’s stale (see Business rules); deleting it is safe. The Markdown files are always the source of truth.
• templates/ — the note templates cdno fills when scaffolding a note. The built-ins are written here at init so you can edit them; pure variable substitution, no logic.

Next: Business rules.

Business rules

Cuaderno enforces a small set of rules that keep the method honest. Knowing them explains why some commands behave the way they do.

Markdown is the source of truth

The files on disk are canonical. The SQLite index in .cuaderno/index.db is a cache — it makes search, linting, and link lookups fast, but it can always be rebuilt from the Markdown. A stale index is recoverable; a stale file would be data loss, so the tool never lets the cache override the files. You can delete index.db at any time, or rebuild it explicitly with cdno reindex.

Startup reconciliation

On every CLI invocation, MCP session, and app launch, Cuaderno reconciles the index against the filesystem — comparing modification times and content hashes — and quietly repairs anything stale before doing your command. This is why edits you make to notes by hand (in your editor, via sync) are picked up without a manual reindex.

The five-project cap

At most five projects count at once. A project counts when it is active and names no one else as its holder: parked projects don’t count, closed ones don’t, and neither does an active project that someone else is moving (below). Creating a project at the cap creates it parked; the cap is checked whenever a project that did not count begins to: on activation, so activating a sixth stops you — you must park one first — and when you take an active project back from its holder. Parked projects live in projects/_parked/. Closed ones are not open at all: a project that is finished is completed, and one that is not going to happen is dropped, both into projects/_done/<year>/. Closing never needs a slot, and a parked project can be closed directly. The limit is configurable via config.toml (see Configuration); five is the default because it’s the point past which “active” stops meaning anything.

Parked projects are complete maps

Parking changes two things only: the project does not count, and you read it at the monthly review rather than daily. A parked map takes every plan write an active one does: next actions, Current State, milestones, waiting-on items, the core question and a holder, from the CLI and over MCP alike, so you never activate a project just to write on it. Its hard milestones and action due dates stay in the commitments register.

Only starting, switching or resuming work, and parking need an active project (cdno action start, switch, resume, and cdno project park): a project you start work on is a project you are moving, so it counts. Activate it first, parking another if the cap is full.

Handed-off projects

An open project may name who else is moving it in a held_by: line at the top of its map: held_by: "the harbour office". cdno project hand-off writes it and take-back clears it, each logging a holder on [[<slug>]] entry in today’s daily note. An active project that names a holder stays where it is, keeps its actions, its log and its dates in the register, and does not count toward the cap: the cap counts your attention, not someone else’s.

Three guards keep it honest. If you cannot name who has it, it is yours. A handed-off map says what you are waiting for in its Waiting On. And handing off is never the answer to a full cap: name a holder only when someone else really has the project. To make room, park, complete or drop one.

The deny-list. A held_by: value that names you or nobody (me, tbd, someone, ?, …) reads as no holder, so the map stays yours and counts, and the hand-off verb refuses it. Those values are a config key, [projects] holder_sentinels, with a default list you can replace, or set to [] to accept any name. Its stated limit: the tool cannot know your own name, so held_by: "<your name>" is read as someone else unless you add your name to the list. A value that is not a plain name (an unquoted wikilink, a number, a date) also reads as no holder; cdno lint reports it so you can quote it.

The method version

The vault records which version of the Research Logbook Method it follows, as [vault] method_version in .cuaderno/config.toml. That is the method’s version, not cdno’s: cdno init writes the version this cdno implements, and only cdno migrate changes it. A vault with no key is read as RLM 1.0. A cdno refuses to write to a vault on another major version (an older one: migrate it; a newer one: upgrade cdno), while reads keep working; a minor difference only prints a notice.

Append-only notes

daily, weekly, evidence, and tracking notes are append-only — Cuaderno only ever grows them, never overwrites, with one exception: when a note is renamed, references to it are corrected to the new name, even here. They are the historical record. (Projects are mutable on purpose; see next.)

Project state history is preserved

A project’s Current State is the one piece of freely-mutable prose in the vault. To keep history intact, every time you update it (via cdno project state or the MCP update_project_state tool) the previous state is auto-logged to today’s daily note before the new text overwrites it. You get a clean current view and a full audit trail in the journal. A hand-off or take-back logs the same way, as holder on [[<slug>]] with was: and now: lines.

Commitments are aggregated, not stored in one place

The commitments view is computed from four sources, so a promise is counted wherever it naturally lives:

1. Project milestones marked with a hard deadline (--hard), of an open (active or parked) project.
2. Stewardship periodic commitments (the recurring lines on a stewardship dashboard).
3. Standalone commitment notes in commitments/.
4. Action notes carrying a self-imposed due: that isn’t pinned to a milestone, of an open (active or parked) project.

A project’s own dates (sources 1 and 4) count while the project is open, active or parked: a hard date on a parked map is still a promise. Completing or dropping a project takes its milestones and action due dates out of the view until it is activated again. A standalone commitment that names a parked or closed project keeps surfacing, since it is a promise to someone else.

cdno commitments merges and sorts all four by date, with overdue items flagged.

Atomicity and its limits

Each write is captured as a transaction (file writes + index updates) that commits as a batch and rolls back on failure — while the process is alive. Startup reconciliation catches index staleness afterward, but a crash midway through a rare multi-file operation can still leave partial state on disk. In practice this is vanishingly rare; the takeaway is simply that the Markdown is authoritative and reindex + lint will surface anything odd.

Next: Contexts and energy.

Contexts and energy

Two small enumerations show up across many commands. Both are fixed vocabularies (not free text), so they stay consistent and filterable.

Contexts — the life domain

A context classifies which part of life a project, stewardship, or commitment belongs to. The set is fixed:

You set a context when you create a project (--context), stewardship (--context), or commitment (--context). It groups and colours items in views and lets the system reason about balance across your life, not just your work.

Contexts are a compile-time set, not configurable — keeping the vocabulary small and shared is the point. (Stewardships accept the same set.)

Energy — the effort a thing needs

An energy level tags how much focus an action demands, so the morning suggestion can match the work to how you actually feel:

You tag an action with --energy when you add it. Then:

# "I have a clear morning" — bias the suggestion toward deep work:
cdno orient --energy deep

# "I'm fried" — surface something light instead:
cdno orient --energy light

cdno orient uses the energy bias to pick which next action to suggest as your starting point. Matching the task to your state — rather than forcing the hardest thing first — is part of what makes the daily loop sustainable.

Focus

Energy says what kind of work to pick; focus says what you are on right now. It is a single slot, and it is deliberate at both ends: you put something in it, and you take it out.

cdno now reads it back. Nothing is stored beside the daily log: the focus is replayed from it each time, so there is nothing to keep in sync and a line you write by hand counts as long as it has the writers’ shape.

One slot. Starting something while something else is in focus is refused, naming the way forward (switch, or pause first). You can always move on; you just say so, which makes the move a line in the log instead of a silent change of subject. The same holds on reading: a newer start displaces an older one for good, and finishing the newer one does not bring the older back.

The window. A start left open at midnight is still the focus in the morning, with its day named, and expires after that. The window is carry_over_days, default 1; set it to 0 to read today only. resume re-anchors a carried focus to today, so work you keep going on does not expire, and work you stop lets it lapse.

Pause and resume. pause is the honest way to stop without finishing: the action stays open on the map, and an optional --next records where to pick up. Pauses are remembered for paused_lookback_days, default 14, which covers a weekend. A paused action stops being offered once something later started, resumed, finished, dropped or promoted it. Promoting a bullet while it is in focus is fine: the focus follows it to the new note.

With an assistant. Over MCP the focus rides along on the reads and on the results of eighteen write tools, so an agent knows what you are on without asking. The server never refuses a write for being outside the focus. The agent’s job is to notice a change of subject and say it in one sentence, offering to capture the thought and stay, to do it now as an aside, or to move over if you say so, and to give you a cue to get back (next: is what it reads out). It raises a given topic at most once per focus, never asks you why, and never pauses or resumes without your yes.

The during: tag. While a focus is open, a log line written by cdno log, an inbox capture, and a ## Notes entry (on its noted pointer line in ## Logs) are tagged with its project: during: [[surrogate-model]] under the log line, captured_during: surrogate-model in an inbox item. The tag is what lets a later review see where captures came from, and it survives triage because the discard line copies it.

Next: Configuration.

Configuration

Vault behaviour is configured in .cuaderno/config.toml, written for you by cdno init. The defaults are sensible — you can run for a long time without touching it. This page explains what is configurable and why; the Configuration reference lists every key.

What you can configure

• The method version. [vault] method_version records which version of the Research Logbook Method the vault follows: the method’s version, not cdno’s. cdno init writes it; you change it only with cdno migrate, never by hand. A vault without it is read as RLM 1.0.
• The active-project cap. Change the default of five via [vault] max_active_projects. It counts the projects that are active and name no one else as their holder.
• The holder deny-list. [projects] holder_sentinels lists the held_by: values that name you or nobody (me, tbd, someone, …), so a map carrying one stays yours and counts. Replace the list to add your own name or words in your language, or set [] to accept any name. The tool cannot know your own name: add it if you want it read as yours.
• Ignore globs. Patterns for files the index should skip — CLAUDE.md, README.md, scratch notes — so they don’t appear in search, lint, or link checks. Patterns are additive (no negation), matched against vault-relative paths, and never delete anything on disk — they only scope what the index considers.
• Templates. Override any built-in note template by adding a file under .cuaderno/templates/.
• Custom note types. Declare your own types under [note_types.<name>]. cdno init declares the bundled concept type for you; a vault created before it existed gets it with cdno config note-type install --name concept (see Custom note types).
• Schema extensions. Add vault-specific required frontmatter fields per note type (e.g. require collaborators on every project), enforced by cdno lint.

The hands-on walkthrough is Customising templates and frontmatter.

Templates

When cdno scaffolds a note, it fills a template. Templates are pure variable substitution — no conditionals, no logic. cdno init writes two starter templates (.cuaderno/templates/daily.md, and concept.md for the concept type it declares); every other built-in type uses its built-in default until you add a file for it. cdno picks the most specific template that exists:

1. a custom variant template (for tracking, e.g. tracking-gym.md), then
2. a custom type template (e.g. project.md), then
3. the built-in variant default, then
4. the built-in type default.

Because templates also define the canonical order of frontmatter keys, cdno normalise uses them to reorder hand-authored or migrated notes into a consistent shape.

Variables

Templates use {{placeholder}} markers that cdno fills from the values each note’s creation command supplies — {{title}}, {{context}}, {{created}}, and so on. The exact set available per note type, and how to use them in a custom template, is covered in Customising templates and frontmatter. An unknown placeholder is left verbatim, so use only the ones a type provides.

Custom templates can also reference static vault variables you set under [variables] in config.toml (e.g. {{author}}); these resolve on every note type, with per-type values taking precedence over a config variable of the same name.

For values that change per note, prompted variables under [variables.prompt] are gathered at creation — from a --var name=value flag, an interactive prompt, or (failing both) a clear error. The tutorial covers them in full.

Example

[vault]
name = "My Research Vault"
method_version = "1.2"             # written by `cdno init`, changed only by `cdno migrate`
max_active_projects = 5            # the active-project cap

# Skip these from the index entirely (search/lint/links). Never deletes files.
ignore = ["CLAUDE.md", "README.md"]

# Require an extra field on every project note — enforced by `cdno lint`:
[schemas.project]
extra_required = ["collaborators"]

# Names that mean "me" or "nobody" in a project's `held_by:` (replaces the default list):
[projects]
holder_sentinels = ["me", "tbd", "someone", "A. Researcher"]

# Static template variables — resolve in any custom template (e.g. {{author}}):
[variables]
author = "A. Researcher"

# Prompted variables — gathered at note creation (--var, prompt, or error):
[variables.prompt]
collaborators = "Who are the collaborators?"

For the complete key-by-key reference, see Configuration reference.

That’s the concepts tour — next, put it to work in the Tutorials.

The daily loop

The core rhythm of Cuaderno is a daily loop: orient → act → log → close. None of it is mandatory or guilt-inducing; it’s a habit that keeps the vault current with almost no overhead.

Morning: orient

Start the day by asking the tool what deserves attention:

cdno orient --energy deep

orient shows commitments due soon, your active projects with their current state and top next action, and a single suggested starting point — biased toward the energy you tell it you have. Drop --energy to get a neutral suggestion; pass --energy light on a low day.

Want just the project snapshot without commitments? Use cdno status.

If you left something open yesterday, cdno now still shows it this morning, with the day named. Pick it up with cdno action resume, or set it aside with cdno action pause --next "…" and choose something else. orient itself does not list the focus or your paused work; cdno now does.

Through the day: act and log

As you work, two verbs carry most of the weight.

Log what happens — append a timestamped line to today’s journal:

cdno log "scaled the mesh to 2M cells; 4x runtime, still stable"

Capture stray thoughts without breaking flow — they land in the inbox for later triage:

cdno capture "does Chen 2025 use the same preconditioner?"

Make progress on projects as you go:

# Add the next action you just thought of:
cdno action add --project surrogate-model --title "Profile the assembly step" --energy medium

# Record where a project now stands (auto-logs the previous state to today's journal):
cdno project state --slug surrogate-model --text "Mesh scaling works; assembly is the bottleneck"

# File a useful result into the right portfolio:
cdno file --portfolio sparse-vs-dense-ood --source "ablation run B" --origin projects/surrogate-model

# Say what you are starting, so `cdno now` can answer for you later:
cdno action start --project surrogate-model --query "assembly step"

# Tick off a finished action (substring match on the bullet):
cdno action complete --project surrogate-model --query "feature set B"

When you lose the thread, ask what you were doing rather than guessing:

$ cdno now
On surrogate-model — Profile the assembly step (medium), since 09:30 (1h 30m).

There is no state behind that — it replays today’s journal and yesterday’s (the [focus] carry_over_days window in .cuaderno/config.toml), so a start made here, or by an agent over MCP all count equally, and completing, dropping or pausing the action clears it. With nothing open it says so, and shows the last thing you paused and the note you left yourself. See cdno now for the full shape, including what a start typed by hand has to look like.

When the day changes direction, say so rather than stacking one thing on another. Starting a second action while one is open is refused; the way through is a verb:

# Stopping for now, with a note to your future self:
cdno action pause --next 'pick up at "Prior approaches"'

# Moving to something else right now (a pause and a start together):
cdno action switch --project other-project --query "CI"

# Coming back; prints the note you left:
cdno action resume

Each one is a line in the journal, so the record shows when you moved and, if you said, why. When you capture a thought while something is in focus, the inbox item remembers which project you were on. See Focus.

Evening: close

A light wind-down — note anything for your stewardships and reflect:

# Log a tracked activity under a stewardship:
cdno track gym --stewardship health --content "Upper body; good energy"

# A closing reflection is just another log line:
cdno log "good focus day; pick up assembly profiling tomorrow"

That’s it. The journal now holds a faithful record of the day, your projects reflect reality, and tomorrow’s orient will pick up where you left off. Anything still in focus at midnight is carried into tomorrow, and cdno action pause is the way to put it down on purpose.

Letting Claude run the loop

Each step has an MCP equivalent (get_orientation, append_to_log, add_action, update_project_state, …), so an assistant can drive the same loop conversationally. See Connect to Claude and the example skills.

Next: Managing projects.

Managing projects

A project is a lightweight map of a piece of active work: a current state, next actions, milestones, and things you’re waiting on. You keep at most five active at once. All the verbs live under cdno project (plus cdno action for the next-action list).

Create one

cdno project create --title "Surrogate model" --context work
# -> projects/surrogate-model.md   (slug derived from the title)

--context is the life domain. Optionally link the project’s core question with --question questions/research/surrogate-cost — and if you skip it, or the question changes later, cdno project core-question --slug surrogate-model --question <target> sets it afterwards (--clear detaches). If you’re already at five active projects, the new one is created parked — activate it once you free a slot.

See where things stand

cdno project list                 # active projects + a state snippet
cdno project show surrogate-model # one project in detail
cdno status                       # all active projects + their top action

Add --json to any of these for structured output (see JSON output).

Update the current state

The Current State is the project’s one mutable paragraph — “where is this right now?”. Updating it auto-logs the previous state to today’s journal first, so you never lose the trail:

cdno project state --slug surrogate-model \
  --text "Mesh scaling works to 2M cells; assembly is now the bottleneck"

Next actions

Actions are the things to do next. By default they’re inline bullets on the project:

cdno action add --project surrogate-model --title "Profile the assembly step" --energy medium
cdno action list --project surrogate-model
cdno action complete --project surrogate-model --query "profile the assembly"

See Actions for the inline-vs-manifest distinction and promotion.

Milestones

Milestones are markers of progress. Mark one --hard to make it a real deadline that shows up in the aggregated commitments view:

cdno project milestone add --slug surrogate-model --title "Submit to ICML" --date 2026-01-22 --hard
cdno project milestone done --slug surrogate-model --query "submit to icml"

--date is optional. When a milestone is gated by a condition rather than a date, leave it off rather than inventing an estimate — a made-up date reads back later like a commitment somebody made:

cdno project milestone add --slug surrogate-model --title "All Round-1 replies received"

An undated milestone records target: TBD, stays out of the commitments view, and completes exactly like a dated one. --hard needs a real date.

Waiting-on

Track external blockers so they’re visible instead of forgotten:

cdno project waiting add --slug surrogate-model --description "Cluster quota increase from IT"
cdno project waiting resolve --slug surrogate-model --query "cluster quota"

Park and re-activate

Parking is first-class and reversible — it’s how you respect the five-project cap without deleting anything:

cdno project park --slug surrogate-model        # -> projects/_parked/, frees a slot
cdno project activate --slug surrogate-model     # bring it back (must be under the cap)

A parked map is still a complete map. Parking changes two things only: the project stops counting, and you read it at the monthly review instead of every day. You can keep writing on it exactly as on an active one, without activating it first:

cdno action add --project bayesian-opt --title "Re-read the acquisition-function survey" --energy light
cdno project state --slug bayesian-opt --text "Shelved until the ICML submission is in"
cdno project milestone add --slug bayesian-opt --title "Decide whether to restart" --date 2026-07-01

Its hard milestones and dated actions stay in cdno commitments: a deadline on a parked map is still a promise. What a parked map refuses is work: cdno action start (and switch and resume) needs an active project, because a project you are working on is one you are moving. If you find yourself working on a parked map, activate it, parking another if the cap is full.

Hand a project off

Some projects stay open while someone else is moving them: the survey is with the harbour office, the draft is with your co-author. Name the holder, and the map says so:

cdno project hand-off --slug hull-survey --to "the harbour office"
# Handed hull-survey to the harbour office (projects/hull-survey.md)

The map gains held_by: "the harbour office", today’s daily note gets an entry:

- **09:10**: holder on [[hull-survey]]
  was: (mine)
  now: the harbour office

and the project, if active, no longer counts toward the cap: cdno project list shows it with a held by: the harbour office · does not count toward the cap line. It stays where it is, keeps its actions, log and deadlines, and is still read at the weekly review, where the question is not “did it move?” but “what came back, and what is waiting on my decision?”. Say what you are waiting for:

cdno project waiting add --slug hull-survey --description "Inspection report from the harbour office"

When the work comes back to you, take it back:

cdno project take-back --slug hull-survey
# Took hull-survey back (projects/hull-survey.md)

That logs holder on [[hull-survey]] with now: (mine), and an active project counts again, so at the cap the take-back is refused with the projects that count. A parked project stays parked; taking it back only clears the name.

Three guards keep it honest:

• If you cannot name who has it, it is yours. --to tbd, --to someone or --to me is refused (the list is [projects] holder_sentinels).
• A hand-off is not made mid-work. While an action on the project is in focus, pause it first.
• Handing off is never how you make room at the cap. Name a holder only when someone else really has the project. To free a slot, park, complete or drop one.

Close a project

A project ends one of two ways, and the log records which:

cdno project complete --slug surrogate-model                               # the work is done
cdno project drop --slug bayesian-opt --reason "superseded by the ICML work"  # it is not happening

Both move the map to projects/_done/<year>/, stamp closed: with today’s date and free the slot; both work on a parked project too. If anything is still open, the command stops and lists it:

surrogate-model has 2 open items:
  - [ ] Draft methods section with ablation figures (medium)
  - [ ] ICML paper submitted — hard: 2026-05-22
Complete or drop each of them (or add it to the project that now owns it), then run again.

Tick what was done, drop what is not happening (each with its own reason), and run complete again. A drop can instead let the open items go with the project: it asks first, or takes --drop-open in a script. Commitments you made to other people are never touched by either.

cdno project list --closed shows what has ended, newest first, and the MCP weekly and monthly contexts (get_weekly_context, get_monthly_context) list the projects that closed in their window. A closed project can come back with cdno project activate, or take the other outcome later if the first one was wrong.

Next: Research and evidence.

Research and evidence

This is the knowledge-building half of the method: name the questions that matter, open a portfolio for each, and file evidence into it as you go. Over months a portfolio becomes a dossier you can actually reason from.

Name a question

cdno question create --domain research --text "Does sparse attention beat dense out-of-distribution?"
# -> questions/research/does-sparse-attention-beat-dense-out-of-distribution.md

--domain is research or life. List the active ones any time:

cdno questions                  # grouped by domain
cdno questions --json | jq .

As a question’s life changes, transition it (each transition is logged to the journal):

cdno question park   --slug does-sparse-attention-beat-dense-out-of-distribution
cdno question answer --slug does-sparse-attention-beat-dense-out-of-distribution
cdno question retire --slug does-sparse-attention-beat-dense-out-of-distribution
cdno question activate --slug does-sparse-attention-beat-dense-out-of-distribution

Open a portfolio for it

A portfolio is a folder that accumulates evidence about one question:

cdno portfolio create --question "Sparse vs dense attention OOD"
# -> portfolios/sparse-vs-dense-attention-ood/_index.md

# Optionally tie it to a project when you create it:
cdno portfolio create --question "Sparse vs dense attention OOD" --project projects/surrogate-model

Already have a portfolio and want to link it after the fact? Use the retrofit verb (one of --question/--project, not both):

cdno portfolio link --portfolio sparse-vs-dense-attention-ood --project projects/surrogate-model

File evidence

Every useful artefact — a paper, an experiment result, a conversation — goes in as an evidence note. --source is the citation/reference; --origin is a wikilink to whatever produced it:

cdno file --portfolio sparse-vs-dense-attention-ood \
          --source "Chen et al. 2025, NeurIPS" \
          --origin projects/surrogate-model \
          --content "They report a 4x speedup at 95% accuracy on the OOD split."

Attaching a real file

To file a non-Markdown artefact (PDF, image, video), point --attach at it. Cuaderno copies it into the portfolio and scaffolds a linked evidence stub beside it (here --content is the abstract). Add --move to move instead of copy:

cdno file --portfolio sparse-vs-dense-attention-ood \
          --source "Chen et al. 2025" \
          --origin projects/surrogate-model \
          --attach ~/Downloads/chen2025.pdf \
          --content "Key result: 4x speedup at 95% accuracy."

Review what’s accumulated

cdno portfolio list                              # all portfolios + evidence counts + staleness
cdno portfolio show --portfolio sparse-vs-dense-attention-ood
cdno search "preconditioner" --portfolio sparse-vs-dense-attention-ood

portfolio list flags staleness — dossiers you haven’t fed in a while — which is a useful prompt during your monthly scan. Periodically synthesise the findings into the portfolio’s _index.md.

Not everything worth keeping is evidence. What a result taught you about a technique — understanding you will reuse, independent of any question — is a concept, and it lives in its own library; see The concept library for the filing test.

Next: Building a concept library.

Building a concept library

This walkthrough follows one piece of understanding from a scribble in the day to a refined concept note: you work something out, note it, meet it again three weeks later, promote it, and then improve it. The method behind each step is in The concept library.

It assumes a vault created by cdno init, which declares the concept type. For an older vault, first run cdno config note-type install --name concept. The project surrogate-model stands in for whatever you are working on.

The input files below are scratch; write them outside the vault (for example under /tmp), or a stray .md in the vault root is reported as unindexable. The commands here use /tmp.

1. Note the substance in the day

On 2 September you work out why a low-rank refit is cheap. It is not a one-line event, so it does not go in ## Logs; write it to a file (or let the editor open, below) and log it as a note:

cat > /tmp/woodbury.md <<'EOF'
(A + UCV)^-1 = A^-1 - A^-1 U (C^-1 + V A^-1 U)^-1 V A^-1.

Cheap when A^-1 is already known and the update is low-rank: today's use was the
k=3 refit on [[surrogate-model]]. #concept
EOF

cdno log note --heading "Woodbury identity" --body-file /tmp/woodbury.md

Noted journal/2026/daily/2026-09-02#Woodbury identity

The body ends with #concept because this looks reusable. Run interactively without the flags, cdno log note asks for the heading and opens the body in your editor instead.

The daily note now holds the entry under ## Notes, and a pointer to it in ## Logs, with the entry’s wikilinks copied onto the pointer line:

# Wednesday, 2 September 2026

## Notes
### Woodbury identity
(A + UCV)^-1 = A^-1 - A^-1 U (C^-1 + V A^-1 U)^-1 V A^-1.

Cheap when A^-1 is already known and the update is low-rank: today's use was the
k=3 refit on [[surrogate-model]]. #concept

## Logs
- **14:32**: noted [[journal/2026/daily/2026-09-02#Woodbury identity]] ([[surrogate-model]])

## Notes did not exist yet, so it was created just above ## Logs. You did not have to decide whether this deserves a note of its own — that decision can wait.

2. Meet it again

On 24 September the same identity comes up in a k=5 refit. Note it again, under a heading of its own for that day. --date writes to a chosen day’s note (stamped at the current time); --json shows everything the command returns:

printf 'Refit again with k=5 on [[surrogate-model]]: Woodbury keeps the update at O(k^3) rather than a full re-inverse.\n#concept\n' > /tmp/refit.md

cdno log note --heading "Low-rank refit" --body-file /tmp/refit.md --date 2026-09-24 --json

{
  "log_line": "noted [[journal/2026/daily/2026-09-24#Low-rank refit]] ([[surrogate-model]])",
  "message": "Noted journal/2026/daily/2026-09-24#Low-rank refit",
  "path": "journal/2026/daily/2026-09-24.md",
  "target": "journal/2026/daily/2026-09-24#Low-rank refit"
}

target is the entry’s address: cite it anywhere as [[<target>]].

A heading already used that day, or one that reuses a section name, is refused and nothing is written:

$ cdno log note --heading "Logs" --body-file /tmp/refit.md --date 2026-09-24
Error: heading `Logs` is not allowed in `## Notes`: it is the name of a daily section

3. Find the candidates

The subject has now come up on two dates — the moment to promote. Search the daily notes for the tag’s word:

cdno search concept --type daily

Search: concept

▎ 1. Thursday, 24 September 2026    daily
▎ journal/2026/daily/2026-09-24.md
▎ …a full re-inverse. #[concept] ## Logs - **14:40**: noted [[journal…

▎ 2. Wednesday, 2 September 2026    daily
▎ journal/2026/daily/2026-09-02.md
▎ …refit on [[surrogate-model]]. #[concept] ## Logs - **14:32**: noted [[journal…

Search matches the word concept, not the tag, so in a lived-in vault it also returns days that only created, revised or linked a concept note. Open each hit (cdno open 2026-09-24) and read the ## Notes entries that end in #concept to see which share a subject.

4. Check the library first

Before you create anything, make sure the library does not already hold this concept:

cdno search woodbury --type concept

Search: woodbury
  (no matches)

Had there been a hit, you would refine that note (step 6) rather than create a second one.

5. Promote: create with origin

Write the concept’s opening in a file — without the # Title line, which the engine writes — and create the note with origin pointing at both entries:

cat > /tmp/concept-body.md <<'EOF'
A low-rank correction to a matrix whose inverse you already hold can be inverted
without starting again.
EOF

cdno note create concept --title "Woodbury identity" --body-file /tmp/concept-body.md \
  --origin "[[journal/2026/daily/2026-09-02#Woodbury identity]] [[journal/2026/daily/2026-09-24#Low-rank refit]]"

Created concepts/woodbury-identity.md

---
type: concept
created: 2026-09-25
tags: []
origin: '[[journal/2026/daily/2026-09-02#Woodbury identity]] [[journal/2026/daily/2026-09-24#Low-rank refit]]'
---

# Woodbury identity

A low-rank correction to a matrix whose inverse you already hold can be inverted
without starting again.

## Statement

## Why it matters

## See also

The body fills the template’s {{body}} slot, and the template adds its three sections after it. origin is stored as a single quoted string. Its links are indexed with the write, so the daily notes it names show the concept among their backlinks straight away.

Fill in tags in your editor (tags: [linear-algebra]). A --field tags=… value is written as a plain string, not a list, so the tag list is easiest to edit by hand.

The creation is logged to the day you run it, and you do not log it again:

- **09:10**: concept created [[concepts/woodbury-identity]] — Woodbury identity

6. Refine it

Fill the empty sections one at a time. Each call names the section, the file holding its new text (without the heading), and a reason:

printf '(A + UCV)^-1 = A^-1 - A^-1 U (C^-1 + V A^-1 U)^-1 V A^-1\n' > /tmp/statement.md
cdno note revise woodbury-identity --section Statement --content-file /tmp/statement.md \
  --reason "stated the identity"

Revised concepts/woodbury-identity.md

With --json, the result says what was logged:

printf 'Refitting a rank-k update costs O(k^3) plus the products with A^-1, instead of a fresh O(n^3) inverse; the k=5 refit on [[surrogate-model]] is the worked case.\n' > /tmp/why.md
cdno note revise woodbury-identity --section "Why it matters" --content-file /tmp/why.md \
  --reason "added the cost comparison" --json

{
  "changed": true,
  "log_line": "revised [[concepts/woodbury-identity#Why it matters]] — added the cost comparison",
  "message": "Revised concepts/woodbury-identity.md",
  "new_hash": "1d1d1cbac3cb10a7",
  "path": "concepts/woodbury-identity.md",
  "section_target": "concepts/woodbury-identity#Why it matters"
}

Running the same revision again changes nothing, so nothing is written or logged:

$ cdno note revise woodbury-identity --section Statement --content-file /tmp/statement.md --reason "again"
No change to concepts/woodbury-identity.md

The reason is not optional. In a script, leaving it out is an error; in a terminal, you are asked for it:

$ cdno note revise woodbury-identity --no-interactive --section "See also" --content-file /tmp/see-also.md
Error: missing required flag: --reason (provide it explicitly or run interactively in a TTY)

To rewrite the whole body instead, pass --body-file, or run cdno note revise woodbury-identity in a terminal with no file and the current body opens in your editor. If the note changes on disk while that editor is open, the revision is refused rather than overwriting the change.

Only custom types that are not append-only can be revised; a project, for one, is refused:

$ cdno note revise surrogate-model --body-file /tmp/why.md --reason "tidy"
Error: note 'projects/surrogate-model.md' cannot be revised: 'project' is a built-in note type; its sections are owned by its own commands

7. Read the trail

The day’s ## Logs now tells the concept’s story in three lines, and the two earlier days keep their noted pointers:

## Logs
- **09:10**: concept created [[concepts/woodbury-identity]] — Woodbury identity
- **09:14**: revised [[concepts/woodbury-identity#Statement]] — stated the identity
- **09:21**: revised [[concepts/woodbury-identity#Why it matters]] — added the cost comparison

There is no was: / now: copy of the old text: the log records when and why, and if you keep the vault in git, git records what. Tracing how your understanding of the identity evolved is a search over the journal: cdno search woodbury --type daily.

With an assistant

Over MCP the same walk uses four tools, and the assistant’s tool descriptions carry the habits above:

1. note_to_daily with heading and body — step 1 and 2.
2. search_notes with query: "concept" and note_type: "daily", then read_note on each hit — step 3.
3. search_notes with note_type: "concept", then create_custom_note with type_name: "concept", title, body and origin — steps 4 and 5.
4. revise_note with section, content and a reason it drafts from what it changed — step 6. A whole-body revise_note needs the content_hash from read_note as expected_hash.

See Write tools and Context-gathering tools for the parameters and refusal codes.

Next: Actions.

Actions

An action is the next concrete thing to do on a project. Cuaderno treats actions as cheap by default: the normal form is a single bullet on the project map, not a note you have to create and maintain. You only give an action its own note when it grows into real investigation. All verbs live under cdno action.

Add a next action

cdno action add --project surrogate-model --title "Profile the assembly step" --energy medium

This appends a checkbox bullet to the project’s next-actions list, tagged with its energy. That’s usually all an action ever is.

List open actions

cdno action list --project surrogate-model

Bullets that have been promoted to notes show their status (active / blocked / completed / dropped) inline. --json gives the structured list.

Promote an action to a manifest note

When an action becomes an investigation that spans days and produces evidence, promote it. This rewrites the bullet as a wikilink and scaffolds an action note (with status, energy, criteria, links). The match is a case-insensitive substring of the bullet text; energy is inherited:

cdno action promote --project surrogate-model --query "profile the assembly"

You can also create an action already promoted by passing --note to add:

cdno action add --project surrogate-model \
                --title "Characterise sample efficiency across mesh sizes" \
                --energy deep --note

Start an action

Starting is optional — nothing forces you to declare it — but it is what makes cdno now able to answer “what am I in the middle of?”, which matters most on the days you come back from an interruption and cannot remember:

cdno action start --project surrogate-model --query "assembly step"

This logs started [[surrogate-model]] — Profile the assembly step (medium) to today’s journal. What gets written is the resolved bullet text, not your query, so the later completion logs matching text and the focus clears by itself.

For work that is on no map yet — the fix you noticed, the errand in front of you — --unplanned adds the bullet and starts it in one go:

cdno action start --project surrogate-model --unplanned \
    --title "Chase the licence renewal" --energy light

That is deliberately a separate flag rather than a fallback when --query matches nothing. A fallback would turn every typo into a new action, silently.

Promoting an action between starting it and closing it is fine: promotion rewrites the bullet, and cdno now follows it to the new note, keeping the original start time.

Pause, switch and resume

Only one action is in focus at a time, so starting a second while the first is open is refused, with the command that does what you meant:

$ cdno action start --project surrogate-model --query "feature set B"
Error: Profile the assembly step is already in focus on surrogate-model (since 09:30).
To move on to this instead: cdno action switch --project surrogate-model --query 'feature set B'
Or complete or pause it first.

There are three ways to leave an action without finishing it, and they say different things:

# Stopping for now; leave yourself a note on where you were.
cdno action pause --next 'pick up at the profiler output' --reason "meeting"

# Moving to something else right now; pauses the open one and starts the new one together.
cdno action switch --project surrogate-model --query "feature set B" \
    --next 'profiler output half read'

# Coming back, later today or after a night's sleep.
cdno action resume

resume prints the next: you left, and brings the action back into focus as of now. Unlike drop, a pause does not close the bullet: it stays on the map and you can still complete it later. switch is a pause immediately followed by a start, and shows in the log as exactly that. In a terminal, pause and switch ask once where to pick up; press Enter to skip.

A start left open overnight is still your focus in the morning (cdno now says since Saturday 14:05). cdno action resume makes it today’s; otherwise it lapses after a day. See Focus for the idea and action for every flag.

Two open bullets with identical text cannot be told apart by a substring query, so neither can be closed until one is edited. This is not specific to starting; action add twice does the same.

Complete an action

Completing matches a bullet by substring, ticks it off, and logs it to today’s journal. If the action had a manifest note, that note is archived to actions/_done/<year>/ and becomes append-only:

cdno action complete --project surrogate-model --query "feature set B"

Drop an action

Not everything on the list gets done. When an action is superseded, abandoned or reprioritised, drop it rather than completing it:

cdno action drop --project surrogate-model --query "demo proposal" \
    --reason "superseded by the demo-planning action"

This matches and archives exactly like complete, but the note is stamped status: dropped with no completion date, and the journal records action dropped on … instead of action done on ….

The distinction matters more than it looks. The daily log is what the weekly review, the monthly scan and every later verdict read back from — so completing work that was never performed leaves your own vault asserting something untrue, and the only repair is a correction line written by hand. A dropped action also stays out of the completed-actions views, because it carries no completion date.

--reason is optional and worth giving. “Superseded by X” and “no longer wanted” are different facts, and only one of them tells you to go looking for the replacement.

Inline vs. manifest — when to promote

Keeping the default cheap is deliberate — it means capturing the next step never costs more than a sentence. See The Research Logbook Method for the rationale.

Next: Commitments and deadlines.

Renaming a note

A note’s slug is its file name, and every [[wikilink]] and every project: field types it. Sometimes the slug you got is not the one you want to live with. This tutorial renames a project whose derived slug stopped mid-title, follows what the rename changes, and covers what to do on a second machine. The reference is cdno note rename.

How you get a bad slug

The slug is derived from the title, and a long title is cut at 50 characters:

cdno project create --title "Calibrate the surrogate model against the high-fidelity thermal runs" --context work
# -> projects/calibrate-the-surrogate-model-against-the.md

Every later link now has to say [[calibrate-the-surrogate-model-against-the]]. The way to avoid this is to name the note when you create it:

cdno project create --title "Calibrate the surrogate model against the high-fidelity thermal runs" \
  --context work --slug surrogate-calibration

Every create verb takes --slug (see the slug rule), and an agent creating a note over MCP is told to propose a short one. For a note that already exists, rename it.

Preview first

Give the project an action note and start it, so that the journal and the action note both point at the project:

cdno action add --project calibrate-the-surrogate-model-against-the --title "Run the baseline sweep" --note --energy deep
cdno action start --project calibrate-the-surrogate-model-against-the --query baseline

Then preview the rename:

cdno note rename calibrate-the-surrogate-model-against-the --to surrogate-calibration --dry-run

Dry run: nothing written.
  move     projects/calibrate-the-surrogate-model-against-the.md -> projects/surrogate-calibration.md
  rewrite  actions/run-the-baseline-sweep.md                      1 field (project:)
  rewrite  journal/2026/daily/2026-11-06.md                       3 links
  alias    projects/surrogate-calibration.md gains `calibrate-the-surrogate-model-against-the`
  log      journal/2026/daily/2026-11-06.md
             renamed [[surrogate-calibration]] — Calibrate the surrogate model against the high-fidelity thermal runs
               was: calibrate-the-surrogate-model-against-the
  4 references in 2 notes · plan 2109…

Your plan hash will differ: the log lines carry their time stamps.

Each line is one change: the file moves, two other notes have references corrected (three links in the journal, from the lines for the project’s creation, the action and the start; the project: field of the action note), the project gains an alias, and today’s log gets one entry. Nothing is written. If the preview is refused, it is refused exactly as the write would be, so a dry run is a real check.

Write it

cdno note rename calibrate-the-surrogate-model-against-the --to surrogate-calibration \
  --reason "the derived slug stopped mid-title"

With the note and --to given, the command writes as soon as it has checked the plan, without a confirm, in a terminal or not; the dry run was your look, and it is advice, not a lock. Leave out --to in a terminal and you are asked for it, shown the preview and asked to confirm. That confirmed write is tied to the preview: if a note it would rewrite changed while you decided, it refuses with stale_plan and writes nothing. Over MCP the guard applies when the agent passes the preview’s plan_hash as expected_plan.

What changed

The project map has a new aliases: entry for the old name:

aliases: [calibrate-the-surrogate-model-against-the]

and the old name still works. cdno open calibrate-the-surrogate-model-against-the finds the project, and says it was found by its former name. cdno project show takes it too, and prints the current slug in its header.

Today’s log gains one entry:

- **09:44**: renamed [[surrogate-calibration]] — Calibrate the surrogate model against the high-fidelity thermal runs
  was: calibrate-the-surrogate-model-against-the
  reason: the derived slug stopped mid-title

was: is plain text on purpose. It records what the note was called, and a link there would be rewritten by the next rename. Every earlier state on [[…]] and started [[…]] line in the journal now names surrogate-calibration, so the project’s history is still one search, and a link clicked in an editor lands on the note.

This is the one place the vault edits the past. The log is append-only: what was recorded and when never changes. A reference is an address, not content, and correcting an address changes neither (see the method page). cdno lint accepts exactly that and nothing else in an archived note.

Renaming back

Rename old to new and back to old and you get aliases: [new]. The first renamed line’s link is rewritten to [[old]] like any other link to the note, and its was: old stays as written; the second reads renamed [[old]] … was: new.

When it is refused

Nothing is written on a refusal, and each has a code (the table says what to do for each). The common ones: the new slug is invalid or taken, the note is a kind that cannot be renamed (a daily note, an archived action; see which notes can be renamed), or the vault is behind its upstream.

The other machine

If the vault is a git repository synced between machines, the other one does nothing special: the renamed files, the corrected links and the alias arrive through the sync like any edit.

• Rename on a machine that is up to date. A rename refuses with behind_upstream while the vault is behind, and --skip-sync-check overrides that only when you know nothing unpushed on the other side touches these notes.
• If the sync stops on a conflict, resolve it, then run cdno lint. A link that came back with the old name still works through the alias, and lint warns that [[old]] names a renamed note, now new. Leaving it is harmless; cdno note rename new --relink rewrites every such link to the new name in one go (relinking the stragglers), and editing one by hand is allowed too, even in a past log entry.
• Run any cdno command in the vault once on every machine, on a cdno that has note rename, before renaming anything an archived action references; the reference says why and what cdno lint says otherwise.

Over MCP

An agent previews with rename_note { dry_run: true }, shows you the plan, and writes with the plan’s plan_hash as expected_plan. See Renaming a note.

Commitments and deadlines

A commitment is a dated promise — to others, or a hard promise to yourself. Cuaderno keeps these distinct from your to-do list and gives you one aggregated view of everything with a deadline, wherever it lives.

The aggregated view

cdno commitments              # everything due, sorted by date, overdue flagged
cdno commitments --weeks 6    # look six weeks ahead instead of the default two

cdno commitments is a computed view. It always includes a 30-day overdue look-back on top of the lookahead window, so nothing slips silently into the past. It draws from four sources (see Business rules):

1. Project milestones marked --hard, of an open (active or parked) project.
2. Stewardship periodic commitments (recurring dashboard lines).
3. Standalone commitment notes (below).
4. Action notes with a self-imposed due: not tied to a milestone, of an open (active or parked) project.

A project’s own dates (the first and last) count while the project is open, active or parked: a hard date on a parked map is still a promise. Completing or dropping a project takes its milestones and action due dates out of the view until it is activated again. A standalone commitment that names a parked or closed project keeps surfacing, since it is a promise to someone else.

Standalone commitments

For a one-off promise that isn’t naturally a project milestone or a recurring stewardship line:

cdno commit create --title "Pay rent" --due 2026-06-01 --context personal
# -> commitments/pay-rent.md

# Optionally attribute it to a project or stewardship:
cdno commit create --title "Review Erik's draft" --due 2026-05-20 --context work --project projects/icml-paper

When it’s fulfilled, mark it done — it’s stamped and moved to commitments/_done/<year>/:

cdno commit done --slug pay-rent

When a promise ends without being kept

Not every promise is kept. The client cancels, the plan changes, the thing is overtaken by events. Marking it done would be the wrong record — cdno commitments and every weekly and monthly review read the daily log back, and a completion says the promise was fulfilled:

cdno commit drop --slug quarterly-report --reason "the client cancelled the engagement"

The note is archived beside your completed ones, stamped status: dropped with no completion date, so it never counts as finished work. --reason is optional; a typo needs no explanation, a cancellation usually deserves one.

If the date merely moved, reschedule is the verb you want — it records the move rather than ending the promise.

Nothing is destroyed by a drop: the note keeps its body and its created date. But a drop is re-decided rather than undone — there is no un-drop. If the promise comes back, make it again, and the record honestly shows both decisions.

Deadlines that live elsewhere

You often don’t need a standalone note — put the deadline where the work is:

# A hard project milestone shows up in `cdno commitments`:
cdno project milestone add --slug icml-paper --title "Camera-ready" --date 2026-02-01 --hard

# A recurring obligation on a stewardship dashboard:
cdno stewardship add-periodic --stewardship finances --title "File quarterly taxes" \
     --every "every 3 months" --next 2026-07-15

Both surface in the same aggregated list, so cdno commitments is the single place to answer “what have I promised, and when?”.

Next: Stewardships and tracking.

Stewardships and tracking

A stewardship is a small, bounded, perpetual responsibility — your health, your finances, a service you maintain. Unlike a project it never “finishes”; you just tend it. Stewardships can carry recurring commitments and, when expanded, time-series tracking. Verbs: cdno stewardship and cdno track.

Two shapes: flat and expanded

# Flat — a single dashboard file, no tracking. Good for "finances".
cdno stewardship create --name "Finances" --context household

# Expanded — a folder with room for tracking/ and routines/. Use --tracking.
cdno stewardship create --name "Health" --context personal --tracking

A flat stewardship is stewardships/<slug>.md. An expanded one is stewardships/<slug>/ with an _index.md, a tracking/ subfolder for entries, and a routines/ subfolder for reference docs (workout plans, checklists — not logs). Only expanded stewardships accept tracking entries.

See what you’re tending

cdno stewardship list                 # each one's variant, tracking count, staleness badge
cdno stewardship show --slug health

Periodic commitments

Recurring obligations attached to a stewardship show up in the aggregated commitments view:

cdno stewardship add-periodic --stewardship health --title "Dental check-up" \
     --every "every 6 months" --next 2026-09-01

--every takes a recurrence: daily, weekly, monthly, yearly, or every N months.

Tracking entries

For habits and metrics on an expanded stewardship, file a tracking note. The activity is positional and selects the template — a vault’s .cuaderno/templates/tracking-<activity>.md if you have one, else a generic fallback. (Ready-made variants live in the repo’s examples/templates/tracking/; see Customising templates.)

cdno track gym --stewardship health --content "Upper body A; RDL up to 25kg"
cdno track body --stewardship health --content "Weight 78.4kg, resting HR 54"
cdno track swim --stewardship health --content "1500m, 28min"

• --stewardship can be omitted when there’s exactly one expanded stewardship — Cuaderno defaults to it. With more than one, it’s required.

• --routine links a reference doc from the stewardship’s routines/ folder into the entry — but only when the resolved template has a routine: field (the gym.md example variant does; the generic default has none, so it no-ops there).

• --content is optional; leave it empty and fill the entry’s tables in afterward.

• --at files the entry for a day that has already passed. Recording lags the event more often than not — a statement reconciled at the weekend, a reading taken this morning and typed up tonight — and without it the entry lands on the wrong day and the trend bends.

  cdno track body --stewardship health --at 2026-04-06
  

  Filing is always journalled to today’s daily log, naming the day the entry describes, so a backfill stays visible in the record rather than quietly appearing in the past. Dates more than 50 years back or a year ahead are refused — that far out is a typo, and a typo would reshape a trend without saying so.

Numbers belong in frontmatter

A number written into the body is prose; a number in frontmatter is data. An agent files them through the MCP create_tracking_entry tool’s metrics parameter, and each key becomes a frontmatter key:

---
type: tracking
stewardship: finances
activity: savings
date: 2026-07-25
balance: 12480.50
contributed: 400.00
---

When one entry holds several comparable items — three subjects practised, four categories spent against — write a sequence of flat records rather than one key per item, so the same subject can recur within the entry:

detail:
  - { minutes: 25, subject: harmony }
  - { minutes: 20, subject: harmony }
  - { minutes: 15, subject: sight-reading }

A metric that reports a level rather than a total — a balance, a measurement, the last set of the day — reduces to the last record in the entry, and “last” means the order the records appear in the file. If you append them out of order, give every record an at field and they sort by it:

detail:
  - { balance: 1200, at: "09:00" }
  - { balance: 1240, at: "18:00" }

It is all-or-nothing: if any record lacks an at, or carries one that does not parse (09:00, 9:00, 9:00 AM and their with-seconds forms all do), the file’s own order stands and nothing is reordered. The key is at rather than time precisely because time is a plausible metric — a swim split, a lap time — and ordering a record set by one of its own measurements would report a number that was never the last reading.

Write the colon. at: 18:00 needs no quoting — the colon is what keeps YAML reading it as text — but at: 1800 is a number and never reaches the time parser at all.

Falling back to file order is the safe answer — ordering a half-stamped set would have to invent a position for the unstamped records, and whichever position it invented would quietly change which reading a last metric reports. But the fallback used to be invisible, so a set stamped morning / evening looked identical to one that sorted correctly. cdno lint now reports an at it cannot use, and a set where only some records carry one, naming the note and the value. An entry with no at anywhere is never reported: that is the normal way to write these notes.

Declaring a metric under [schemas.tracking.fields] (see Configuration) gets it type-checked on the way in — a float for a measurement or an amount, an int for a count. Anything undeclared is written as given, except the four keys that identify the note — type, stewardship, activity, date — which a metric may not name. They are the note’s identity rather than data about it, and the engine owns them: date is fixed by the filename, and activity is what every reader groups by.

Tracking entries are append-only — they’re your historical record. Read them back over a window via the MCP get_stewardship_tracking tool, or with cdno search.

From entries to series

Filing an entry is half the story. The other half — how those numbers turn into a chart, and why a series sometimes shows a number that means nothing — comes down to two things: which aggregate each metric declares, and which source, body table or frontmatter, the activity is read from. Every [tracking.<activity>] key is documented in full in the Tracking section of the configuration reference; this is the plain-language version of why those keys exist.

The metric-kind taxonomy

Every number you track is one of four kinds, and the kind decides the aggregate it wants:

Summing is right for exactly one of these — a total — and wrong for the rest. It’s wrong for a level because it adds successive readings of one quantity instead of reporting the quantity: three statements through a spending-free month, each reading a balance of roughly 12,480, would sum to over 37,000 — a number nothing in the account corresponds to. It’s wrong for a rating because the series grows with how often you record it, not with how the session actually went — log twice a day instead of once and the total doubles for no reason but the logging cadence. An occurrence doesn’t want a number at all: declaring the activity with no metrics is a complete, valid use — the record is “this happened”, not “how much”.

Two worked examples

A scalar activity, a level. The savings activity shown above has no repeated records — every entry is one reading. balance is a level, so it wants last, not the default sum; contributed is a total, so the default is already right:

[tracking.savings]
# no `records` — this activity's metrics are scalars read straight off the entry

[tracking.savings.metrics.balance]
aggregate = "last"     # a LEVEL — the reading itself, not a running total of readings
unit      = "EUR"

[tracking.savings.metrics.contributed]
aggregate = "sum"      # a TOTAL — money added since the last entry
unit      = "EUR"

Filed against the frontmatter shown earlier (balance: 12480.50, contributed: 400.00), this produces two series: savings · balance, whose points are each entry’s balance verbatim, and savings · contributed, whose points are the sum of every contribution recorded on that date.

A record-based activity, two aggregates over the same records. practice splits by subject and tracks two different kinds of number per session:

[tracking.practice]
records  = "detail"        # frontmatter key holding the repeated records
group_by = "subject"       # one series per distinct subject

[tracking.practice.metrics.minutes]
type      = "int"
aggregate = "sum"          # a TOTAL — minutes practised
unit      = "min"

[tracking.practice.metrics.focus]
aggregate = "mean"         # a RATING — sum would grow with how often you log, not with how focused you were

One entry covering two subjects in the same sitting:

---
type: tracking
stewardship: study
activity: practice
date: 2026-07-25
detail:
  - { minutes: 25, focus: 8, subject: harmony }
  - { minutes: 20, focus: 6, subject: harmony }
  - { minutes: 15, focus: 9, subject: sight-reading }
---

Four series come out of it, named <activity> · <group> · <metric>:

• practice · harmony · minutes = 45 (25 + 20, summed)
• practice · harmony · focus = 7 (the mean of 8 and 6)
• practice · sight-reading · minutes = 15
• practice · sight-reading · focus = 9

Same records, same date, two different reductions — because minutes and focus are different kinds of number, not because one config option was chosen for the whole activity.

Gaps, not zeros

A subject you didn’t practise on a given day produces no point on that day, not a zero. Zero-filling would draw a false line down to the axis — a session that didn’t happen is not the same as a session scored zero. The same rule means a brand-new subject needs no configuration change: the first time ear-training shows up in a detail record, its series starts there, on that date, with every date before it correctly absent rather than zero.

Which source a series comes from

An undeclared activity — no [tracking.<activity>] for it in config.toml — is read from the first table in the note’s body: one series per column, each column’s numeric cells summed. That’s right for a rep count and wrong for almost everything else, which is why the declared path above exists. If you’re still filing through a table, see Wide, not long in the example templates — a table column is a series, and a Metric / Value row shape sums unrelated numbers into one meaningless total.

Declaring an activity moves it to frontmatter: once the declaration yields a series for that activity, its body tables are no longer read — every note of it, not just the ones carrying frontmatter metrics. So the same metric can never appear twice under two disagreeing numbers, one from a table and one from the declared reduction. It also means a half-migrated activity shows only what its frontmatter carries, so migrate an activity’s notes together rather than one at a time.

Next: Weekly review.

Weekly review

The weekly review is the one slightly-longer ritual in the method — a short retrospective plus a single goal for the week ahead. It’s where you celebrate progress, notice what’s stuck, and set direction without micromanaging.

The weekly note

Each ISO week has a weekly note with four sections:

• Wins — what moved (actions completed, evidence filed, projects advanced).
• Challenges — what got in the way.
• One Improvement — a single thing to change next week.
• This Week’s Goal — the week’s anchor: one goal everything else orbits.

View the current week’s note (or any week) any time:

cdno weekly                       # this ISO week
cdno weekly --date 2026-04-20     # the week containing that date

The guided ritual

cdno review weekly walks you through it. Interactively, it prompts for each retrospective section and writes them into this week’s note, then asks for next week’s goal and sets it as the This Week’s Goal of next week’s note — so when the new week starts, its anchor is already there.

cdno review weekly

Run non-interactively (or with --no-interactive), it reads the current note rather than prompting — handy for scripts or a quick scan.

A weekly cadence that works

A simple routine, ~15 minutes:

1. cdno status — skim active projects and their top actions.
2. cdno commitments --weeks 2 — what’s due in the next fortnight?
3. cdno stewardship list — any habit looking stale?
4. cdno review weekly — capture Wins / Challenges / One Improvement, set next week’s goal.

The point isn’t a perfect record; it’s a regular moment to look up from the work, acknowledge what you did, and choose one direction. Parking, completing or dropping a project here, or retiring a question, is a good outcome, not a failure.

A question per relationship

Not every open project is asked the same thing, because not every project is yours to move. Walk the active projects (cdno project list shows which name a holder) and ask each the question its relationship implies:

• Yours (no holder): did it move? If it sat still, is it still the priority, or should it wait? Parking it is a fine answer.
• Handed off, and its map changed this week: what came back, and what is waiting on my decision? Not “did it move?”: the moving is someone else’s.
• Handed off over an empty Waiting On: a name over an empty Waiting On is a parked map wearing a name. Park it, or take it back.
• Handed off, but you worked on it yourself on two or more days this week: doing a thing on a handed-off map does not make it yours, doing most of its work does. Take it back, or change the name to whoever really has it.
• Handed off, and stuck for weeks (at the monthly review, from its list of stuck projects): chase the holder, or take it back.

A handed-off project that did not change this week needs no question at all. The questions are prompts, never verdicts, and a hand-off is never an answer to a full cap: to make room, park, complete or drop a project. See Managing projects.

With Claude

The MCP tools get_weekly_context, read_weekly_note, and upsert_weekly_section let an assistant run the same review conversationally — reading your week back to you and writing the sections as you talk. get_weekly_context carries, per active project, counts, held_by, changed_this_week, waiting_on_empty and focus_days_while_held, so an assistant can ask each project the question above (the stuck-project question reads get_monthly_context’s stuck_projects, not these fields); the weekly-review example skill shows how. See Connect to Claude.

Next: Inbox and triage.

Inbox and triage

The inbox is a pressure-release valve: capture a thought now, decide what to do with it later. This keeps the daily loop friction-free — you never have to stop and classify something mid-flow.

Capture

cdno capture "does Chen 2025 use the same preconditioner?"
cdno capture "ask IT about the cluster quota"

Each capture becomes a small slug-named note in inbox/. That’s the whole cost — no fields, no decisions. Capture liberally.

Triage

When you have a moment (a natural fit for the weekly review), process the inbox:

cdno triage

Interactively, triage walks each pending capture and offers, for each one, to:

• keep it as a project action — turn it into a next action on a project, or
• discard it — it served its purpose, or
• skip it — leave it for next time.

Run non-interactively (or with --no-interactive), triage just lists what’s pending — a quick way to see the backlog without acting on it.

A healthy inbox is empty-ish

The inbox is a transit point, not a filing cabinet. The goal isn’t zero at all times — it’s that nothing important lives only there. Anything worth keeping becomes an action, a piece of evidence, a question, or a log line; the rest gets discarded without ceremony.

With Claude

The MCP tools capture, triage_inbox (lists pending items), and discard_inbox_item let an assistant capture on your behalf and help you clear the backlog conversationally.

Next: Searching your vault.

Searching your vault

Cuaderno keeps a full-text index of every note, so you can find anything fast — ranked best-first, with filters by type, date, and portfolio. The command is cdno search.

The index covers each note’s title as well as its body, and a title match counts for ten times a body match. So searching for words you remember from a note’s heading surfaces that note first, even if a dozen other notes mention the same words in passing — there is no separate “search by title” command to remember.

If you already know exactly which note you want, cdno open takes you straight there by slug, date, or path, without ranking anything.

In a terminal, cdno search also follows its results with a picker: choose a hit and it opens in your editor. The results print first either way, so piping or redirecting the output is unaffected.

Basic search

cdno search "preconditioner"
cdno search "sparse attention"     # multiple words are ANDed

The query is matched case-insensitively and terms are combined with AND. Quotes and operators are treated as literal words, not search syntax. Results come back ranked, best match first.

Filter the results

# Only one note type:
cdno search "ablation" --type evidence

# Within a date window (inclusive):
cdno search "mesh" --from 2026-03-01 --to 2026-03-31

# Only inside one portfolio:
cdno search "speedup" --portfolio sparse-vs-dense-attention-ood

# Cap the number of hits (default 20):
cdno search "todo" --limit 5

Filters combine, so you can scope tightly:

cdno search "preconditioner" --type evidence --portfolio sparse-vs-dense-attention-ood --from 2026-01-01

Scripting with --json

--json returns the ranked hits as a JSON array — each with path, note_type, title, snippet, and score — ready for jq or another tool:

cdno search "speedup" --json | jq -r '.[].path'

See JSON output for the exact shape.

When search feels stale

Search reads the SQLite index, which is reconciled automatically on every run. If results ever look out of date (e.g. after a bulk external edit), rebuild it explicitly:

cdno reindex

The Markdown files are always the source of truth; the index is just a rebuildable cache (see Business rules).

Next: Customising templates and frontmatter — tailor how notes are scaffolded and which frontmatter fields they require.

For exhaustive detail on any command, see the CLI reference.

Customising templates and frontmatter

When cdno scaffolds a note it fills a template. Every note type has a built-in template, and you can override any of them per-vault — to change the structure, the default sections, or the frontmatter fields. You can also require extra frontmatter fields so cdno lint keeps your notes consistent. This tutorial walks through both, hands-on.

What’s covered here is the shipped behaviour. Both kinds of config variable now resolve in custom templates: static [variables] and interactive [variables.prompt] (gathered from a TTY prompt or a --var name=value flag).

Where templates live

Templates live in .cuaderno/templates/, one Markdown file per note type (e.g. project.md, evidence.md). cdno resolves the effective template at creation time:

1. a custom variant file — <type>-<variant>.md (tracking uses this: the variant is the activity slug, e.g. tracking-gym.md), then
2. a custom type file — <type>.md, then
3. the built-in variant default, then
4. the built-in type default.

So a custom file in .cuaderno/templates/ always wins over the built-in. No activity-specific variants ship built-in (tier 3 is empty today) — tracking variants are entirely yours to add; see Tracking variants below.

cdno init writes two starter templates — .cuaderno/templates/daily.md, and concept.md for the concept custom type it declares. Every other built-in type uses its built-in default until you add a file for it. The quickest way to get an editable copy of a built-in is cdno templates eject <type> — e.g. cdno templates eject project writes .cuaderno/templates/project.md matching the built-in, ready to edit. You can also just create the file yourself, as the next section shows.

Customise a template

Say you want every project to start with a ## Risks section. Eject the built-in as a starting point:

cdno templates eject project        # writes .cuaderno/templates/project.md

That writes the full built-in template. Insert a ## Risks section (you can reference any of the {{placeholders}} that cdno templates vars project lists) and leave the rest as-is, so .cuaderno/templates/project.md reads:

---
type: project
context: {{context}}
status: {{status}}
created: {{created}}
core_question: {{core_question}}
closed: null
---

# {{title}}

## Current State
New project. No work done yet.

## Risks

## Next Actions
- [ ] Define first concrete step (light)

## Waiting On
(nothing yet)

## Milestones
- [ ] First milestone — target: TBD

## Links
- Portfolio: (none yet)

Now create a project:

cdno project create --title "Surrogate model" --context work

The new projects/surrogate-model.md follows your template — including the ## Risks section:

---
type: project
context: work
status: active
created: 2026-06-30
core_question: null
closed: null
---

# Surrogate model

## Current State
New project. No work done yet.

## Risks

## Next Actions
- [ ] Define first concrete step (light)

## Waiting On
(nothing yet)

## Milestones
- [ ] First milestone — target: TBD

## Links
- Portfolio: (none yet)

cdno templates eject <type> is the recommended way to get an editable base — it matches the built-in at the moment you eject. (You could instead hand-write the file, or shape it from a note cdno already created, but eject saves the guesswork.) If a later release adds a frontmatter key to the built-in, your copy does not gain it by itself: cdno lint and cdno templates list say so, and cdno templates sync <type> adds it without touching your edits.

Editing a template only affects notes created afterwards — existing notes are untouched. (And cdno normalise only reorders frontmatter keys; it won’t add a new section like ## Risks to old notes.)

closed: in a customised project template. The built-in project template ends its frontmatter with closed: null, the date a project is completed or dropped. A .cuaderno/templates/project.md you ejected before that key existed does not gain it by itself, and nothing breaks if it never does: closing a project writes the key whenever it is missing. cdno lint and cdno templates list say when your template lacks it, and cdno templates sync project adds it next to its built-in neighbour (after core_question: when you kept that) without touching anything else. The same command covers any key a future release adds to a built-in template.

Tracking variants

tracking is the one type whose template is chosen per activity. cdno track <activity> slugifies the activity and looks for .cuaderno/templates/tracking-<activity>.md, falling back to the generic tracking template when there’s none. So a custom .cuaderno/templates/tracking-gym.md gives cdno track gym a bespoke layout without touching cdno track swim, and .cuaderno/templates/tracking.md overrides the generic fallback for everything else.

Only the neutral generic template ships built-in — no activity-specific variants are baked into the product. Ready-made gym, body, and swim variants (exercise table, body-metrics table, swim-set table) live in the repo under examples/templates/tracking/; copy one to .cuaderno/templates/tracking-<activity>.md to use it, or start your own from it.

Template variables

Templates use {{placeholder}} markers. cdno substitutes the values the note’s creation command supplies. Two rules to know:

• An omitted optional value renders as null (e.g. core_question: null above when you don’t pass --question).
• An unknown placeholder is left verbatim — {{nope}} stays as the literal text {{nope}} in the note. So a template should only use the placeholders its note type actually provides.

Each type provides these:

You can use any subset, in any order, and add as much static Markdown around them as you like.

Daily specifics. weekday and day_name are aliases for the same value — the weekday name (e.g. Sunday) — so use whichever reads better. week is the ISO-week label YYYY-Www (e.g. 2026-W27), matching the weekly note for that date, so [[{{week}}]] in a daily template links straight to it.

Discover them from the CLI. cdno templates vars <type> lists exactly this table for a type — the complete set its create path supplies — and folds in any [variables] / [variables.prompt] names your config adds, classified by source. For example cdno templates vars tracking. See the templates reference.

Static config variables

Beyond the per-type placeholders above, a custom template can reference vault-wide static variables you define under [variables] in .cuaderno/config.toml. These resolve on every note type. For example:

# .cuaderno/config.toml
[variables]
author = "A. Researcher"
institution = "University of Examples"

A custom template can then use {{author}} / {{institution}} and they’ll be substituted at creation. Precedence: a per-type (contextual) placeholder of the same name always wins over a config variable, so config vars only fill names the note type doesn’t already supply.

Prompted variables

A static variable is the same on every note. When you want a value that changes per note — a ticket id, a collaborator, a meeting code — declare it under [variables.prompt], where the value is the prompt message:

# .cuaderno/config.toml
[variables.prompt]
ticket = "Ticket reference?"

Reference it in a custom template like any other placeholder (e.g. ticket: {{ticket}} in the project frontmatter). When you create a note whose effective template uses a prompted variable, cdno gets the value one of three ways:

• --var name=value on the command (repeatable), e.g. cdno project create --title T --context work --var ticket=ABC-123;
• otherwise, in an interactive TTY, cdno asks (“Ticket reference?”) and shows the value in the confirm preview before writing;
• otherwise (non-interactive, no --var) it errors rather than writing a note with a literal {{ticket}}:

Error: missing value for template variable 'ticket' (pass `--var ticket=value`, set a default under
[variables] in .cuaderno/config.toml, or run interactively in a TTY)

--var is available on every note-creating command: project create, question create, stewardship create, commit create, portfolio create, file, track, action add --note, and action promote.

A few rules worth knowing:

• A prompted name that also has a static [variables] default is satisfied by that default — you’re not asked, and it won’t error. (The static default wins by precedence, so --var can’t override it; remove the default if you want to be prompted.)
• A [variables.prompt] entry whose {{name}} your template doesn’t actually use is ignored.
• The same precedence applies: a per-type placeholder of the same name wins over a prompted variable.
• --var only applies to templated notes. cdno file --attach (the attachment stub) and a plain action add (no --note) aren’t templated, so --var is ignored there.
• The implicit-write paths — daily (log), weekly, and inbox (capture) notes — don’t gather prompted values, and neither do MCP-driven creations (there’s no --var over MCP). A [variables.prompt] placeholder in one of those templates fails at creation (an UnresolvedPrompts error) instead of being asked for; give it a static [variables] default instead.

Frontmatter field order and normalise

Your template also defines the canonical order of frontmatter keys for that type. Notes cdno creates are already in that order; for hand-authored or migrated notes, cdno normalise reorders their frontmatter to match the template (--check reports without writing). So if you reorder the keys in project.md, a later cdno normalise brings older project notes into line.

Require extra frontmatter fields

Beyond the built-in required fields, you can demand vault-specific ones per type with a [schemas.<type>] section. For example, to require every project to name an owner, add to .cuaderno/config.toml:

[schemas.project]
extra_required = ["owner"]

This is enforced by cdno lint, which now errors on any project missing the field (a missing key, or one whose value is null, fails):

cdno lint
# [error] projects/surrogate-model.md: missing required field `owner` for note type `project`
# Error: found 1 error(s), 0 warning(s)

lint exits non-zero on errors, so this is a good gate to run in a pre-commit hook or CI over a git-tracked vault.

Satisfy the requirement going forward

Add the field to your template so new notes carry it. Give it a non-null default you can edit per note (an empty key — owner: — is YAML null and still fails the lint; use a placeholder value):

---
type: project
context: {{context}}
status: {{status}}
created: {{created}}
core_question: {{core_question}}
closed: null
owner: unassigned
---

New projects are now born with owner: unassigned (edit it as needed) and pass the lint. Existing notes aren’t changed retroactively — fix them by adding the field, then re-run cdno lint until it’s clean.

Required fields are about presence, not value: any non-null value satisfies the check. Combine extra_required with a template default and the occasional cdno lint and your vault stays uniform without any per-note ceremony.

Give a field a type

extra_required only checks that a key is present. When you want cdno lint to also check the value — that meds is a boolean, mood is one of a fixed set, since is a real date — declare a typed field instead, under [schemas.<type>.fields.<name>]:

[schemas.daily.fields.meds]
type = "bool"
default = false

[schemas.daily.fields.mood]
type = "string"
values = ["low", "ok", "good"]

Now a daily note whose meds: isn’t a boolean, or whose mood: isn’t one of the three allowed values, gets a cdno lint warning. Typed fields are also recognised by cdno templates, so a custom template referencing {{meds}} no longer warns that it “renders literally”.

A typed field’s default is populated at create, too: add meds: {{meds}} to your custom daily.md and every new daily note is scaffolded with meds: false — the declared default — rather than a literal {{meds}}. A field with no default renders null. (As with any placeholder, the field only appears in a note if the template references it; and if the note’s create path already supplies that name, or a [variables] static var does, that value wins over the default.) See Typed schema fields in the configuration reference for the full grammar and its limits.

Edit templates from the CLI

cdno templates covers the whole loop without leaving the terminal.

cdno templates list                         # every type, which template is in effect, and where
cdno templates show project                 # the effective content, verbatim
cdno templates eject project                # copy the built-in default into .cuaderno/templates/
cdno templates save --note-type project     # write it: --file, --file - for stdin, or $EDITOR
cdno templates sync --all                   # add keys a release added to the built-ins, keep your edits
cdno templates new --note-type people       # scaffold a starter for a custom type

list names the source in effect for each type — builtin_default, custom_base, a variant, or none for a custom type with no template yet. save on a built-in creates the override for you, so it needs no prior eject, and show is byte-verbatim, which means the round trip holds:

cdno templates eject project
cdno templates show project | diff - .cuaderno/templates/project.md   # no output

See the templates reference for every flag.

See also

• Configuration — the configurable surface.
• Configuration reference — every config.toml key.
• Frontmatter fields — the built-in fields per note type.
• normalise, lint.

Tracking people

Cuaderno’s built-in types don’t include a “person” — deliberately, since a person decomposes into the notes you already keep (daily logs, meetings, actions, commitments). But if you want to answer questions like:

• What was my last interaction with Jane?
• When did I ask Jane to do something — and what did she ask me?

…a custom note type plus a linking convention gets you there, with no bespoke CRM. This recipe is the worked example; the files live in examples/note-types/person/.

1. Declare the type

Add to .cuaderno/config.toml:

[note_types.person]
folder = "people"

That’s the minimum — a person’s identity is the note title. (Add required/optional fields if you want enforced frontmatter; see the reference.)

Optionally copy the example person.md to .cuaderno/templates/person.md for a note with a ## Log section. Without a template, Cuaderno synthesises a minimal note.

2. Create people

cdno note create person --title "Jane Smith"

This writes people/jane-smith.md. cdno note list person enumerates them; cdno lint keeps them honest.

3. Link people from your notes

The key habit: whenever a person shows up in a daily log, a meeting section, or an action, reference them with a [[people/<slug>]] wikilink:

## Logs
- **14:30**: standup — [[people/jane-smith]] asked me to review the sparse-attention draft

Body wikilinks are indexed, so every mention becomes a backlink on the person’s note, and the raw text is full-text searchable.

4. Answer the questions

“What was my last interaction with Jane?” — the reliable answer is the top line of her person note’s ## Log, which you keep most-recent-first. To scan across the vault, search her slug:

cdno search "people/jane-smith" --type daily --from 2026-06-01

Search ranks by relevance, not date, so bound the window with --from / --to and read the dates on the hits (daily notes carry their date in the filename) rather than trusting the order. Drop --type to include meetings and action notes.

“What did Jane ask me — and what did I ask her?” — this is direction, which lives in your prose, not in structure. Write the log line so the direction is explicit (“Jane asked me…”, “I asked Jane…”), and either keep a running ## Log in her person note or let search surface the lines. A Claude skill can read the dated results and summarise who-owes-what; the structure gives it the material, the prose gives it the direction.

Why a “person” type and not a built-in

A custom person type is schema-only — it gives you a folder, linting, search, and backlinks, but no bespoke behaviour. That’s exactly right here: people don’t need caps, state machines, or aggregation; they need to be findable and linkable. If you later want richer per-person structure, add fields to the config declaration — no code change. See Custom note types for the full schema.

CLI reference

cdno is the command-line interface to a Cuaderno vault. This section documents every command. For the why behind them, see Concepts and Tutorials.

cdno [OPTIONS] <COMMAND>

Run cdno --help for the command list, or cdno <command> --help for any command’s flags.

Global options

These apply to every command:

Finding the vault

When --vault is not given, cdno discovers the vault by walking up from the current directory until it finds a .cuaderno/ folder. If that finds nothing, it falls back to the CUADERNO_VAULT_PATH environment variable. Standing inside a vault always wins over the env var. See Initialise a vault.

Interactive vs. scripted

Write commands follow one convention (the “flags-and-prompts” pattern):

• Interactive terminal, missing a required flag → cdno prompts for it, then asks you to confirm before writing.
• Non-interactive (either stream not a terminal — piped, redirected, < /dev/null, or running in CI, which is the usual reason neither is — or --no-interactive) → a missing required flag is an error. Supply every flag and the command runs unattended.

This means the same command serves a human at a prompt and a script with no changes.

Read commands add one thing on top. In a terminal, several listings offer to open one of the rows they just printed — cdno project list asks which project you want to see, prints it, and asks again until you press Esc. The listing itself is printed first either way, so piping, --no-interactive, and --json all behave exactly as they did before. See Colour and interactivity.

JSON output

--json makes any supported verb emit structured output:

• Read verbs (commitments, questions, status, now, orient, search, open, and the list/show verbs of project/portfolio/stewardship, plus action list) emit their listing or detail object.
• Write verbs (log, capture, file, track, and the create/update verbs of project, action, portfolio, stewardship, question, commit) emit a { "path": ..., "message": ... } result, and run non-interactively (so prompts can’t corrupt the JSON on a terminal). project complete and drop add what was let go, and print a refusal object and exit 1 while items are open (see JSON output).
• migrate emits its report, the plan with --dry-run (see migrate).
• Maintenance / interactive / bootstrap commands (init, lint, reindex, normalise, triage, review, weekly, monthly) ignore --json.

The CLI’s JSON shapes match the MCP server DTOs. See JSON output for every shape.

Naming a note: --slug

Every verb that creates a note derives its filename, the slug, from the title. For a long title the derived slug can stop mid-thought (rerun-the-surrogate-model-ablation-on), and it is what every later [[wikilink]] has to type. The create verbs therefore take an optional --slug <SLUG> to name the file yourself: project create, question create, portfolio create, action add --note, action promote, note create, stewardship create and commit create. The title is unchanged; only the filename is.

An explicit slug must be:

• lowercase a-z, 0-9 and single -, with no - at either end;
• at most 50 characters;
• not something YAML would read as a number, a boolean, a null or a date (2026, yes, null, 2026-11-05): add a word to it.

An explicit slug is used exactly or refused, never rewritten. If another note already holds the name (as its filename, or as the folder of a folder note such as portfolios/surrogate-model/) the create is refused and nothing is written; pick another name. The -2 suffix belongs to derived slugs only. --slug is never prompted for; omit it and the slug derives from the title. In a terminal a refusal reads:

$ cdno project create --title "Surrogate model" --context work --slug surrogate-model
Error: creating project

Caused by:
    slug 'surrogate-model' is taken by 'projects/surrogate-model.md' (as its stem)

Under --json a refusal is a coded object.

A derived slug takes -2 when the name is held, and a folder note’s name counts as held: a question titled “Surrogate model” created beside the portfolio portfolios/surrogate-model/ gets surrogate-model-2, since the bare name would shadow the portfolio’s _index in a [[surrogate-model]] link. This applies to the verbs that disambiguate: project create, question create, action add --note and action promote, note create and commit create. portfolio create and stewardship create keep the raw derived slug (a portfolio’s slug correlates with its question’s) and refuse a collision outright.

cdno action add --project surrogate-model --note --energy deep \
  --title "Rerun the surrogate model ablation on the held-out split with feature set B" \
  --slug feature-set-b-ablation
# -> actions/feature-set-b-ablation.md

Renaming a note after the fact is a separate verb, planned under RFC 0007.

The commands

cdno init

Create a new vault: the folder tree, a default .cuaderno/config.toml (which declares the concept custom type), and starter daily.md and concept.md templates (every other built-in type uses an in-binary default until you eject one).

cdno init [OPTIONS] [PATH]

Arguments

Options

Only the global options apply. init ignores --json.

Examples

# Create a vault in a new directory:
cdno init ~/notebook

# Initialise the current directory as a vault:
cdno init

It fails if the target already contains a .cuaderno/ directory (it won’t clobber an existing vault).

See also

• Initialise a vault — what the tree contains and how discovery works.
• Vault structure.

cdno log

Append a log entry to today’s daily note (creating the note if it doesn’t exist yet).

cdno log [OPTIONS] <MESSAGE>
cdno log note [OPTIONS]

Arguments

Options

Plus the global options. With --json, emits a {path, message} result.

Examples

cdno log "scaled the mesh to 2M cells; 4x runtime, still stable"

# Backdate an entry:
cdno log "forgot to record: fixed the sampler seed" --at 2026-04-24T18:30

# Scripted:
cdno log "nightly run complete" --json
# -> { "path": "journal/2026/daily/2026-04-25.md", "message": "Logged to ..." }

Daily notes are append-only — log only ever adds.

A first argument, before any option, that names a subcommand (note) selects it. To log that bare word as a message, pass it after --: cdno log -- note.

cdno log note

Write worked-out substance (a derivation, a procedure, a page of reasoning) to a daily note as one ### <heading> entry under ## Notes. The pointer line noted [[journal/<year>/daily/<date>#<heading>]] is written to ## Logs for you in the same write, followed by the body’s wikilinks in parentheses when it has any. Keep ## Logs for one-line events and put the substance here.

cdno log note [--heading <STRING>] [--body-file <PATH>] [--date <YYYY-MM-DD>]

Without --heading or --body-file, an interactive session prompts for the heading and then opens the body in your editor, and confirms before writing; under --no-interactive (or --json) each is a missing-flag error.

The heading must be unique within the day, must not reuse a daily section name (Standup, Intention, Agenda, Meeting, Notes, Logs), and must not contain [, ], |, # or inline markup (bold, italics, code) nor start with ^. Headings inside the body must be level 3 or deeper and are held to the same uniqueness rule. A refused entry writes nothing.

End an entry that could be reused beyond today with the tag #concept on the body’s last line, so the review can find it as a candidate for promotion to a concept note.

The command prints Noted <target>, where the target is the entry’s anchored link (journal/…#<heading>). With --json it emits path, message, target and log_line:

cdno log note --heading "Woodbury identity" --body-file woodbury.md --json
# -> { "path": "journal/2026/daily/2026-04-25.md",
#      "message": "Noted journal/2026/daily/2026-04-25#Woodbury identity",
#      "target": "journal/2026/daily/2026-04-25#Woodbury identity",
#      "log_line": "noted [[journal/2026/daily/2026-04-25#Woodbury identity]] ([[projects/surrogate-model]])" }

Cite the entry elsewhere as [[<target>]].

Focus tag

When an action is in focus, a carried one included, cdno log and cdno log note append an indented continuation naming its project to the line they write, so a later review can see where a thought came from:

- **11:12**: checked the mesh
  during: [[surrogate-model]]

With nothing in focus the line is written as given. If the focus window cannot be read the line is written untagged rather than the command failing. The tag sits below the entry’s head, so it never affects how cdno now reads the log.

Related MCP tool

append_to_log — the same operation for AI clients; note_to_daily is the counterpart of cdno log note.

See also

• The daily loop.
• The concept library — why substance goes in ## Notes, and how an entry is promoted to a concept note.

cdno capture

Drop a quick note into inbox/ with a slug-based filename, to be processed later with triage.

cdno capture [OPTIONS] <TEXT>

Arguments

Options

Only the global options. With --json, emits a {path, message} result.

Examples

cdno capture "does Chen 2025 use the same preconditioner?"
cdno capture "ask IT about the cluster quota" --json

When an action is in focus, the new inbox item’s frontmatter gets captured_during: <project-slug>, recording where your attention was when the thought arrived. It is the one thing capture adds on its own; with nothing in focus the item is exactly what you typed.

Capture is meant to be frictionless — no fields, no decisions. Classify later during triage.

Related MCP tool

capture.

See also

• Inbox and triage.
• triage — process what you’ve captured.

cdno triage

Process uncategorised inbox/ captures. For each one, keep it as a project action, discard it, or skip it.

cdno triage [OPTIONS]

Options

Only the global options. triage ignores --json.

Behaviour

• Interactive — walks each pending capture and prompts you to keep (turn into a project action), discard, or skip.
• Non-interactive (piped or --no-interactive) — just lists what’s pending, without changing anything.

A capture’s captured_during tag outlives the file. When triage clears an item, whether you discarded it or kept it as an action, the log line it writes (triaged inbox item … -- discarded: …) carries the item’s tag as a during: [[<slug>]] continuation, copied from the item rather than from whatever is in focus at triage time.

Examples

# Work through the inbox:
cdno triage

# Just see the backlog (no changes):
cdno triage --no-interactive

Related MCP tools

triage_inbox (lists pending items) and discard_inbox_item (clears one).

See also

• Inbox and triage.
• capture.

cdno orient

Daily orientation: the commitments due soon, your active projects, a single suggested starting point, and any stewardship habits that have lapsed.

A habit counts as lapsed when its line in a stewardship dashboard’s ## Active Habits section declares it so — a status starting with “lapsed” after the em-dash, e.g. - Swimming 1x/week — lapsed since March. The dashboard is the source of truth (updated during reviews); orientation only surfaces what it says, without judgement.

cdno orient [OPTIONS]

The suggested start is drawn from the projects that count toward the cap first (active, and naming no one else as holder; parked projects are not listed at all): a project handed to someone else (cdno project hand-off) is not your move, so it is suggested only when no project of yours has an open action, and then with its holder named. Its card in the project list carries a held by: line.

Projects that share a core question are one undertaking, so two or more of them read as one card: the question as its title, then one line naming each project with its next action (held by <name> beside one someone else is moving). A project with no question, or the only one under its question, keeps its own card. Under --json the same arrangement is the groups array (see JSON output).

In a terminal this then offers to open one of the projects it just listed, printing what cdno project show would and asking again until you press Esc. Piped output, --no-interactive, and --json skip the prompt. See Colour and interactivity.

orient does not show what is in focus or the last thing you paused, and neither field is in its --json: run cdno now for those. The MCP get_orientation does carry both, because an agent has no other cheap way to know.

Options

Plus the global options. With --json, emits the orientation as a structured object.

Examples

cdno orient                 # neutral suggestion
cdno orient --energy deep   # bias toward a heavy-focus action
cdno orient --energy light  # bias toward something quick on a low day
cdno orient --json | jq '.slots'   # active, counted and cap

Related MCP tool

get_orientation.

See also

• The daily loop.
• status — projects only, without the commitments digest.

cdno status

A quick snapshot: your active projects and each one’s top next action. Lighter than orient — no commitments digest, no suggestion.

cdno status [OPTIONS]

In a terminal this then offers to open one of the projects it just listed, printing what cdno project show would and asking again until you press Esc. Piped output, --no-interactive, and --json skip the prompt. See Colour and interactivity.

Options

Only the global options. With --json, emits the snapshot as structured data.

Examples

cdno status
cdno status --json | jq '.[].slug'

Related MCP tool

list_projects — the projects view for AI clients.

See also

• orient — the fuller morning view.
• Managing projects.

cdno now

What you are in the middle of: the action most recently started, unless it has since been completed, dropped or paused. Focus is one slot: starting something new displaces the old start, which never comes back.

cdno now [OPTIONS]

There is no state behind this. It replays the ## Logs of today and of the [focus] carry_over_days days before it (default 1, so a start left open yesterday is still your focus this morning), so a start made from cdno action start, from an agent over MCP, or typed into the daily note by hand all count — and a completion, a drop or a pause clears it. Nothing to keep in sync, and nothing to go stale.

cdno action promote rewrites the bullet it matched, and the focus follows it: the action promoted on line it logs renames the open start to the new note, with the original start time, so action complete and action drop still close it.

A line you type yourself has to match the shape the writers emit:

- **09:30**: started [[surrogate-model]] — Draft the methods section (deep)

Both halves are required. The - **HH:MM**: stamp is what makes the line a log entry at all, and the separator is an em dash (U+2014), not a hyphen. The parser requires that exact codepoint, so that ordinary prose beginning “started something” is never mistaken for a focus. That strictness means a line missing the stamp, or typed with -, is simply not picked up here — but cdno lint reports it, naming the line and the likely cause, so a near-miss does not stay invisible.

$ cdno now
On surrogate-model — Draft the methods section (deep), since 09:30 (1h 30m).

cdno now has three shapes.

Something is in focus. The line above. A start carried over from an earlier day names it (since Saturday 14:05 (21h 7m)), and the elapsed time counts across midnight.

A carried focus that was picked up again. A focus carried over from an earlier day and re-anchored with action resume reads the new time first and keeps the original:

$ cdno now
On surrogate-model — Draft the methods section (deep), picked up 08:50 today (started Saturday 14:05).

Resuming a pause shows the plain since HH:MM shape, because the pause had already closed the earlier start.

A day more than six days back is shown as a date (2026-09-22 14:05), since a weekday name would be ambiguous.

Nothing in focus. It says so, and shows the most recent pause that nothing has picked up since, with its re-entry hint:

$ cdno now
Nothing started.
Last paused: surrogate-model — Draft the methods section (10:40), next: pick up at "Prior approaches"

The pause is looked for in the last paused_lookback_days days (default 14), so a Friday pause is still there on Monday. Pick it up with cdno action resume.

--line

--line prints one sanitised line of at most 160 characters for a prompt segment or hook:

Focus: surrogate-model — Draft the methods section (since 09:30)
Focus: none (last paused: surrogate-model — Draft the methods section, next: pick up at "Prior approaches")

Control characters are stripped and an over-long line is cut. It prints nothing and exits 0 when no vault is found or anything goes wrong, so it can sit in a prompt without ever breaking it. With --json as well, --line wins. The Claude Code hook example runs it before every prompt.

--json

Every key is always there and is null when it has no value (all of them but last_paused when nothing is in focus), so a caller can test one field without first branching on the shape of the document.

The action field is the bullet text exactly as logged, energy suffix and all. That is the same string cdno action complete matches, which is why the pairing works.

Related MCP tools

current_focus — the same read, for an agent.

See also

• Focus — the idea behind the slot and the window.
• action start — what puts something here; pause, switch and resume move it.
• orient — what to begin when nothing is open.

cdno open

Open a note in your editor. Where cdno search answers “where did I write about this”, open answers “take me to the note I mean” — it is addressing, not searching.

cdno open [OPTIONS] [REFERENCE]

Run it with no reference and it offers a picker over every note, most-recently-edited first.

Arguments

A reference can be any of:

Portfolios and expanded stewardships are addressed by their folder name, not the literal _index: cdno open surrogate-model reaches portfolios/surrogate-model/_index.md.

The calendar words always mean the journal. A note genuinely named today stays reachable as <type>:today.

Options

Plus the global options. With --json, a resolved reference emits {"path": …} and --list emits an array of {path, title, type}.

When stdout is not a terminal, cdno open prints the path instead of launching anything. So cdno open today | cat, a script, --no-interactive, and --json all behave the same way, and no editor is ever started into a pipe.

Choosing the editor

First one set wins:

export CUADERNO_EDITOR='code -g {path}'

{path} marks where the note’s path goes. Leave it out and the path is appended, so a bare nvim works. Quoting is honoured, so a program name may contain spaces:

export CUADERNO_EDITOR='"/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w {path}'

A value whose first word contains :// is handed to the operating system instead of executed, with the path percent-encoded — obsidian://open?path={path}.

cdno waits for the editor to exit. It does not try to guess whether your editor is a terminal or a GUI one — code -w blocks and code does not, and a guess would be wrong in a way you could not override. Waiting is correct for every terminal editor and harmless for a GUI one that returns immediately. If the editor exits non-zero, cdno open exits with the same code, the way git commit treats an abandoned edit.

There is no per-vault editor setting, on purpose

You might expect .cuaderno/config.toml to carry this — a research vault that opens in Obsidian, a code vault that opens in your editor. It deliberately does not.

A vault is a git repository, and --vault exists so cdno can be pointed at one you did not create. A setting that names a program to run cannot live in data that gets cloned and synced: opening a note in someone else’s vault would run their choice of program on your machine. It is the same reason git does not honour every setting from a repository you just cloned.

Restricting such a setting to a bare binary name would not help. sh is a binary name, and sh <the note> executes the note’s own contents — which, in a vault you cloned, the author also wrote. The fix is that the setting comes from your shell rather than from the data.

If you work across vaults that want different editors, set CUADERNO_EDITOR in a per-directory shell hook (direnv, or your shell’s chpwd), which keeps the decision on your machine.

Archived notes

Opening a note under actions/_done/ prints a warning first: its text was frozen when it was archived, and cdno lint reports an edit to the existing text as an error. Appending to it is fine. The warning does not stop you — markdown remains the source of truth.

When a reference does not resolve

Two cases, and they say different things:

• Nothing matched. The error names the closest few notes by their type-scoped form — so a mistyped slug tells you what you probably meant rather than dumping the vault.
• The slug matched more than one note. cdno open never guesses, because opening the wrong note is a mistake you only discover after typing into it. The error names each type-scoped form instead, and any of them resolves. This happens when a stewardship and a portfolio share a name, for instance — stewardships/gym.md and portfolios/gym/_index.md are both gym.

A reference that looks like a path never falls back to fuzzy matching: a typo there means “no such file”, not a near-miss opened on your behalf.

Examples

cdno open                             # pick from every note
cdno open today                       # today's daily note
cdno open surrogate-model             # by slug
cdno open project:surrogate-model     # when one slug is used by two types
cdno open 2026-W34                    # that week's weekly note
cdno open --path today                # print the path, open nothing
cdno open --list | head               # every note, tab-separated
cdno open today --json | jq -r .path
cdno open notes --editor 'code -g {path}'

With a fuzzy finder

cdno open has its own picker, so you do not need fzf at all. If you would rather use yours — your keybindings, your preview window — --list gives it candidates. Because --list emits vault-relative paths and open accepts absolute ones, the round-trip works from any directory, with no need to cd into the vault first:

cdno open "$(cdno open --list | fzf --with-nth=2.. --delimiter='\t' | cut -f1)"

Worth a shell function:

cdo() {
  local pick
  pick=$(cdno open --list | fzf --with-nth=2.. --delimiter='\t' | cut -f1) || return
  [ -n "$pick" ] && cdno open "$pick"
}

This beats running fzf over the vault directory directly, because the candidates carry each note’s title rather than only its filename — filenames here are slugs, so a note titled “Surrogate model” would otherwise never match the words you remember. The listing also respects the vault’s ignore globs.

See also

• search — full-text search when you do not know which note you want.
• Searching your vault.

cdno weekly

Show the weekly review/plan note: Wins, Challenges, One Improvement, and This Week’s Goal.

cdno weekly [OPTIONS]

Options

Plus the global options. weekly ignores --json.

Examples

cdno weekly                     # this ISO week
cdno weekly --date 2026-04-20   # the week containing 20 Apr 2026

To write the weekly sections rather than just view them, use the guided review weekly.

Related MCP tools

read_weekly_note and get_weekly_context.

See also

• Weekly review.
• review.

cdno monthly

Show the monthly review note: Wins, Themes, Next Month’s Focus, and the month’s linked weeks.

cdno monthly [OPTIONS]

Options

Plus the global options. monthly ignores --json.

Examples

cdno monthly                     # this calendar month
cdno monthly --date 2026-04-20   # the month containing 20 Apr 2026

To write the monthly sections rather than just view them, use the guided review monthly.

Related MCP tools

read_monthly_note and get_monthly_context.

See also

• Note types.
• review.

cdno commitments

List aggregated commitments across the vault — the hard milestones of active projects, standalone commitment notes, stewardship periodic commitments, and self-imposed action-note deadlines — sorted by date, with overdue items flagged.

cdno commitments [OPTIONS]

Options

Plus the global options. With --json, emits the list as structured data.

Examples

cdno commitments              # next 2 weeks + anything overdue
cdno commitments --weeks 6    # next 6 weeks
cdno commitments --json | jq '.[] | select(.overdue)'

How it’s computed

This is a derived view, not a single file. It merges four sources (see Business rules): project milestones marked --hard, stewardship periodic commitments, standalone commit notes, and action notes with a self-imposed due:. A project’s own dates count while the project is open, active or parked: a hard date on a parked map is still a promise. Completing or dropping a project takes its milestones and action due dates out of the view until it is activated again. A standalone commitment that names a parked or closed project keeps surfacing, since it is a promise to someone else.

Related MCP tool

get_commitments.

See also

• Commitments and deadlines.
• commit — create a standalone commitment.

cdno questions

List active questions grouped by domain (research, life) — the orientation surface against the question system. For lifecycle changes (park / answer / retire / activate), use cdno question.

cdno questions [OPTIONS]

Options

Only the global options. With --json, emits the list as structured data.

Examples

cdno questions
cdno questions --json | jq '.[].slug'

Related MCP tool

get_active_questions — which additionally accepts a domain filter.

See also

• Research and evidence.
• question — create questions and transition their status.

cdno search

Full-text search across all notes, ranked best-first, with optional filters by note type, date window, and portfolio.

Titles are searched too, and weighted ten times a body match. A note whose title contains your words ranks above one that merely mentions them, so you do not need a separate command to look one up by name. When you already know which note you want and can name its slug or date, cdno open resolves it directly instead of ranking.

cdno search [OPTIONS] <QUERY>

Arguments

Options

Plus the global options. With --json, emits an array of hits, each with path, note_type, title, snippet, and score.

Examples

cdno search "preconditioner"
cdno search "sparse attention" --type evidence
cdno search "mesh" --from 2026-03-01 --to 2026-03-31 --limit 5
cdno search "speedup" --portfolio sparse-vs-dense-attention-ood --json | jq -r '.[].path'

Related MCP tool

search_notes.

See also

• Searching your vault.
• reindex — rebuild the index if results look stale.

cdno review

Guided review rituals.

cdno review [OPTIONS] <COMMAND>

Subcommands

review ignores --json.

cdno review weekly

Walk the retrospective sections (Wins, Challenges, One Improvement) into this week’s note, then set next week’s goal as the This Week’s Goal of next week’s note. When run non-interactively, it reads the current note instead of prompting.

cdno review weekly [OPTIONS]

Options

Only the global options.

Examples

cdno review weekly                  # interactive: prompts for each section, sets next week's goal
cdno review weekly --no-interactive # read the current weekly note without prompting

cdno review monthly

Walk the monthly sections (Wins, Themes, Next Month’s Focus) into this month’s note. Unlike the weekly ritual there is no cross-note carry-forward — every section lands in the same month’s note. When run non-interactively, it reads the current note instead of prompting.

cdno review monthly [OPTIONS]

Options

Only the global options.

Examples

cdno review monthly                  # interactive: prompts for each section
cdno review monthly --no-interactive # read the current monthly note without prompting

Related MCP tools

get_weekly_context, read_weekly_note, upsert_weekly_section, read_monthly_note, upsert_monthly_section.

See also

• Weekly review.
• Note types.
• weekly / monthly — just view the notes.

cdno project

Manage project maps: create, update state, set the core question, hand off and take back, add/complete/drop milestones, manage waiting-on items, park/activate, complete/drop the project itself, and list/show. Next actions have their own verb, cdno action.

cdno project [OPTIONS] <COMMAND>

Subcommands

Write subcommands honour --json (a {path, message} result, run non-interactively); list/show emit their data under --json.

A parked project is a complete map, so every subcommand that writes a project’s body (state, core-question, hand-off, take-back, milestone, waiting, and the cdno action verbs that take --project, except start, switch and resume) accepts an active or a parked slug. When --slug is omitted in a terminal, the picker and shell completion offer the active and parked projects; park offers active projects only. See Business rules.

cdno project create

Create a new project map. Created parked if you’re already at the active cap.

cdno project create --title "Surrogate model" --context work
cdno project create --title "Thesis" --context university --var ticket=ABC-123
cdno project create --title "Surrogate model for the mesh-scaling study" --context work --slug surrogate-model
cdno project create --title "Thesis" --context university --question questions/research/surrogate-cost

cdno project state

Update the Current State section. The previous state is auto-logged to today’s daily note first (see Business rules).

cdno project state --slug surrogate-model --text "Mesh scaling works; assembly is the bottleneck"

cdno project core-question

Set or clear the project’s core question after creation, auto-logging the previous value to today’s daily note in the same was: / now: shape state uses.

core-question — --slug, and either --question <target> or --clear

cdno project core-question --slug surrogate-model --question questions/research/does-it-scale
cdno project core-question --slug surrogate-model --clear

--question takes the bare wikilink target, the same form create --question takes — questions/research/foo, not [[…]], which is rejected rather than double-wrapped.

Passing neither flag non-interactively is an error, not a silent detach: dropping a project’s question is a decision and has to be asked for.

cdno project hand-off

Record that someone else is moving an open (active or parked) project: the map gets held_by: "<name>", and today’s daily note gets a holder on [[<slug>]] entry with indented was: / now: lines, the side with no holder written (mine). A hand-off records a fact about the project: someone else is moving it now, and the next move is theirs. Because the active cap counts the projects that are yours to move, an active project that names a holder is not counted; but handing off is never the answer to a full cap. Name a holder only when someone else really has the project; to make room, park, complete or drop one. The map stays where it is, and its deadlines stay in cdno commitments.

cdno project hand-off --slug hull-survey --to "Ana Ruiz"
# Handed hull-survey to Ana Ruiz (projects/hull-survey.md)

A hand-off is refused when:

• the value names you or nobody (me, tbd, someone, or another entry of holder_sentinels): if you cannot name who has the project, it is yours. Keep it, or run cdno project take-back if it was handed off;
• the value is a date, which names no one: give the person’s name instead;
• an action on the project is in focus: pause it first with cdno action pause, then hand it off;
• the project is closed: only an active or parked project has a holder, so activate it first if the work has come back.

Handing a project to the holder it already names changes nothing and logs nothing.

cdno project take-back

Clear a project’s holder: the map gets held_by: null and the daily note a holder on [[<slug>]] entry with now: (mine). An active project then counts toward the cap again, so taking one back at the cap is refused with the list of counted projects; park, complete or drop one of them first. A parked project stays parked: taking it back clears the name only and needs no slot.

cdno project take-back --slug hull-survey
# Took hull-survey back (projects/hull-survey.md)

cdno project park

Move an active project to projects/_parked/, freeing a slot against the five-project cap.

cdno project park --slug surrogate-model

cdno project complete

Close a project because its work is done. The map moves to projects/_done/<year>/<slug>.md with status: completed and closed: set to today, and the daily log gets project completed [[<slug>]] — <title>. It works on an active or a parked project and never needs a slot, since closing adds nothing to the active count.

A completion is a claim that the work was done, so it is refused while any action or milestone is still open, and there is no flag to force it. The refusal lists what is open:

surrogate-model has 3 open items:
  - [ ] Run feature set B on full geometry mesh (deep)
  - [ ] [[actions/characterise-kan-ppo-sample-efficiency]] (deep)
  - [ ] ICML paper submitted — hard: 2026-05-22
Still open, not touched: [[commitments/reviewer-report]] (due 2026-10-15)
Complete or drop each of them (or add it to the project that now owns it), then run again.

Tick what was done (cdno action done, milestone done), drop what is not happening (cdno action drop, milestone drop, each with its own reason), and run the command again:

cdno project complete --slug surrogate-model
# Completed surrogate-model. 4 of 5 slots in use.

Standalone commitments linked to the project are never touched: a promise to someone else does not end with the project. The success message names any that are still open.

cdno project drop

Close a project that is not going to happen. The map moves to projects/_done/<year>/<slug>.md with status: dropped and closed: set to today, and the daily log gets project dropped on [[<slug>]] — <title>, with the reason on an indented reason: line. Like complete, it works on an active or a parked project and never needs a slot: ending a shelved plan does not bring it back first.

With open actions or milestones, drop lists them as complete does. In a terminal it then asks Let these N go and drop <slug>? [y/N], and pressing Enter keeps everything. On y each open item is dropped with the project, logged as its own action dropped on / milestone dropped on line with reason: project dropped (<your reason>) (or plain reason: project dropped without --reason), and an attached action note is archived as dropped. If the list changed while you were answering, nothing is dropped and the new list is shown. Non-interactively the list is printed and the command exits 1, unless you pass --drop-open.

cdno project drop --slug bayesian-opt-survey --reason "superseded by the ICML work"
cdno project drop --slug bayesian-opt-survey --reason "superseded" --drop-open
# Dropped bayesian-opt-survey. 4 of 5 slots in use. Let go: 2 actions, 1 milestone.

Items that were in fact done should be ticked first: a drop records that work was let go, not that it was finished.

Under --json a refusal from either verb prints the same project_has_open_items object the MCP server returns (the items plus an open_items_hash) and exits 1; a success prints path, message, dropped_actions, dropped_milestones and untouched_commitments.

A closed project can be closed again with the other outcome, as a new decision: a dropped project that turns out to have been finished can be completed, and the reverse. It is re-filed under this year’s folder with today’s closed: date and a new log line. Closing it again with the same outcome is refused, naming the date it already has.

cdno project activate

Bring a parked, completed or dropped project back to projects/. A closed project also has its closed: date cleared, so it can be closed again later with a fresh one. The log says project [[<slug>]] activated. Fails if it would exceed the active cap — park another first. The interactive picker and shell completion offer parked and closed projects, labelled.

cdno project activate --slug surrogate-model

cdno project list

List active projects with a state snippet. Each project renders as a card — a coloured bar keyed to its context, the slug as a title, and the state wrapped underneath. Honours --json.

A project that names someone else as its holder carries one more line, held by: <name> · does not count toward the cap. A value on holder_sentinels leaves the map yours, so it prints no holder line. Under --json each row carries held_by and counts (see JSON output).

In a terminal this then offers to open one of the projects it just listed, printing the same thing cdno project show would and asking again until you press Esc. Piped output, --no-interactive, and --json skip the prompt. See Colour and interactivity.

With --closed it lists completed and dropped projects instead, newest first, each with its outcome and closing date. Under --json each row carries slug, title, context, outcome and closed_on.

cdno project list
cdno project list --json | jq '.[].slug'
cdno project list --no-interactive     # listing only, never a prompt
cdno project list --closed

cdno project show

Show a compact summary of a single project (any status). The slug is an optional positional: omit it in a terminal and cdno offers a picker covering active and parked projects. Honours --json (emits the project summary object).

For an active or parked project it ends with Held by: <name> when the map names someone else (a sentinel prints none), and Counts toward the cap: yes or no.

cdno project show surrogate-model
cdno project show                      # pick from a list
cdno project show surrogate-model --json

cdno project milestone

Manage milestones — markers of progress. A --hard milestone is a real deadline counted in cdno commitments.

add — --slug, --title, --date <YYYY-MM-DD> (optional), --hard done — --slug, --query (case-insensitive substring of the milestone title)

drop — --slug, --query, --reason (optional)

cdno project milestone add --slug surrogate-model --title "Submit to ICML" --date 2026-01-22 --hard
cdno project milestone add --slug surrogate-model --title "All Round-1 replies received"
cdno project milestone done --slug surrogate-model --query "submit to icml"
cdno project milestone drop --slug surrogate-model --query "book the venue" --reason "the funder withdrew"

Use drop rather than done when the milestone is not going to happen — superseded, mis-typed, or overtaken by events. done ticks the bullet and writes milestone done on ... to the daily log, asserting a milestone that was met; drop removes the bullet and writes milestone dropped on ... instead, so a later reader can tell a plan that changed from a plan that was kept. --reason is optional and never prompted for: a correction is simply a drop with no reason. Only open - [ ] bullets are matched — a completed milestone is a record of what happened, not a plan to revise.

--date is optional. Some milestones are gated by a condition rather than a date — “all Round-1 replies received” on a correspondence-driven project — and omitting the flag records the milestone as target: TBD rather than making you invent an estimate. An undated milestone does not appear in cdno commitments, which is the point: a date you made up reads later like a commitment somebody made. It completes with done exactly like a dated one.

Interactively, the calendar is offered behind a yes/no so the undated case is reachable without knowing the flag can be omitted.

--hard requires --date: a hard deadline with no date is rejected rather than quietly downgraded to a soft target.

cdno project waiting

Track external blockers.

add — --slug, --description resolve — --slug, --query (substring of the item)

cdno project waiting add --slug surrogate-model --description "Cluster quota from IT"
cdno project waiting resolve --slug surrogate-model --query "cluster quota"

Related MCP tools

create_project, update_project_state, park_project, complete_project, drop_project, activate_project, hand_off_project, list_projects, get_project_context, add_milestone, complete_milestone, set_core_question, add_waiting_on, resolve_waiting_on.

See also

• Managing projects.
• action — the next-action list.

cdno action

Manage a project’s next actions: add (optionally as a manifest note), promote a bullet to a note, start, pause, switch, resume, complete, drop, and list.

cdno action [OPTIONS] <COMMAND>

Subcommands

Write subcommands honour --json ({path, message}, non-interactive); list emits its data under --json. A refused start, pause, resume or switch prints a rejection object instead; see When start is refused.

start, pause, switch and resume are the focus verbs: they move the one slot that cdno now reads. See Focus for the idea and the log markers they write below.

cdno action add

Append a next action to a project. --note also scaffolds a manifest note and wikilinks the bullet.

cdno action add --project surrogate-model --title "Profile the assembly step" --energy medium
cdno action add --project surrogate-model --title "Characterise sample efficiency" --energy deep --note
cdno action add --project surrogate-model --title "Rerun the ablation on the held-out split with feature set B" --energy deep --note --slug feature-set-b-ablation

cdno action promote

Promote an existing plain bullet to a wikilinked manifest note. Substring-matches the bullet text; energy is inherited.

cdno action promote --project surrogate-model --query "profile the assembly"
cdno action promote --project surrogate-model --query "profile the assembly" --slug profile-assembly

cdno action start

Log that work on an action is starting: writes started [[slug]] — <bullet> to today’s daily note, which is what cdno now reads back.

The action must already be on the map. A start names a bullet, so that the later completion logs matching text and the focus clears — a start naming nothing could never be closed. What gets logged is the resolved bullet text, not your query, so --query "draft methods" logs Draft methods (deep).

cdno action promote rewrites the bullet it matched, and the focus follows it: cdno now switches to the new note ([[actions/<slug>]] (deep)), keeps the original start time, and complete and drop still pair with the start.

When start is refused

Focus is one slot, so start while another action is in focus is refused, naming the open one and the way forward:

$ cdno action start --project other-project --query "CI"
Error: Draft the methods section is already in focus on surrogate-model (since 09:30).
To move on to this instead: cdno action switch --project other-project --query CI
Or complete or pause it first.

You can always move on; you just say so. In a terminal the refusal is followed by Switch to it instead? (default no); y runs the switch without asking for a hint or a reason. Piped, with --no-interactive or with --json, it fails fast instead.

Starting the action that is the focus is refused too. If it was started today there is nothing to do. If it was carried over from an earlier day the message points at cdno action resume. A typo or an ambiguous --query is reported as such, not as a refusal, and a refused --unplanned start adds no bullet.

With --json the refusal is the same object the MCP server returns, on stdout, with a non-zero exit:

{
  "code": "focus_open",
  "message": "An action is already in focus. Ask the person before switching; do not retry.",
  "details": {
    "focus": {"project": "surrogate-model", "action": "Draft the methods section (deep)",
              "started": "09:30", "date": "2026-10-04", "carried": false},
    "attempted": {"project": "other-project", "query": "CI"},
    "same_action": false,
    "remedy": "switch_action"
  }
}

remedy is switch_action when something else is in focus, already_focused for the same action started today, and resume_action for the same action carried over. attempted is {project, query}, or {project, title} for an --unplanned start.

An ambiguous --query is a question rather than a dead end: in a terminal you get a picker over the candidates, and non-interactively they are listed one per line. The same holds for complete, drop and promote, which resolve through the same matcher.

One case no picker can settle: two open bullets whose text differs only in case, or not at all. The domain’s whole-bullet tiebreak compares case-insensitively, so it sees two exact matches, declines, and picking either re-ambiguates. Edit one of the bullets to tell them apart.

# start something already planned
cdno action start --project surrogate-model --query "feature set B"

# start something that was never planned — adds the bullet and starts it
cdno action start --project surrogate-model --unplanned \
    --title "Fix the CI badge" --energy light

--unplanned is deliberately explicit rather than a fallback when --query matches nothing: a fallback would turn every typo into a new action, silently. --title and --energy require it, so passing them alone is a parse error naming --unplanned rather than a start on some other bullet.

cdno action pause

Set the action in focus aside without finishing it. It acts on the current focus and takes no project or query: there is exactly one focus, and it is the one paused. Nothing is looked up on the project map, so a focus on a project you have since parked can still be paused, and the bullet stays where it is.

cdno action pause --next 'pick up at "Prior approaches"' --reason "CI is red"

With nothing in focus it says Nothing started — nothing to pause. and exits non-zero. A pause is not a drop: a paused action stays open on the map, and can be completed or dropped later as usual.

cdno action switch

Pause the action in focus and start another, in one commit. It takes the same target flags as start, plus the hint and reason for the action being set aside.

cdno action switch --project other-project --query "CI" \
    --next "related-work paragraph half done" --reason "a collaborator is blocked on it"

A switch is a pause followed by a start in the log; there is no separate marker. If the target does not resolve, nothing is written, not even the pause. With nothing in focus it is a plain start, and a --next it had nothing to attach to is reported rather than dropped. A prompted switch shows pause <X>, start <Y> and asks to confirm, and the picker leaves out the bullet that is already in focus.

cdno action resume

Pick work up again. It takes no query or title: the text comes from the log, not from the map.

$ cdno action resume
Resumed on surrogate-model, logged to journal/2026/daily/2026-10-04.md
next: pick up at "Prior approaches"

Without --project it resumes the focus carried over from an earlier day if there is one, else the most recent pause within paused_lookback_days (default 14). It writes resumed [[slug]] — <text>, which re-anchors the focus to now, so a Tuesday start you keep working on does not expire on Thursday, and prints the pause’s next: hint when it has one. A pause that a later start, resume, completion, drop or promotion of the same action followed is no longer offered.

With nothing to pick up it says Nothing to resume — nothing is carried over or paused. (Nothing to resume on <project> — … with --project) and exits non-zero. It is refused with a focus_open refusal (the same object as above, without attempted) when a different action is in focus (pause it or switch instead; resume never switches for you) or when the same action was already started today. With --json a success carries path, message and resumed_from: kind (carried or paused), date, next and reason.

What the focus verbs write

Each verb is one entry in today’s ## Logs. next: and reason: are indented continuation lines, written only when given:

- **10:40**: action paused on [[surrogate-model]] — Draft the methods section (deep)
  next: pick up at "Prior approaches"
  reason: a collaborator is blocked on CI
- **10:40**: started [[other-project]] — Fix red CI on main (medium)
- **14:05**: resumed [[surrogate-model]] — Draft the methods section (deep)

paused closes the focus the way action done on and action dropped on do; resumed opens it again. complete and drop are unchanged, including on a paused action. When a focus is open, a log line written by cdno log, cdno capture or the triage verbs carries a during: tag naming its project.

cdno action complete

Mark a next action completed by case-insensitive substring match. A wikilinked bullet also archives its note to actions/_done/<year>/.

cdno action complete --project surrogate-model --query "feature set B"

cdno action drop

Close a next action without recording it as done — for work that was superseded, abandoned or reprioritised. Matches the bullet exactly as complete does; a wikilinked bullet also archives its note to actions/_done/<year>/, stamped status: dropped with no completion date.

cdno action drop --project surrogate-model --query "demo proposal" \
    --reason "superseded by the demo-planning action"

Use this rather than complete whenever the work was not actually performed. complete writes action done on [[…]] into the daily log, which is the record the weekly review, the monthly scan and every later verdict read back from — so completing something that never happened leaves the vault asserting work nobody did, and the only repair is a correction line written by hand.

--reason is optional but worth giving: “superseded by X” and “no longer wanted” are different facts, and only one of them tells a later reader to go looking for the replacement. It is recorded on a continuation line under the log entry.

A dropped action does not appear in the completed-actions views that the weekly and monthly reviews build, because it carries no completion date.

cdno action list

List a project’s open action bullets, with attached-note status (active / blocked / completed / dropped) inline when present. Honours --json.

cdno action list --project surrogate-model
cdno action list --project surrogate-model --json

Related MCP tools

add_action, promote_action, start_action, start_unplanned_action, pause_action, switch_action, switch_unplanned_action, resume_action, complete_action, drop_action. (Open actions are also visible via get_project_context; what is currently started via current_focus.)

See also

• Actions.
• now — what is currently started.
• project.

cdno portfolio

Manage evidence portfolios: create, list, show, and link to a question or project. Filing evidence into a portfolio is the separate cdno file verb.

cdno portfolio [OPTIONS] <COMMAND>

Subcommands

create/link honour --json ({path, message}); list/show emit their data under --json.

cdno portfolio create

Create a new portfolio. The slug derives from the question.

--question takes either free text or the slug of an existing question. Given a question’s slug, the portfolio takes that question’s text as its title, the two are linked both ways, and the portfolio’s slug is the question’s. An explicit --slug must then be omitted or equal to that slug; any other value is refused, because the pair is correlated by slug.

cdno portfolio create --question "Sparse vs dense attention OOD"
cdno portfolio create --question "Sparse vs dense attention OOD" --project projects/surrogate-model
cdno portfolio create --question "Sparse vs dense attention OOD" --slug sparse-vs-dense
cdno portfolio create --question surrogate-generalises          # from an existing question's slug

cdno portfolio list

List every portfolio with its evidence count and staleness. Honours --json.

In a terminal this then offers to open one of the portfolios it just listed, printing what cdno portfolio show would and asking again until you press Esc. Piped output, --no-interactive, and --json skip the prompt. See Colour and interactivity.

cdno portfolio list
cdno portfolio list --json | jq '.[] | {slug, evidence_count}'

cdno portfolio show

Show a portfolio’s frontmatter and its evidence inventory. Honours --json (a detail object with the evidence list).

cdno portfolio show --portfolio sparse-vs-dense-attention-ood
cdno portfolio show --portfolio sparse-vs-dense-attention-ood --json

cdno portfolio link

Link an existing portfolio to an existing question or project (the retrofit path — pass exactly one of --question/--project). Backlinks are set on both sides.

cdno portfolio link --portfolio sparse-vs-dense-attention-ood --project projects/surrogate-model
cdno portfolio link --portfolio sparse-vs-dense-attention-ood --question questions/research/surrogate-cost

Related MCP tools

create_portfolio, get_portfolio_contents (show), link_portfolio_to_question, link_portfolio_to_project.

See also

• Research and evidence.
• file — add evidence to a portfolio.

cdno file

File a piece of evidence into a portfolio. Without --attach it writes a plain Markdown evidence note; with --attach it copies a non-Markdown artefact (PDF, image, video) into the portfolio and scaffolds a linked evidence stub beside it.

cdno file [OPTIONS]

Options

Plus the global options. With --json, emits a {path, message} result and runs non-interactively.

Examples

# A plain prose evidence note:
cdno file --portfolio sparse-vs-dense-attention-ood \
          --source "Chen et al. 2025, NeurIPS" \
          --origin projects/surrogate-model \
          --content "4x speedup at 95% accuracy on the OOD split."

# Attach a PDF (copied into the portfolio; --content is the abstract):
cdno file --portfolio sparse-vs-dense-attention-ood \
          --source "Chen et al. 2025" --origin projects/surrogate-model \
          --attach ~/Downloads/chen2025.pdf --content "Key result: 4x speedup."

# Move the artefact in instead of copying:
cdno file --portfolio sparse-vs-dense-attention-ood --source "fig 3" \
          --origin projects/surrogate-model --attach ./fig3.png --move

Evidence notes are append-only.

Related MCP tool

file_to_portfolio.

See also

• Research and evidence.
• portfolio — create and inspect portfolios.

cdno question

Manage question notes: create one, then transition its status. Each status transition is logged to today’s daily note. To list active questions, use cdno questions.

cdno question [OPTIONS] <COMMAND>

Subcommands

All honour --json ({path, message}, non-interactive).

cdno question create

Create a new question under questions/<domain>/<slug>.md. The slug derives from the text.

cdno question create --domain research --text "Does sparse attention beat dense OOD?"
cdno question create --domain research --text "Does the surrogate model generalise to unseen meshes?" --slug surrogate-generalises

Status transitions

park, answer, retire, and activate each take a --slug. The interactive picker offers only eligible questions for that transition (e.g. you can only park an active question).

cdno question park   --slug does-sparse-attention-beat-dense-ood
cdno question answer --slug does-sparse-attention-beat-dense-ood
cdno question retire --slug does-sparse-attention-beat-dense-ood
cdno question activate --slug does-sparse-attention-beat-dense-ood

Related MCP tools

create_question, set_question_status. (List via get_active_questions.)

See also

• Research and evidence.
• questions — list active questions.

cdno stewardship

Manage stewardship dashboards: create (flat or expanded), list, show, and append a periodic commitment line. Filing a tracking entry is the separate cdno track verb.

cdno stewardship [OPTIONS] <COMMAND>

Subcommands

create/add-periodic/complete-periodic honour --json ({path, message}); list/show emit their data under --json.

cdno stewardship create

Create a stewardship dashboard. --tracking makes it expanded (a stewardships/<slug>/ folder with room for tracking/ and routines/); without it, the dashboard is a single flat file.

cdno stewardship create --name "Finances" --context household           # flat
cdno stewardship create --name "Health" --context personal --tracking   # expanded
cdno stewardship create --name "Household finances and taxes" --context household --slug finances

cdno stewardship list

List every stewardship with its variant, tracking count, and staleness badge. Honours --json.

In a terminal this then offers to open one of the stewardships it just listed, printing what cdno stewardship show would and asking again until you press Esc. Piped output, --no-interactive, and --json skip the prompt. See Colour and interactivity.

cdno stewardship list
cdno stewardship list --json | jq '.[] | {slug, variant}'

cdno stewardship show

Show a stewardship’s frontmatter and an excerpt of the dashboard body. Honours --json (a detail object including variant and body_markdown).

cdno stewardship show --slug health

cdno stewardship add-periodic

Append a periodic commitment line to the dashboard’s ## Periodic Commitments section. The line becomes a row in the aggregated cdno commitments view.

cdno stewardship add-periodic --stewardship health --title "Dental check-up" \
     --every "every 6 months" --next 2026-09-01

cdno stewardship complete-periodic

Complete one occurrence of a periodic commitment, rolling its next: date forward by that line’s own recurrence. Named to pair with add-periodic: it completes an occurrence, not the stewardship, which is perpetual and never completes.

cdno stewardship complete-periodic --stewardship health --title "dental"
cdno stewardship complete-periodic --stewardship health --title "dental" --at 2026-08-25

Before this verb there was no way to mark a periodic commitment done: it is a bullet, not a note, so cdno commit done has nothing to act on, and the reminder kept firing until the file was hand-edited — the one edit the vault asks you not to make.

The next date is computed from the due date, never from --at. A check-up every 6 months, done a week early each time, would creep a week earlier every cycle if the schedule followed the work. Anchored to the due date, a run of early completions leaves the schedule where it was. A late completion advances until next: is in the future, so one neglected commitment comes back on schedule rather than several reminders deep.

One case the calendar imposes: a monthly commitment on the 31st has no 31st to land on in February, so it clamps to the 28th and keeps the 28th thereafter — the bullet records the next date, not the day the schedule nominally wants.

The entry records the completion and where the schedule moved to:

- **09:30**: periodic done on [[health]] — Dental check-up
  was: 2026-09-01
  now: 2027-03-01

A line whose recurrence the parser cannot read is refused rather than guessed — see Recurrence syntax for the accepted forms. Such a line is otherwise unaffected: it still appears in cdno commitments and lint still accepts it.

Related MCP tools

create_stewardship, get_stewardship_tracking, add_periodic_commitment, complete_periodic.

See also

• Stewardships and tracking.
• track — file a tracking entry.

cdno track

File a tracking note under an expanded stewardship. The activity is positional and selects the template: a vault’s .cuaderno/templates/tracking-<activity>.md if present, else the generic built-in. No activity-specific templates ship built-in — ready-made gym/body/swim variants are in examples/templates/tracking/.

cdno track [OPTIONS] <ACTIVITY>

Arguments

Options

Plus the global options. With --json, emits a {path, message} result and runs non-interactively.

Examples

cdno track gym --stewardship health --content "Upper body A; RDL up to 25kg"
cdno track body --stewardship health --content "Weight 78.4kg, resting HR 54"
cdno track swim --stewardship health --content "1500m, 28min"

# --routine needs a template with a routine: field (the example gym.md has one):
cdno track gym --routine upper-body-a

# With one expanded stewardship, --stewardship can be omitted:
cdno track gym --content "Legs day"

Tracking entries are append-only and only land in expanded stewardships (those created with --tracking).

Until a vault has any tracking template, cdno track prints a one-line hint (on stderr) pointing at examples/templates/tracking/ for a structured layout. It goes quiet once you author a template, and is suppressed under --json.

Merging a day

A second cdno track for the same activity and date merges into the first rather than erroring: --content is appended to the entry’s ## Notes, and any metrics are folded into its frontmatter. Recording a day in two passes — a morning and an evening session, spending logged as it happens — is ordinary rather than exceptional.

Merging is not blind concatenation. A record carrying a stable id replaces the record with that id, so re-applying the same payload is idempotent; a record without one appends, so re-running an import that omits ids double-counts every summed metric. Scalars are last-write-wins: there is no array to key on, and the later reading is what a level means — but sending a plain value for a key that already holds records is refused, since that would discard the day’s entries on a note type that only grows.

Related MCP tool

create_tracking_entry.

See also

• Stewardships and tracking.
• stewardship.

cdno templates

Inspect and edit note templates. Use vars before writing a custom template in .cuaderno/templates/ to see which {{placeholders}} a note type supports — unknown placeholders render verbatim, so this is how you learn the valid set without reading the source.

cdno templates vars <type>

List the {{placeholders}} a note type’s template supports.

cdno templates vars [OPTIONS] <TYPE>

Arguments

Takes only the global options.

Sources

Each placeholder is classified by where its value comes from:

A config or prompt name that collides with a supplied key is omitted: the supplied value shadows it, so it would never take effect.

With --json, emits an array of { name, source } objects (prompt entries also carry message).

Examples

cdno templates vars project
cdno templates vars tracking
cdno templates vars question --json | jq -r '.[].name'

cdno templates eject <type>

Copy a built-in template into .cuaderno/templates/<type>.md as an editable starting point. Note types use an in-binary default until you add a file for them (only daily is seeded on cdno init); this materialises one so you can customise it (add sections, reorder frontmatter, reference {{placeholders}} from templates vars) without hand-reconstructing it from the source tree.

cdno templates eject [OPTIONS] <TYPE>

Arguments

Options

Plus the global options. With --json, single-type eject emits the { path, message } write result; --all emits an object with written and skipped arrays (note-type names).

Only base note-type templates eject — no <type>-<variant> template ships built-in. To create a tracking activity variant, copy one from examples/templates/tracking/ to .cuaderno/templates/tracking-<activity>.md instead.

Examples

cdno templates eject project              # → .cuaderno/templates/project.md
cdno templates eject tracking             # → the generic tracking template
cdno templates eject project --force      # overwrite an earlier customisation
cdno templates eject --all                # eject all built-ins, skip customised
cdno templates eject --all --force        # eject all, overwriting everything

The written file is exactly the built-in default, so a note created straight after ejecting is byte-identical to before — customise from there.

cdno templates sync <type>

Bring a customised template up to date with frontmatter keys a later release added to the built-in one, without losing your customisation. A file you ejected or saved never receives such keys by itself; nothing breaks without them (new notes from it just lack the key), but nothing else adds them either, and eject --force would throw your edits away.

cdno templates sync [OPTIONS] <TYPE>
cdno templates sync --all [--check]

For each key of the built-in template’s frontmatter that your file lacks, sync inserts the built-in line verbatim: a literal such as closed: null, or a placeholder line such as core_question: {{core_question}}. It goes right after the nearest built-in key that precedes it and your file has: after that key’s whole block, or, when that key has a one-line plain value, straight after its line, so a comment above your next key stays with it; failing that, right before the nearest built-in key that follows it; failing that, last in the frontmatter. A key your file already has, quoted ("closed": null) or with a space before the colon, counts as present. Nothing else changes: your own keys, their values, their order and the body stay byte for byte, and no key is ever removed. Running it again on an up-to-date file writes nothing.

cdno templates sync project
# project: added `closed` to .cuaderno/templates/project.md; kept your `owner`
cdno templates sync --all --check     # in CI: fails while any override is behind

--json emits an array with one object per override (with <TYPE> and no override, one not_customised object), each with note_type, path, status (synced, behind, up_to_date, not_customised, no_frontmatter or unreadable, the last with an error), added and kept (your own keys, listed so you can see nothing was dropped). A file with no --- frontmatter block, or one that cannot be read, is reported and left alone; an unreadable one makes the command exit non-zero, with or without --check. It writes through the same path as templates save.

cdno templates list and cdno lint both say when an override has fallen behind.

cdno templates list

Every note type with the state of its template: whether a custom override exists, which source is in effect, and the path the override lives (or would live) at. A custom override that lacks a key its built-in has gained shows custom (lacks closed; …) in the Template column.

cdno templates list [OPTIONS]

--json reports source as a stable token — builtin_default, builtin_variant, custom_base, custom_variant, or none — rather than the human label in the table, and lists the missing keys under missing_builtin_keys (empty when there are none).

cdno templates show <type>

Print a template’s effective content verbatim: the custom override when one exists, else the built-in default. A custom type with no template yet shows the starter new would write.

cdno templates show [OPTIONS] <TYPE>

Output is byte-verbatim, so it round-trips:

cdno templates eject project
cdno templates show project | diff - .cuaderno/templates/project.md   # no output

--json emits {content, source} instead.

cdno templates save

Write a template. On a built-in type this creates the custom override transparently — no prior eject needed.

cdno templates save [OPTIONS]

Without --file, an interactive run opens $EDITOR seeded with the template as it stands. Off a terminal --file is required, so a scripted save cannot silently truncate a template to nothing.

cdno templates save --note-type project --file my-project.md
cat my-project.md | cdno templates save --note-type project --file -

cdno templates new

Scaffold a starter template for a config-defined custom type that has none yet — a frontmatter block of type plus each declared required field as a {{placeholder}}, and a # {{title}} heading.

cdno templates new [OPTIONS]

Refuses a built-in type, which already has a default to edit — use eject or save for those — and refuses to overwrite an existing template.

A custom type has exactly one template, so --variant is not accepted on show, save or new for one; declare a separate note type instead.

Related

• Customising templates and frontmatter — how to write a custom template and use [variables] / [variables.prompt].

cdno config

Inspect, check and edit .cuaderno/config.toml — the vault’s configuration file.

cdno config <COMMAND> [OPTIONS]

These verbs deliberately do not open the vault. Opening one validates the config first, so a config that will not parse means no vault at all — and that is exactly when you need to read, check and fix it. Every other command would fail with a bare “loading config.toml”; these report the line, the column and the reason.

Commands

The save gate

Every write — edit and all the structured setters alike — goes through the same three steps:

1. Validate first. A config that would not reopen is never written.
2. Compare and swap. If the file changed on disk since it was read, the save is refused rather than clobbering the other edit.
3. Write verbatim. Comments and key order survive.

So a refused save always leaves the file byte-identical. edit additionally keeps your rejected buffer and prints its path — a refused save must not also lose the work.

edit round-trips a scratch copy rather than opening config.toml itself: handing an editor the real file would route the write around all three steps. It needs a terminal, and refuses an editor that detaches instead of waiting, because there is then no moment at which the buffer is known to be written.

Setting a value merges, it does not replace

note-type set and field set change only the flags you pass. An omitted flag keeps its current value, so a one-flag edit cannot silently drop the rest of the entry.

To clear something, pass it empty (--template '', --required ''), or use the paired negative flag for a boolean (--no-append-only, --no-settable, --no-log-on-change, --no-required).

Changing a field’s --type is the one exception: default and values are declared against the old type, so they are dropped and the command says so. Re-set them in the same command or afterwards.

Installing a bundled note type

cdno ships with note types that cdno init declares in every new vault. Today there is one, concept. note-type install adds one to a vault created before it existed, so the older vault ends up exactly as a new one would:

cdno config note-type install --list            # what ships, and whether this vault has it
cdno config note-type install --name concept --dry-run
cdno config note-type install --name concept

It takes three steps, in this order, and each writes only what is absent:

1. Template. Creates .cuaderno/templates/ if needed and writes the type’s template, but only when no file of that name exists. A template you have edited is never overwritten; the report says whether it matches the bundled one. If your declaration names a different template file, the bundled one is not installed.
2. Folder. Creates the type’s folder (concepts/) if absent.
3. Declaration. Appends the [note_types.<name>] block, comment included, through the same save gate as every other verb. If the config already declares the type, the declaration is never modified: it is compared with the bundled one, key by key, and the report names the note-type set command that would adopt each bundled value you might want.

declaration  written
template     written .cuaderno/templates/concept.md
folder       created concepts/

Re-running is safe. When there is nothing left to write, the report ends with concept: already installed, nothing to do and the command exits 0.

A config the vault would not open (check it with cdno config validate) is refused before anything is written, even when the type is already declared.

Two refusals are phrased in plain words, and in both nothing is left behind:

• a config that declares note_types as an inline table cannot take an appended block; add it with cdno config edit;
• another custom type already using the folder (concepts) is refused by the gate.

--list prints each bundled type’s purpose, folder, fields, template and its section headings, with this vault’s state: not installed, installed (matches), installed (declaration differs), installed (template customised) or installed (template missing). --dry-run prints the exact block and template that would be written, checks the result would validate, and writes nothing. With --json, the report is one object with changed, as the other verbs carry it:

{"changed": true, "note_type": "concept",
 "declaration": "written",
 "template": {"path": "templates/concept.md", "action": "written"},
 "folder": {"path": "concepts", "action": "created"}}

Once installed, a bundled type is an ordinary custom declaration: edit it with note-type set, or delete it with note-type remove.

Options

Promptable arguments are flags. Omit one in a terminal and you are asked for it; omit one with --no-interactive (or off a TTY) and you get a named error rather than a usage dump.

Common to every verb: the global options.

Examples

cdno config show                       # verbatim, pipeable back into the file
cdno config validate                   # exit 0 iff the vault would open
cdno config validate --file draft.toml # check a candidate first
cdno config edit                       # $EDITOR round trip through the gate

# Declare a custom note type, then extend it.
cdno config note-type set --name people --folder people --required name,email
cdno config note-type set --name people --folder humans          # keeps required + template
cdno config field set --note-type people --field email --type string --required

# Add the concept library to a vault created before it existed.
cdno config note-type install --name concept

# Template variables.
cdno config var set --name author --value "Your Name"
cdno config prompt set --name subject --message "What is this note about?"

# Plot a declared tracking metric.
cdno config plot set --activity gym --metric weight --plot line

See also

• Configuration reference — every key the file accepts.
• Custom note types.
• templates — the templates those note types render through.

cdno watch

Watch the vault and reconcile the index whenever a note changes outside cdno.

cdno watch [OPTIONS]

Every other command reconciles once, at startup, and exits. That is enough when the process is short-lived, but it means a note you edit in another editor is invisible to search, lint and backlinks until the next cdno command happens to run. watch closes that gap: it stays in the foreground and reconciles on each debounced change.

Markdown on disk remains the source of truth — this only keeps the cache honest.

Options

Only the global options.

Behaviour

• Foreground until Ctrl-C. There is no daemon mode; run it in a spare terminal or under your own process supervisor.
• Debounced and coalesced. An editor’s atomic-save storm becomes one pass, and a bulk change (a git checkout across hundreds of notes) reconciles once rather than once per file.
• Markdown only, outside .cuaderno/. Reconciliation reads every directory in the vault, and the filesystem reports those reads — so reacting to them would make each pass trigger the next. Restricting to .md files outside .cuaderno/ keeps the watcher from hearing itself.
• A failed pass does not stop the watch. The usual cause is a file caught half-written; the next event reconciles again.

Each pass prints what changed, so an edit that did not land is visible as no index change.

Limitations

• A .cuaderno/config.toml change needs a restart. Honouring a new ignore glob means rebuilding the vault rather than reconciling it. watch says so at startup rather than quietly using stale globs.
• Interrupting a pass is safe but leaves the index incomplete until the next run — it is a cache, and the notes are untouched.

Examples

cdno watch                       # in the vault
cdno watch --vault ~/notebook    # or point it at one

See also

• reindex — force a full rebuild.
• Business rules.

cdno frontmatter

Set typed frontmatter fields on a note through the index. Every other write surface (cdno log, section upserts) is body-oriented; this is the one that writes a frontmatter field, so a flag like the daily meds: true can be toggled without a hand-edit that would desync .cuaderno/index.db.

The field must be declared in .cuaderno/config.toml under [schemas.<type>.fields.<key>] and marked settable = true — the write is driven entirely by that spec (see the configuration reference).

cdno frontmatter set <note> <key> <value>

Set a declared, settable field to a new value.

cdno frontmatter set [OPTIONS] <NOTE> <KEY> <VALUE>

Arguments

Takes only the global options. With --json, emits the { path, message } write result.

Rules

• Declared + settable, default-deny. An undeclared key is rejected; a declared field without settable = true (absent or false) is rejected.
• Type-checked. A value that doesn’t parse as the declared type — or isn’t one of a string field’s values — is rejected and nothing is written.
• Reserved keys are blocked. type, status, a calendar type’s period key (date/week/month), and a project’s closed date are engine-owned regardless of config — use the lifecycle commands (cdno project park/activate/complete/drop, cdno question set-status, …) for those, so their auto-logging and index invariants are never bypassed.
• No-op on no change. Setting a field to the value it already holds writes nothing and logs nothing.
• Optional auto-log. When the field declares log_on_change = true, a real change stamps a key: old → new line into today’s daily note in the same commit.
• Strict-exists (v1). The key must already be present in the note’s frontmatter (the daily flags exist via the template default). A missing key errors rather than being appended; ordered-insert is a planned follow-up. Slug resolution for projects/questions is likewise a follow-up — v1 resolves today/dates and explicit note paths.

Examples

cdno frontmatter set today meds true          # toggle today's daily meds flag
cdno frontmatter set today workout true        # if log_on_change, also logs it
cdno frontmatter set 2026-07-09 closed true    # a specific day's daily note
cdno frontmatter set projects/surrogate.md phase review

Related

• Configuration reference — declaring [schemas.<type>.fields], including settable and log_on_change.
• Frontmatter fields — the built-in per-type frontmatter shapes.

cdno note

Create, list and revise notes of a config-defined custom type (declared under [note_types.<name>] in .cuaderno/config.toml). Built-in types have their own verbs (cdno project create, cdno question create, …); this is the generic surface for custom types.

cdno note create <type>

Create a note of custom type <type>, written to <folder>/<slug(title)>.md.

cdno note create [OPTIONS] <TYPE> --title <TITLE>

Arguments

Options

Plus the global options. With --json, emits a {path, message} result. If the type ships no template (.cuaderno/templates/<type>.md), a minimal note is synthesised from the declared fields plus a # <title> heading.

Creation is logged to today’s daily note as <type> created [[…]] — <title>; do not log it again by hand.

cdno note list <type>

List every note of custom type <type>, by path.

cdno note list <TYPE>

cdno note revise [note]

Refine a mutable custom note (such as a concept) in place. The revision is logged to today’s daily note as revised [[<path>]] — <reason>, or revised [[<path>#<Section>]] — <reason> for a section, in the same write; do not log it again by hand. Built-in note types (project, action, daily, …) and custom types declared append_only = true are refused.

cdno note revise [OPTIONS] [NOTE]

Arguments

Options

Plus the global options. With neither --body-file nor --section, an interactive session opens the note’s current body in your editor, then asks for the reason and confirms before writing; under --no-interactive both are required. A note chosen in a picker (an omitted, ambiguous or unmatched reference) also brings the confirm, even when every flag was given. The note is read before anything is gathered, and a note that changed on disk after that read (an edit saved while the editor was open, say) is refused rather than overwritten: read it again and redo the revision.

Text identical to the note’s current content writes and logs nothing and prints No change to <path>. That includes closing the editor without changing anything: the reason and confirm are still asked for, and the result is No change to <path>. With --json, emits {path, message, changed, new_hash, log_line, section_target}.

cdno note rename [note]

Rename a note’s slug and follow every reference to it (RFC 0007): the wikilinks that resolve to it, the project: / portfolio: style fields that name it, an aliases: entry for the old slug on the note itself, and one renamed line in today’s daily log. The old name keeps resolving through the alias.

Renamable: projects, questions (a question whose slug a portfolio shares moves the portfolio with it), active action notes, portfolios and custom notes kept as single files. A portfolio with a same-slug question is renamed through the question. Dailies, weeklies, monthlies, evidence, tracking, inbox items, archived action notes, stewardships, commitments, a custom note kept as a folder and a note with no type are refused (note_not_renamable).

With --relink the note keeps its slug, and the links that still reach it through a former name are rewritten to the current one. An archived action note can be relinked, though not renamed.

Arguments

Options

The preview

A long title makes a slug that stops mid-thought. This is a real run against a throwaway vault (see the tutorial for the whole story):

$ cdno project create --title "Calibrate the surrogate model against the high-fidelity thermal runs" --context work
Created projects/calibrate-the-surrogate-model-against-the.md

$ cdno action add --project calibrate-the-surrogate-model-against-the --title "Run the baseline sweep" --note --energy deep
Action added to projects/calibrate-the-surrogate-model-against-the.md with note actions/run-the-baseline-sweep.md

$ cdno action start --project calibrate-the-surrogate-model-against-the --query baseline
Started on calibrate-the-surrogate-model-against-the, logged to journal/2026/daily/2026-11-06.md

$ cdno note rename calibrate-the-surrogate-model-against-the --to surrogate-calibration --dry-run
Dry run: nothing written.
  move     projects/calibrate-the-surrogate-model-against-the.md -> projects/surrogate-calibration.md
  rewrite  actions/run-the-baseline-sweep.md                      1 field (project:)
  rewrite  journal/2026/daily/2026-11-06.md                       3 links
  alias    projects/surrogate-calibration.md gains `calibrate-the-surrogate-model-against-the`
  log      journal/2026/daily/2026-11-06.md
             renamed [[surrogate-calibration]] — Calibrate the surrogate model against the high-fidelity thermal runs
               was: calibrate-the-surrogate-model-against-the
  4 references in 2 notes · plan 2109…

$ cdno note rename calibrate-the-surrogate-model-against-the --to surrogate-calibration \
    --reason "the derived slug stopped mid-title"

The last command prints the same preview, with the reason: line (the reason is part of the plan, so its hash differs), and then Renamed `calibrate-the-surrogate-model-against-the` to `surrogate-calibration`. With the note and --to given on the command line the write runs straight away, in a terminal or not: nothing is prompted, so nothing is confirmed. Use --dry-run first to see the plan. Leave out --to in a terminal if you want to be asked for it, shown the preview and asked to confirm.

A rewrite line reads N links, M fields (project:, …) or both (2 links / 1 field (project:)). When the reference matched a former name, the first line is found by its former name `old` . The log block is the entry as it will be appended, without its time stamp. Warnings follow the totals line. In an interactive session, anything that was prompted (the note, the slug) brings the preview and a confirm. That confirmed write is given the preview’s plan hash within the same command: it writes exactly what was shown, or, if a referrer changed while the confirm waited, refuses with stale_plan and writes nothing. The hash does not join a --dry-run to a later run, so a change made between the two is not caught: a dry run is a look, not a lock. A rename to the note’s current slug writes nothing.

With --json: the plan (target, from, new_slug, moves, edits with their changes, references, notes, log_line, warnings, plan_hash) plus written (a bool), index_stale and dry_run. Refusals are rejection objects and exit 1; a rollback that itself failed (rename_incomplete) lists the paths to check by hand, one per line in text.

The sync check

A rename rewrites many notes at once, so in a vault that is a git repository synced with another clone it first checks that it is not about to rewrite notes the other clone has already changed. Unless --dry-run, it fetches the upstream (no credential prompt, at most 5 seconds; a fetch that fails or times out prints one warning: line and the check reads the upstream as last fetched). Then:

The whole check runs again once the rename holds the vault’s write lock, with the same override and no fetch, so a merge started, or a fetch landed, while the confirm prompt waits is still refused, and nothing is written. A dry run is checked exactly as the write is, against the upstream as last fetched (it never fetches): it refuses with the same code and exit code, so --dry-run --skip-sync-check is how to see the plan of a vault that is behind. Warnings go to stderr; under --json they are warnings entries of kind sync_check in the plan instead (on stderr only before a refusal).

Refusals

Every refusal writes nothing. With --json each is a rejection object with the code below; in text the message is printed and the exit status is 1.

The seven note_not_renamable reasons, and what to do for each. In text mode the code itself is not printed, only the message (note '…' cannot be renamed: <reason>); --json carries both.

A rename that would write over a file the vault already holds is refused as slug_taken. That includes a rename that changes only the case of a slug (Alpha to alpha): it is refused where the filesystem cannot tell the two names apart (macOS and Windows by default) and allowed where it can (a default Linux filesystem). The message names the note itself as the holder (slug 'alpha' is taken by 'projects/Alpha.md' (as its stem)), which is expected. To change only the case, rename through a temporary slug (Alpha to alpha-tmp, then alpha-tmp to alpha); the note ends up with both old names as aliases. The old spelling (Alpha) stays listed but nothing resolves it, because aliases must be slug-shaped; it can be deleted by hand.

Renaming back, and former names

The old slug is kept on the note as aliases: [<old>], and no other note may take it while it is listed. Renaming old to new and then new back to old is allowed, and leaves aliases: [new]. In the log, the first renamed line’s head link is rewritten to [[old]], like any other link to the note, while its was: old line stays as written: was: is a copied value, never a link, so it is the record of what the note was called at the time. The second line reads renamed [[old]] — … was: new.

A command that is given a former name still finds the note. cdno open, cdno note revise and the rename preview say so (found by its former name `old` ). cdno project show does not: it prints the note’s current slug in its header, which is how to learn the new name there.

A link written with an old name still works in cdno, so leaving it is harmless. Editing it by hand to the new name is allowed too, even in a past log entry or an archived action note: it is the same address correction a rename makes.

Relinking the stragglers: --relink

A link written with a former name after the rename is a straggler: cdno still resolves it through the alias, and cdno lint reports it, but an editor cannot follow it. The usual way one appears is a vault synced between two machines with a journal merged line by line (merge=union): the rename rewrote a log line on one machine, the other appended a line beside it, and the merge kept both versions, so the old line comes back holding the old name (the merge keeps the whole hunk, so usually several lines come back, not one). --relink rewrites every straggler in one go:

$ cdno lint
[warning] journal/2026/daily/2026-11-06.md: `[[calibrate-the-surrogate-model-against-the]]` names a renamed note — now `surrogate-calibration`

$ cdno note rename surrogate-calibration --relink --dry-run
Dry run: nothing written.
  rewrite  journal/2026/daily/2026-11-06.md  1 link
  log      journal/2026/daily/2026-11-06.md
             relinked [[surrogate-calibration]] — Calibrate the surrogate model against the high-fidelity thermal runs
               references: 1
  1 reference in 1 note · plan 1c09…

$ cdno note rename surrogate-calibration --relink

The last command prints the same preview and Relinked 1 reference to `surrogate-calibration`. It goes through the same preview, plan hash, sync check and refusals as a rename, with these differences:

• Only a reference through a former name is rewritten, links and fields alike. A link is rewritten when it resolves to the note through one of its aliases (the links cdno lint warns about), and only to an address that resolves to the same note. A link that already names the note by its slug or path is left alone, and so is a link a former name no longer reaches (another note took that file name since). A reference can only ever move to where it already points. A field such as project: that holds one of the note’s former names is rewritten too (lint does not report these, since a field is not a link): a field is read by its value alone, so until the relink it named no note at all.
• It corrects addresses; it does not tidy the merge. The lines the union merge duplicated stay after the relink, now with identical text twice. They are the merge’s, not journal entries, so deleting the extra copy by hand is yours to do if you want it.
• An archived action note can be relinked. A rename refuses it (archived, its frozen prefix would change), but a relink changes nothing on the target, so the links to a completed action that was renamed before it was archived can be repaired. Every other refusal of a rename applies: note_not_renamable for the other reasons, stem_shared, the referrers’ own and the sync check.
• Nothing moves and no alias changes. The note stays where it is, byte for byte unless it links to itself by a former name, and its aliases: stay listed, so an old link anywhere else (a file ignore hides, the other machine) keeps working.
• The log line is relinked. It reads relinked [[<slug>]] — <title> with an indented references: <n> line and no was:, since the name did not change. With no straggler there is nothing to write: Nothing to relink: no link reaches `<slug>` through a former name., and nothing is logged.

With --json the shape is a rename’s, with moves empty and new_slug equal to from.

On the other machine

Some vaults live in a git repository with a working copy on more than one machine, synced by a tool that merges. Three things apply:

• Rename on a machine that is up to date. The sync check above refuses a rename while the vault is behind its upstream. Your sync tool carries the result to the other machine on its next run. Use --skip-sync-check only when you know the other machine has nothing unpushed that touches these notes, for instance when the upstream is unreachable and you accept the risk.
• A conflict is the other machine’s edit meeting the rename. The sync stops rather than resolve it. Resolve it as you would any merge, then run cdno lint: a link the merge brought back with the old name is reported as a straggler ([[old]] names a renamed note — now new). It still resolves in cdno, through the alias, but an editor cannot follow it: run cdno note rename <note> --relink to rewrite every one to the current name (or fix one by hand).
• Run any cdno command in the vault once on every clone, on a cdno that stamps RLM 1.2 (one that has note rename), before renaming anything an archived action references. (Starting the MCP server on it counts too.) That records each archived action note in a form that ignores link addresses, which is how cdno lint tells a corrected link from an edit. A clone that receives a renamed archived note before it has done so reports an archived action note error from cdno lint (modified an existing line, or truncated below its frozen prefix after a shorter slug) that names cdno reindex. cdno reindex clears it, at the cost of the stored records: every archived action note then loses that check.

Examples

cdno note create person --title "Ada Lovelace" --field name=Ada --field role=advisor
cdno note create person --title "Ada Lovelace, programmer and mathematician" --field name=Ada --slug ada-lovelace
cdno note list person
cdno note rename calibrate-the-surrogate-model --to surrogate-calibration --dry-run
cdno note rename calibrate-the-surrogate-model --to surrogate-calibration --reason "the derived slug was too long"
cdno note rename calibrate-the-surrogate-model --to surrogate-calibration --dry-run --skip-sync-check   # plan a vault that is behind
cdno note rename surrogate-calibration --relink --dry-run   # the links still under a former name
cdno note rename surrogate-calibration --relink
cdno note revise concept:woodbury-identity --section Proof --content-file proof.md \
  --reason "shorter proof via push-through"

Related

• Renaming a note — the long-title case end to end.
• Custom note types — declaring a type and the full feature.
• The concept library and Building a concept library — note create --origin and note revise in use.

cdno commit

Manage standalone commitments — dated promises kept as their own notes. To view all commitments (from every source), use cdno commitments.

cdno commit [OPTIONS] <COMMAND>

Subcommands

All four honour --json ({path, message}, non-interactive).

cdno commit create

Create an active commitment note. Optionally attribute it to a project or stewardship.

cdno commit create --title "Pay rent" --due 2026-06-01 --context personal
cdno commit create --title "Review Erik's draft" --due 2026-05-20 --context work --project projects/icml-paper
cdno commit create --title "Send the surrogate-model results to the steering group" --due 2026-12-01 --context work --slug send-results

cdno commit done

Mark a commitment completed: stamps status and completed, and moves the note to commitments/_done/<year>/<slug>.md.

cdno commit done --slug pay-rent

cdno commit drop

End an active commitment that was not kept — cancelled, superseded, or overtaken by events.

cdno commit drop --slug quarterly-report
cdno commit drop --slug quarterly-report --reason "the client cancelled the engagement"

Use this rather than done when the promise was not fulfilled. done writes commitment completed [[slug]] into the daily log, which every weekly and monthly review reads back from, so using it for a cancelled promise makes the vault assert something nobody did. Deleting the note is not the alternative either: that destroys the record that the promise was ever made, and desyncs the index on the way out.

The note is archived to commitments/_done/<year>/ like a completion, stamped status: dropped with completed cleared — so it never appears as completed work. The log entry says what happened, with the reason on its own line:

- **16:30**: commitment dropped on [[quarterly-report]] — Quarterly report
  reason: the client cancelled the engagement

A dropped commitment can afterwards be neither completed nor rescheduled. Nothing is destroyed — the note keeps its body and its created date — but a drop is re-decided rather than undone: if the promise comes back, make it again, and the record shows both decisions.

cdno commit reschedule

Move an active commitment’s due date, recording the move in today’s daily note.

cdno commit reschedule --slug quarterly-report --due 2026-06-15

Commitments slip, and that is normal rather than an error state. Use this instead of deleting and recreating the note: recreating destroys the body — the notes on who was chased and what was promised — and resets created, the one field that shows how long something has been slipping.

The log entry carries both dates:

- **09:30**: commitment rescheduled on [[quarterly-report]] — Quarterly report
  was: 2026-06-01
  now: 2026-06-15

That is what makes repeated slippage visible instead of silently rewritten: a commitment moving once is a checkpoint, a commitment moving for the fourth time is a signal. Moving a date earlier is allowed; moving it to the date it already carries is refused, since the entry would assert a slip that never happened.

Related MCP tools

create_commitment, complete_commitment, drop_commitment, reschedule_commitment. (View via get_commitments.)

See also

• Commitments and deadlines.
• commitments — the aggregated view.

cdno lint

Validate every indexed note and report what is wrong with it — frontmatter, links, attachment pairing, and lines the canonical parsers silently skip. Errors fail the command; warnings (such as broken wikilinks) are non-fatal unless --strict is given.

A wikilink or embed that points at an attachment — a pasted image, a filed PDF — is not a broken link: attachments are never indexed, but the target is resolved against the filesystem (relative to the linking note, then to the vault root) before a link is called broken. Only a target that matches nothing at all is reported, and a missing ![[embed]] reads as a missing file rather than a link that “resolves to no note”.

A link that resolves only through a note’s aliases: entry — a former name — is a straggler: it still works, but lint warns and names the note’s current slug ([[old]] names a renamed note — now new), so you can fix the link by hand, or rewrite them all with cdno note rename <note> --relink. Lint also warns when an alias collides with another note’s name. If it equals another note’s file stem, the stem wins and the alias can never be followed (alias x on <path> is shadowed by <other>). If it equals the folder name of a folder note such as portfolios/x/_index.md, the alias takes the bare link [[x]] (alias x on <path> takes bare [[x]] from folder note <other>); the folder form [[portfolios/x]] still reaches the folder note. A straggler to a folder note is told to use the folder form, since a bare link to the new name would not resolve.

It also reports lines that were plainly meant to be structured but will never be read as such, because the parsers that consume them skip what they cannot parse rather than complaining. That covers malformed ## Active Habits and ## Periodic Commitments bullets on a stewardship dashboard, and — in a daily note’s ## Logs — a start or close marker that cdno now will not see:

[warning] journal/2026/daily/2026-09-15.md: log line `- **09:30**: started [[alpha]] - Draft methods (deep)` reads as a `started` marker but `cdno now` will not see it -- found an ASCII hyphen (-) where an em-dash (—) separates the slug from the action

The shape has to be - **HH:MM**: started [[slug]] — text, and every part of it matters: the - bullet and the stamp are what make the line a log entry at all, and the separator must be a real em dash (U+2014). A stamp that was attempted and mangled — - 09:20: unbolded, - **25:99**: out of range, - **09:40** with no colon — is caught too, not only one that is missing outright. The check is deliberately narrow — the marker has to open the entry and be followed immediately by [[ — so ordinary prose in ## Logs, including a sentence that merely mentions starting something or names a note mid-sentence, is never flagged. The renamed [[new]] — Title line a rename writes, and the relinked [[new]] — Title line of --relink, get the same near-miss check (neither is a focus marker, so cdno now never reads them), and a was: continuation under it that contains a [[ link is a warning, because the value is a copied slug and a link would be rewritten by the next rename.

It checks that an archived action note (actions/_done/<year>/) has only grown since it was archived. The archival recorded the note’s frozen prefix; lines appended after it (a late retrospective) are fine, while an edit to an existing line, or a cut into the prefix, is an error:

[error] actions/_done/2026/characterise.md: archived action note modified an existing line (append-only after completion)

A rename may change the prefix in one way only: it re-targets references, rewriting the address of a wikilink ([[old]] becomes [[surrogate-model]]) and a reference field such as project:. So the prefix is accepted when either its bytes are unchanged or they match with every wikilink address and reference-field value set aside. The cost of that rule is that a hand edit which only re-targets a reference inside a frozen prefix is no longer detected; any other change still is. This holds on every clone that opened the vault once on this version with the backfill completing (it is retried at every open, and a lock timeout only postpones it) before the renamed file arrived: a note archived on an older version and renamed elsewhere first is reported as an error that names cdno reindex, which clears it by rebuilding the index without any archival snapshots, so every archived note loses this check. On a renamed note, a hand addition that follows an unmatched backtick at the end of the prefix with no blank line in between is reported too; start a late addition after a blank line. A note archived by a newer cdno, whose snapshot this cdno cannot read in the second form, gets a warning naming the version, and only the unchanged-bytes form is checked for it.

It checks each project map’s status against the folder the map sits in and against its closed: date. A status its folder contradicts is an error, since the project verbs find a map by its folder and act on it by its status; the message says which way to repair it:

[error] projects/_parked/alpha.md: project says `status: active` but is not at `projects/<slug>.md`; move it there, or set the status its folder stands for

A completed or dropped map outside projects/_done/<year>/ is told to move there and set closed: <date>, or to set status: active and close it with cdno project complete. A closed: date that disagrees with the status is a warning: a completed or dropped map without one cannot be placed by the reviews, and an active or parked map carrying one should have closed: null.

It reads each open map’s held_by: (the name of whoever else is moving it) against the vault’s [projects] holder_sentinels list (see configuration). A value that is not a plain name, such as an unquoted wikilink, is an error, because the holder you wrote is not honoured and the map still counts toward the cap (or would, once a parked map is activated). For an unquoted wikilink the message says to quote it; for anything else (a number, a date, a list) it says to write a single quoted name:

[error] projects/harbour.md: project `held_by:` is not a plain name, so the holder is not honoured and the map counts toward the cap; quote it: `held_by: "[[people/ana]]"`

A value on the list, or a blank one, names you or nobody, so the map is yours and counts. That is a warning:

[warning] projects/harbour.md: project `held_by: "tbd"` does not name someone else: delete the line, or name the holder; a holder that names you or nobody means the map is yours

And it warns, once, on .cuaderno/config.toml when the projects that count (active and naming no other holder) exceed max_active_projects, listing them. The project verbs refuse to go over the cap, so this catches a cap lowered in config or maps edited by hand:

[warning] .cuaderno/config.toml: 6 projects count toward the cap of 5 (`max_active_projects`): [[alpha]], [[bravo]], [[charlie]], [[delta]], [[echo]], [[foxtrot]]; park or close one until no more than 5 count

If a project map cannot be read at all (an unknown status, a missing context or created), the count is unknown, and the same file gets an error saying so: could not count the projects against the cap: …. The project verbs fail on such a map too, so fix it first.

It also warns when a customised template (.cuaderno/templates/<type>.md) lacks a frontmatter key that the built-in template has, typically one a release added after you customised it, and reports a customised template it cannot read (for instance one that is not UTF-8) as an error:

[warning] .cuaderno/templates/project.md: custom template `project` lacks `closed` (run `cdno templates sync project`)

cdno templates sync adds the key without touching your edits. Lint cannot tell a new key from one you removed on purpose, so a built-in key you deleted from your template is reported too.

It reads [vault] method_version (see configuration) and reports, on .cuaderno/config.toml, a vault this cdno would not write to as an error: one on an older major version (the message points at cdno migrate --dry-run, then cdno migrate) or a newer major (upgrade cdno). A vault on a newer minor version is a warning, since writes proceed:

[warning] .cuaderno/config.toml: this vault follows RLM 1.3, a newer minor version than the RLM 1.2 this cdno implements — writes proceed; upgrade cdno for the practices it adds

A vault on this cdno’s version, or on an older minor one (an unstamped vault included), gets no row here. A malformed method_version ("v1", "1.1.0") is not a lint row: it is a configuration error, so the vault does not open and every command, lint included, fails with an error naming the key. The one exception is a long-running server (cdno-mcp-server) whose config was edited to a malformed value after it opened: it keeps running, and there lint (and the MCP lint tool) reports one error row on .cuaderno/config.toml naming the key instead of aborting. Fix the value (see configuration).

While the vault records a method version below RLM 1.1 (an unstamped vault reads as 1.0), it gives one warning per overdue hard date on a parked project map, on every run, since the commitments register keeps those dates as of RLM 1.1: the one-time read-through of parked deadlines. The row sits on the map for a hard milestone and on the action note for a due:, and names the fix:

[warning] projects/_parked/beta.md: hard milestone `Grant report` (2026-04-15) on parked project [[beta]] is overdue and in the commitments register again (a parked map's hard dates are promises under RLM 1.1): drop it with `cdno project milestone drop`, or re-date it on the map; this read-through row disappears once the vault records RLM 1.1, which `cdno migrate` records

An action note’s row says to re-date its due: in the note, or drop the action with cdno action drop. Future dates are not warned on; cdno migrate --dry-run lists them all. Once the vault records RLM 1.1 the rows are gone for good.