From aa0a6f275f0df53745e43728e193614a16d29a2b Mon Sep 17 00:00:00 2001 From: Max Schaefer Date: Thu, 12 Nov 2026 16:52:42 +1100 Subject: [PATCH] Trim README to setup and usage and drop duplicate comments --- .mise.toml | 1 - AGENTS.md | 2 +- README.md | 139 +++++++-------------------------------------- tests/mcp.test.mjs | 1 - 4 files changed, 21 insertions(+), 122 deletions(-) diff --git a/.mise.toml b/.mise.toml index 9895d15..a8c67b9 100644 --- a/.mise.toml +++ b/.mise.toml @@ -21,7 +21,6 @@ exit "$status" # Hk's oxfmt step skips templated code, so check its rendered output. [tasks."check:templates"] -# Templates read keys with fnox; tests/bin holds a stand-in. env = { PATH = "{{config_root}}/tests/bin:{{env.PATH}}" } run = ''' set -eu diff --git a/AGENTS.md b/AGENTS.md index 7132d4e..db61cf7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ - Every tool a CI job runs must be in its `with.tools` or declared by the repository with `project-tools: true`. - `mise use --global` and `mise upgrade --global` edit live files; reconcile those changes back into `home/`. - Linux hosts apply this source too: limit macOS-only targets with `.chezmoiignore` or `.chezmoi.os` blocks. -- Workstation Compose definitions live under `.config/services`; Homelab owns Mercury’s boot configuration. Mise service tasks start already-applied definitions. +- Workstation Compose definitions live under `.config/services`; Homelab owns Mercury’s boot configuration. - Preserve Connect’s existing rootful Podman secret and volume on Linux; keep the `onepassword-connect` Compose project, named volume and OrbStack hostname on macOS. A runtime migration must not recreate credentials or data. - Keep application-managed hooks, caches, history, account state and generated host inventories outside this repository. - Preserve application destination paths and unrelated local state when changing source attributes or templates. diff --git a/README.md b/README.md index ea5c33e..90e03e1 100644 --- a/README.md +++ b/README.md @@ -3,22 +3,8 @@ My macOS workstation preferences, managed by [chezmoi](https://www.chezmoi.io/) and installed through Mise; the same source sets up agents on Linux. Shared agent instructions and my own skills live in the separate -[Agents repository](https://github.com/maxexcloo/agents), but the links and skill -discovery that wire them into the workstation are managed here. - -## Configuration - -Edit preferences in `home/`, then run `chezmoi apply`. The tree mirrors the home -directory using chezmoi attributes. Credential-bearing preferences use native -modify templates to preserve unrelated application settings and local state. - -MCP endpoints are defined in `home/.chezmoidata.toml`. Bifrost keys are stored in -the 1Password Automation vault and referenced through -`home/dot_config/fnox/config.toml`. Fnox and the 1Password CLI read vaults -through the machine's 1Password Connect server, managed here with the -`services:connect` Mise task. Save its token as `token` beside -the Connect credentials file. `chezmoi apply` writes each agent's Bifrost key into -its private configuration. Keep key values out of Git and command output. +[Agents repository](https://github.com/maxexcloo/agents); clone it beside this +checkout. ## Usage @@ -27,6 +13,9 @@ Install Homebrew, then the packages and applications in `home/dot_Brewfile` with them in sync. Enable the 1Password desktop integration for Git signing and SSH authentication on macOS. +Fnox and the 1Password CLI read vaults through the machine's 1Password Connect +server. Save its token as `token` beside the Connect credentials file. + From this checkout, bootstrap the shared Mise directory with a temporary chezmoi, then install the global tools it declares: @@ -41,129 +30,41 @@ chezmoi status chezmoi apply ``` -`setup` points chezmoi at this checkout, so plain `chezmoi` commands work from -anywhere afterwards. Use `mise tasks` to discover tasks, `mise run fmt` to format -files and `mise run check` to validate them. Formatting and checks need the shared -Mise configuration; they do not resolve credentials or need vault access. - -To sync another workstation, clone this repository, pull the revision you want -and run the same commands. Changes to live files aren't imported automatically. +Edit preferences in `home/`, then run `chezmoi apply`. To sync another +workstation, pull the revision you want and run the same commands. `mise use --global` and `mise upgrade --global` edit the live Mise configuration, so copy those edits back into `home/`. -## Workstation Services - -Compose definitions live in `~/.config/services`. Apply them with chezmoi before -using the small `services:*` Mise tasks to start a service. macOS uses Docker -Compose through OrbStack; Mercury uses rootful `podman-compose` so Connect keeps -its existing Podman volume and secret. Homelab owns Mercury’s boot service. - -Mercury’s switch from Quadlets to Compose requires an approved handover: stop the -old Connect pod, start the Compose stack, then verify credential-backed access and -retained data before removing the old Quadlet files. The Compose definition uses -the existing volume and secret as external resources; do not recreate them or run -both owners at once. Keep the old definitions available until that verification. -The macOS project, data volume, credential mount and OrbStack endpoint stay the same. - -## Agent Launch - -Launch Claude Code, Codex, OpenCode and Pi directly. In Orca, reset each agent's -Command to its executable name and use its native permission controls. Select -Auto for supporting agents; Codex uses its workspace sandbox with automatic -approval review. Put environment variables in Orca's Environment setting. - -Claude also enables its native Bash sandbox and refuses unsandboxed retries. -OpenCode asks before shell commands or access outside the project; existing -permission rules are preserved. Keep its `--auto` flag off to retain those prompts. -Pi has no native sandbox or equivalent permission gate. - -Agent logins, sessions and history stay on each machine. Sign in once per agent -per machine; keep existing agent homes when changing launch settings. - -Before applying this removal, use `nono list --installed` and `nono remove` for -each installed pack so its native unwiring removes hooks and plugin registration. -Apply the preferences, then remove the installed nono tool with `mise uninstall nono`. -Restart Fish sessions to unload functions already in memory. These are explicit -activation steps after review. - -## Agent Threads +Run `atuin mcp install` once per machine to register Atuin's MCP server with +installed agents. -[Atuin Threads](https://docs.atuin.sh/18.24/ai/threads/) is enabled with native -daemon autostart; use Atuin 18.24+ on both Mac and Mercury. Capture includes -conversations, tool inputs/outputs and edit diffs, including the whole session -when continuing an old one. Threads sync end-to-end encrypted through the -existing auto-sync; both machines need the same Atuin account and encryption -key. Local transcripts and the search index remain sensitive. +## Shared Tasks & CI -Use `atuin resume` to search and resume, `atuin resume THREAD_ID --fork` to fork, -or `atuin resume THREAD_ID --in codex` to continue in another agent. Keep the -matching checkout available: Threads carries context, not repository files or -Orca workspace state. Native resume uses agent executables from `PATH`. - -Run `atuin mcp install` to register the native stdio server with installed agents, -then restart them. This grants read access to shell history and captured threads; -see [native MCP setup](https://docs.atuin.sh/18.24/ai/mcp/). - -## Shared Agent Guidance - -Clone the Agents repository beside this checkout. Chezmoi links its shared -instructions and skills into the workstation. Claude Code loads that repository -as a plugin because it does not discover the shared skill collection recursively. - -Upstream skills are installed through `home/.chezmoiexternal.toml`. Keep personal -rules in the Agents repository so upstream packages stay unmodified. - -## Browser Tools - -[agent-browser](https://agent-browser.dev) uses the Browserless container started -by `mise run services:browserless` when needed. Mise installs the CLI; chezmoi -configures its skill and native endpoint setting. -Both platforms use the same Compose definition. On Linux it runs under the user’s -Podman runtime; start it explicitly when needed. Apply its configuration with -chezmoi first; the start task does not apply preferences or enable boot startup. - -## Shared Tools & Tasks - -`home/dot_config/mise/conf.d/tools.toml` declares shared tools; -`home/dot_config/mise/config.toml` adds workstation-only configuration. - -Mise loads the shared tasks globally; `mise tasks` lists them. Repositories select -them through `depends` and keep their own tests, builds and operational tasks. -Run tasks from the repository root. Checks skip when their inputs are missing. -A project's task overrides the shared task of the same name, including `check` -and `fmt`. +Mise loads the shared tasks globally. Repositories select them through `depends`; +a project's task overrides the shared task of the same name. ```toml [tasks.check] depends = ["check:python", "check:updates", "test:python"] ``` +GitHub Actions uses `maxexcloo/dotfiles/.github/actions/mise@main` with the tools +a job needs in `with.tools`; set `project-tools: true` to also install the tools +the repository's Mise configuration declares. + ## Dependency Updates -Repositories with dependencies extend -`github>maxexcloo/dotfiles//renovate/default.json5` in `renovate.json5`, adding only -their own exceptions. Home Assistant integrations also extend -`github>maxexcloo/dotfiles//renovate/home-assistant.json5` to keep their minimum -Home Assistant version and test fixtures in step. +Repositories extend `github>maxexcloo/dotfiles//renovate/default.json5` in +`renovate.json5`, adding only their own exceptions. Home Assistant integrations +also extend `github>maxexcloo/dotfiles//renovate/home-assistant.json5`. -For pins the shared preset does not detect automatically, add a comment on the -line above: +For pins the shared preset does not detect, add a comment on the line above: ```yaml # renovate: datasource=github-releases depName=/ version: ``` -The Mend Renovate app runs on GitHub; each repository's Dependency Dashboard lists -pending updates. Shared presets are read from GitHub, so changes take effect once -merged. - -GitHub Actions uses `maxexcloo/dotfiles/.github/actions/mise@main`. The action -loads only the shared tools and tasks from its own revision, then installs the -tools in the workflow's `with.tools`. Set `project-tools: true` to also install -every tool the repository's own Mise configuration declares. The action doesn't -apply workstation preferences or resolve credentials. - ## Licence AGPL-3.0 — see [LICENSE](LICENSE). diff --git a/tests/mcp.test.mjs b/tests/mcp.test.mjs index d0c803e..c2e4093 100644 --- a/tests/mcp.test.mjs +++ b/tests/mcp.test.mjs @@ -5,7 +5,6 @@ import { fileURLToPath } from "node:url"; const root = fileURLToPath(new URL("..", import.meta.url)); const base = ["--source", root, "--config", "/dev/null", "--config-format", "toml"]; -// The templates read keys with fnox; a stand-in returns fixed values without 1Password. const env = { ...process.env, PATH: `${root}tests/bin:${process.env.PATH}` }; const execute = (args, input = "") => execFileSync("chezmoi", [...base, ...args], { env, input, encoding: "utf8" });