# The .rebasely folder One folder at the root of a repository holds what people and agents need besides the code: a knowledge base, a map of the system and the workflows that build it. Rebasely shows the first two on the repository's Concepts tab and serves them to agents over MCP. ## Layout Everything is plain files, reviewed and versioned with the code they describe. All three parts are optional; add the one you need first. ``` .rebasely/ knowledge/ index.md where to start: links to every note concepts/storage.md how a part of the system works decisions/0001-r2-for-blobs.md numbered, append-only decisions guides/local-dev.md how to do something architecture/ system.yaml components, the code they own, what they talk to views/write-path.yaml a subset of the components flows/upload.yaml a dataflow: the ordered steps of one request workflows/ ci.yml Rebasely Actions ``` ## A .duragit folder Rebasely used to be called duragit, and the folder was `.duragit/`. Repositories that still have one keep working. For each of `architecture` and `workflows`, Rebasely uses `.rebasely/` when it exists, and `.duragit/` otherwise. The knowledge base was called `kb/` until October 2026, so Rebasely reads the first of `.rebasely/knowledge`, `.rebasely/kb` and `.duragit/kb` that exists. The folders are never merged: once `.rebasely/knowledge/` exists, nothing in the older ones is read. The same rule holds for the Concepts tab, for agents over MCP, for Actions, and for `rebasely kb check` and `rebasely arch check`. To move a repository over, rename the folders and push: `git mv .duragit .rebasely`, then `git mv .rebasely/kb .rebasely/knowledge`. A pull request that does only that shows the knowledge base as moved, with no note changed. ## Knowledge base Markdown notes in `.rebasely/knowledge/`, in folders you make, up to four levels deep, the way you organize code. A common start: `concepts/` explain how something works, `decisions/` record why it is that way, `guides/` say how to do something. `index.md` is the start of the notes on the Concepts tab, and a folder's own `index.md` or `README.md` shows under its list of files. Each note starts with YAML frontmatter and a `# Title`, and links to other notes by id with `[[id]]`: ```markdown --- id: storage type: concept owner: ada component: api describes: - src/api/storage/** reviewed: 2026-10-01 --- # Storage Uploads stream to R2 as they arrive; see [[0001-r2-for-blobs]] for why, and [[local-dev]] to run it on your machine. ``` - `id` is the file name without `.md`, in kebab-case; `type` is `concept`, `decision` or `guide`; `owner` is who keeps it current; `reviewed` is the date someone last checked it against the code. - A concept says which code it `describes` (path patterns) and may name its `component` in `system.yaml`. The Concepts tab links both. - Decisions are numbered (`NNNN-name.md`) and append-only: once accepted, a decision is not rewritten. A later one replaces it, and the old one gets `status: superseded` and `superseded-by: `. The Concepts tab shows each decision's number and status, and which decision replaced it. ```markdown --- id: 0002-signed-download-links type: decision owner: ada status: accepted --- # 0002 Signed download links Private files are served through links signed for one reader... ``` The Concepts tab shows the notes as they are in the repository: the folder tree beside each folder or note, at an address that mirrors the path (`.rebasely/knowledge/decisions/0002-signed-download-links.md` is `///concepts/decisions/0002-signed-download-links`), with breadcrumbs and View source on every page. It resolves every `[[id]]` to its note (a link to a note that does not exist is marked missing), shows which notes link to each one, and searches titles and text. Markdown renders as in a README: no raw HTML, and relative links go to the repository's files. ## Architecture `.rebasely/architecture/system.yaml` lists the components of the system: what `kind` each is (`worker`, `durable-object`, `r2-bucket`, `d1`, `kv`, `queue`, `container`, `library` or `external`), the code it `owns` (path patterns; every file has at most one owner), its `binding` in the Worker's wrangler config, and what it `talks_to`, with the kind of each connection: ```yaml components: api: kind: worker description: The HTTP API and the upload path. owns: [src/api/**] talks_to: - { to: repo-do, via: rpc } - { to: blobs, via: r2 } repo-do: kind: durable-object description: One per repository; owns its refs. binding: REPO owns: [src/repo/**] blobs: kind: r2-bucket binding: BLOBS ``` A view in `views/.yaml` is a subset worth looking at on its own: ```yaml description: What an upload touches. components: [api, blobs] ``` A dataflow in `flows/.yaml` is one thing the system does, step by step: a `title`, a `description`, and `steps` in order, each going `from` one participant `to` another with a short `label`. A participant is a component of `system.yaml` or one of the flow's `actors`, the people and programs outside the system (a browser, a git client). Quote a label that has a comma in it. ```yaml title: An upload description: A file goes to R2 and the repository records it. actors: [browser] steps: - { from: browser, to: api, label: PUT /files/:name } - { from: api, to: repo-do, label: reserve the name } - { from: api, to: blobs, label: stream the bytes } - { from: api, to: repo-do, label: "commit the file, then answer" } ``` A flow has at most 60 steps and 10 actors, a label at most 80 characters and a title at most 100; a repository has at most 50 flows, each file at most 256 KiB. When a pull request changes a flow, its Files changed page shows the flow under [Visual](https://rebasely.com/docs/pull-requests#visual) as numbered steps between the participants, with the steps it adds, removes, reroutes (the same label between other participants), relabels and moves. When a pull request changes any of these files, its Files changed page can show the change as a picture: the [Visual](https://rebasely.com/docs/pull-requests#visual) view. *Diagram: Files changed has a Code and Visual switch. Visual draws the system as the pull request leaves it: the billing Worker it adds and its connections are marked added, the objects bucket it changes is marked changed, and the legacy-db database it removes stays in place, dashed and struck through, with its connection.* *Visual marks what a pull request adds, changes and removes in the architecture.* The Concepts tab opens with the architecture: it draws the components and their connections, with a switcher for the views, and lists each component with its description, owned paths (linked to the files), binding and connections. Select a component to see what it talks to and what uses it. If paths a component owns are gone from the branch, the page says the map may be out of date. ## Workflows `.rebasely/workflows/*.yml` are Rebasely Actions workflows: push them and their jobs run on Cloudflare Sandboxes. The repository's Actions tab lists the runs and has a starter workflow to copy. ## Keeping it honest Notes and maps go stale when nothing checks them. The [Rebasely CLI](https://rebasely.com/docs/start#git) does, in the repository's working tree: - `rebasely kb check` checks every note's frontmatter, that each `[[id]]` names a note, that a superseded decision names a decision that exists, and that each `component` is in `system.yaml`. It marks a concept stale when code it `describes` changed in commits after the note was last edited, until someone edits the note or moves `reviewed` past those commits. `rebasely kb list` shows each note's state. - `rebasely arch check` checks `system.yaml` against the code: every owned pattern matches files, no file has two owners, each binding exists in the wrangler config with the right kind, and every connection it finds in the code (imports, `env.BINDING` reads, service bindings) is declared in `talks_to`, and the other way round. It checks that every view and flow names only components of `system.yaml` (or, in a flow, its own actors), that every step has a label and goes between two different participants, and that flows stay within the limits above. Both exit 1 when something is wrong, so they fit in a workflow (staleness needs the history, so check out more than the last commit): ```yaml - run: curl -fsSL https://rebasely.com/cli/rebasely.mjs -o /tmp/rebasely.mjs - run: node /tmp/rebasely.mjs kb check - run: node /tmp/rebasely.mjs arch check ``` ## Agents Agents read the same context through the [MCP server](https://rebasely.com/docs/mcp): `kb.list` lists the notes, `kb.read` returns one with its links resolved and the notes that link to it, `kb.search` searches them, and `arch.get` returns the components and connections, of one view or around one component. They answer only what the token may read; a private repository the token cannot reach gets the same answer as one that does not exist. The [Rebasely agent skill](https://rebasely.com/docs/skills/rebasely/SKILL.md) tells coding agents to read the knowledge base and the architecture before they change anything, and to update the notes, add a decision and fix `system.yaml` in the same change when they change behavior. --- Source: https://rebasely.com/docs/dot-rebasely