gitroll 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to GitRoll are documented here. GitRoll follows [semantic versioning](https://semver.org). The Roll file format has its own version, documented in [SPEC.md](SPEC.md).
 
+## 0.3.0 (2026-09-16)
+
+- **Search says what it looks at.** Somebody will eventually search for a word that is inside a receipt and expect a match, so the terminal app, the browser app, `gitroll help more` and the README now say the same thing: search reads what you wrote — an event's words, title, topics, tags, amount, front matter and the names of its attached files — and not what is inside those files, not other Rolls (unless `find --all`), not deleted events and not older versions. A search that finds nothing says it there and then.
+
+### Changed
+- **The format is much simpler, and this is a breaking change.** An event is now an ordinary Markdown file under `.gitroll/events/`, named for its date and what happened (`2026-09-15-ac-serviced.md`). Front matter is optional: a heading and a paragraph is a complete event. Gone are year/month folders, UUID file names, required `version`, `id`, `created`, `author` and `occurred` fields, hash-named attachments and attachment manifests, project definition files, and custom event types. Files kept with an event are ordinary files in `.gitroll/files/`, linked with ordinary relative Markdown links. GitRoll launched today with no users, so nothing is migrated.
+- **Everything GitRoll owns lives in `.gitroll/`** at the root of a Git repository. A log can be a repository of its own or sit beside a project you already have: adding one creates `.gitroll/` and nothing else, leaves your README and branch alone, and commits only the files GitRoll wrote. `.gitroll/` is a namespace, not a privacy boundary — a log in a public repository is public.
+- **An event's identity is its path**, so `git mv` is a rename and Git history follows it. `gitroll move` renames an event and rewrites its links. Authors come from Git history instead of a field in the file.
+- **Dates come from the file name** unless the front matter says otherwise, and an event with neither is shown as undated rather than rejected. Date filters compare calendar days as written, so an event stays on its author's day everywhere.
+- **Projects and tags need no setup.** Naming one on an event is all there is to it.
+- **`.gitroll/config.yaml` records `template_version`.** GitRoll reads it, never changes it while logging or editing, refuses to write to a repository whose template is newer than the app, and reports a missing marker as an unknown version instead of assuming it is current (`gitroll template --set 1` records one).
+- **Editing preserves what you wrote:** comments, key order and unknown front matter keys survive a save, and the body is left untouched unless the text itself changed.
+
+### Added
+- **Imports from GitHub and CI.** `gitroll import github` logs merged pull requests and releases, `gitroll import ci` logs builds that failed (`--status all` for the rest), for this Roll's own repository or one you name. Filter with `--since`, `--until`, `--branch`, `--author`, `--label`, `--status` and `--limit`, and see what would happen with `--dry-run`. GitHub is asked through the GitHub CLI if it's signed in, then `GITHUB_TOKEN`, then not at all; no token is ever stored. JSON piped in from `gh api` or a webhook works too. Nothing is logged twice — `source: { adapter, id }` is the thing's own identity, a repeated import starts where the last one left off and says so, and an event you edited after importing stays as you left it. See [docs/IMPORT.md](docs/IMPORT.md).
+- **Ask your Roll is a normal feature**, not an experiment behind an environment variable. `gitroll ai` lists where a model can run (on your computer first, so nothing leaves it), `gitroll ai test` says which thing is wrong when it doesn't work, and `gitroll ai on`/`off` switches it without forgetting the settings. The app has the same thing behind ✨ in the header, and tests what you typed before it saves. Keys are read from environment variables and never stored; a Roll's `ai: false` still turns Ask off for everyone. Answers cite events and link to them, and an answer can be turned into a draft event — which stays a draft until you save it. `gitroll summary` drafts an update from a date range the same way.
+- **The Roll's branch is visible**: in the browser header, the terminal header and `gitroll status` (including `--json`, which also carries the head commit, the repository and why syncing is blocked). A detached HEAD and a repository with no commits are named rather than guessed at, and syncing on a detached HEAD stops and says what to do.
+- **Code references.** `#412`, `owner/repo#412`, a commit SHA and GitHub URLs in an event's text become links when the event says which repository it is about. `gitroll log --code` records the repository, branch and commit you're on, as `source: { repo, branch, commit }`.
+- **`gitroll log --editor`** (and `gitroll edit --editor`), using `$VISUAL` or `$EDITOR`, and **`gitroll completion bash|zsh|fish`** for commands, Rolls, templates, tags, projects and saved searches.
+- **Templates** for the kinds of event developers write often — debugging, incident, deployment, experiment and architecture decision — in `gitroll log --template`, `gitroll templates`, and the app's composer.
+- **`gitroll restore`**, and *Put this version back* in History: an earlier version returns as a new commit, so nothing is ever rewritten.
+- **`gitroll conflicts` and `gitroll resolve`**, and a Conflicts screen in the app: an event changed in two places, side by side, settled by keeping one version or writing one out of both. Both stay in history.
+- **Related events and backlinks** from ordinary Markdown links between events (`gitroll related`, and on every event in the app).
+- **Saved searches** (`gitroll find … --save <name>`, then `find @name`, `gitroll searches`) and **`gitroll find --all`** across every Roll on this computer.
+- **A workspace in the terminal.** `gitroll` now opens a persistent prompt with your recent entries above it. Type what happened and press Enter to log it; press `/` for a searchable command menu (`/log`, `/find`, `/topics`, `/roll`, `/sync`, `/status`, `/undo`, `/web`, `/help`) with descriptions and autocomplete.
+- **A complete composer** (Ctrl+O or `/log`): text over several lines, date, amount, tags, topics and files, with topic and tag autocomplete, dragged or pasted file paths, and `Ctrl+E` to write in your own editor. Entries can be edited or duplicated from the composer too.
+- **Unsaved drafts are kept.** Leaving the composer, switching Rolls or quitting keeps what you wrote, and GitRoll offers it again next time. Drafts live with your settings, never inside a Roll.
+- **Interactive search** (`/find`): results as you type, arrow-key selection, a preview beside the list in a wide terminal, and edit, duplicate, delete or write a new entry without leaving it. Your query and selection are still there when you come back.
+- **Undo deletion** with Ctrl+Z (or `/undo`), and the header now says which Roll you're in, where it lives, and whether it's saved only on this computer or backed up.
+- **The Roll you switch to is remembered**, so it opens next time.
+- **The workspace always says where it's writing:** the Roll, the branch and the folder, in the header. Saving names the file it wrote, and switching Rolls says which folder you landed in.
+- **Saved, committed and backed up are three different things**, and the header keeps them apart: files changed in the folder but not committed are counted separately from changes committed here but not yet at your backup.
+- **Git states that stop a sync explain themselves.** A detached HEAD, an unfinished merge or an unfinished rebase each say what still works (logging always does) and the command that clears it, instead of a branch name GitRoll guessed at. `gitroll status` reports the same.
+- **Files GitRoll can't read are named, not dropped.** An entry whose front matter can't be parsed — a date typed by hand, say — used to disappear from the terminal app with no explanation. The workspace now says how many there are, and `/problems` lists each one with the part to fix and opens it in your editor. GitRoll never rewrites them: the writing stays exactly where its author left it.
+- **The workspace picks up changes made anywhere else.** Editing a file in your editor, or logging from another window, updates the timeline by itself — never while you're in the middle of writing something.
+- **An entry edited in your editor is never silently overwritten.** If the file changed on disk while the composer was open on it, saving stops and asks, instead of replacing their version with yours.
+
+- **Deleted events have somewhere to go.** `/deleted` lists what has been deleted from this Roll, read back out of Git history, and puts any of it back with the text exactly as it was written. Restoring is a new change, so the history shows both the deletion and the recovery — nothing is rewritten.
+- **An event's files can be opened from the terminal** with `o` (`Tab` picks another), in whatever application normally opens them. A file an event links to that isn't in the Roll — not synced yet, say — is marked rather than failing quietly.
+- **What happens to attachments is said plainly:** files are copied into `.gitroll/files/` and linked from the event, so the originals can move or be deleted afterwards, and unlinking one leaves the copy alone because another event may link the same file.
+
+### Changed
+- **Backing up happens when you ask, in every interface.** 0.2.0 gave the browser app an automatic backup shortly after each save and on returning to the window; the terminal app has always waited to be asked. Uploading a private logbook somewhere else is a decision rather than housekeeping, so now both wait. Nothing about the writing is at risk in the meantime: saving still commits to Git immediately, and the header says how far behind the backup is.
+
 ## 0.2.0 (2026-09-15)
 
 ### Changed
@@ -11,7 +55,7 @@ All notable changes to GitRoll are documented here. GitRoll follows [semantic ve
 - **Search is one query box.** Filters and typed words are the same string now, so they can't disagree. Suggestions appear as you type (`has:`, `topic:`, `type:`, `after:`, `amount:` and the values for each), and the whole thing works from the keyboard. The syntax is the same one `gitroll find` takes.
 - **Event text is rendered as Markdown**, which is what the format always said it was. Headings, lists, emphasis, quotes, code and tables all display, and photos and files can be embedded in the text itself. The editor has a toolbar, `Ctrl`/`⌘`+`B`/`I`/`K`, and a preview. What is written to disk is still plain Markdown a person can read.
 - **Backing up happens by itself**, shortly after you save and when you return to the window, and reports what it is actually doing (checking, downloading, combining, uploading) instead of one spinner. The header button is now a status indicator; it only asks for a hand when a sync fails for a reason a person has to resolve.
-- **"Project" is now "Topic"** and **"Kind" is now "Type"** throughout the interface. Nothing changes on disk: events still store `projects`, exactly as SPEC.md version 1 describes. `topic:` and `topics:` are accepted as search filters alongside `project:`.
+- **"Project" is now "Topic"** and **"Kind" is now "Type"** throughout the interface, in the browser app and the terminal workspace alike. Nothing changes on disk: events still store `projects`, exactly as SPEC.md version 1 describes. `topic:` and `topics:` are accepted as search filters alongside `project:`.
 - **The timeline is paginated**, so a Roll with years of events stays responsive.
 - **Accessibility:** the app now meets WCAG 2.1 AA. Everything is reachable and operable from the keyboard, focus is always visible, dialogs replace the browser's own `alert`/`confirm`/`prompt`, results and errors are announced, and colours meet contrast requirements in both light and dark mode. Secondary text is slightly darker than before for that reason.
 
@@ -34,6 +78,16 @@ All notable changes to GitRoll are documented here. GitRoll follows [semantic ve
 ## 0.1.1 (2026-09-15)
 
 ### Added
+- **Imports from GitHub and CI.** `gitroll import github` logs merged pull requests and releases, `gitroll import ci` logs builds that failed (`--status all` for the rest), for this Roll's own repository or one you name. Filter with `--since`, `--until`, `--branch`, `--author`, `--label`, `--status` and `--limit`, and see what would happen with `--dry-run`. GitHub is asked through the GitHub CLI if it's signed in, then `GITHUB_TOKEN`, then not at all; no token is ever stored. JSON piped in from `gh api` or a webhook works too. Nothing is logged twice — `source: { adapter, id }` is the thing's own identity, a repeated import starts where the last one left off and says so, and an event you edited after importing stays as you left it. See [docs/IMPORT.md](docs/IMPORT.md).
+- **Ask your Roll is a normal feature**, not an experiment behind an environment variable. `gitroll ai` lists where a model can run (on your computer first, so nothing leaves it), `gitroll ai test` says which thing is wrong when it doesn't work, and `gitroll ai on`/`off` switches it without forgetting the settings. The app has the same thing behind ✨ in the header, and tests what you typed before it saves. Keys are read from environment variables and never stored; a Roll's `ai: false` still turns Ask off for everyone. Answers cite events and link to them, and an answer can be turned into a draft event — which stays a draft until you save it. `gitroll summary` drafts an update from a date range the same way.
+- **The Roll's branch is visible**: in the browser header, the terminal header and `gitroll status` (including `--json`, which also carries the head commit, the repository and why syncing is blocked). A detached HEAD and a repository with no commits are named rather than guessed at, and syncing on a detached HEAD stops and says what to do.
+- **Code references.** `#412`, `owner/repo#412`, a commit SHA and GitHub URLs in an event's text become links when the event says which repository it is about. `gitroll log --code` records the repository, branch and commit you're on, as `source: { repo, branch, commit }`.
+- **`gitroll log --editor`** (and `gitroll edit --editor`), using `$VISUAL` or `$EDITOR`, and **`gitroll completion bash|zsh|fish`** for commands, Rolls, templates, tags, projects and saved searches.
+- **Templates** for the kinds of event developers write often — debugging, incident, deployment, experiment and architecture decision — in `gitroll log --template`, `gitroll templates`, and the app's composer.
+- **`gitroll restore`**, and *Put this version back* in History: an earlier version returns as a new commit, so nothing is ever rewritten.
+- **`gitroll conflicts` and `gitroll resolve`**, and a Conflicts screen in the app: an event changed in two places, side by side, settled by keeping one version or writing one out of both. Both stay in history.
+- **Related events and backlinks** from ordinary Markdown links between events (`gitroll related`, and on every event in the app).
+- **Saved searches** (`gitroll find … --save <name>`, then `find @name`, `gitroll searches`) and **`gitroll find --all`** across every Roll on this computer.
 - **Scoop (Windows):** `scoop bucket add gitroll https://github.com/jimhoyd-com/scoop-bucket`, then `scoop install gitroll/gitroll`. Every release installs the manifest with Scoop on Windows before publishing. `gitroll version`, `upgrade` and `uninstall` recognize Scoop installs.
 - **npm:** `npm install --global gitroll`, published by the release workflow with provenance through npm trusted publishing (no stored npm token).
 
@@ -42,6 +96,16 @@ All notable changes to GitRoll are documented here. GitRoll follows [semantic ve
 First public release.
 
 ### Added
+- **Imports from GitHub and CI.** `gitroll import github` logs merged pull requests and releases, `gitroll import ci` logs builds that failed (`--status all` for the rest), for this Roll's own repository or one you name. Filter with `--since`, `--until`, `--branch`, `--author`, `--label`, `--status` and `--limit`, and see what would happen with `--dry-run`. GitHub is asked through the GitHub CLI if it's signed in, then `GITHUB_TOKEN`, then not at all; no token is ever stored. JSON piped in from `gh api` or a webhook works too. Nothing is logged twice — `source: { adapter, id }` is the thing's own identity, a repeated import starts where the last one left off and says so, and an event you edited after importing stays as you left it. See [docs/IMPORT.md](docs/IMPORT.md).
+- **Ask your Roll is a normal feature**, not an experiment behind an environment variable. `gitroll ai` lists where a model can run (on your computer first, so nothing leaves it), `gitroll ai test` says which thing is wrong when it doesn't work, and `gitroll ai on`/`off` switches it without forgetting the settings. The app has the same thing behind ✨ in the header, and tests what you typed before it saves. Keys are read from environment variables and never stored; a Roll's `ai: false` still turns Ask off for everyone. Answers cite events and link to them, and an answer can be turned into a draft event — which stays a draft until you save it. `gitroll summary` drafts an update from a date range the same way.
+- **The Roll's branch is visible**: in the browser header, the terminal header and `gitroll status` (including `--json`, which also carries the head commit, the repository and why syncing is blocked). A detached HEAD and a repository with no commits are named rather than guessed at, and syncing on a detached HEAD stops and says what to do.
+- **Code references.** `#412`, `owner/repo#412`, a commit SHA and GitHub URLs in an event's text become links when the event says which repository it is about. `gitroll log --code` records the repository, branch and commit you're on, as `source: { repo, branch, commit }`.
+- **`gitroll log --editor`** (and `gitroll edit --editor`), using `$VISUAL` or `$EDITOR`, and **`gitroll completion bash|zsh|fish`** for commands, Rolls, templates, tags, projects and saved searches.
+- **Templates** for the kinds of event developers write often — debugging, incident, deployment, experiment and architecture decision — in `gitroll log --template`, `gitroll templates`, and the app's composer.
+- **`gitroll restore`**, and *Put this version back* in History: an earlier version returns as a new commit, so nothing is ever rewritten.
+- **`gitroll conflicts` and `gitroll resolve`**, and a Conflicts screen in the app: an event changed in two places, side by side, settled by keeping one version or writing one out of both. Both stay in history.
+- **Related events and backlinks** from ordinary Markdown links between events (`gitroll related`, and on every event in the app).
+- **Saved searches** (`gitroll find … --save <name>`, then `find @name`, `gitroll searches`) and **`gitroll find --all`** across every Roll on this computer.
 - **Rolls:** plain Markdown-and-YAML records with attachments named by their SHA-256 hash, specified in SPEC.md.
 - **Local web app:** timeline, search with quick filters, projects, logging with photos and files, editing with history, and a sync button.
 - **CLI:** `setup`, `log`, `find`, `sync`, `rolls`, `switch`, `new`, `join`, `share`, `backup`, `rename`, `remove`, `projects`, `types`, `template`, `export`, `import`, `check`, `doctor`, `ask`, `ai`.

package/README.md

@@ -4,7 +4,24 @@
 
 Write down what happened: the AC was serviced, you paid the contractor, you opened a bank account. Add a photo or a receipt. Find it again in seconds, years later.
 
-Your logbook, called a **Roll**, is a folder of plain files on your computer that you can back up to your own private GitHub repository.
+Your logbook, called a **Roll**, is a `.gitroll/` folder of plain Markdown files in a Git repository of your own — either a repository just for the log, or one that already holds a project.
+
+**You don't need GitRoll to keep one.** An event is a Markdown file:
+
+```
+.gitroll/events/2026-09-15-ac-serviced.md
+```
+
+```markdown
+# AC serviced
+
+Replaced the capacitor. Paid $325.
+One-year warranty on the repair.
+
+[Receipt](../files/ac-receipt.pdf)
+```
+
+Commit it, push it, done. No front matter, no ids, no timestamps — the date comes from the file name. GitRoll is an app that reads and writes exactly this, and everything it can do, you can do with a text editor. The whole format is in [SPEC.md](SPEC.md).
 
 **GitRoll is free and open source (MIT).** There are no accounts, subscriptions, usage limits, telemetry or servers. Use it for anything, personal or commercial, on as many computers and Rolls as you like.
 
@@ -61,21 +78,75 @@ GitRoll opens right in your terminal: use ↑↓ to browse, `n` to log, `/` to f
 
 In the browser:
 
-- **Log:** start typing in the box at the top and click **Save** (or press `n` from anywhere, and `Ctrl`/`⌘`+`Enter` to save). Text is Markdown, `#tags` and amounts like `$40` are picked up as you type, and photos and files can be dropped or pasted straight in. The row of buttons under the box sets the type, the topic, when it happened and the amount — including logging something that happened last week.
+- **Log:** start typing in the box at the top and click **Save** (or press `n` from anywhere, and `Ctrl`/`⌘`+`Enter` to save). Text is Markdown, `#tags` and amounts like `$40` are picked up as you type, and photos and files can be dropped or pasted straight in. The row of buttons under the box sets the topic, the date and the amount — including logging something that happened last week.
 - **Find:** type words in **Search**, or a filter like `has:photo`, `topic:house`, `after:2026-01-01` or `amount:>500`. Suggestions appear as you type; press `/` to jump to the box. The same filters work in `gitroll find`.
 - **Edit:** open an event and click **Edit**. **History** shows every earlier version.
-- **Back up:** GitRoll backs up by itself shortly after you save and when you come back to the window. The indicator in the header shows where that has got to; click it to back up now or to see why one failed.
+- **Back up:** GitRoll never uploads on its own. Your events are saved and committed the moment you write them; sending them to your backup is something you ask for — `gitroll sync`, `/sync` in the terminal app, or the indicator in the header of the browser app, which shows how far behind the backup is and why a sync failed.
 - **Keyboard:** press `?` for the full list of shortcuts.
+- **Ask:** press ✨ to set up a model — on your computer, so nothing leaves it — then ask questions in the search box. Every answer links to the events it came from. See [docs/AI.md](docs/AI.md).
 
 If the page asks you to open GitRoll from the link in your terminal, copy that link. It's a per-session key that keeps other programs on your computer out.
 
+## If you write code
+
+A log that lives in the repository it is about answers the questions Git can't: why this, what we tried, what broke at 3am and what fixed it.
+
+```bash
+cd ~/code/my-project
+gitroll log --template incident --code --editor "Checkout timeouts"
+```
+
+- **`--template`** opens one of `debugging`, `incident`, `deployment`, `experiment` or `decision` (an ADR) — headings worth answering, which you can delete if they don't apply.
+- **`--code`** records the repository, branch and commit you're on, so the event knows which work it is about.
+- **`--editor`** writes it in `$VISUAL` or `$EDITOR`.
+
+Then `#412`, `owner/repo#412`, a commit SHA or a GitHub URL in the text become links to the right repository, and an ordinary Markdown link to another event (`[the incident](2026-09-14-checkout-timeouts.md)`) shows up on both events — the second one as a backlink.
+
+The header (in the browser and the terminal) and `gitroll status` show which repository and **branch** the log itself is on, so you always know where what you write is going. `gitroll completion bash|zsh|fish` prints a completion script for commands, Rolls, templates, tags and saved searches.
+
+| Command | What it does |
+| --- | --- |
+| `gitroll ask "what broke in checkout last month?"` | Answer from your events, with links to them |
+| `gitroll summary --since 2026-09-01` | Draft an update from what you logged. Nothing is saved until you save it. |
+| `gitroll restore <file>` | Put an earlier version back, as a new commit |
+| `gitroll conflicts` / `gitroll resolve <file> --mine` | Settle an event that was changed in two places |
+| `gitroll related <file>` | What it links to, and what links back |
+| `gitroll find "tag:incident" --save incidents` | Keep a search; run it later with `gitroll find @incidents` |
+| `gitroll find "postgres" --all` | Search every Roll you have |
+| `gitroll import github` / `gitroll import ci` | Log merged pull requests and releases, and builds that failed |
+
+A lot of what happened is already written down in merged pull requests and in the build that broke at 3am. `gitroll import github` and `gitroll import ci` bring those in as ordinary events — failures only by default, picking up where the last import left off, and never logging the same thing twice. See [docs/IMPORT.md](docs/IMPORT.md).
+
+## Adding a log to a project you already have
+
+Run `gitroll` inside any Git repository. If it has no log yet, GitRoll offers to add one, to open a different Roll, or to cancel — and it creates nothing until you say so:
+
+```bash
+cd ~/code/my-project
+gitroll
+```
+
+Choosing *Add a log to this repository* creates `.gitroll/` and nothing else. Your project's own README, files and branch are untouched, and GitRoll commits only the files it wrote, so anything you had staged or half-finished stays exactly as it was. From then on, decisions, incidents and releases live next to the code they are about:
+
+```
+.gitroll/events/2026-09-15-auth-decision.md
+```
+
+**`.gitroll/` is a namespace, not a privacy boundary.** The log is exactly as visible as the repository it lives in, so a log in a public repository is public.
+
 ## Your data lives in your own repository
 
-You don't fork or clone this repository to use GitRoll; it holds only the app's source code. `gitroll setup` creates a separate **private** repository in your own GitHub account for your Roll, containing only your entries and files. (A fork of this public repository couldn't be made private.)
+You don't fork or clone this repository to use GitRoll; it holds only the app's source code. `gitroll setup` creates a separate **private** repository in your own GitHub account for your Roll, containing only your events and files. (A fork of this public repository couldn't be made private.)
 
 ## Upgrading
 
-Your Rolls contain no app code, so upgrading never changes them: new versions read the same files. If a future version ever needs to change the file format, it will tell you and make the change as a normal commit you can review.
+Your Rolls contain no app code, so upgrading never changes them: new versions read the same files. `.gitroll/config.yaml` records which template revision your repository follows:
+
+```yaml
+template_version: 1
+```
+
+GitRoll reads that marker and never changes it while logging or editing — upgrading the app does not upgrade your repository. If a future version ever needs to change the format, it will say so, make the change as a normal commit you can review, and update the marker only once that has worked. A repository whose template is newer than your app refuses writes and tells you to upgrade; one that doesn't record a version is reported as unknown rather than assumed to be current (`gitroll template --set 1` records it).
 
 | How you installed | Upgrade with |
 | --- | --- |
@@ -118,15 +189,23 @@ Prefer to skip `gitroll setup`? Every release publishes the starter files to [ji
    git clone git@github.com:you/my-roll.git
    ```
 
-3. Open it:
+3. Log something — with or without GitRoll:
+
+   ```bash
+   cd my-roll
+   $EDITOR .gitroll/events/2026-09-15-ac-serviced.md
+   git add .gitroll && git commit -m "AC serviced" && git push
+   ```
+
+   Or open it in the app, which checks the log, adds it to your list, and opens it:
 
    ```bash
    cd my-roll && gitroll
    ```
 
-   GitRoll checks the Roll, adds it to your list, and opens it. To add it without opening, run `gitroll rolls add .` instead.
+   To add it without opening, run `gitroll rolls add .` instead.
 
-Running `gitroll` inside an **empty** folder or freshly cloned empty repository offers to set it up as a Roll. GitRoll never changes a folder that already has other files in it.
+Running `gitroll` inside an **empty** folder offers to make it a Roll; inside a repository that already holds a project, it offers to add a `.gitroll/` folder to it. Either way it asks first and never touches anything else.
 
 ## Everyday commands
 
@@ -144,25 +223,61 @@ gitroll sync
 
 | Command | What it does |
 | --- | --- |
-| `gitroll` | Open GitRoll in the terminal (press `o` for the browser app) |
+| `gitroll` | Open GitRoll in the terminal (`/web` opens the browser app) |
 | `gitroll open` | Open GitRoll in your browser |
 | `gitroll upgrade` / `gitroll uninstall` | Get the latest version, or remove the app (your Rolls stay) |
-| `gitroll menu` or `gitroll -i` | Full-screen terminal app: browse with arrow keys, `n` log, `/` find, `s` sync, `r` switch Roll |
+| `gitroll menu` or `gitroll -i` | The workspace: type an entry at the prompt, `/` for commands, ↑↓ to browse |
 | `gitroll log "text" [files]` | Log something, with optional photos or receipts |
-| `gitroll find "words"` | Find events |
+| `gitroll find "words"` | Find events (see [What search looks at](#what-search-looks-at)) |
 | `gitroll sync` | Back up, and get changes from anyone you share with |
 | `gitroll rolls` / `gitroll switch <name>` | See your Rolls and pick one |
-| `gitroll rolls add [folder]` | Add a Roll you cloned yourself |
+| `gitroll rolls add [folder]` | Add a repository with a log that you cloned yourself |
+| `gitroll init --dir <folder>` | Add a log (`.gitroll/`) to a repository you already have |
+| `gitroll move <file> <new path>` | Rename or reorganize an event, keeping its links and history |
+| `gitroll template` | Show the repository's template version (`--set 1` records one) |
 | `gitroll new "Business" --github` | Create another Roll with a private GitHub backup |
 | `gitroll share <github-user>` | Let someone else log in this Roll |
+| `gitroll ai` / `gitroll ask "…"` | Set up a model, then ask questions of your own events |
+| `gitroll log --template incident --code` | Start from a template, recording the branch and commit you're on |
+| `gitroll restore <file>` / `gitroll conflicts` | Put a version back; settle an event changed in two places |
+| `gitroll import github` / `gitroll import ci` | Log merged pull requests, releases and failed builds ([docs/IMPORT.md](docs/IMPORT.md)) |
+| `gitroll completion <shell>` | Completion for bash, zsh or fish |
 | `gitroll doctor` | Check your setup, privacy and backup |
 | `gitroll help more` | Everything else |
 
 ### Interactive or basic
 
-- **Interactive:** `gitroll menu` (or `gitroll -i`) opens a full-screen terminal app. Move with ↑↓, Enter reads an entry, `n` logs something, `/` finds as you type, `s` syncs, `r` switches Roll, `o` opens the browser app and `q` quits. In a simple terminal it falls back to a numbered menu. Also, `gitroll log` with no text asks what happened, which files to attach (you can drag them into the terminal), and which project.
+- **Interactive:** `gitroll` (or `gitroll menu` / `gitroll -i`) opens a workspace that stays open. Your recent entries sit above a prompt; type what happened and press Enter to log it. Press `/` for commands with descriptions and autocomplete — `/log`, `/find`, `/topics`, `/roll`, `/sync`, `/status`, `/problems`, `/deleted`, `/web`, `/help` — and `?` for the key list.
+
+  | Key | What it does |
+  | --- | --- |
+  | Enter | Log what's in the prompt, or open the entry you picked |
+  | ↑ ↓ | Pick one of the recent entries above the prompt |
+  | Ctrl+O | Open the full composer: text over several lines, date, amount, tags, topics and files, with topic and tag autocomplete |
+  | Ctrl+S | Save, in the composer |
+  | Ctrl+E | Edit the text in your own editor (`EDITOR` or `VISUAL`) |
+  | Ctrl+Z | Undo the last deletion |
+  | Ctrl+R | Re-read the Roll from its folder |
+  | Esc | Go back, one step at a time |
+  | Ctrl+C | Quit — unsaved text is kept as a draft and offered again next time |
+
+  `/find` searches as you type, shows the selected entry beside the results in a wide terminal, and gives you `Ctrl+O` to write a new entry, `Ctrl+E` to edit, `Ctrl+K` to duplicate and `Ctrl+D` to delete. Open an entry with Enter to edit (`e`), duplicate (`y`), attach files (`a`), open one of its files in the application that normally opens it (`o`, `Tab` to pick another), see its history (`h`) or delete it (`d`). Attached files are copied into `.gitroll/files/` and linked from the event, so the originals can move or go; unlinking one leaves the copy where it is, since another event may link the same file. Deleting an event only takes it off the timeline: `/deleted` lists what has gone and puts any of it back as a new change. The header always says which Roll you're in, where it lives, and whether your entries are backed up. In a simple terminal it falls back to a numbered menu. Also, `gitroll log` with no text asks what happened, which files to attach (you can drag them into the terminal), and which project.
 - **Basic:** every command also works in one line with no questions asked, for scripts and automation. Prompts and colors are off automatically outside a terminal, when `NO_COLOR` is set, or with `--plain`.
 
+### What search looks at
+
+`gitroll find`, `/find` in the terminal app and the search box in the browser all read the same thing: **what you wrote.**
+
+| Searched | Not searched |
+| --- | --- |
+| The words of an event, and its title | What's inside an attached file — no PDF text, no text in photos |
+| Its topics and tags | Other Rolls, unless you ask with `--all` |
+| Its amount and currency | Events you deleted (`/deleted` lists those) |
+| Anything in its front matter | Older versions of an event (`gitroll history <id>` shows those) |
+| Its file name, and the names of files attached to it | |
+
+It covers this Roll as its files are right now, on the branch you're on. Filters combine: `topic:house tag:payment type:expense after:2026-01-01 before:2026-06-30 amount:>500 has:photo by:jimmy`.
+
 ## Sharing a Roll
 
 ```bash
@@ -173,11 +288,13 @@ They accept the GitHub invitation, install GitRoll, and run `gitroll join you/ho
 
 ## Templates and themes
 
-Add your own kinds of entries, save a Roll's setup as a template for new Rolls, and restyle GitRoll with a small CSS file. See [docs/TEMPLATES.md](docs/TEMPLATES.md).
+Start new Rolls from a template repository, and restyle GitRoll with a small CSS file. See [docs/TEMPLATES.md](docs/TEMPLATES.md).
 
 ## Privacy
 
-- Your entries live only on your computer and, if you back up, in your own GitHub repository. GitRoll collects nothing and keeps no copy.
+- Your events live only on your computer and, if you back up, in your own GitHub repository. GitRoll collects nothing and keeps no copy.
+- **Ask uses the model you choose.** With one on your computer, nothing leaves it. With a hosted provider, GitRoll says exactly what is sent before you turn it on, never sends attachments, and never stores your API key — it reads the environment variable you name. A Roll can turn Ask off for everyone with `ai: false`.
+- A log is as visible as the repository it is in. `.gitroll/` is a namespace, not a privacy boundary: in a public repository, the log is public.
 - It removes location data from photos, and warns before you save something that looks like a password or card number.
 - Before every sync it confirms your backup repository is private, and refuses to upload if it's public or it can't tell. It only opens on your own computer.
 - **Limitations:** files aren't encrypted, and deleting an entry doesn't erase it from history.
@@ -186,7 +303,7 @@ Details are in [SECURITY.md](SECURITY.md).
 
 ## For developers
 
-Every entry is a Markdown file with YAML front matter, so `git clone` gives you everything and your records stay readable without GitRoll. The format is specified in [SPEC.md](SPEC.md). The same rules are available as a library, [`@gitroll/core`](packages/core), for building your own tools.
+Every event is a Markdown file, front matter optional, so `git clone` gives you everything and your records stay readable — and writable — without GitRoll. The format is specified in [SPEC.md](SPEC.md). The same rules are available as a library, [`@gitroll/core`](packages/core), for building your own tools.
 
 ```bash
 make setup
@@ -204,10 +321,10 @@ Run `make` to list every shortcut. See [CONTRIBUTING.md](CONTRIBUTING.md) to con
 
 | Path | What it is |
 | --- | --- |
-| `src/core` | The GitRoll Format: parsing, validation, event types, search, privacy checks (published as `@gitroll/core`) |
+| `src/core` | The GitRoll format: parsing, validation, search, privacy checks (published as `@gitroll/core`) |
 | `src/node` | Git operations, the CLI and the local web server |
 | `src/web` | The browser interface |
-| `template` | Starter files for a new Roll (data only: no code or workflows) |
+| `template` | Starter files for a new Roll: a `.gitroll/` folder and a short root README (data only: no code or workflows) |
 
 ## GitRoll.com
 

package/SECURITY.md

@@ -24,16 +24,20 @@ GitRoll never asks for, stores or sends a GitHub password or token. Syncing runs
 - Uploaded HTML, SVG, XML and JavaScript are always downloaded, never rendered.
 
 **Files**
-- Every read and write is checked to stay inside the Roll folder. GitRoll never follows symbolic links, and `gitroll check` reports any it finds.
-- Attachments are named by their SHA-256 hash, so tampering shows up in `gitroll check`.
-- Templates can only add type definitions, projects, a README and a theme stylesheet. Code, scripts and workflows are never copied into a Roll.
+- Every read and write is checked to stay inside the repository. GitRoll never follows symbolic links, and `gitroll check` reports any it finds.
+- GitRoll reads and writes only `.gitroll/`, and commits only the files it wrote, so work in progress elsewhere in a repository is never swept into its commits.
+- A link in an event is resolved inside the repository only. A link that climbs out of the root or starts at `/` is not an attachment, is never opened, and is reported by `gitroll check`.
+- A file stored by GitRoll gets a readable name and never overwrites one that is already there (`ac-receipt-2.pdf`).
+- A repository whose `template_version` is newer than the app blocks every write, so an older GitRoll can't half-rewrite a newer format.
+- Templates can only add a config marker, a README and a theme stylesheet. Code, scripts and workflows are never copied into a Roll.
 
 **Privacy**
 - Location (GPS) data is removed from JPEG photos before they're saved. Turn this off per Roll with `attachments: { remove_location: false }`.
 - Saving an event warns if the text looks like a password, API key, private key, card number or Social Security number, and `gitroll check` lists such events.
 - Before every upload, sync checks each address `git push` would actually send to (including `pushurl` and `insteadOf` rewrites). It refuses if a GitHub repository is public, or if its privacy can't be confirmed (offline, rate limited). It also refuses non-GitHub hosts unless you explicitly run `gitroll trust <address>`. Nothing is cached, so every sync is checked.
-- Your display name comes from settings on your computer, never from the shared Roll, so collaborators can't sign events as each other.
-- "Ask your Roll" only sends questions and the matching events to an AI model on your computer, unless you explicitly allow a remote one. API keys are read from environment variables and never stored. A Roll can turn Ask off for everyone with `ai: false`.
+- Events carry no author field. Who wrote and changed each one comes from Git history, so collaborators can't sign events as each other by editing a file.
+- **"Ask your Roll" sends nothing anywhere by default.** It is off until you set it up, and a model on your own computer is what it offers first; with one, no part of an event leaves the machine. A non-local address has to be chosen deliberately, must be `https://`, and GitRoll says exactly what would be sent (your question and the text of the matching events; never attachments) before you turn it on. API keys are read from an environment variable you name and are never stored in settings or in a Roll. A Roll can turn Ask off for everyone with `ai: false`, and GitRoll honours that whatever an individual has set up.
+- **AI never writes to a Roll.** An answer can be turned into a draft, and a draft is saved only when a person saves it.
 - `gitroll doctor` reviews your setup: repository visibility, credentials embedded in the backup address, your email appearing in history, commit signing, settings file permissions and AI endpoint.
 
 **Git behavior**
@@ -47,6 +51,7 @@ GitRoll never asks for, stores or sends a GitHub password or token. Syncing runs
 
 ## Limitations to understand
 
+- **`.gitroll/` is a namespace, not a privacy boundary.** A log is exactly as visible as the repository it lives in. In a public repository, every event and every file in it is public.
 - **You're responsible for keeping your repository private.** GitRoll checks GitHub's visibility before syncing, but can't check other Git hosts, and can't stop you from making the repository public later.
 - **Delete isn't erasure.** Deleting an event hides it from the timeline, but it stays in Git history, as do its attachments, on every computer and repository that synced it. Truly removing data means rewriting history (for example with `git filter-repo`) on every copy. Removing a collaborator doesn't delete what they already downloaded.
 - **Files aren't encrypted.** Anyone with access to your computer, your backups or the GitHub repository can read them. Use full-disk encryption on your devices.