Notes
This page is generated from docs/guide.en.md · Edit this page on GitLab
The sticky notes and the notepad tab of everyday work, inside the tool — so anchored to what it tracks (merge requests, tickets) and inside the backup. Four sub-tabs: Today (the brief), Todos, Pages, Period (catching up on a window of dates). Nothing goes to the AI or to a forge without an explicit gesture: the brief, todos and pages live in the local database and spend no tokens at all; Period queries the forge and the clones, and spends AI only if you start a review.
Today — the morning brief
Sections ordered action-first: what calls for a gesture before what merely informs. Each is hidden when empty — a screen showing seven headings, six of them subtitled “nothing”, teaches you that nothing happened, which was not the question. Every line reaches its object in one click.
- Reminders — due dates that have passed and today's, with the “done” checkbox and the snooze buttons right there: that is the whole point of a brief, acting without changing screen.
- Today's todos — the high priorities with no date and the ones due today. High-without-a-date is there because “important but with no deadline” is exactly what gets lost: nothing ever surfaces it on its own. A todo already listed under Reminders does not appear twice.
- Sessions waiting for an answer — the sessions where the AI asked a question. They are the costliest to forget: the session is blocked, the queue is free, and nothing restarts without you. 4 bis. AI sessions waiting — three numbers, one and the same oversight: the work is done, only a gesture is missing. A session never run will produce nothing; a project committed but not pushed exists for nobody; a branch pushed without a merge request will never be reviewed. Numbers rather than lists — the detail lives in AI Dev, and three more lines would stop the brief being a brief. A branch that already has an open MR (even one created elsewhere) does not count: offering to open a second one would be worse than saying nothing.
- Failed verifications — the last red verdict per batch or per MR. Stale verdicts are left out: the branch has moved, the verdict covers code that is no longer there, and showing it would send you to fix a problem that may already be fixed. 4 ter. Remarks never sent — the inline comments written in the viewer and left there. This is the quietest loss of work in the tool: you write three remarks, close the window to check something else, and the merge request is merged without them. Oldest first — age is what worries, not the count — and the button reopens the viewer, where they are sent from. 4 quater. Follow-ups never sent — same family, another screen: a correction written while the session was running, then forgotten. The ones that leave on their own at the end (“automatically”) say so: they are waiting for nobody. 4 quinquies. Git left hanging — a merge half-resolved yesterday evening, and the failed Git operations of the last 24 hours (a protected branch someone tried to delete, a refused tag). A half-finished merge lives only in a working folder: no badge recalls it, and you find it three days later while looking for something else. Resume reopens the merge screen, See history opens the Git log filtered on the project and on failures only. 4 sexies. Containers down — what the background watch saw on its last round. A container is down when it is
restarting,dead, or exited in error: a requested stop (docker stop) is not a failure, and painting it red would sound the alarm every day. The section is dated — it is a reading, not a live state — and absent until Docker has been looked at, rather than announcing “0 containers down” without having looked at anything. - MRs to review — the ones that arrived since yesterday, not the whole queue (which has its own tab and its own badge).
- Dormant MRs — reviewed more than N days ago (adjustable, 5 by default) and still open: the work is done, the decision is missing. 6 bis. Overlapping MRs — one line per pair of open merge requests of the same repository that change the same files:
!214 ↔ !219 · groupe/tarification · 3 files · for 2 days, oldest pairs first. Click: Reviews filtered on the repository, both merge requests on top. The cross dismisses one pair, not a repository: a new pair reappears. 6 ter. MRs without tests — one line per open merge request carrying the emphasised badge:!214 — VAT refactor · groupe/tarification · 14 files · 0 tests · opened 2 days ago, oldest first. Click: the merge request in Reviews. The cross dismisses this merge request on this commit: a fetch on a new commit brings it back. 6 quater. MRs adding dependencies — one line per open merge request whose manifest gains a direct dependency:!214 — VAT refactor · groupe/tarification · +2 dependencies · 1 major · opened 2 days ago, oldest first, eight at most. Click and cross: as for the MRs without tests. - Activity since yesterday — one line, three numbers. Deliberately poor: it is context, not a task; the detail lives in Stats.
Searching inside a job's log. A verification run pours out two thousand lines: the field in the panel's toolbar hides those that do not contain what you are looking for, and the Errors box keeps only the red ones. Nothing is cut — the count says what is hidden, and unticking brings everything back. A double-click on a line that talks about a merge request opens its report.
Dismissing a line that comes back every morning. The brief recomputes everything each time it opens: a fact that stays true reappears indefinitely, even once handled elsewhere — a red verification you have already been through eventually teaches you to stop reading the section. A cross on hover dismisses the line: it leaves the brief and does not come back. Applies to verifications, waiting sessions and merge requests.
⚠ You dismiss a finding, not a subject. The cross remembers the object you saw — this verdict, that merge request: a new verification of the same set carries another identifier and will reappear. That is deliberate — otherwise a real regression would stay invisible forever. Nothing is deleted (the verdict keeps its page in Reviews), the brief shows at the bottom how many lines it is hiding, and Show them again brings them all back in one click. A dismissed line makes the next one move up: sections cap at eight, and a section that shrinks with every gesture would end up lying about what is left to do.
Everything is computed in SQL, with no AI and no network: the brief appears instantly, before the first coffee, and costs nothing. A summary written by an agent was tempting; it would have charged one call every morning to rephrase facts that already read fine.
Landing. On the first opening of the day, the app opens here rather than on the tab you left. Once per calendar day, never twice — otherwise every page reload would drag back to the brief someone who was reading a report. Switch it off in Settings → General.
Todos
A flat list, sorted by priority first, then in the order you give it. Two different questions, each keeping its answer: priority says what is pressing, your order says in which order you work through it. "To do" reorders with the mouse (grip on the left, drag and drop) or with the keyboard (two arrows per row — dragging is neither announceable nor reliable with a keyboard or a finger), and the order is saved: an order that does not survive a reload is not an order.
⚠ Reordering only happens inside a priority. Taking a todo into another group would bring it straight back, and a gesture that does not land is worse than no gesture: the arrows switch off at group boundaries, and dragging does not cross them. To change group you change the priority — a different gesture, and an explicit one. The due date no longer sorts anything here: it stays visible and keeps feeding the morning brief and the reminders. On the day of the update your list keeps exactly the order it had. The Done and Archived views keep their chronological order: you do not arrange your drawer.
- Inline add at the top of the list: you type, Enter, it exists — normal priority, no date. A new todo goes to the top, where you just typed it; looking for it at the bottom of a list of thirty would be absurd.
- Binary status: to do / done. No “in progress”: a workstation todo gets ticked, it is not steered.
- Priority high / normal / low. Normal shows no badge — flagging it would be noise.
- Due date = reminder: a single date, serving both. It is shown relatively (“tomorrow 9 am”, “in 3 days”), and in red only once it has passed: a due date ahead is not an alarm.
- Snooze in one click: +1 h or tomorrow 9 am. “Tomorrow 9 am” means 9 am on the clock, not “in 24 hours” — a daylight-saving change must not shift the appointment.
- Optional link to a merge request, a ticket or a repository: the line becomes clickable. A todo linked to a merge request shows that MR's state under its title (score, verdict, how long it has been open): you can tell whether it still has a reason to exist.
- A todo linked to a ticket says what it became: its Jira status, and the merge requests carrying its key. Nothing is asked of the network — the state comes from watching, or from what discovery filed away.
- A todo tied to a merge request ticks itself when that MR is merged, with a note saying what closed it — “Closed automatically: merge request !201 was merged or closed”. Nothing is deleted and it can be reopened; Settings → General carries the switch (“Tick linked todos when their merge request is merged”) for anyone who would rather close them by hand.
- Nothing is deleted. A finished todo stays struck through for seven days — you want to see what you did this week — then moves to Archived, where it stays readable. Reopening it takes it out of the drawer. A Delete button exists, but ticking “done” is the normal gesture.
- Three filters: To do · Done · Archived.
- The menu carries the count: red for what presses (overdue or high priority), blue for the rest to do.
Quick capture — the n key
From any tab, n opens a small dialog: one field, Enter creates the todo, Esc cancels. A “+ details” link unfolds priority, due date and note when that is useful. After creation, a discreet toast — and no navigation: you were in the middle of something else. If capture cost more than two seconds, you would go back to the sticky note. The key is ignored while the cursor is in an input.
Pages
Flat note pages: no folders, no hierarchy. On the left the list (pinned first, then most recently modified, each title in full, over several lines when needed, the date and the sub-page count below it) with a search covering the title AND the content — the word you are after is often in the body. On the right the editable title, then the editor and the Markdown preview side by side (the same renderer as the review reports, hence the same escaping).
- Autosave as you type, with a one-second delay and a discreet “Saved” indicator. Saving on every character would mean one request per letter; saving only on close would lose the work of a page left open.
- Pasting a screenshot (Ctrl+V) into the editor inserts it at the caret, on its own line, and the preview shows it right away. The image goes to disk (
data/notes/<page>/) and the page only keeps a link: putting the screenshot into the content as base64 would swell the row by several megabytes, resent in full on every autosave — that is, about every second while you write. - A
`mermaidblock becomes a diagram. What the librarian draws reads as a diagram, not as text. The rendering library lives in the repository (public/vendor/mermaid.min.js, never a CDN: nothing leaves the machine) and is loaded only on the first diagram met — a page holding none does not pay its five megabytes. The colours follow the theme, and switching themes redraws the diagrams, whose colours are baked into the SVG. A diagram that does not compile keeps its source on screen, with the error above it: a typo does not take the page down. - Pin keeps a page at the top of the list.
- Full screen. A button next to Rendered / Two columns / Markdown drops the page list and expands the editor to the whole window; the three view buttons stay, so the display can still be switched while reading. Escape, or the same button, returns to the two-column layout.
- Export downloads the page as
.md, under a name slugified from the title. ⚠ Screenshots are referenced by their address inside Mergerie: the.mdread elsewhere will show the text, not the images. - Delete asks for confirmation — it is the only irreversible action of the tab. The page's screenshots go with it, files included.
Autolink — !214 and PROJ-720 become links
What you write in a note are the identifiers of everyday work. They become clickable at render time (pages, todo notes); storage stays plain text — you re-read your notes elsewhere, and an exported .md must not carry HTML.
!214→ the merge request. One repository carries that number: direct link. Several: a link to Reviews with the search pre-filled, showing the candidates — we do not guess, and a wrong link is worse than a link that asks you to choose. None: the text stays text, no dead link. Resolved are the merge requests still open, plus those that moved in the last six months: past that, a closed MR is no longer a reference you write in a note, and re-reading the whole table on every visit to the tab would cost a lot for three references.PROJ-720→ the ticket, if Jira is configured.- A pasted URL becomes clickable (new tab).
http/httpsonly: a note is text you paste without re-reading it, and a link you build has no business being able to run anything —javascript:and the like stay text. Sentence-ending punctuation stays outside, and a reference inside a URL is not transformed again (pasting a Jira link does not build a second link inside the first). - Nothing is transformed inside a code block:
!42in a shell snippet is code. - The content is escaped first, the autolink applies afterwards and only injects tags it builds itself. No fragment of a note can become markup.
And the other way round: “1 note mentions it”. The link only existed on one side — the note led to the merge request, and the merge request had no idea three paragraphs had been written about it on Monday. A review report and a Jira ticket sheet now list the notes that cite them, with the excerpt taken around the citation (a page title almost never says what was said about that object). The rule for “citing” is the one used by the rendering, not a second search: a!=218 is a comparison, not a citation, and a list of incoming links that contains false ones is worth nothing.
“Add to the todos”, from an MR or a ticket
A button on the detail of a merge request and on that of a Jira ticket opens the quick capture pre-filled: proposed title (Follow !214 — <title>), link set, normal priority, no date — all of it still editable. If an open todo already follows that object, the button becomes “See the todo”: creating a silent duplicate would be the surest way to make the list useless within a week.
And from four other places. “Rebase this branch before Monday”, “this verifier has been red since Tuesday”, “this build breaks one time in three”, “this container goes down every night” are exactly what you jot down — and nothing carried them: the button existed only on a merge request and a ticket, so you wrote free text with no link back. The same button now sits on a branch row (explorer), a verification report, a Jenkins build row and a container row. The todo keeps what it needs to go back: the explorer opens on the branch's repository, the verification report reopens, so does the Jenkins job sheet.
Reminders
The channel is the existing desktop notifications, with its own “Reminders” category (on by default, Settings → Notifications).
- A due date reached gives one notification, once — and snoozing makes it ring again: without that, pushing back an already-notified reminder would silence it for good.
- The notification is marked as sent after it is displayed, not when the list is read: a notification that fails (permission denied, tab closed in between) must not consume the only chance to warn you.
- Catch-up at startup: if several reminders are overdue when the page loads, they give a single grouped notification (“3 reminders waiting”) — ten pop-ups at startup get dismissed unread.
- ⚠ A limit worth knowing: reminders are sent by the browser. The Mergerie tab therefore has to be open somewhere. A reminder that falls due while everything is closed is not lost — it goes out on the next load, in the catch-up.
- The snooze buttons live in the interface, not in the notification: notification actions would require a service worker, which is out of scope.
The notes, the todos and their history live in the database of the data folder: they are therefore covered by the backup (Settings → General), just like the review reports.
Period — catching up on what happened
“I am away for ten days. When I am back, what moved on the repositories?” While you are away the workstation is off: discovery did not run, and what was opened and merged in between shows up nowhere. Period therefore rebuilds a window of dates from the forge and the clone of each repository, not from what Mergerie saw. Two dates, Build, and a job queries everything; the screen fills in when it ends. The window also serves to re-read a sprint, prepare a retro or pick up a repository you did not follow — it is a period, not a leave.
The sections, in the order of the gestures to make:
- Direct pushes on watched branches — in red, at the top: commits that entered
main(or a protected branch) without a merge request. Nobody reviewed them; it is the most valuable information on the screen. Grouped by push (consecutive commits by the same author), labelled revert, manual merge or bot (bots are hidden by default). A commit that went through a merge request is never there, whatever the merge strategy — merge commit, squash, fast-forward, or GitHub's rebase-merge that rewrites SHAs (recognised by the patch content). What the forge could not confirm is marked unverified, in orange: a visible doubt beats a colleague wrongly accused. Gestures: See the diff (the full-screen explorer of ⛶ Open the code, the same as for a merge request or a session: the whole tree of the commit, the touched files marked, each file in full with its changes in place, and on the left the author and the push's list of commits), Review this push (a pre-filled exploration session: the AI reads the commits like a review), Verify this branch, Add to todos, Fix session. - Merged merge requests — each one says whether it was reviewed before the merge (by you, or by a colleague on the shared database) or never. Review after the fact reads the merge request as it was merged, by its SHAs: the base at the time of the MR and its head, fetched from the ref the forge keeps even once the branch is deleted — a three-dot diff would be empty once the head is in the target. The prompt tells the AI the MR is already merged and asks it to sort findings into fix now / watch / nothing to report; nothing is posted to the forge on its own. Review the N unreviewed starts the batch and announces the cost.
- Arrived, still open — they are in the Reviews queue; here they are only flagged.
- Closed without merge, known before and active during (collapsed: a label change is enough to touch an MR), tags, deleted branches and pipelines — a red pipeline on a watched branch at the date of your return opens the section by itself.
- Done by the team in Mergerie — with a shared data repository: the reviews, sessions, todos and pages written by someone else during the window, and what the sync brought in since the start of the window, whatever date the colleague wrote (marked arrived through the sync: that signal depends on no clock but yours). An MR merged and reviewed by a colleague appears once, under “merged”, with the mention. In Reviews, a new for you badge marks the cards whose report arrived through the sync and was never opened here — useful every day, not only when you are back.
- Jira (when configured) — the tickets that changed status or were assigned to you during the window: yours, the watched ones, those of the period's merge requests. A Jira that fails makes the section partial, never the period.
- Meanwhile, Mergerie did… — if the workstation stayed on: the scheduled agents' passes (one line per agent, with its failures) and the verifications started in the window, the report one click away.
On GitLab, direct pushes are grouped exactly as the forge saw them (its push events); GitHub does not expose them, so the heuristic (same author, less than thirty minutes) stays there. Review the N unreviewed orders the batch by decreasing risk (sensitive files, then size), bots excluded.
Summarise the period (≈ 1 AI call) — the option, never the default: ten lines per repository on what changes for someone coming back, citing the !iid, rendered at the top like an agent report and labelled written by an AI, not to be trusted blindly. Useful beyond thirty merge requests; below that, the list reads faster.
Each line carries seen: the screen is a list to empty. The state survives a reload and Rebuild; the sub-tab counter is the number of unseen lines. A repository whose forge was down, or where a cap was hit, is partial and says so on its section — never exhaustive in appearance only.
Along the way the database is repaired: merge requests merged during the absence are written with their dates and SHAs, the session that had opened the branch is linked (“Create the MR” does not reappear on a branch already merged), linked todos are ticked, and the brief's journal is dated at the merge, not at your return.
The brief's banner. When this workstation has not seen a gesture (keyboard, mouse) for more than N days (Settings → General, 3 by default — a weekend is not an absence), Today opens on “You have not opened Mergerie for 12 days — see what happened”: one click builds the period of the absence. Presence is measured on a real gesture, not on a tab left open: an office desktop left on for the whole leave is not “present”. And the first gesture of your return does not drop the banner: the absence is frozen at the moment it ends, until the period is opened or the banner is dismissed with its cross. I am leaving, in the Period bar, sets the start of the absence to the minute: a quick stop at the office no longer moves it, and the window offered on your return is exact; Cancel forgets it.
Settings. General: the banner threshold, hide bots, watch protected branches on top of the default branch (a team decision: it is the definition of “entered without review”). Repositories: a list of watched branches specific to a repository, in its edit row.