openlogbook 0.1.0__tar.gz

openlogbook-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+* @bighydro
+SPEC.md @bighydro
+schema/ @bighydro

openlogbook-0.1.0/.github/ISSUE_TEMPLATE/adapter.md

@@ -0,0 +1,12 @@
+---
+name: New adapter
+about: Propose an adapter for a source
+labels: adapter
+---
+**Source** (app/service, export format, how to get the export):
+
+**Kinds and payload schemas it would produce:**
+
+**Tier:**
+
+**Synthetic fixture attached?** (never real data)

openlogbook-0.1.0/.github/ISSUE_TEMPLATE/rfc.md

@@ -0,0 +1,12 @@
+---
+name: RFC (payload profile or spec change)
+about: Propose a payload profile or a change to SPEC.md
+labels: rfc
+---
+**Summary**
+
+**Schema** (JSON Schema, draft 2020-12)
+
+**One synthetic example line**
+
+**Backwards compatibility**

openlogbook-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## What
+
+## Why
+
+## Checklist
+- [ ] Tests added or updated; `uv run pytest` green
+- [ ] No real personal data in fixtures (synthetic only)
+- [ ] No write/update/delete path into the log except `Logbook.append`
+- [ ] If SPEC.md changed: version bumped, `conformance/` regenerated, CHANGELOG entry
+- [ ] Signed-off (`git commit -s`, DCO)

openlogbook-0.1.0/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: { interval: monthly }
+  - package-ecosystem: uv
+    directory: /
+    schedule: { interval: monthly }

openlogbook-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+  schedule:
+    - cron: "17 4 * * 1"   # weekly scorecard
+permissions: { contents: read }
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --group dev
+      - run: uv run ruff check . && uv run ruff format --check .
+      - run: uv run mypy logbook
+      - run: uv run pytest --cov=logbook --cov-report=xml
+      - name: conformance
+        run: uv run logbook verify --root conformance/sample-logbook --expect conformance/expected.json
+      - uses: codecov/codecov-action@v7
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+  scorecard:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions: { security-events: write, id-token: write }
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ossf/scorecard-action@v2
+        with: { results_file: results.sarif, results_format: sarif, publish_results: true }

openlogbook-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: release
+on:
+  push: { tags: ["v*"] }
+permissions: { contents: write, id-token: write, attestations: write }   # id-token: PyPI trusted publishing + Sigstore; attestations: provenance
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: actions/attest-build-provenance@v4      # SLSA provenance for every wheel
+        with: { subject-path: dist/* }
+      - uses: pypa/gh-action-pypi-publish@release/v1  # OIDC; configure "trusted publisher" once on PyPI
+      - uses: softprops/action-gh-release@v3
+        with: { files: dist/*, generate_release_notes: true }

openlogbook-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+.env
+data/
+.DS_Store
+
+# never commit a personal record into the code repo
+/logbook.json
+/logbook/[0-9][0-9][0-9][0-9]/
+/notes/
+/inbox/

openlogbook-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks: [{ id: ruff, args: [--fix] }, { id: ruff-format }]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks: [{ id: end-of-file-fixer }, { id: trailing-whitespace }, { id: check-json }, { id: check-yaml }, { id: detect-private-key }]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks: [{ id: gitleaks }]

openlogbook-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

openlogbook-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,31 @@
+# Architecture — five layers
+
+```
+5  Agents      any agent with MCP: add, ask, confirm, verify. the UI.
+4  Surfaces    day page · timeline · person · books · shared pages
+3  Engines     logbook → days, trips, people, places. versioned. recomputable.
+2  Adapters    one per source. export in → observations out. pure.
+1  Logbook     the folder, the chain, the CLI. the standard.
+```
+
+The dependency arrow points down only. An adapter never knows an engine exists. A surface reads derived rows and notes, never the raw log. Agents are operators, not authors: they may run adapters and draft, they may never write a note, a confirmation or a visibility decision — that stays with the human, enforced in layer 1.
+
+| Layer | Contract | Repo |
+|---|---|---|
+| 1 | the format (SPEC.md); `logbook add/show/verify/export` | this repo |
+| 2 | `run(input_path, since) -> iterator[Observation]`; fixture-tested; no network by default | `logbook-adapter-<source>` |
+| 3 | `pass(logbook, date_range) -> derived rows` carrying `engine_version`; idempotent; stable derived IDs | `logbook-engine` |
+| 4 | reads derived rows + notes; writes only notes and confirmations (as tier-2 lines) | `logbook-web`, `logbook-books` |
+| 5 | MCP server exposing `logbook.add`, `logbook.query`, `logbook.ask`, `logbook.confirm`, `logbook.verify` | `logbook-mcp` |
+
+## Derived is disposable
+
+Days, trips, people and places are computed from the log and can be thrown away. Their IDs are derived from (owner, kind, rounded start, place) so a recompute yields the same ID and human notes stay attached. Human input — notes, confirmations, visibility choices — is written to the log as tier-2 lines, so it survives any recompute and any export.
+
+## The circle (layer 4/5, protocol to be defined)
+
+A shared page is a signed bundle: the day's derived rows the owner chose to share, their notes marked shareable, photo references, and the owner's signature. Transport is undecided (peer-to-peer over a relay vs. a small server); the bundle format will be defined before any transport is built, so that the first two implementations can exchange pages by any means, including a USB stick.
+
+## Reference stack
+
+Python 3.12, no required dependencies for layer 1. Engines may use SQLite as an index; PostGIS is a plugin, never a requirement. Web layer: server-rendered HTML. Everything runs on one machine that is always on, or on a laptop that sometimes is.

openlogbook-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+- Format v0.1: folder layout, envelope, hash chain, tiers, conformance rule.
+- CLI: init, add (text or JSONL), show, verify, export.
+- Conformance fixture with expected head.

openlogbook-0.1.0/CLAUDE.md

@@ -0,0 +1,12 @@
+# For agents working in this repository
+
+You are one of several coding agents that build this project alongside a human captain. Read SPEC.md and ARCHITECTURE.md first.
+
+Hard rules — a change that needs to break one is wrong; stop and say so:
+- Never write to the log except through `Logbook.append`. Never UPDATE or DELETE a line, in code or by hand.
+- Never add real personal data to the repository. Fixtures are synthetic; the sample person lives in Oslo and does not exist.
+- Never add network calls to an adapter's default path.
+- Never change the envelope (SPEC §2–3) without a spec version bump, a regenerated conformance fixture, and an ADR in `docs/adr/`.
+- Test first: write the failing test, run it, implement, run it, commit with `-s`. One issue per task, closed by the commit.
+
+Conventions: `uv` for everything (`uv sync --group dev`, `uv run pytest`, `uv run ruff check --fix .`, `uv run mypy logbook`). Conventional commits (`feat:`, `fix:`, `spec:`, `docs:`, `adapter:`). Plain English names inside the code: Logbook, Line, Day, Note — no metaphors.

openlogbook-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of conduct
+
+This project follows the Contributor Covenant, version 2.1 (https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be kind, be precise, argue about the work. Report problems to the address in the repository profile; the captain handles them privately and promptly.

openlogbook-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+The easiest and most useful thing to build is an adapter for the export you already have.
+
+1. Copy `adapters/template/`.
+2. Put a small, **synthetic** export in `fixture/` — never real data, not even yours.
+3. Write `run(input_path, since)` yielding observations with a `payload.schema`.
+4. Run the tests; the expected output file is generated on first run and checked in.
+5. Open a pull request. Name it `adapter: <source>`.
+
+Rules for every contribution: no network calls unless the adapter is explicitly a live adapter; no writes to any source; nothing that updates or deletes a line in the log — if a change seems to need it, the change is wrong.
+
+Code is Apache-2.0. Contributions to SPEC.md are CC0.

openlogbook-0.1.0/GOVERNANCE.md

@@ -0,0 +1,7 @@
+# Governance
+
+Captain: bighydro. A ship has one captain and the captain signs the log. The captain merges, releases monthly, and writes the CHANGELOG.
+
+The envelope (SPEC §2–3) changes only by major version and ships with a migration tool. Payload profiles change freely through RFCs in `rfcs/`: open a pull request with the schema and one fixture; two weeks of comment; merge.
+
+Decisions are made in public issues. When the steward and a contributor disagree, the captain decides and writes down why in the log (the issue). If the ship ever has three officers of the watch, this file gets replaced with something better.

openlogbook-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Apache License 2.0 — https://www.apache.org/licenses/LICENSE-2.0
+
+Copyright 2026 bighydro
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at the URL above. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+SPEC.md and everything under schema/ and rfcs/ are dedicated to the public domain under CC0 1.0.

openlogbook-0.1.0/LORE.md

@@ -0,0 +1,69 @@
+# Lore — where the logbook comes from
+
+A project needs to know its ancestors. Logbook has two lines of descent, human and computational, and they turn out to be the same line.
+
+## I. The human logbook
+
+**The knot and the board.** In the 1500s a sailor measured a ship's speed by throwing a flat wooden board — the *log* — over the stern on a line knotted at fixed intervals, and counting how many knots ran out while a small sandglass emptied. Speed at sea is still given in *knots* because of that board. The readings were entered in a book beside the helm: the log-book. Course, speed, wind, weather, position, every few hours, in ink, in order, initialled by the officer of the watch. Within a century "logbook" meant the whole record of a voyage: who came aboard, who died, what was sighted, what was decided. It was never written for an audience. It was written because things happened, and because later someone would need to know what actually occurred.
+
+**Truth by construction.** A ship's log is admissible in court. Entries are made at the time, in sequence, in a bound book with numbered pages; an error is struck through with a single line so the original stays legible, and the correction is initialled. Nothing is erased. Nothing is written later and backdated. Three rules — append only, corrections as new entries, never delete — that are four hundred years older than any database and identical to the ones this project enforces.
+
+**The voyages we know only because someone kept the book.** Antonio Pigafetta kept the diary of Magellan's circumnavigation (1519–22); only eighteen men came home, and most of what we know of the first voyage around the earth is his book. James Cook's journals fixed the coastlines of the Pacific. Charles Darwin kept a diary aboard *Beagle* for five years (1831–36); *On the Origin of Species* grew out of those notebooks, twenty years later, because he could reread what he had actually seen rather than what he remembered seeing. Robert Falcon Scott's last diary was found beside his body in the Antarctic in 1912; Shackleton's men kept theirs on the ice for two years and every one of them came home. Lighthouse keepers, weather stations, station masters, mine foremen: for three centuries the ordinary world was run by people making dated entries in ruled books, and the climate scientists of our own century now reconstruct the weather of the 1800s from ships' logs, because those pages are the only instruments that were there.
+
+**The captain's logbook and the pilot's.** Every pilot alive keeps a logbook. It is a legal document: date, aircraft, route, hours, landings, who was in command. A licence is granted on the strength of it and can be lost over it. It is the one place where a pilot's life in the air is true, and pilots are sentimental about theirs in a way they are about nothing else. The captain's log — the phrase is now a joke from television — was the same thing at sea: the commander's own record, in the first person, of what was decided and why.
+
+**The private book.** Beside the official log there was always another book. Marcus Aurelius wrote his *Meditations* for no reader but himself; the Greek title is simply "to himself". Samuel Pepys kept a diary in shorthand for nine years (1660–69) and recorded the plague, the Great Fire, and his own small vanities with equal care; nobody read it for a century and a half. Benjamin Franklin ruled a small book into thirteen virtues and marked each evening's faults with a dot — the first self-tracker. Leonardo's notebooks, Thoreau's journal, the commonplace books in which people for centuries copied what they wanted to keep: none of these were feeds. They were written by one person, for that person, to be reread.
+
+**The captain of my soul.** William Ernest Henley wrote *Invictus* in 1875 from a hospital bed, after losing a foot to tuberculosis of the bone:
+
+> I am the master of my fate,
+> I am the captain of my soul.
+
+The poem is a claim of ownership over one's own voyage. A logbook is the instrument that makes the claim true: you cannot be the captain of a voyage no one recorded.
+
+## II. The computational logbook
+
+**Same word, same object.** When engineers needed a name for an ordered, append-only, timestamped record of what a machine had done, they took the sailor's word. Operating systems have written *log files* since the 1960s; Unix `syslog` (Eric Allman, 1980s) gave every program a common place to write a dated line. The metaphor was exact: something happened, write it down, in order, don't go back.
+
+**The log as the truth.** Database engineers discovered that the log was not a byproduct of the database — it *was* the database. The write-ahead log (formalised in the ARIES papers, C. Mohan and colleagues, 1992) writes every change to an append-only file *before* touching the tables, so that after a crash the tables can be rebuilt from the log, but the log can never be rebuilt from the tables. Journaling filesystems did the same for disks. Leslie Lamport's *Time, Clocks, and the Ordering of Events* (1978) showed that in a distributed system the only thing that can be agreed on is an order of events — a log. Jay Kreps's essay *The Log* (LinkedIn, 2013), which led to Apache Kafka, says it in one sentence: the log is the source of truth; every table, index, cache and view is a derived, disposable projection of it. This project's first principle — the log is immutable, moments are disposable, notes are sacred — is that sentence applied to a life.
+
+**Making the log unforgeable.** Ralph Merkle (1979) showed how to hash a tree of records so that changing any leaf changes the root. Stuart Haber and W. Scott Stornetta (1991) chained timestamped documents by hashing each one together with the previous — a linked hash chain, built so that no one, not even the keeper, could later alter a page without breaking every page after it. Git (2005) made every commit a hash of its content and its parent, so that a repository's history is verifiable by anyone who holds it. Bitcoin (2008) put the same chain in public. Logbook uses the 1991 version: one person's private chain, verifiable by that person, needing no one else's agreement. The ship's log struck a line through errors and initialled the page; the hash chain is the initial.
+
+**The dream of a machine that remembers for you.** Vannevar Bush described the *memex* in 1945 — a desk that stores everything a person reads and the trails between them. Ted Nelson's Xanadu, Douglas Engelbart's augmentation, and the hypertext that became the web all descend from it. Steve Mann wore a camera and computer through the 1990s, logging his life continuously. Gordon Bell at Microsoft spent the 2000s on MyLifeBits, scanning and recording everything he did, and wrote *Total Recall* (2009) about it. The Quantified Self movement (Gary Wolf and Kevin Kelly, 2007) turned self-tracking into a practice. Every one of these got the *record* right and left the *recount* and the *circle* unbuilt: a life captured and never read back, held by one person or one company, shared with no one. Logbook is the next step on that trail, with the two missing parts.
+
+## III. Fusing the two sciences
+
+The fusion is not a metaphor; the same structure appears on both sides.
+
+| Computer science | Human science | In Logbook |
+|---|---|---|
+| The log is the source of truth; views are derived and disposable | Autobiographical memory is reconstructive: we do not replay the past, we rebuild it each time from fragments, and the rebuild drifts (Bartlett, 1932; Loftus) | The record is fixed; the recount is a view that can be regenerated, and every sentence links to its evidence so the drift is visible |
+| Write-ahead: record before you act on it | The *experiencing self* and the *remembering self* disagree; memory keeps the peak and the end and drops the duration (Kahneman) | Observations are written at the time by instruments; the evening note is the remembering self's line, kept separate and marked as such |
+| Idempotent replay; recompute from history when the rules improve | Reminiscence: rereading a diary changes what a memory means without changing what happened | Engines are versioned and re-run over all history; notes are never touched |
+| Hash chain: tamper-evident, verifiable by the holder | Narrative identity: a self is the story a person can tell about the connected events of their life (McAdams) | A verifiable chain is a story that cannot be quietly rewritten, by you or anyone |
+| Access control, capability tokens | Trust is built in dyads, one relationship at a time, by reciprocal disclosure (Altman & Taylor's social penetration theory) | The circle: a page for a page, named person to named person, no broadcast |
+| Garbage collection is forbidden; the log is never pruned | Forgetting is the default: the Ebbinghaus curve (1885) drops most of a day within a week | Never prune. The instrument remembers so that you may forget freely and reread when it matters |
+| Derived metrics: counters, dashboards | Gratitude and expressive writing measurably improve wellbeing (Pennebaker, 1986; Emmons & McCullough, 2003) — and extrinsic rewards crowd out intrinsic motivation (Deci) | Reveal, never reward: the logbook may show you a first or a milestone; it never scores you |
+
+The rule of thumb for any new feature: find its twin on the other side of the table. If a computing idea has no human counterpart, it is plumbing and should be invisible. If a human idea has no computing counterpart, it is a note — and notes are sacred.
+
+## IV. The statement against the attention economy
+
+Herbert Simon said it in 1971: a wealth of information creates a poverty of attention. The industry that followed — Tim Wu called its practitioners *the attention merchants* — learned to harvest that scarce attention and sell it. Aza Raskin designed infinite scroll in 2006 and has spent years apologising for it. Shoshana Zuboff named the model *surveillance capitalism* (2019): your record, held by someone else, used to predict and steer you. Neil Postman had warned in 1985 that we were amusing ourselves to death; Jaron Lanier gave ten arguments for deleting your accounts; Cal Newport wrote the manual for leaving.
+
+Every one of these critics described the disease. Fewer built the alternative, and the alternative cannot be "less feed"; it has to be a different object. A feed is other people's present, ranked by a machine to keep you looking, held by a company, measured in your attention. A logbook is your own past, in order, held by you, measured in nothing. The feed asks *what is happening?* and never lets you finish answering. The logbook asks *what happened?* and lets you close the book.
+
+The design decisions follow directly:
+
+- **No feed.** There is no page that shows other people's lives. There is a page that shows one day of yours.
+- **No audience.** Sharing is a page handed to a named person who hands one back. There is no post, no follower, no public.
+- **No counts.** Nothing is liked, viewed, or ranked. Nothing near a person has a number.
+- **No engagement loop.** One evening question; ignore it forever and nothing happens.
+- **No harvest.** The files are on your disk. There is no server to sell to, no model trained on you without your key.
+- **Reveal, never reward.** The logbook can tell you it was your hundredth flight hour or your first time in Portugal. It cannot give you a badge for it.
+
+Social media promised connection and delivered an audience. A logbook makes the old promise honestly: you, your voyage, the few people you choose to show it to — and a book that will still open in fifty years, because it is only paper made of files.
+
+*You are the captain of your ship. This is the log.*
+
+— bighydro, captain of this one

openlogbook-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: openlogbook
+Version: 0.1.0
+Summary: A diary that writes itself. Your life, in a folder.
+Project-URL: Homepage, https://github.com/bighydro/logbook
+Project-URL: Specification, https://github.com/bighydro/logbook/blob/main/SPEC.md
+Project-URL: Changelog, https://github.com/bighydro/logbook/blob/main/CHANGELOG.md
+Author: bighydro
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: append-only,diary,hash-chain,lifelog,local-first,logbook,personal-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Logbook
+
+**A diary that writes itself.**
+
+Your life already gets recorded — by your phone, your photos, your calendar, your messages. Logbook writes it all down once, in one folder that only you hold, and reads it back to you as days. You hand a page to someone you care about; they hand one back.
+
+It is the opposite of social media: no feed, no followers, no likes, no counts. Reveal, never reward. Nothing leaves without a name.
+
+![How Logbook works](docs/how-it-works.svg)
+
+## Sixty seconds
+
+```bash
+pipx install openlogbook        # or: pip install .
+logbook init                    # creates ~/Logbook and your key
+logbook add "had lunch with a friend by the lake"
+logbook add ~/Downloads/takeout.zip     # any export, no flags
+logbook show today
+logbook verify                  # the chain is intact
+```
+
+That is the whole product. Everything else is a layer somebody plugs in.
+
+## What is in the folder
+
+```
+~/Logbook/
+  logbook/          the record. one file per month. append only. never edit.
+    2026/09.jsonl
+  inbox/            drop anything here. it gets read, then moved to done/.
+  notes/            what you write. plain Markdown, one file per day.
+  logbook.json      who this is, your timezone, the chain head.
+```
+
+Nothing here needs the app to make sense. Open the files in any editor twenty years from now.
+
+If you also keep a clone of this repository, set `LOGBOOK_HOME` to your record's folder and pass that path to `logbook init`. On a case-insensitive disk (macOS by default) `~/Logbook` and a clone named `~/logbook` are the same folder; `init` refuses a folder that contains `pyproject.toml`, `.git` or `logbook/__init__.py`, and the CLI never picks such a folder as your record.
+
+## Three rules
+
+1. **Append only.** Every line is hash-chained to the one before. A broken chain is an error, never repaired silently.
+2. **Files first.** No database is required to read, verify or export a logbook. Databases are caches.
+3. **Nothing leaves.** Personal lines are encrypted with your key. There is no server. Sharing is a page handed to a named person.
+
+## Read next
+
+- [VISION.md](VISION.md) — why, and the rules the product refuses to break
+- [LORE.md](LORE.md) — where the logbook comes from: ships, pilots, diaries, and the log in computing
+- [SPEC.md](SPEC.md) — the format, one page; this is the part meant to become a standard
+- [ARCHITECTURE.md](ARCHITECTURE.md) — the five layers and what each may depend on
+- [ROADMAP.md](ROADMAP.md) — what ships when
+- [CONTRIBUTING.md](CONTRIBUTING.md) — the easiest thing to build is an adapter for the export you have
+
+## Status
+
+v0.1 — the format, the CLI (init, add, show, verify, export) and the conformance fixture. Engines (days, trips, people) and the circle (sharing) are the next layers; see the roadmap.
+
+Apache-2.0 for code. The specification is CC0.

openlogbook-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Logbook
+
+**A diary that writes itself.**
+
+Your life already gets recorded — by your phone, your photos, your calendar, your messages. Logbook writes it all down once, in one folder that only you hold, and reads it back to you as days. You hand a page to someone you care about; they hand one back.
+
+It is the opposite of social media: no feed, no followers, no likes, no counts. Reveal, never reward. Nothing leaves without a name.
+
+![How Logbook works](docs/how-it-works.svg)
+
+## Sixty seconds
+
+```bash
+pipx install openlogbook        # or: pip install .
+logbook init                    # creates ~/Logbook and your key
+logbook add "had lunch with a friend by the lake"
+logbook add ~/Downloads/takeout.zip     # any export, no flags
+logbook show today
+logbook verify                  # the chain is intact
+```
+
+That is the whole product. Everything else is a layer somebody plugs in.
+
+## What is in the folder
+
+```
+~/Logbook/
+  logbook/          the record. one file per month. append only. never edit.
+    2026/09.jsonl
+  inbox/            drop anything here. it gets read, then moved to done/.
+  notes/            what you write. plain Markdown, one file per day.
+  logbook.json      who this is, your timezone, the chain head.
+```
+
+Nothing here needs the app to make sense. Open the files in any editor twenty years from now.
+
+If you also keep a clone of this repository, set `LOGBOOK_HOME` to your record's folder and pass that path to `logbook init`. On a case-insensitive disk (macOS by default) `~/Logbook` and a clone named `~/logbook` are the same folder; `init` refuses a folder that contains `pyproject.toml`, `.git` or `logbook/__init__.py`, and the CLI never picks such a folder as your record.
+
+## Three rules
+
+1. **Append only.** Every line is hash-chained to the one before. A broken chain is an error, never repaired silently.
+2. **Files first.** No database is required to read, verify or export a logbook. Databases are caches.
+3. **Nothing leaves.** Personal lines are encrypted with your key. There is no server. Sharing is a page handed to a named person.
+
+## Read next
+
+- [VISION.md](VISION.md) — why, and the rules the product refuses to break
+- [LORE.md](LORE.md) — where the logbook comes from: ships, pilots, diaries, and the log in computing
+- [SPEC.md](SPEC.md) — the format, one page; this is the part meant to become a standard
+- [ARCHITECTURE.md](ARCHITECTURE.md) — the five layers and what each may depend on
+- [ROADMAP.md](ROADMAP.md) — what ships when
+- [CONTRIBUTING.md](CONTRIBUTING.md) — the easiest thing to build is an adapter for the export you have
+
+## Status
+
+v0.1 — the format, the CLI (init, add, show, verify, export) and the conformance fixture. Engines (days, trips, people) and the circle (sharing) are the next layers; see the roadmap.
+
+Apache-2.0 for code. The specification is CC0.

openlogbook-0.1.0/ROADMAP.md

@@ -0,0 +1,15 @@
+# Roadmap
+
+Phases, not dates. Each phase ends with something a stranger can use.
+
+**0 — the format (now).** SPEC v0.1, JSON Schema, conformance fixture, this CLI. Verify passes on the sample logbook.
+
+**1 — three drops.** Adapters for Google Takeout (location, photos, calendar, mail headers, YouTube, Chrome), Apple Health (sleep, steps, workouts) and WhatsApp exports (messages, tier 2); an email adapter follows as its own task. `logbook add <zip>` sniffs which is which. Encryption at rest for tiers 2–3 (spec v0.2).
+
+**2 — days.** The reference engine: stays, moves, flights, places, meetings, people, trips. `logbook show <day>` becomes a page. The MCP server ships, so any agent can add, ask and confirm.
+
+**3 — the circle.** The shared-page bundle format; exchange between two logbooks by file; then a transport. Per-person pages: last real contact, shared moments, birthdays.
+
+**4 — the community.** Adapter template and bounty list (Strava, Garmin, Immich, Dawarich, Telegram, iMessage, bank CSV, Spotify, Letterboxd). Payload-profile RFCs. A second implementation in another language by someone who only read the spec.
+
+**5 — v1.0.** The envelope frozen; conformance badge; books and published pages as community layers; data-portability law gives every service a reason to emit the format.

openlogbook-0.1.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security
+
+This software stores a person's whole life. Treat every bug as if it were serious.
+
+Report vulnerabilities privately to the address in the repository profile. You will get a reply within 48 hours. Fixes ship before disclosure.
+
+Threat model (v0.1): the logbook lives on a machine the owner controls. The adversary is anyone who obtains the files. Tier 1 is plain; tiers 2 and 3 are encrypted at rest from v0.2 with a key that never leaves the owner's machine. There is no server and no account. Adapters are untrusted code: they run without network by default and can only append.

openlogbook-0.1.0/SPEC.md

@@ -0,0 +1,76 @@
+# Logbook format — specification v0.1
+
+Status: draft. License: CC0. Anyone may implement this without asking.
+
+The key words MUST, MUST NOT, SHOULD and MAY are to be interpreted as described in RFC 2119.
+
+## 1. The folder
+
+```
+<root>/
+  logbook.json            identity and chain head
+  logbook/<YYYY>/<MM>.jsonl   the record
+  notes/<YYYY>/<YYYY-MM-DD>.md   free text, optional
+  inbox/                  optional; not part of conformance
+```
+
+`logbook.json`:
+
+```json
+{"format": "logbook/0.1", "owner_id": "<uuid>", "created_at": "<RFC3339 UTC>",
+ "timezone": "<IANA tz>", "seq": 4181, "head": "<hex sha256>"}
+```
+
+## 2. The line (the envelope)
+
+One observation per line, JSON, UTF-8, newline-terminated, in `logbook/<YYYY>/<MM>.jsonl`, where YYYY and MM are taken from `at` in UTC.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | uuid | UUIDv7 (RFC 9562) recommended; identity of this line; outside the hash so it may be assigned at write time |
+| `seq` | integer ≥ 1 | position in the owner's chain; strictly increasing by 1 |
+| `at` | RFC3339 UTC | when the thing happened (not when it was recorded) |
+| `end` | RFC3339 UTC or null | when it stopped, if it had a duration |
+| `tz` | IANA name | the owner's timezone at `at` |
+| `source` | string | who reported it: `manual`, `apple-health`, `google-takeout`, … |
+| `kind` | string | what it is: `location`, `photo`, `event`, `message`, `sleep`, `note`, … |
+| `tier` | 1, 2 or 3 | privacy tier, §4 |
+| `payload` | object | whatever the source said; MUST contain `schema`, e.g. `"location/v1"` |
+| `recorded_at` | RFC3339 UTC | when the line was written |
+| `prev` | hex sha256 | hash of the previous line; 64 zeros for the first |
+| `hash` | hex sha256 | §3 |
+
+Unknown fields MUST be preserved by readers and MUST NOT be added by writers at the top level; extensions go inside `payload`.
+
+## 3. The chain
+
+```
+content = canonical_json({at, end, tz, source, kind, tier, payload})
+hash    = sha256( prev + "|" + seq + "|" + sha256(content) + "|" + recorded_at )
+```
+
+`canonical_json` is RFC 8785 (JSON Canonicalization Scheme): keys sorted by UTF-16 code units, no whitespace, UTF-8, ES6 number serialisation, no NaN/Infinity. A logbook is **valid** when, taking every line from every file and ordering by `seq` (files partition by the month of `at`, so backfilled history lands in old files; file order is not chain order), every line's `seq` is the previous plus one, every `prev` equals the previous `hash`, every `hash` recomputes, and `logbook.json` `seq`/`head` match the last line.
+
+Corrections are new lines. A source that revises an earlier record writes a new line with `payload.supersedes = "<id>"`. Nothing is ever rewritten or removed.
+
+## 4. Tiers
+
+| Tier | Typical content | At rest |
+|---|---|---|
+| 1 | location, photo metadata, calendar, public activity | plain |
+| 2 | notes, messages, decisions, confirmations, personal mail | encrypted with the owner's key (v0.2) |
+| 3 | money, health | encrypted with the owner's key (v0.2) |
+
+Derived data inherits the highest tier of its evidence. v0.1 conformance requires the field; v0.2 will define the encryption envelope for tiers 2–3 (`payload_enc` replacing `payload`, age/X25519 recipient = the owner's key).
+
+## 5. Payload profiles
+
+The envelope is the standard. Payloads are versioned by `payload.schema` and proposed as RFCs in `rfcs/`. Seed profiles: `location/v1`, `photo/v1`, `event/v1`, `message/v1`, `transaction/v1`, `health-sample/v1`, `note/v1`. A logbook with unknown schemas is still valid.
+
+## 6. Conformance
+
+An implementation is conformant when `verify` on `conformance/sample-logbook` reports valid and prints the head in `conformance/expected.json`, and when appending one line to a copy of it yields a logbook that still verifies. Level 2 conformance (v0.2) adds encryption. Two independent implementations must agree before v1.0 is frozen.
+
+## 7. What this spec does not say
+
+Nothing about servers, databases, user interfaces, engines, agents, or how two logbooks exchange pages. Those are layers. The spec is finished when it is small enough to implement in an afternoon.

openlogbook-0.1.0/VISION.md

@@ -0,0 +1,39 @@
+# Vision
+
+## One sentence
+
+A logbook is a folder of plain files that records what happened to you, that only you hold, and that anything can plug into.
+
+## Three ideas, and only three
+
+**The record.** Everything that happened to you, written down once, in files you own. Your phone, photos, calendar, messages and every other export you can get your hands on flow into one append-only, hash-chained log. Nothing is ever edited. Nothing is ever pruned. If every app you use disappeared tomorrow, the record stays.
+
+**The recount.** The record reads your life back to you without your effort. Every day gets a page. Days become trips, trips become chapters; people, places, meals, decisions and achievements appear on their own. You only confirm, correct, and add a line in your own words. A diary asks you to write; a logbook writes you.
+
+**The circle.** You hand a page to a named person, and they hand one back. Two logbooks, one shared moment, each side keeps its own words and photos. No audience, no feed, no counts — you see their side of a dinner because you were at the dinner.
+
+## What it refuses to have
+
+The opposite of social media is not a feature; it is a list of things the product will never contain:
+
+- no feed, no timeline of other people
+- no followers, likes, reactions, or view counts
+- no ranking, no algorithm choosing what you see
+- no public-by-default; every share names a person
+- no streaks, no scores, no metrics near people
+- no engagement loop; there is one evening question and it can be ignored forever
+- nothing leaves without a named recipient
+
+## Reveal, never reward
+
+A logbook may *reveal* — your first time in a country, your hundredth flight hour, the year with the most dinners at home — and may never *reward*. Revealing invites gratitude; rewarding invites compulsion. That single line is the product philosophy, and it is the line social media crossed.
+
+Life is an adventure that can only be replayed when it is logged, the way chess is a game because the board remembers every move. The logbook is the board. The adventure is yours.
+
+## Why "logbook"
+
+Pilots and sailors keep logbooks: dated, factual, in order, never edited, kept for years because one day someone needs to know what actually happened. Computing borrowed the word — log files, the commit log, the write-ahead log — for an append-only record that is the source of truth from which everything else is derived. That is exactly the structure here. The name is not a metaphor from computing; it is the original object computing took the metaphor from, returned to its purpose: a person keeping a true record of a voyage.
+
+## Where it can go
+
+A logbook is signed by a key only you hold. A long, verifiable record that belongs to a key is a stronger claim of identity than any platform can issue — not *who you are*, but *what happened to you*, proven by you. We are modest about this in year one. The first real protocol question is how two logbooks exchange a page. Get that right and the rest follows.

openlogbook-0.1.0/adapters/README.md

@@ -0,0 +1,9 @@
+# Adapters
+
+One adapter per source. `run(input_path, since) -> iterator[dict]` where each dict has the keys `at, end, tz, source, kind, tier, payload` (see SPEC §2) — everything except the chain fields, which the logbook adds on append.
+
+Rules: pure by default (no network), never write to the source, never invent `tier` lower than the source deserves, fixture-tested with **synthetic** data only.
+
+Planned first (ADR 0008): `google-takeout`, `apple-health`, `whatsapp`, then `email`.
+
+Wanted — pick one and open an issue with the adapter template: immich, dawarich, strava, garmin, apple-fitness, eight-sleep, oura, withings, telegram, imessage, signal, gmail, ics-calendar, google-calendar, flighty, flightradar24, notion, obsidian, spotify, apple-music, letterboxd, goodreads, kindle-highlights, youtube-history, chrome-history, twitter-archive, instagram-export, bank-csv (generic, with per-bank mapping files), revolut, paypal, amazon-orders, uber, airbnb, vivino, steam, boat-passage logs.

openlogbook-0.1.0/adapters/template/README.md

@@ -0,0 +1,3 @@
+# adapter: example
+
+What export it reads, how to get that export from the source (menu path), which `kind`s and `payload.schema`s it produces, and what tier. Fixture in `fixture/` is synthetic.