gitroll 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+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.1.0 (2026-09-15)
+
+First public release.
+
+### Added
+- **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`.
+- **Event types:** Log, Expense, Maintenance, Decision, Issue and Milestone, plus custom types with fields and defaults.
+- **Syncing:** with a private GitHub repository using your own Git credentials, with automatic merging when the same entry was edited in two places.
+- **Templates and themes:** reusable Roll templates and per-Roll themes.
+- **Template repository:** starter files are published to `jimhoyd-com/gitroll-template` on each release; `gitroll rolls add` registers a Roll you cloned yourself.
+- **Dates and time zones:** timestamps keep the author's offset; a hand-typed date (`2026-09-15`) means noon local time so it stays on that day everywhere; only real ISO 8601 dates are accepted (no `Sept 15` or February 30), and `gitroll check` reports others. Rules are in SPEC.md, with tests across time zones and daylight-saving changes.
+- **End-to-end tests** of the built app: two people sharing a Roll, the browser app over HTTP, and the terminal app in a real terminal.
+- **Template repository renamed** to `jimhoyd-com/gitroll-template`, with step-by-step instructions for starting from it.
+- **Upgrade and uninstall:** `gitroll version`, `gitroll upgrade` (checksum-verified, or Homebrew) and `gitroll uninstall` (never deletes Rolls; `--remove-settings` optional), plus `scripts/uninstall.sh`. Releases verify that uninstalling removes the app and keeps Rolls and settings.
+- **Homebrew:** `brew install jimhoyd-com/tap/gitroll`, published automatically by the release workflow.
+- **Plain `gitroll` opens the terminal app** in a terminal; `gitroll open` (or `--no-browser`/`--plain`, or a script) keeps the browser/basic behavior.
+- **Interactive and basic CLI:** full-screen `gitroll menu` / `gitroll -i` (arrow keys, live find, log, sync, switch Roll) and a step-by-step `gitroll log`; every command also runs without prompts, with `--plain` or outside a terminal.
+- **Plain `gitroll`:** opens the Roll you're in (checking its shape), offers to set up an empty folder, and never changes a repository with other files.
+- **`@gitroll/core`:** the format as a platform-free library.
+- **Release artifacts:** a versioned package tarball with `SHA256SUMS`, build provenance, and generated Homebrew and Scoop definitions, each verified by installing on clean Linux, macOS and Windows machines.
+
+### Experimental (hidden)
+- **"Ask your Roll":** local AI answers with citations. Off unless `GITROLL_EXPERIMENTAL=ai` is set.
+
+### Security
+- Every read and write stays inside the Roll folder, and symbolic links are refused and reported.
+- The local app binds to loopback only, with a per-session access key, CSP, CSRF and DNS-rebinding protection.
+- Attachments are never cached by the browser, and active content is always downloaded rather than rendered.
+- GPS location is removed from photos, and text that looks like a password, key or card number triggers a warning.
+- Sync checks the real push destinations before every upload, and refuses public, unconfirmable, or untrusted non-GitHub destinations.
+- Distributed builds include third-party license notices.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jimmy Ho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# GitRoll
+
+**A private logbook. Log what happened, find it later.**
+
+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.
+
+**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.
+
+## Install
+
+GitRoll needs [Git](https://git-scm.com/downloads) and [Node.js](https://nodejs.org) 20 or newer.
+
+**Mac or Linux:** download and run the installer. It fetches the latest release, verifies its SHA-256 checksum, and installs it.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jimhoyd-com/gitroll/main/scripts/install.sh -o install.sh
+```
+
+```bash
+sh install.sh
+```
+
+**Windows (or any system with Node.js):** download `gitroll-<version>.tgz` and `SHA256SUMS` from the [latest release](https://github.com/jimhoyd-com/gitroll/releases/latest), check the checksum, then install the downloaded file:
+
+```bash
+npm install -g gitroll-<version>.tgz
+```
+
+Every release is tested by installing it on clean Linux, macOS and Windows machines before it's published. Homebrew (`brew install jimhoyd-com/tap/gitroll`), Scoop and the npm registry are coming; they'll be listed here once they're live.
+
+For one-command backup and sharing, also install the [GitHub CLI](https://cli.github.com) and run `gh auth login`. It's optional.
+
+## Start
+
+```bash
+gitroll setup
+```
+
+This asks for a name, creates your Roll in `~/GitRoll`, and offers to back it up to a new **private** GitHub repository. After that, just run:
+
+```bash
+gitroll
+```
+
+GitRoll opens right in your terminal: use ↑↓ to browse, `n` to log, `/` to find and `q` to quit. Prefer clicking? Press `o` (or run `gitroll open`) to use it in your browser; keep the terminal open while you do.
+
+In the browser:
+
+- **Log:** click **Log**, write what happened, and add photos or files. **More options** has project, kind, amount, date and tags. Then click **Save**.
+- **Find:** type in **Search**, use **This month**, **This year** or **With files**, or click any project or `#tag`.
+- **Edit:** open an entry and click **Edit**. **History** shows every earlier version.
+- **Back up:** click **Sync**. The number on the button counts changes that aren't backed up yet.
+
+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.
+
+## 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.)
+
+## 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.
+
+| How you installed | Upgrade with |
+| --- | --- |
+| Homebrew | `brew upgrade gitroll` (or `gitroll upgrade`) |
+| The installer, or npm | `gitroll upgrade`. It downloads the latest release, checks it against `SHA256SUMS`, and installs it. Running the installer again also works. |
+| From source | `git pull && npm ci && npm run build` |
+
+Not sure? `gitroll version` shows the version and how it was installed. `gitroll upgrade --dry-run` shows what would happen without changing anything.
+
+## Uninstalling
+
+Uninstalling removes the app only. **Your Rolls are never deleted:** they're ordinary folders (in `~/GitRoll` by default) and your private GitHub repositories, and they keep working if you reinstall later.
+
+```bash
+gitroll uninstall
+```
+
+It shows what it removes and what it keeps, then asks before doing anything. Add `--remove-settings` to also delete GitRoll's settings (your list of Rolls and trusted backups, in `~/.config/gitroll` or `%APPDATA%\GitRoll`), or `--dry-run` to only see the plan.
+
+If the `gitroll` command no longer works, remove it directly:
+
+| How you installed | Uninstall with |
+| --- | --- |
+| Homebrew | `brew uninstall gitroll` |
+| The installer, or npm (Mac, Linux, Windows) | `npm uninstall --global gitroll` |
+| Mac or Linux, any method | [`scripts/uninstall.sh`](scripts/uninstall.sh): download it, read it, then run `sh uninstall.sh` (add `--remove-settings` to also remove settings) |
+
+To delete a Roll as well, remove its folder and, if you backed it up, delete its repository on GitHub. That's permanent.
+
+## Advanced: start from the template
+
+Prefer to skip `gitroll setup`? Every release publishes the starter files to [jimhoyd-com/gitroll-template](https://github.com/jimhoyd-com/gitroll-template):
+
+1. Click **Use this template → Create a new repository**, and choose **Private**.
+2. Clone your new repository:
+
+   ```bash
+   git clone git@github.com:you/my-roll.git
+   ```
+
+3. Open 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.
+
+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.
+
+## Everyday commands
+
+```bash
+gitroll log "AC serviced, capacitor replaced. $325" invoice.pdf
+```
+
+```bash
+gitroll find "capacitor"
+```
+
+```bash
+gitroll sync
+```
+
+| Command | What it does |
+| --- | --- |
+| `gitroll` | Open GitRoll in the terminal (press `o` for 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 log "text" [files]` | Log something, with optional photos or receipts |
+| `gitroll find "words"` | Find events |
+| `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 new "Business" --github` | Create another Roll with a private GitHub backup |
+| `gitroll share <github-user>` | Let someone else log in this Roll |
+| `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.
+- **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`.
+
+## Sharing a Roll
+
+```bash
+gitroll share partner-github-name
+```
+
+They accept the GitHub invitation, install GitRoll, and run `gitroll join you/home`. Everyone syncs with the same private repository. If two people edit the same entry, GitRoll keeps both versions and tags the entry `#conflict`. See [docs/SHARING.md](docs/SHARING.md).
+
+## 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).
+
+## 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.
+- 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.
+
+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.
+
+```bash
+make setup
+```
+
+```bash
+make check
+```
+
+```bash
+make demo
+```
+
+Run `make` to list every shortcut. See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute and [packaging/README.md](packaging/README.md) for releases.
+
+| Path | What it is |
+| --- | --- |
+| `src/core` | The GitRoll Format: parsing, validation, event types, 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) |
+
+## GitRoll.com
+
+GitRoll.com is an optional, separate, paid service for using your Rolls from any browser or phone. It isn't part of this repository, and the free app never needs it. Your Rolls work the same with or without it.
+
+## License
+
+[MIT](LICENSE). Bundled third-party licenses are listed in `dist/THIRD_PARTY_NOTICES.txt`.

package/SECURITY.md

@@ -0,0 +1,59 @@
+# Security and privacy
+
+GitRoll is local-first software. There's no GitRoll server, account, database, analytics or telemetry. This page explains where data goes, what GitRoll protects against, and what it doesn't.
+
+## Where your data lives
+
+| Place | What's there | Who controls it |
+| --- | --- | --- |
+| Your computer | The Roll folder: events, photos, receipts, full history | You |
+| Your GitHub repository (optional) | A copy, updated when you sync | You, and anyone you share with |
+| GitRoll settings (`~/.config/gitroll`, or `%APPDATA%\GitRoll`) | Where your Rolls are, your display name, AI settings. No events. | You |
+| Anywhere else | Nothing | |
+
+GitRoll never asks for, stores or sends a GitHub password or token. Syncing runs your installed `git`, which uses your own SSH key or credential helper.
+
+## Protections
+
+**Local app**
+- Listens only on `127.0.0.1`. Other addresses are refused, so other devices can't connect.
+- Each run creates a random access key. The browser receives it once, from the link GitRoll opens, then keeps it in an HttpOnly, SameSite=Strict cookie. Other programs or users on the same computer can't read or change your Roll without it.
+- Blocks DNS-rebinding requests (the Host header must be local) and cross-site form posts (writes must be JSON).
+- A strict Content Security Policy: no third-party or inline scripts, no framing.
+- Private responses and attachments are sent with `Cache-Control: no-store`, so receipts and photos aren't left in the browser cache.
+- 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.
+
+**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`.
+- `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**
+- Git runs without a shell, with prompts disabled and network timeouts, so a sync can't hang.
+- GitRoll never force-pushes or rewrites history. When two people change the same event, both versions are kept.
+
+**Supply chain**
+- The installed package has no runtime dependencies; bundled third-party code is listed in `THIRD_PARTY_NOTICES.txt`.
+- Rolls contain no workflows, so logging and syncing use no GitHub Actions.
+- GitRoll's own repository uses CI pinned to commit SHAs, CodeQL and Dependabot.
+
+## Limitations to understand
+
+- **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.
+- **Your email may be in history.** Git records the name and email you commit with. Use GitHub's noreply address if that matters to you.
+- **No compliance certification.** GitRoll doesn't make you compliant with GDPR, HIPAA or similar rules. You (and GitHub, as your host) remain responsible for how the data is stored and shared.
+- **AI answers can be wrong.** Always check the cited events.
+
+## Reporting a vulnerability
+
+Please report security issues privately with GitHub's "Report a vulnerability" button on the GitRoll repository, not in a public issue.

package/SPEC.md

@@ -0,0 +1,144 @@
+# GitRoll Format, version 1
+
+A Roll is an ordinary Git repository. It must stay readable and useful without GitRoll: every file is Markdown, YAML, or an unmodified original attachment.
+
+## Layout
+
+```
+.gitroll/config.yaml          required
+.gitroll/types/<type>.yaml    optional custom event types
+entries/YYYY/MM/<id>.md       one event per file
+projects/<slug>.yaml          optional project metadata
+attachments/<sha256><.ext>    attachment bytes, named by content hash
+```
+
+Entries never live inside project folders. An event references projects, so one event can belong to several.
+
+`YYYY/MM` is taken from the event's `created` timestamp and never changes when the event is edited. Readers must not depend on that folder structure: any `.md` file under `entries/` is an event.
+
+## Dates and time zones
+
+- **Format.** Timestamps are ISO 8601. Writers record local time with its offset, for example `2026-09-15T14:30:00-07:00`, so both the author's wall-clock time and the exact instant are kept. Readers must accept:
+  - `2026-09-15T14:30:00-07:00` or `2026-09-15T21:30:00Z`: an exact instant.
+  - `2026-09-15T14:30` or `2026-09-15T14:30:00`: no offset, so the reader's local time.
+  - `2026-09-15`: a date typed by hand, meaning noon local time, so it falls on that day in every time zone. Writers expand it to `2026-09-15T12:00:00` when they next save the event.
+  - Anything else (such as `Sept 15`) is invalid, and `gitroll check` reports it.
+- **Ordering** uses the instant, so events logged in different time zones sort correctly.
+- **Display and filters** use the viewer's time zone. An event logged at 9:00 in New York shows as 6:00 to someone in Los Angeles, and "this month", `after:` and `before:` use the viewer's local days.
+- **Folders** (`entries/YYYY/MM`) use the year and month as written in `created`, the author's local date, and never move.
+- **Fields** of kind `date` in custom types hold a date (`2026-09-15`) and are shown as that calendar day, without time zone conversion.
+
+## `.gitroll/config.yaml`
+
+```yaml
+version: 1
+name: My Roll
+attachments:
+  max_mb: 25              # optional per-file limit for new attachments
+  remove_location: true   # optional; remove GPS data from photos (default true)
+ai: true                  # optional; false turns off "Ask your Roll" for everyone
+```
+
+`.gitroll/theme.css` (optional) overrides the app's style variables. See docs/TEMPLATES.md.
+
+The author name on new events comes from each person's own GitRoll settings or `git config user.name`, never from the shared config.
+
+## Events
+
+An event is a Markdown file with YAML front matter. The body is free Markdown text.
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `version` | yes | Format version, currently `1` |
+| `id` | yes | Globally unique id. Writers use UUIDv7 (time-sortable). Must match the file name. |
+| `type` | no | Event type id, default `log`. Lowercase letters, digits and `-`. |
+| `created` | yes | ISO 8601 timestamp with offset: when the event was recorded |
+| `occurred` | no | When it happened. Defaults to `created`. Same format as `created`; see [Dates and time zones](#dates-and-time-zones). |
+| `author` | no | Who logged it |
+| `projects` | no | List of project slugs |
+| `tags` | no | List of lowercase tags |
+| `attachments` | no | List of `{ hash, name, type, size }`, where `hash` is `sha256:<hex>` |
+| `amount` | no | `{ value, currency }`, where currency is an ISO 4217 code |
+| `data` | no | Type-specific structured fields (a mapping) |
+| `source` | no | `{ adapter, id, url? }` for events created by an import. `adapter` + `id` is unique within a Roll. |
+
+Unknown front matter keys must be preserved by writers. Unknown `data` keys must be preserved too.
+
+### Edits and deletion
+
+Edits rewrite the file in place (same path, same `id`), and each edit is its own commit. Deleting an event removes its file in a commit. Git history is the audit trail: previous versions are never rewritten or force-pushed away by GitRoll.
+
+## Event types
+
+A type is a template: a label, an icon, and optional fields stored under `data`. It never changes how an event is stored. An event whose type isn't known is still a valid event and renders as a general log.
+
+Built-in starter types: `log`, `expense`, `maintenance`, `decision`, `issue`, `milestone`.
+
+A custom type lives in the Roll, so its data never depends on a plugin being installed:
+
+```yaml
+# .gitroll/types/vehicle-service.yaml
+label: Vehicle service
+icon: 🚗
+amount: expected        # none | optional | expected (whether to show the amount field)
+fields:
+  - key: odometer       # lowercase letters, digits, underscore
+    label: Odometer
+    kind: number        # text | longtext | number | date | select | boolean | url
+  - key: shop
+    label: Shop
+    kind: text
+```
+
+Optional `defaults` prefill the form when someone picks the type. They're plain values; GitRoll never runs anything from a Roll:
+
+```yaml
+defaults:
+  text: Changed the oil.
+  tags: [car]
+  projects: [truck]
+  amount: { value: 60, currency: USD }
+  data: { shop: Jiffy Lube }
+```
+
+A custom file with the same id as a built-in type overrides it.
+
+## Attachments
+
+Attachments are content-addressed. An event refers to an attachment only by `hash`; the file name in the event is the original, human-readable name.
+
+In format version 1 the bytes are stored in the repository at `attachments/<sha256hex><.ext>`. Identical files are stored once. Validators check that each file's SHA-256 matches its name.
+
+GitRoll removes GPS location data from JPEG photos before hashing and storing them (unless `remove_location` is false), so a stored photo may differ from the camera original only in that metadata.
+
+Rolls must not contain symbolic links. Readers must not follow them, and validators report them.
+
+Because events reference only hashes, other storage (such as Git LFS or object storage) can be added later without changing existing events. A future store would be declared in `.gitroll/config.yaml`; readers resolve a hash by looking in the repository first.
+
+## Projects
+
+```yaml
+# projects/bathroom-remodel.yaml
+name: Bathroom Remodel
+description: Main bathroom, 2026
+created: 2026-09-01T10:00:00-05:00
+```
+
+An event may reference a slug that has no project file; readers show the slug as the name.
+
+## Validation
+
+`gitroll check` reports:
+
+- a missing or invalid `.gitroll/config.yaml`
+- event files that don't parse, lack required fields, or whose file name doesn't match their `id`
+- duplicate ids or duplicate `source` identities
+- attachment references with no matching file, and attachment files whose content doesn't match their hash
+- invalid project or type definition files
+- `data` values that don't match a known type's field kinds
+
+Validation runs locally. A Roll requires no CI.
+
+## Reserved for later versions
+
+These names are reserved and currently ignored, so they're preserved like any unknown key: `pinned`, `related`, `resolves`, `entities`, `status`, `encryption`.

package/dist/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,19 @@
+GitRoll includes the following third-party software.
+
+========================================================================
+yaml 2.9.1 (ISC)
+========================================================================
+
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.