remanso/CONTEXT.md

Remanso

Remanso displays markdown Notes from GitHub repositories with Zettelkasten-style backlinks, and publishes/reads decentralized public notes over ATProto. This glossary is the shared vocabulary for the domain — it must appear verbatim in code, tests, commits, and docs.

Naming convention: Themed river/Amazonian names (after Remanso, a still backwater) are used for user-facing surfaces and places (e.g. Igarapé). Core technical concepts keep their standard Zettelkasten/Obsidian names (Note, Backlink, Path, Card, Draft, Fleeting) for discoverability.

Language

Core note model

Note: A single markdown document in a repository, identified by its Path. Editing a Note does not change its identity. Avoid: "file" when you mean the semantic document.

Path: A Note's stable identity — its location within the repo (e.g. ideas/zettel.md). What authors link to and what survives edits.

SHA: The git blob hash of a Note's content — a content version, not the Note's identity. Changes on every edit. Legitimately used as the address of a Snapshot reference (an immutable shared version). Avoid: treating SHA as the Note's identity (identity is Path); but SHA is the right address for an immutable snapshot.

File / RepoFile: The repo artifact carrying a Note's metadata (path, sha, size, …) as returned by the GitHub API. A File is how a Note appears in a repo listing, not a separate domain entity.

Note kinds

A Note's kind is inferred from its folder, not stored as a field.

Fleeting Note: A transient, quick-capture Note you later distill into a permanent one (Zettelkasten sense). Stored under the inbox / _inbox folder. Avoid: "Inbox Note" for the concept — inbox is only the storage folder convention; the domain term is Fleeting Note.

Draft Note: A work-in-progress Note, stored under the drafts / _drafts folder.

Task: An actionable item in todo.txt (todo.txt format); may recur. Completing a Task archives it to done.txt, and for a recurring Task schedules the next occurrence. A Task is not a Note. Avoid: "Todo Note" — Tasks live in a single todo.txt file, not as Notes.

Reading & navigation

Igarapé: The primary reading surface — the channel you travel as you read a Note and follow its backlinks (Amazonian/Tupi: a narrow navigable waterway through the forest). Any kind of Note appears in the Igarapé. Named to extend the river metaphor set by Remanso (a still backwater). Avoid: "Flux" (dropped — internal jargon, no domain meaning).

Index: A flat listing of every Note in a repo (path, sha, size). A catalogue view, unrelated to time or edits. Avoid: "History" / "Historic Notes" for this — it is an index, not a chronological record.

History: The chronological log of repos the user has recently visited (powers the "last visited" navigation). Avoid: using "history" for the Note Index, or for edit/version tracking (no such feature exists; there is no "edit history").

Backlink: An inbound reference to a Note — another Note that links to it. The Zettelkasten/Obsidian standard term (kept plain per the naming convention).

Stacked Notes: The navigation pattern in the Igarapé where following a Backlink opens the target Note alongside the current one, accumulating a horizontal stack you can read across.

Live reference: A reference to a Note by Path that resolves to its current content (e.g. a Backlink you follow in your own repo). Reflects edits.

Snapshot reference: A reference to a Note by SHA that resolves to that exact, immutable version (e.g. a shared/bookmarked stack link). Content-addressed; deliberately unaffected by later edits, so what was shared cannot change underneath a reader. Not a fragility — an integrity feature.

Spaced repetition

Card: A flashcard reviewed via spaced repetition — its content (front, back, references) and its review schedule together form one Card. Content lives in _cards/ markdown; the schedule lives in the local DB (an implementation split, not two domain concepts). Avoid: using "Card" to mean only the content, or only the schedule. The pair (Repetition in code) is the Card.

Level: A Card's mastery level (1–8); higher levels space reviews further apart.

Need-review: A Card the user has manually flagged to resurface for review, independent of its scheduled date.

Decentralized publishing (ATProto)

Published Note: A Note published to the decentralized ATProto network as a space.remanso.note record, addressed by DID + rkey (not by Path). A distinct entity created by publishing a Note; carries its own snapshot (title, images, content, theme, language). Avoid: "Public Note" — reserve "public" for a Note in a public GitHub repo (see below).

Publish: The act of making a Note public as a Published Note, via a single low-friction gesture — suffixing the file *.pub.md in the IDE — rather than an in-app form. "Lower every wall to make your voice public."

DID: The decentralized identifier of a Published Note's Author (e.g. did:plc:…). Standard ATProto term.

rkey: The record key identifying one Published Note within an Author's PDS repo. Standard ATProto term.

Author: The publisher of a Published Note — a handle plus a PDS, resolved from a DID.

PDS: Personal Data Server — where an Author's ATProto records (and image blobs) are hosted.

Relationships

• A Note is identified by exactly one Path.
• A Note has one current SHA, which changes on every edit.
• A File is the repo-listing view of a Note (it carries the Note's Path and current SHA).
• A Note can be published as a Published Note, which is then addressed by DID + rkey instead of Path.
• A Published Note has exactly one Author; an Author is identified by a DID and hosted on a PDS.
• Following a Backlink in the Igarapé produces Stacked Notes.

Example dialogue

Dev: "When I follow a Backlink in the Igarapé, do I navigate by Path or SHA?" Maintainer: "The identity is the Path — that's what the link author wrote. The SHA is just the current content version; we happen to use it as a runtime handle, but if it ever disagrees with the Path, the Path wins."

Dev: "And if I publish this Note?" Maintainer: "It becomes a Published Note — a separate ATProto record addressed by DID + rkey, not by Path. The repo Note stays as it is."

Flagged ambiguities

• Identity = Path; two reference modes (refined 2026-06-28) — see ADR-0001. A Note's identity is its Path, so Live references (Backlinks in your repo) must resolve to current content. But a Snapshot reference (a shared ?stackedNotes=sha link) deliberately pins a SHA for immutability — that is an integrity feature, not a fragility. The earlier framing of "SHA-as-handle = fragility" was too absolute; ADR-0001 is to be amended to record both modes.
• useNotes() / useFolderNotes() are named "notes" but return RepoFile[]. Per this glossary they return Files (the repo-listing view), not Note objects — a naming drift to reconcile in code.
• FluxNote / FluxNoteView should be renamed to Igarapé (Igarape / IgarapeView) in code — "Flux" is dropped jargon.
• HistoricNotes view (route /history) is the Index, not history — rename to NoteIndex and move off the /history path.
• CLAUDE.md describes modules/history/ as "Edit history tracking" — incorrect; it is the visited-repos History. Correct the doc; there is no edit-history feature.
• Card cluster: Repetition (the content+schedule pair) is the Card — rename Repetition → Card. The content-only struct and RepetitionCard (schedule) become named sub-parts (e.g. CardContent, ReviewSchedule). The hook already calls the pairs cards — make the types agree.
• ATProto cluster: rename PublicNote / PublicNoteRecord / PublicNoteListItem → PublishedNote*, and move PublicNoteListItem out of Note.ts into the atproto module (it is not a repo-Note concept).
• "Public" is overloaded: a Note in a public GitHub repo (auth-free access) vs the ATProto entity (now Published Note). Resolved — "public" refers only to repo visibility.