From a4c0dc263bb7c614277d69aea52858e77023de15 Mon Sep 17 00:00:00 2001 From: Anthony Cardinale Date: Sat, 2 May 2026 17:27:59 -0400 Subject: [PATCH] Add reference links: chezmoi, age, duckdb, launchd, age-spec, task-durations companion repo --- AGENTS.md | 13 +++++++++++++ README.md | 10 ++++++++++ docs/architecture.md | 2 ++ docs/security.md | 2 ++ docs/setup-new-fleet.md | 2 ++ 5 files changed, 29 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 49ff70b..60729c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,19 @@ > **For Claude Code, Codex, Aider, or any other coding agent dropped into this repo.** > Follow this file top-to-bottom. It walks the user through replacing every placeholder with real values. Treat each numbered section as one Q&A round: ask the listed questions, wait for answers, fill in the files, then move on. +## Background reading you may need mid-flow + +If you hit a chezmoi-specific question you can't answer from this file alone, consult the live docs: + +- **[chezmoi homepage](https://www.chezmoi.io)** — overview, install, quick start. +- **[chezmoi command reference](https://www.chezmoi.io/reference/commands/)** — every subcommand (`init`, `add`, `apply`, `diff`, `update`, `re-add`, `edit-config`, `cd`, `source-path`, `execute-template`). +- **[chezmoi templates](https://www.chezmoi.io/reference/templates/)** — the `{{ .chezmoi.homeDir }}` and `{{ .chezmoi.hostname }}` syntax used throughout this template. +- **[chezmoi encryption](https://www.chezmoi.io/user-guide/encryption/age/)** — how `chezmoi add --encrypt` works with age. +- **[age homepage](https://github.com/FiloSottile/age)** — keypair format, `age-keygen`, `age` and `age -d` commands. +- **[Apple launchd guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)** — if a plist fails to load, this is the reference for `launchctl load`/`unload`/`list`. + +If the user asks about cross-fleet time estimates, the companion repo is [`task-durations`](https://gitea.tojo.team/cardinale/task-durations) (separate; install instructions in this template's README). + ## Operating rules for this setup session 1. **One question at a time.** Don't fire all questions in a giant wall of text. Ask one, wait for the answer, ask the next. diff --git a/README.md b/README.md index d62b64d..178eba9 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,16 @@ python3 ~/.claude/scripts/task-durations/extract.py # initial corpus build Architecture writeup is in [task-durations' own docs/](https://gitea.tojo.team/cardinale/task-durations/src/branch/main/docs/fleet-architecture.md). +## References + +The plumbing this template builds on: + +- **[chezmoi](https://www.chezmoi.io)** — dotfile manager. Source: [twpayne/chezmoi](https://github.com/twpayne/chezmoi). Reference docs: [reference](https://www.chezmoi.io/reference/), [quick start](https://www.chezmoi.io/quick-start/), [user guide](https://www.chezmoi.io/user-guide/command-overview/). +- **[age](https://github.com/FiloSottile/age)** — file encryption used for the secrets file and SSH keys in the chezmoi source. +- **[DuckDB](https://duckdb.org/)** — analytics engine for the optional task-durations feature ([Hive partitioning docs](https://duckdb.org/docs/stable/data/partitioning/hive_partitioning)). +- **[launchd](https://www.launchd.info/)** — macOS service manager that runs the watcher + puller + pull-fleet jobs. Apple's reference: [launchd.plist(5)](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html). +- **Companion repo:** [task-durations](https://gitea.tojo.team/cardinale/task-durations) — the cross-fleet time estimator referenced from the launchd plist and Stop hook. + ## License MIT — see [LICENSE](LICENSE). diff --git a/docs/architecture.md b/docs/architecture.md index 77f3030..34a36bc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,6 +2,8 @@ This template provides a two-way dotfile sync across N macOS machines. Every change you make on any machine propagates to the others within ~7 minutes. There's no central server — each machine is a peer. +Underlying technologies: [`chezmoi`](https://www.chezmoi.io) ([reference](https://www.chezmoi.io/reference/)) for templating + applying dotfiles, [`age`](https://github.com/FiloSottile/age) for encrypting secrets at rest, and [launchd](https://www.launchd.info/) for the daemons that fire on file change and on a 5-minute timer. + ## Three moving parts ``` diff --git a/docs/security.md b/docs/security.md index f331e1b..752dd56 100644 --- a/docs/security.md +++ b/docs/security.md @@ -2,6 +2,8 @@ What's encrypted, what isn't, and where each line is drawn. +Encryption uses [age](https://github.com/FiloSottile/age) ([format spec](https://age-encryption.org/v1)). [chezmoi's age integration docs](https://www.chezmoi.io/user-guide/encryption/age/) describe how `chezmoi add --encrypt` works and how the recipient public key is configured. + ## Encryption boundaries | Lives where | Encrypted at rest? | Why | diff --git a/docs/setup-new-fleet.md b/docs/setup-new-fleet.md index c455e71..c6bddac 100644 --- a/docs/setup-new-fleet.md +++ b/docs/setup-new-fleet.md @@ -8,6 +8,8 @@ If you'd rather have an agent (Claude Code, Codex, etc.) walk you through this i brew install chezmoi age duckdb ``` +Reference docs for the moving parts: [chezmoi](https://www.chezmoi.io) ([quick start](https://www.chezmoi.io/quick-start/)), [age](https://github.com/FiloSottile/age), [DuckDB](https://duckdb.org/). + You need git access to whichever forge you'll host the fleet repo on (gitea, GitHub, forgejo, gitlab — anything chezmoi can clone over HTTPS or SSH). ## 1. Fork this template