Help and FAQ.

Bringing text in.

Paste text into Import Text, or drop a file on it, and blk/txt splits it into dated blocks. A date on its own line, such as 21/03/2024 or 2024-03-21, dates everything after it until the next date line, and a blank line separates one block from the next. Text written before the first date line is left out by default, with a warning naming how many lines were skipped; check Treat everything as one block dated today to keep it instead, dated the day you import it. New, in the top bar, adds a single block by hand. If you have nothing to import yet, load a sample corpus from the empty dashboard: six months of example blocks with their own entity types and metrics already set up.

Blocks and entities.

Every parsed piece of text is a block. An entity pattern is a rule that finds one kind of value, such as a ticket number or a hostname, in a block's text and links every block where that value appears; blk/txt ships with ticket, URL, and environment patterns, plus #tag and @mention out of the box. Add your own under Entity patterns, either by writing a pattern or by pointing at examples and letting one get built for you. Changing a pattern reprocesses every block already imported, not only the ones you add afterward; there is a Reprocess all blocks button on the same page for running it again on demand. Locked blocks are the one exception, because their text is encrypted and there is nothing to read a pattern against.

You can teach a counterexample, such as "this is not a ticket", and limit a type to certain sources. A preview shows what a change would match across your whole history before you save it, and every example you have taught stays as a test a later change must pass. From this same page you can download the types, aliases, metrics, and examples you taught as a file with no note content, and import someone else's only after a preview. A note that only says the thing broke again, with no ticket or host in the sentence, has nothing for a later search to retrieve.

Search.

The search box on the dashboard runs against the full-text index built from every block you have imported. Wrap words in quotes for an exact phrase, and put a minus sign in front of a word to leave out any block that contains it. Search is stemmed, so searching "provisioning" also finds blocks that say "provisioned". Narrow further with the date and block-kind filters next to it.

The five questions, and where each lives.

An entity's dossier page answers most of what you would ask about it: how often it comes up is the rate chart at the top, next to how many days you have written about it, and what it comes up alongside is Related further down the page. Since when is first seen, next to last seen. Which way it is moving lives on Metrics, and in the same-day metrics shown on the dossier itself. What has gone quiet, subjects that used to show up and have stopped, lives on Quiet. Recap gives a shorter version of all five for the last 7 or 30 days, without opening any one dossier.

Letter, under More, reads a window of those answers back in the app without being asked, and saved copies stay in an archive. On a metric's page, the latest recorded value keeps every change. A phrase such as try, deployed, or reverted suggests a label, which stays a suggestion until you confirm it, and the label only knows the phrases you teach under Cue phrases.

Days with nothing written.

Quiet lists subjects that used to come up and have stopped. Beside each one, Since then says how many of the quiet days had no writing at all, so a gap in a subject is told apart from a gap in your notebook. A subject opened as a block gets the same split: runs of days with nothing written are marked apart from days you wrote about something else.

Only blocks you wrote count as writing. Agent notes and log sources do not fill a day, and a locked block still counts for its date. A day with no writing says nothing about the subject either way. A subject block lists its first 60 gaps while its totals count every one.

Patterns in your writing.

On Entity patterns, Look for patterns reads your notes for lines that keep starting with the same words and a colon, such as root cause:, in at least 5 different blocks. Each one shows blocks that use it and blocks that say the same words another way, so you can judge before you press Add as a pattern. Preview shows what it would match first.

Nothing is added on its own, and no note ever has to carry the line. The scan runs only when you ask. It reads at most your 5,000 most recent unlocked blocks, skips agent notes and logs, checks at most 20 candidates, and leaves out one whose words often turn up without the colon or whose lines are often empty. Dismiss a candidate and it does not come back.

Instruments.

Write a small statement inside double curly braces in any block's text, and it becomes a live number wherever that block is shown. {{ count ticket:INC-9 }} counts every mention of that ticket. Add in 30d to bound it to the last 30 days (7d, 90d and 365d also work), or in 2026-01-01..2026-03-31 for an exact range; leave it out and every mention counts. {{ first ticket:INC-9 }} and {{ last ticket:INC-9 }} give the date of the first or the most recent mention. {{ quiet ticket:INC-9 }} gives the number of days since the last mention, and how many of those days had no writing recorded at all. {{ latest weight }} gives a metric's latest recorded reading, with its date. Put a value in quotes if it contains spaces, such as concept:"checkout latency". {{ timeline ticket:INC-9 }} shows the ticket as a block that opens into the days it came up, with days you wrote nothing marked apart from days you wrote about something else. It takes a window the same way count does. {{ open ticket:* }} lists every ticket with an open loose end, and {{ open ticket:INC-9 }} asks about one. Open only knows the cue phrases you teach, so a fix you described in other words still reads as open. It follows the same rule as Loose ends, so a block needs a subject, such as a #tag, a ticket or a host, as well as a cue. {{ rows #release show version, shipped }} builds a table from records you already keep: one row for every block tagged #release, newest first, with a column for each line you start with version: or shipped:. Pick the blocks with a tag, a subject such as ticket:INC-9, every subject of a type such as ticket:*, a relation line such as reverses:*, led to:* or addresses:INC-9, or has:root cause for every block with a root cause: line. A cell shows the first such line in the block, and says not written when the block has none. Each row opens its block, and the count opens exactly the blocks in the table. It takes a window the same way count does, lists at most 50 blocks, and says "at least" when there are more. A locked block shows only its date. Every value links to the exact blocks, or reading, behind it, the same way a count on Recap or Quiet does. A statement that does not match one of these eight forms is left as plain text. The same forms cover a counted ticket, a host you track, and a metric, for example {{ count ticket:INC-9021 in 30d }}, {{ last host:vpn.internal.example }}, and {{ latest p95 }}. p95 has to be a metric you defined. A block shows at most 20 live statements, and further brace text is left as written. The block editor's insert menu writes the syntax for you, and Instruments, under More, lists every block that carries one.

The letter.

Letter, under More, reads your notes back in the app without being asked. It names which subjects went quiet, which subjects appeared for the first time, which numbers moved, which loose ends opened, and which subjects carried from the week before. Every number opens onto the exact blocks behind it. Save this letter keeps a copy in an archive, newest period first.

Subjects listed together share a window. The letter never says one thing caused another. A loose end shows up here only when a phrase you teach, such as workaround or TODO, is in the opening note and no later note closes it with a phrase such as done or resolved.

Blocks that open, and notes from agents.

A week is a block that opens into its days, and a day opens into its notes. A ticket such as INC-9021 is a block that opens into the days it was worked on, and every count opens onto its blocks. A note without a time of day sits under "any time" rather than being placed by a guess.

Agents on different machines post what they did under their own revocable tokens, and blk/txt groups those notes per agent and per day. It lists what two agents both worked on during one day, and the app shows a daily or weekly digest of those notes. An agent can ask blk/txt what is open before it starts. blk/txt never writes a summary itself: a summary an agent writes is shown under that agent's name and never counted.

Loose ends, logs, and files.

Loose ends lists a workaround, a temporary note, a TODO, or a note that says waiting on, when no later note has closed it. The note also has to name a subject, such as a #tag, a ticket or a host, and it is listed under that subject with its opening words beside it. Loose ends only know the phrases you edit under Cue phrases, so a fix you described in other words stays on the list. The page itself says how many recent blocks it reads and how many items it shows.

Sources can hold a web server access log (Apache or nginx), syslog, or JSON lines beside your notes. blk/txt rolls them up by the hour into counts and the same entities, and each hour opens onto its raw lines. Raw lines are kept for 30 days by default, and they are not stored as individual notes past that window. A source that stops sending shows as no lines received since a date.

You can pick blocks and download one self-contained file, an Evidence pack, that anyone can open offline. It carries the interpretation those blocks need, and each instrument's value is frozen when you build it.

Threads and version history.

On a block's own page, thread view groups it with the blocks that carry the same story forward, so an update spread across several dated blocks reads as one thread instead of separate blocks. Version history keeps every earlier state of the block's text underneath it, so an edit does not erase what the block used to say.

Locking a block.

Locking a block encrypts its text, the earlier wordings in its history and its place with a key derived from your account password; nobody, including the person running the server, can read them without the password. Locking also removes the data your words left behind elsewhere, such as extracted entities, so a locked block cannot be reconstructed from its own metadata. Three things are not covered, and they are worth knowing before you rely on this: backups taken before you locked the block are not encrypted and keep its earlier text for up to 30 days, a block you split off another leaves that other block's history as readable as that block is, and an earlier wording that an unlocked block also once held word for word stays readable in that block's history. There is no recovery path: if you forget your password and it has to be reset, every block you ever locked becomes unreadable for good.

Export.

Export your blocks as JSON, CSV, or Markdown at any time, from Export Blocks. Locked blocks stay redacted in the export unless your vault is unlocked when you run it.

The Markdown export also writes each manual link as a line such as see: 2026-07-19 3f9a1c2b7d4e inside the linking block, and ends with one comment holding the state labels you confirmed and the loose ends you dismissed, keyed by date and a code made from the block's text, never by a row number. Importing the file re-attaches them only to blocks that import added, and reports the rest as unmatched. A locked block carries none while your vault is closed.

Account and API tokens.

API Tokens, under your account menu, are what other tools use to authenticate with blk/txt's API on your behalf, such as a script that pulls your blocks into another system. Generate one from that page, copy it once (it is not shown again), and revoke it whenever you no longer need it.