Where you are in this project and what NOT to touch right now: the focus with its lineage, the parked nodes with the reason each was parked for, the decisions that still govern, and the last safe point with what you were about to do. Read it before anything else when a session opens.

Search the provenance tree. Returns every node whose title, reason, note or outcome contains all of the terms, best first, each with the lineage it hangs from. Ranking is not recency: a hit in the title outranks a hit in a note, a node holding up more tree outranks one holding up less, and recency is only the last tiebreak. Closed nodes are included: what you look for months later is usually finished.

Why a node exists: the chain from the goal down to it, what is open in parallel, what was born from it, and what blocks it from closing. This is the question the whole tool exists to answer. Open siblings and children are capped at eight each, every blocking one kept; full lists them all.

List what is still unfinished in this project: every open node with nothing open under it, the ones that block their parent first, then those holding up the most tree, then the newest. Each comes back as its alias, kind, state, title and the aliases above it; vivac_why on an alias brings the rest. Use it to answer what is left or what is waiting. For where this session stands, read vivac_brief; to look for something by its words, vivac_find.

What governs this project: every pillar, the rules under each pillar and those without one, and the invariants. A pillar's title names it and says what it rejects, in the project's own words. Each rule carries the commands that verify it, each with the folder it runs in, relative to the folder that holds .vivac, or none, which means it is judged. Run a command from its folder: from anywhere else it can pass without checking anything. Read it whenever you are asked to check work against the project's rules, whether or not they arrived when the session opened: vivac hands you the rules and the commands, and the judging is yours. If it comes back with no pillar and no rule while the project keeps its rules in files such as CLAUDE.md or AGENTS.md, propose which are pillars and which are rules, let the person decide, and write them with vivac_add.

Open a node and step into it: it becomes the focus, and everything captured next hangs from it until a matching pop. Call it the moment a new line of work starts or forks away from the current one -- a question that has to be settled before continuing, a detour worth its own trace -- never after the fact, once the reason for taking it has already faded. Look first with vivac_find: work the tree already holds goes under its node, never into a second one. The focus is wherever work was left, perhaps by another session and about something else, so name in parent the node this work continues, or pass root when it continues nothing. why is mandatory: a detour with no reason recorded is the failure this tree exists to catch.

Close the current focus and step back to its parent, recording what came of it. Call it once the work vivac_push opened is actually finished, not on a whim to clear the stack: a node with open closure conditions refuses to close on its own, because a run that closes with its findings still open is exactly the mistake that refusal exists to catch. It steps back to the parent: if the work also settles that node -- the finding it fixed, the question it answered -- pop again.

Close a node that is not the focus, recording what came of it. Call it right after writing a lesson or a measurement that asks nothing of anyone -- a record, whose outcome starts with Record: -- and for work that was finished somewhere else. It never closes over open closure conditions; that takes vivac done --force at a terminal, with a person looking. vivac_pop closes the focus.

File a node without touching the stack: the focus stays exactly where it was. Use it for something that belongs in the tree but is not the next thing about to happen -- a finding surfaced while working on something else, a sibling task filed for later, a piece of an existing structure being brought in. vivac_push is for what comes next; this is for what was just noticed. Look first with vivac_find: what the tree already holds is not filed twice. A finding is one node for each thing found that you tell the person, written when you tell them. One that asks nothing of anyone -- a lesson, a measurement -- is a record: close it right away with vivac_done, its outcome starting with Record:.

Record a decision, with the reason it was made and every alternative that lost. Call it the moment a choice is actually settled, not before and not long after: the alternatives are optional in the schema and not in practice, because without them the same option gets proposed again in a month by whoever was not in the room. When the project has pillars or rules, name in against the ones this was judged against, each with a sentence: a pillar judged in silence reads the same as one skipped.

Attach a fact to a node without changing its state or the stack: something worth keeping that is not itself a new node. Call it beside vivac_push and vivac_pop for anything that would otherwise only live in a chat transcript nobody rereads. When the fact deserves to be found on its own -- a finding, a measurement -- file it as a node with vivac_add instead.

Suspend a node without abandoning it: it drops off the stack and becomes something a later session is told not to touch. Call it when the person says not now, or when work is stuck on something outside this session -- never as a substitute for vivac_pop on something that is simply finished. What is put off has to be a node first: if it is not in the tree yet, file it with vivac_add and park that.

Record a safe stop: a label for this point and what was about to happen next. Each call adds a new stop and never replaces an earlier one, and it neither moves the focus nor closes anything. The latest stop is what vivac_brief shows as the last one, so a session that picks the thread back up -- this one later, or someone else's -- starts where this one left off instead of guessing from the log. Call it at a clean seam: before the session ends, before a long pause or a handoff, or when the person asks for a safe point. To set a node aside, vivac_park; to keep a fact on one, vivac_note.

Record a command that verifies a rule and the folder it runs in, or with off, remove one. vivac never runs it: it hands it to whoever checks the rule. Call it the moment a test for a rule exists, because the day a rule became checkable is part of its history.

Record, after the fact, the pillars or rules a decision was judged against, each with a sentence. Call it the moment the judging happens -- someone asks whether a decision holds against a rule, and it gets checked -- because when a decision was judged is part of its history, and this one shows as late. It only adds to a decision that already exists, and declaring the same rule again replaces its sentence. A new decision takes what it was judged against when it is recorded, through vivac_decide; vivac_rules lists the pillars and rules there are.