napper-sync 0.1.0__tar.gz

napper_sync-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 - 2026-11-08
+
+First public release.
+
+- Napper client: OTP login, automatic token refresh, read/write/delete for all
+  eleven log categories, local field validation, 429 back-off.
+- Famly client and mapping: calendar endpoint, sleep/meal/diaper → Napper,
+  unknown event types reported instead of dropped.
+- Sync core with duplicate detection (10-minute fuzz, span overlap, one-per-day
+  markers), dry-run by default.
+- Corrections: Famly entries carry a deterministic Napper ID, so a later change
+  at the nursery (end time, note, diaper content) updates the entry instead of
+  being skipped. CSV/JSON rows may pin an `id` for the same effect.
+- CSV/JSON import.
+- Discord notifications; systemd units and a Windows task example.
+- Documentation of both APIs as observed.

napper_sync-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+Thanks for taking a look. Two things matter most here, because both APIs are
+undocumented and change without notice:
+
+1. **Verify against the real API before changing a request shape.** The mock
+   in `tests/conftest.py` reproduces what was observed; it cannot tell you
+   that Napper changed. `tools/roundtrip_categories.py` can - it writes one
+   entry per category far in the past and cleans up after itself.
+2. **Never commit anything from `~/.config/napper-sync/`**, and strip IDs,
+   names and tokens from any API output you paste into an issue. Child IDs
+   and account IDs are UUIDs; the `.gitignore` catches the obvious files but
+   not a pasted JSON blob.
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format .
+```
+
+## Adding a Famly event type
+
+1. Capture one real event with `napper-sync famly calendar <from> <to> --json`
+   and anonymise it (replace the child's name in `title`, drop `originator`
+   and `invitees`).
+2. Add a branch in `famly_mapping.translate()` and a test in
+   `tests/test_famly_mapping.py` using the anonymised event.
+3. If Napper needs a category or field that `categories.py` does not have,
+   confirm the field name against your own history
+   (`tools/analyze_categories.py`) first.
+
+## Style
+
+Ruff handles formatting and linting (`ruff format`, `ruff check`). Keep the
+standard-library-only rule for the package itself; dev tooling may use
+anything.

napper_sync-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Wuestling
+
+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.

napper_sync-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+# Make the source distribution self-contained: the tests need conftest.py and
+# reach into tools/, and packagers want the docs and examples next to the code.
+graft tests
+graft tools
+graft docs
+graft examples
+include CHANGELOG.md CONTRIBUTING.md
+global-exclude __pycache__ *.py[cod] .coverage

napper_sync-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: napper-sync
+Version: 0.1.0
+Summary: Unofficial Napper baby-tracker API client, and a sync that imports what the nursery logs in Famly.
+Author: Patrick Wuestling
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PW-CODING/napper-sync
+Project-URL: Issues, https://github.com/PW-CODING/napper-sync/issues
+Project-URL: Documentation, https://github.com/PW-CODING/napper-sync/tree/main/docs
+Project-URL: Changelog, https://github.com/PW-CODING/napper-sync/blob/main/CHANGELOG.md
+Keywords: napper,famly,baby,baby-tracker,sleep-tracker,nursery,daycare,childcare,kita,krippe,sync,api-client
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# napper-sync
+
+**Sync what your nursery logs in [Famly](https://famly.co) - naps, meals, diaper
+changes - into the [Napper](https://napper.app) baby tracker, automatically. Also an
+unofficial Python client for the Napper API.**
+
+[![CI](https://github.com/PW-CODING/napper-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/PW-CODING/napper-sync/actions/workflows/ci.yml)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Auf Deutsch:** Überträgt automatisch, was die Kita in Famly einträgt - Schlaf, Mahlzeiten
+und Windelwechsel - in die Baby-App Napper. Kein Abtippen am Abend, keine Duplikate, und
+nachträgliche Korrekturen der Kita werden übernommen. Läuft per Zeitplan auf einem
+Raspberry Pi oder jedem anderen Rechner und braucht nur die Python-Standardbibliothek.
+Die Dokumentation ist englisch, Fragen und Issues gern auch auf Deutsch.
+
+Napper is a sleep-and-care tracker for babies. Famly is the app many nurseries
+use to tell parents what happened during the day. If your child is in a
+Famly nursery and you track at home with Napper, you end up typing the
+nursery's entries into Napper by hand every evening. This tool does that for
+you, every hour, without creating duplicates.
+
+Along the way it documents two APIs that have no public documentation - see
+[`docs/`](https://github.com/PW-CODING/napper-sync/tree/main/docs).
+
+> **Disclaimer.** This project is not affiliated with, endorsed by, or supported by
+> Napper AB or Famly ApS. It talks to private, undocumented APIs that the official
+> apps use internally. Those APIs may change or disappear with any app update, and
+> using them may not be covered by the services' terms - check the terms that apply
+> to your account before you decide. Use it with your own account, for your own
+> child, at your own risk; how you use it is your responsibility.
+
+## What it does
+
+- **Napper API client** - log in with the e-mailed one-time code, read the
+  history, write and delete entries in all eleven categories Napper knows
+  (nap, bedtime, woke up, night waking, nursing, bottle, solids, pumping,
+  diaper, temperature, medicine), with field validation before anything is sent.
+- **Famly → Napper sync** - reads the nursery's daily events and creates the
+  matching Napper entries, marked `(Famly)` so you can tell them apart. When
+  the nursery corrects an entry later, the Napper entry follows.
+- **Safe by default** - every write is a dry run unless you pass `--live`;
+  duplicate detection makes repeated runs harmless; the Napper rate limit is
+  handled with back-off.
+- **File import** - CSV or JSON for anything else you want to get into Napper.
+- **Unattended operation** - systemd timer, Discord notifications on failure
+  and on successful imports, tokens refreshed automatically.
+
+Standard library only; no runtime dependencies.
+
+## Install
+
+```bash
+pipx install git+https://github.com/PW-CODING/napper-sync
+# or
+pip install --user git+https://github.com/PW-CODING/napper-sync
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+napper-sync login you@example.com     # Napper e-mails a code; paste it
+napper-sync babies                    # find your baby's ID
+napper-sync config init               # write ~/.config/napper-sync/config.toml
+#   -> put the baby ID into [napper] baby_id
+
+napper-sync logs 2026-09-01 2026-09-07          # read a week
+napper-sync add nap 2026-09-18T13:00 2026-09-18T14:20          # dry run
+napper-sync add nap 2026-09-18T13:00 2026-09-18T14:20 --live   # write
+napper-sync add diaper 2026-09-18T15:30 --set diaperContent=WET --live
+napper-sync add medicine 2026-09-18T19:00 --comment "Vitamin D" --live
+napper-sync categories                # every category, field and allowed value
+```
+
+### Famly sync
+
+```bash
+napper-sync famly token <VALUE>       # from localStorage["famly.accessToken"] in a logged-in browser
+napper-sync famly children            # -> [famly] child_id in the config
+napper-sync famly calendar 2026-09-14 2026-09-18    # what the nursery logged
+
+napper-sync sync-famly                # dry run: shows what would be written
+napper-sync sync-famly --live         # write it
+```
+
+To run this hourly on a Raspberry Pi with Discord alerts, see
+[`docs/deployment.md`](https://github.com/PW-CODING/napper-sync/blob/main/docs/deployment.md).
+
+### Importing a file
+
+```bash
+napper-sync sync-file entries.csv --live
+```
+
+Columns `start,end,category,comment` plus any category field as a further
+column; see [`examples/entries.example.csv`](https://github.com/PW-CODING/napper-sync/blob/main/examples/entries.example.csv).
+An optional `id` column pins the Napper ID, so importing a corrected file
+updates the entries instead of duplicating them.
+Categories accept English or German short names (`nap`/`nickerchen`,
+`diaper`/`windel`, `bottle`/`flasche`, …).
+
+## How it stays safe
+
+| Risk | Answer |
+|---|---|
+| Writing by accident | every write and delete is a dry run without `--live` |
+| Duplicates from repeated runs | Famly entries get a stable ID derived from child, category and start, so a repeated run rewrites the same entry instead of adding one; everything else is skipped if the same category exists within 10 minutes or overlaps; day markers are one-per-day |
+| Corrections at the nursery | a changed end time, note or diaper content overwrites the Napper entry on the next run; fields added by hand in the app are kept |
+| Hammering the API | 429 responses are parsed and retried with the server's requested delay |
+| Bad data | field names, enum values and ranges are validated locally before a request is built |
+| Silent breakage | Discord message on expired token, failed write, crashed run; unknown Famly event types are listed, never dropped |
+
+## Project layout
+
+```
+src/napper_sync/
+  napper.py          Napper API client (auth, read, write, delete)
+  categories.py      what each category expects - the data model
+  sync.py            Entry, duplicate detection, the sync loop
+  sources.py         CSV / JSON sources
+  famly.py           Famly API client
+  famly_mapping.py   Famly events -> Napper entries
+  notify.py          Discord webhook
+  config.py          ~/.config/napper-sync/
+  cli.py             the napper-sync command
+tools/               research scripts: analyse history, rediscover endpoints, round-trip and correction checks
+examples/            config, data files, systemd units, Windows task
+docs/                what is known about both APIs, and how to deploy
+tests/               pytest suite against an in-process mock of the Napper API
+```
+
+## Documentation
+
+- [docs/napper-api.md](https://github.com/PW-CODING/napper-sync/blob/main/docs/napper-api.md) - endpoints, auth, the log object,
+  all categories and fields, the traps (seconds in a field called minutes,
+  percent-encoded comments, date-based IDs), and how the write path was found
+- [docs/famly-api.md](https://github.com/PW-CODING/napper-sync/blob/main/docs/famly-api.md) - instances, token, the calendar
+  endpoint and its event shapes
+- [docs/deployment.md](https://github.com/PW-CODING/napper-sync/blob/main/docs/deployment.md) - systemd timer, hardening, Discord
+
+## Development
+
+```bash
+git clone https://github.com/PW-CODING/napper-sync && cd napper-sync
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+The tests run against an in-process HTTP mock that reproduces the real API's
+quirks (whole-day responses on write, 429 throttling, token refresh). Nothing
+touches a real account.
+
+Tools under `tools/` do talk to the real API and are meant for the day an app
+update breaks something: `probe_write_path.py` rediscovers the write endpoint,
+`roundtrip_categories.py` writes one entry per category far in the past,
+checks it and deletes it again, `analyze_categories.py` summarises which
+fields your own history actually uses, and `probe_corrections.py` checks that
+a correction made later at the nursery updates the Napper entry in place.
+
+## Contributing
+
+Issues and pull requests are welcome, in English or German. If an app update
+changed something, the most useful report includes the output of
+`tools/roundtrip_categories.py` or of `napper-sync famly calendar` for a day
+with the new event type (with names and IDs removed).
+
+## Related projects
+
+Community projects around the same two apps, none of which connects them:
+
+- [home-assistant-napper](https://github.com/g-nogueira/home-assistant-napper) -
+  read-only Napper integration for Home Assistant
+- [ha-napper](https://github.com/bbruenings/ha-napper) - another Home Assistant
+  integration for Napper
+- [napper-export](https://github.com/brittraee/napper-export) - export a child's
+  complete Napper history
+- [famly-fetch](https://github.com/jacobbunk/famly-fetch) - download your child's
+  photos from Famly
+
+## Acknowledgements
+
+Reading the Napper API was first worked out by
+[brittraee/napper-export](https://github.com/brittraee/napper-export) and
+[g-nogueira/home-assistant-napper](https://github.com/g-nogueira/home-assistant-napper);
+the OTP login flow and request headers here follow their findings. Writing,
+deleting, the category model and the Famly side were worked out for this
+project.
+
+## License
+
+[MIT](https://github.com/PW-CODING/napper-sync/blob/main/LICENSE)

napper_sync-0.1.0/README.md

@@ -0,0 +1,194 @@
+# napper-sync
+
+**Sync what your nursery logs in [Famly](https://famly.co) - naps, meals, diaper
+changes - into the [Napper](https://napper.app) baby tracker, automatically. Also an
+unofficial Python client for the Napper API.**
+
+[![CI](https://github.com/PW-CODING/napper-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/PW-CODING/napper-sync/actions/workflows/ci.yml)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Auf Deutsch:** Überträgt automatisch, was die Kita in Famly einträgt - Schlaf, Mahlzeiten
+und Windelwechsel - in die Baby-App Napper. Kein Abtippen am Abend, keine Duplikate, und
+nachträgliche Korrekturen der Kita werden übernommen. Läuft per Zeitplan auf einem
+Raspberry Pi oder jedem anderen Rechner und braucht nur die Python-Standardbibliothek.
+Die Dokumentation ist englisch, Fragen und Issues gern auch auf Deutsch.
+
+Napper is a sleep-and-care tracker for babies. Famly is the app many nurseries
+use to tell parents what happened during the day. If your child is in a
+Famly nursery and you track at home with Napper, you end up typing the
+nursery's entries into Napper by hand every evening. This tool does that for
+you, every hour, without creating duplicates.
+
+Along the way it documents two APIs that have no public documentation - see
+[`docs/`](https://github.com/PW-CODING/napper-sync/tree/main/docs).
+
+> **Disclaimer.** This project is not affiliated with, endorsed by, or supported by
+> Napper AB or Famly ApS. It talks to private, undocumented APIs that the official
+> apps use internally. Those APIs may change or disappear with any app update, and
+> using them may not be covered by the services' terms - check the terms that apply
+> to your account before you decide. Use it with your own account, for your own
+> child, at your own risk; how you use it is your responsibility.
+
+## What it does
+
+- **Napper API client** - log in with the e-mailed one-time code, read the
+  history, write and delete entries in all eleven categories Napper knows
+  (nap, bedtime, woke up, night waking, nursing, bottle, solids, pumping,
+  diaper, temperature, medicine), with field validation before anything is sent.
+- **Famly → Napper sync** - reads the nursery's daily events and creates the
+  matching Napper entries, marked `(Famly)` so you can tell them apart. When
+  the nursery corrects an entry later, the Napper entry follows.
+- **Safe by default** - every write is a dry run unless you pass `--live`;
+  duplicate detection makes repeated runs harmless; the Napper rate limit is
+  handled with back-off.
+- **File import** - CSV or JSON for anything else you want to get into Napper.
+- **Unattended operation** - systemd timer, Discord notifications on failure
+  and on successful imports, tokens refreshed automatically.
+
+Standard library only; no runtime dependencies.
+
+## Install
+
+```bash
+pipx install git+https://github.com/PW-CODING/napper-sync
+# or
+pip install --user git+https://github.com/PW-CODING/napper-sync
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+napper-sync login you@example.com     # Napper e-mails a code; paste it
+napper-sync babies                    # find your baby's ID
+napper-sync config init               # write ~/.config/napper-sync/config.toml
+#   -> put the baby ID into [napper] baby_id
+
+napper-sync logs 2026-09-01 2026-09-07          # read a week
+napper-sync add nap 2026-09-18T13:00 2026-09-18T14:20          # dry run
+napper-sync add nap 2026-09-18T13:00 2026-09-18T14:20 --live   # write
+napper-sync add diaper 2026-09-18T15:30 --set diaperContent=WET --live
+napper-sync add medicine 2026-09-18T19:00 --comment "Vitamin D" --live
+napper-sync categories                # every category, field and allowed value
+```
+
+### Famly sync
+
+```bash
+napper-sync famly token <VALUE>       # from localStorage["famly.accessToken"] in a logged-in browser
+napper-sync famly children            # -> [famly] child_id in the config
+napper-sync famly calendar 2026-09-14 2026-09-18    # what the nursery logged
+
+napper-sync sync-famly                # dry run: shows what would be written
+napper-sync sync-famly --live         # write it
+```
+
+To run this hourly on a Raspberry Pi with Discord alerts, see
+[`docs/deployment.md`](https://github.com/PW-CODING/napper-sync/blob/main/docs/deployment.md).
+
+### Importing a file
+
+```bash
+napper-sync sync-file entries.csv --live
+```
+
+Columns `start,end,category,comment` plus any category field as a further
+column; see [`examples/entries.example.csv`](https://github.com/PW-CODING/napper-sync/blob/main/examples/entries.example.csv).
+An optional `id` column pins the Napper ID, so importing a corrected file
+updates the entries instead of duplicating them.
+Categories accept English or German short names (`nap`/`nickerchen`,
+`diaper`/`windel`, `bottle`/`flasche`, …).
+
+## How it stays safe
+
+| Risk | Answer |
+|---|---|
+| Writing by accident | every write and delete is a dry run without `--live` |
+| Duplicates from repeated runs | Famly entries get a stable ID derived from child, category and start, so a repeated run rewrites the same entry instead of adding one; everything else is skipped if the same category exists within 10 minutes or overlaps; day markers are one-per-day |
+| Corrections at the nursery | a changed end time, note or diaper content overwrites the Napper entry on the next run; fields added by hand in the app are kept |
+| Hammering the API | 429 responses are parsed and retried with the server's requested delay |
+| Bad data | field names, enum values and ranges are validated locally before a request is built |
+| Silent breakage | Discord message on expired token, failed write, crashed run; unknown Famly event types are listed, never dropped |
+
+## Project layout
+
+```
+src/napper_sync/
+  napper.py          Napper API client (auth, read, write, delete)
+  categories.py      what each category expects - the data model
+  sync.py            Entry, duplicate detection, the sync loop
+  sources.py         CSV / JSON sources
+  famly.py           Famly API client
+  famly_mapping.py   Famly events -> Napper entries
+  notify.py          Discord webhook
+  config.py          ~/.config/napper-sync/
+  cli.py             the napper-sync command
+tools/               research scripts: analyse history, rediscover endpoints, round-trip and correction checks
+examples/            config, data files, systemd units, Windows task
+docs/                what is known about both APIs, and how to deploy
+tests/               pytest suite against an in-process mock of the Napper API
+```
+
+## Documentation
+
+- [docs/napper-api.md](https://github.com/PW-CODING/napper-sync/blob/main/docs/napper-api.md) - endpoints, auth, the log object,
+  all categories and fields, the traps (seconds in a field called minutes,
+  percent-encoded comments, date-based IDs), and how the write path was found
+- [docs/famly-api.md](https://github.com/PW-CODING/napper-sync/blob/main/docs/famly-api.md) - instances, token, the calendar
+  endpoint and its event shapes
+- [docs/deployment.md](https://github.com/PW-CODING/napper-sync/blob/main/docs/deployment.md) - systemd timer, hardening, Discord
+
+## Development
+
+```bash
+git clone https://github.com/PW-CODING/napper-sync && cd napper-sync
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+The tests run against an in-process HTTP mock that reproduces the real API's
+quirks (whole-day responses on write, 429 throttling, token refresh). Nothing
+touches a real account.
+
+Tools under `tools/` do talk to the real API and are meant for the day an app
+update breaks something: `probe_write_path.py` rediscovers the write endpoint,
+`roundtrip_categories.py` writes one entry per category far in the past,
+checks it and deletes it again, `analyze_categories.py` summarises which
+fields your own history actually uses, and `probe_corrections.py` checks that
+a correction made later at the nursery updates the Napper entry in place.
+
+## Contributing
+
+Issues and pull requests are welcome, in English or German. If an app update
+changed something, the most useful report includes the output of
+`tools/roundtrip_categories.py` or of `napper-sync famly calendar` for a day
+with the new event type (with names and IDs removed).
+
+## Related projects
+
+Community projects around the same two apps, none of which connects them:
+
+- [home-assistant-napper](https://github.com/g-nogueira/home-assistant-napper) -
+  read-only Napper integration for Home Assistant
+- [ha-napper](https://github.com/bbruenings/ha-napper) - another Home Assistant
+  integration for Napper
+- [napper-export](https://github.com/brittraee/napper-export) - export a child's
+  complete Napper history
+- [famly-fetch](https://github.com/jacobbunk/famly-fetch) - download your child's
+  photos from Famly
+
+## Acknowledgements
+
+Reading the Napper API was first worked out by
+[brittraee/napper-export](https://github.com/brittraee/napper-export) and
+[g-nogueira/home-assistant-napper](https://github.com/g-nogueira/home-assistant-napper);
+the OTP login flow and request headers here follow their findings. Writing,
+deleting, the category model and the Famly side were worked out for this
+project.
+
+## License
+
+[MIT](https://github.com/PW-CODING/napper-sync/blob/main/LICENSE)

napper_sync-0.1.0/docs/deployment.md

@@ -0,0 +1,130 @@
+# Running napper-sync unattended
+
+The intended setup is a small always-on Linux box (a Raspberry Pi is plenty;
+a run takes about two seconds of CPU) with a systemd timer. A Windows
+scheduled task works too and is described at the end.
+
+## 1. Install
+
+```bash
+# as the user that will run the sync (not root)
+pipx install git+https://github.com/PW-CODING/napper-sync
+# or: pip install --user git+https://github.com/PW-CODING/napper-sync
+napper-sync --version
+```
+
+Python 3.11 or newer is required (Debian 12 "bookworm" ships 3.11).
+
+## 2. Configure
+
+```bash
+napper-sync config init                 # writes ~/.config/napper-sync/config.toml
+napper-sync login you@example.com       # e-mailed one-time code
+napper-sync babies                      # -> [napper] baby_id
+napper-sync famly token <VALUE>         # see "Getting the Famly token"
+napper-sync famly children              # -> [famly] child_id
+napper-sync config show                 # everything in place?
+```
+
+Then dry-run it once and read the output:
+
+```bash
+napper-sync sync-famly            # shows what would be written
+napper-sync sync-famly --live     # writes
+```
+
+### Getting the Famly token
+
+Log in to Famly in a desktop browser, open the developer tools (F12),
+Console tab, and run:
+
+```js
+JSON.parse(localStorage["famly.accessToken"])
+```
+
+Copy the string (36 characters) into `napper-sync famly token <VALUE>`. If
+your nursery is on a different Famly instance than `app.famly.de`, check
+`localStorage["famly.existingLogins"]` and set `[famly] host` accordingly.
+
+On a headless server, run the browser step on any machine and copy the token
+across (`ssh host 'napper-sync famly token <VALUE>'`).
+
+### Secrets and permissions
+
+Everything sensitive sits in `~/.config/napper-sync/` with mode `600`:
+`napper-tokens.json`, `famly-token`, and the Discord webhook inside
+`config.toml`. Keep that directory out of backups that leave your control, and
+never commit it.
+
+## 3. systemd timer
+
+Copy the three units from `examples/systemd/`, adjust `User=` and the paths in
+`ExecStart=` / `ReadWritePaths=` to your installation, then:
+
+```bash
+sudo install -m 644 examples/systemd/napper-sync.service \
+                    examples/systemd/napper-sync.timer \
+                    'examples/systemd/napper-sync-failed@.service' /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now napper-sync.timer
+
+systemctl list-timers napper-sync.timer        # next run
+sudo systemctl start napper-sync.service       # run once, now
+journalctl -u napper-sync -n 30 --no-pager     # what happened
+```
+
+Design notes, in case you want to change them:
+
+* **`OnCalendar=Mon..Fri 07..18:00`** - hourly during nursery hours plus one
+  run after closing. Nothing is logged at night or on weekends, so nothing
+  runs. `systemd-analyze calendar 'Mon..Fri 07..18:00'` previews the schedule.
+* **`[sync] days = 4`** - each run looks four days back. Three would make the
+  Monday run reach exactly to Friday; four leaves room for entries added
+  Friday evening.
+* **`Persistent=true`** - runs missed while the machine was off are caught up
+  on boot.
+* **`OnFailure=`** - if the process crashes or times out, a second unit posts
+  the last journal lines to Discord. API-level failures (expired token,
+  unreachable host) are reported by the sync itself.
+* **Hardening** - `ProtectSystem=strict` and `ProtectHome=read-only`, with
+  `ReadWritePaths=` opened only for the config directory. That last line is
+  not optional: the Napper id-token is refreshed automatically and written
+  back to `napper-tokens.json`. Without write access the refresh fails
+  silently a few weeks after installation.
+
+## 4. Discord notifications
+
+Create a webhook in your Discord server (channel settings → Integrations →
+Webhooks), put the URL into `[notify] discord_webhook`, and test:
+
+```bash
+napper-sync notify            # "Test message"
+```
+
+You will then hear about:
+
+* an expired Famly token (with the command to fix it),
+* Famly or Napper being unreachable or rejecting a write,
+* a crashed or timed-out run (via the `OnFailure=` unit, journal attached),
+* every run that imported or corrected something, with the list of entries.
+
+A run that finds nothing new stays silent.
+
+What the webhook cannot tell you: that the machine is off or offline. Silence
+is not proof that all is well.
+
+## Windows instead of Linux
+
+`examples/windows-task.ps1` registers an hourly scheduled task that runs
+`napper-sync sync-famly --live`. Output goes nowhere by default; if you want
+a log, wrap the call in a `.cmd` that appends to a file. The Discord
+notifications work the same way.
+
+## Updating
+
+```bash
+pipx upgrade napper-sync      # or: pip install --user -U git+https://github.com/PW-CODING/napper-sync
+sudo systemctl start napper-sync.service && journalctl -u napper-sync -n 20
+```
+
+Config and tokens are untouched by upgrades.