Skip to content
riggerrigger

note

rigger note <PROJECT> <TEXT> [--kind <KIND>] [--principle <NAME>]
rigger note <PROJECT> <TEXT> --kind question [--due <DAY>]
rigger note <PROJECT> [<TEXT>] --kind shipped --tag <TAG> [--release] [--registry <NAME>]...
rigger wish <PROJECT> <TEXT> [--from <PROJECT>]

Records an event against a project. This is how the record grows during a session, instead of by editing markdown afterwards. An assistant does the same through the MCP server; this is the door for the owner and for scripts.

Terminal window
$ rigger note sample "The parser must take hubs as they are." --kind finding
Recorded a finding for sample


$ rigger note sample "Ship the importer next." --kind next
Set the next step for sample; the next session starts from it

Kinds

Section titled “Kinds”
Kind What it is for
decision a decision and the reason behind it
finding something learnt about the code or the domain
pitfall a trap worth remembering
change something that changed in the product
next the one line the next session starts from
state one line for the hub’s state block: where things stand after this sitting
plan a step of the plan of edits, for a card
question something only the owner can settle; it waits in the inbox (v0.23.0)
shipped a release, as the release engine made it (v0.23.0)

An event against a card rather than a project is rigger task note <CARD> <TEXT> [--kind <KIND>] - by the card’s key, an alias or its id; cards live in the desk, so no project is named. A card’s packet reads these back by kind.

finding is the default. Decisions, findings, pitfalls and changes appear under Recent in the context packet; the newest next becomes its Next step and is not repeated among the events.

state is not an event. It goes to the top of the README’s «Состояние» block, which export writes from the record - the one line the old ritual asked for whenever the state shifted, now with somewhere to go once the hub is generated:

Terminal window
$ rigger note sample "**v0.2.0 shipped.** The second stage is closed." --kind state
Added a state line for sample; `rigger export` writes it into the README

The principle a decision stands on

Section titled “The principle a decision stands on”

Most decisions of a line are not new: they are one more instance of something already believed. --principle names which, so the instances can be read together.

Terminal window
$ rigger note sample "Dropped the old column outright." --kind decision \
      --principle "no users, no compatibility"
Recorded a decision for sample
  on the principle "no users, no compatibility"

rigger why --principle then reads every decision that stands on it, across every project, oldest first - the story of how the line came to believe it, rather than six opinions in six hubs.

The vocabulary is whatever has been used. There is no list to keep: a principle has no properties beyond its name, and a list kept beside the decisions would be a second truth. rigger why --principles prints the names with how often each has been invoked, which is what to read before naming one - so a decision joins a thread rather than starting a synonym of it.

Only a decision can carry one. A finding or a change is something that happened, not something believed, and asking for a principle on one is refused rather than quietly dropped.

A question, with the day it is due

Section titled “A question, with the day it is due”

A question is addressed to the owner, and waits in the inbox and in the packet until rigger resolve answers it. Until v0.23.0 only an assistant could ask one, through ask_owner; a script, or the owner at a terminal, had no door to the inbox that rigger inbox reads.

Terminal window
$ rigger note sample "Which registry goes first?" --kind question --due friday
Asked the owner about sample; it waits in the inbox until answered
  due 2026-09-25

--due is the day the answer is needed by - a release waiting on it, say. It takes a date, today, tomorrow, +3d, or a weekday meaning the coming one (today included). Once the day has gone by, the question is called overdue wherever it is shown: first in its line of the inbox, under Waiting on you in the Monday brief, in the week’s toast, and in the packet as (overdue since 2026-09-25). For a person at a terminal the word is also red; in a pipe it is just the word. The day itself is not overdue: a question due today can still be answered on time.

Asking the same question again with --due gives the one already waiting a day, rather than a second copy. --due on anything but a question, or a day that is not a day, is refused before anything is written.

A release, as the engine made it

Section titled “A release, as the engine made it”

A tag says the work was finished; it does not say anyone can install it. The release engine - the thing that tags, publishes and uploads - says what it did, and the record believes it:

Terminal window
$ rigger note sample --kind shipped --tag v0.2.0 --release --registry crates.io --registry npm
sample v0.2.0 shipped - released and published
  reached crates.io, npm
  • --tag names the release, and must name a version.
  • --release says a release with its archives went out.
  • --registry names a registry it reached; repeat it for each.
  • The text is optional here: without one, the event is composed from the flags - v0.2.0 went out: the release with its archives, crates.io, npm.

The version closes on this word, without waiting for sync to read the tag. When sync does read it, the tag’s day and moment replace the engine’s - the tag is the proof - but what the engine said about delivery stays: sync’s own look at GitHub never overwrites it. The same release recorded from an assistant is record_shipped.

What “delivery” means, and the states it has, is on the sync page.

A change can also arrive on its own: rigger sync reads them from commit messages.

rigger wish

Section titled “rigger wish”

A wish is something to sort into the plan later, so it needs no kind:

Terminal window
$ rigger wish sample "Show how many days the project has gone without a commit."
Recorded a wish for sample

Wishes have their own section in the packet, and the same text recorded twice stays one wish - unlike a dated event, a wish is identified by what it says. Once a wish is in the plan, rigger resolve takes it off the list.

A wish a neighbour asked for

Section titled “A wish a neighbour asked for”

When one product needs something of another, --from records who is asking:

Terminal window
$ rigger wish dowel "A status colour that is not the accent." --from lyrid
Recorded a wish for dowel from lyrid

It is still a wish - the same row, sorted by the same resolve, competing for the same stages. What changes is that somebody is waiting for it, so the packet names them on the line and inbox gathers them into a group of their own, where the owner looks for what is waiting.

A name the record does not have is refused: a wish recorded from a neighbour that does not exist is one nobody will ever answer.

JSON

Section titled “JSON”

note and wish print the event they recorded.

Field Type Meaning
event object The event as recorded.
changed boolean False when the same event was already in the record.
event.id integer The id of the event, as resolve takes it.
event.project string The name of the project it was recorded against.
event.card string or null The key of the card it was written against; null for a project.
event.kind string The kind of the event, for example finding, decision or question; a wish is wish.
event.body string The text.
event.created_at string The moment it was recorded, in RFC 3339 UTC.
event.principle string or null The principle a decision stands on.
event.asked_by string or null The project that asked for a wish with --from.
event.due string or null The day a question is due, as YYYY-MM-DD.

With --kind state it prints the state line instead.

Field Type Meaning
state object The state line that was added.
state.project string The name of the project.
state.day string The day it was written, as YYYY-MM-DD.
state.body string The line.

With --kind shipped it prints the release.

Field Type Meaning
project string The name of the project.
shipped object The release as recorded.
shipped.version string The version that went out.
shipped.delivery string tag-only, no-assets, released, publish-running, publish-failed or published.
shipped.registries array The registries the release reached.
shipped.registries[] string One registry name.
shipped.closed boolean Whether the version was closed by this call.
Section titled “Related”
  • context - where these events are read back.
  • mcp - the same recording, as an assistant’s tools.
  • resolve - closing a question or a wish.
  • why - reading a principle across the line.
  • link - tying two projects together.