🤖 codex: clarify scope boundaries (n/a)

What:
- add explicit RFC + README scope boundaries
- replace personal launchd label with neutral com.nix-clawdis.gateway
- switch docs to <user> placeholders and matching launchctl commands

Why:
- avoid confusion between RFC, public repo, and personal nixos-config

Tests:
- not run (docs/config updates only)

README.md

@@ -11,6 +11,11 @@
 - **Batteries included defaults.** Safe, opinionated settings that “just work.”
 - **No mystery steps.** Every command is copy/pasteable.
 
+## Scope boundaries
+
+- This repo is a public, generic Nix package + Home Manager module for Clawdis.
+- It does not include or depend on any personal `nixos-config` or private machine setup.
+
 ## Zero to Clawdis
 
 Never used Nix? Start here:
@@ -39,7 +44,7 @@ Minimal config:
 Then:
 
 ```bash
-launchctl print gui/$UID/com.joshp123.clawdis.gateway | grep state
+launchctl print gui/$UID/com.nix-clawdis.gateway | grep state
 tail -n 50 ~/.clawdis/logs/clawdis-gateway.log
 ```
 
@@ -80,7 +85,7 @@ What I need:
 5) Configure my bot token + allowFrom list
 6) Run build + show launchd status + recent logs
 
-My setup:
+Your setup:
 - macOS version: [FILL IN]
 - Telegram bot token path: [FILL IN]
 - Allowed chat IDs: [FILL IN]

docs/agent-copypasta.md

@@ -15,7 +15,7 @@ Do this:
 5) Enable the Clawdis Home Manager module with Telegram-first defaults.
 6) Use my bot token file and allowFrom IDs.
 7) Run home-manager switch and verify with:
-   - `launchctl print gui/$UID/com.joshp123.clawdis.gateway | grep state`
+   - `launchctl print gui/$UID/com.nix-clawdis.gateway | grep state`
    - `tail -n 50 ~/.clawdis/logs/clawdis-gateway.log`
 
 My inputs:

docs/quickstart-telegram.md

@@ -17,9 +17,11 @@ This is the fastest path to a working Clawdis bot.
 
 ## 2) Enable the module
 
+Replace `<user>` with your Home Manager configuration name.
+
 ```nix
 {
-  homeManagerConfigurations.josh = home-manager.lib.homeManagerConfiguration {
+  homeManagerConfigurations.<user> = home-manager.lib.homeManagerConfiguration {
     pkgs = import nixpkgs { system = "aarch64-darwin"; };
     modules = [
       nix-clawdis.homeManagerModules.clawdis
@@ -42,13 +44,13 @@ This is the fastest path to a working Clawdis bot.
 ## 3) Apply
 
 ```bash
-home-manager switch --flake .#josh
+home-manager switch --flake .#<user>
 ```
 
 ## 4) Verify
 
 ```bash
-launchctl print gui/$UID/com.joshp123.clawdis.gateway | grep state
+launchctl print gui/$UID/com.nix-clawdis.gateway | grep state
 tail -n 50 ~/.clawdis/logs/clawdis-gateway.log
 ```
 

docs/rfc/2026-01-02-declarative-clawdis-nix.md

@@ -19,6 +19,16 @@ The goal is to make Clawdis installation and configuration feel as simple as: ad
 - Deterministic builds and reproducible outputs.
 - Documentation must be suitable for publication on the internet.
 
+## 1.2) Scope boundaries (avoid confusion)
+
+This RFC is only about:
+- The public `nix-clawdis` repo (package + module + docs).
+- A generic, end-user Nix setup that lives outside any personal config repo.
+
+This RFC is explicitly **not** about:
+- Josh’s personal `nixos-config` or any private machine configuration.
+- Editing or publishing personal settings, tokens, or machine-specific modules.
+
 ## 2) Goals / Non-goals
 
 Goals:
@@ -125,13 +135,29 @@ Telegram minimal (opinionated defaults):
 }
 ```
 
+Telegram multi-chat (two groups + one DM):
+
+```nix
+{
+  programs.clawdis = {
+    enable = true;
+    providers.telegram = {
+      enable = true;
+      botTokenFile = "/run/agenix/telegram-bot-token";
+      allowFrom = [ 12345678 -1001234567890 -1009876543210 ];
+    };
+    routing.queue.mode = "interrupt";
+  };
+}
+```
+
 WhatsApp example is deferred until the Telegram-first path is fully verified.
 
 ## 6) Artifacts / outputs
 
 - `clawdis` gateway binary in PATH.
 - Declarative `~/.clawdis/clawdis.json` (generated).
-- Launchd service `com.joshp123.clawdis.gateway` (macOS).
+- Launchd service `com.nix-clawdis.gateway` (macOS).
 - Example configs inline in the RFC (Telegram-first).
 
 ## 7) State machine (if applicable)
@@ -192,6 +218,12 @@ Not applicable (no new APIs). Primary flows are CLI and provider interactions.
 - Strict allowlists for inbound chat IDs.
 - Emit clear, actionable error messages when config is invalid.
 
+## 12.1) Secrets handling (opinionated default)
+
+- Recommend agenix for bot tokens on macOS.
+- Default docs and examples use `/run/agenix/telegram-bot-token`.
+- Provide an example agenix entry and a note on file permissions (readable by the user running Home Manager).
+
 ## 13) Outputs and materialization
 
 - Primary output: working Clawdis instance configured via Nix.
@@ -262,6 +294,8 @@ This RFC is complete when:
 - Telegram‑first quickstart works on macOS with a real bot token.
 - `nix run .#clawdis` launches the gateway and responds in an allowlisted chat.
 - Documentation includes a copy‑paste agent prompt and explicit verification steps.
+- Smoke test: user sends a Telegram message in an allowlisted chat and receives a response.
+- Secrets flow documented with agenix‑style token file wiring.
 - A release tag is published and referenced in examples.
 
 ## 19) Implementation status (current)

docs/troubleshooting.md

@@ -3,7 +3,7 @@
 ## Check launchd status (macOS)
 
 ```bash
-launchctl print gui/$UID/com.joshp123.clawdis.gateway
+launchctl print gui/$UID/com.nix-clawdis.gateway
 ```
 
 ## Check logs
@@ -19,5 +19,5 @@ tail -n 200 ~/.clawdis/logs/clawdis-gateway.log
 - Stuck queue: restart the launchd agent
 
 ```bash
-launchctl kickstart -k gui/$UID/com.joshp123.clawdis.gateway
+launchctl kickstart -k gui/$UID/com.nix-clawdis.gateway
 ```

docs/zero-to-clawdis.md

@@ -35,6 +35,8 @@ cd ~/code/clawdis-local
 
 Create `flake.nix`:
 
+Replace `<user>` with your Home Manager configuration name.
+
 ```nix
 {
   description = "Clawdis local";
@@ -52,7 +54,7 @@ Create `flake.nix`:
       pkgs = import nixpkgs { inherit system; };
     in {
       devShells.${system}.default = pkgs.mkShell { };
-      homeManagerConfigurations.josh = home-manager.lib.homeManagerConfiguration {
+      homeManagerConfigurations.<user> = home-manager.lib.homeManagerConfiguration {
         inherit pkgs;
         modules = [
           nix-clawdis.homeManagerModules.clawdis
@@ -85,13 +87,13 @@ nix run home-manager/release-24.11 -- init
 Then switch:
 
 ```bash
-home-manager switch --flake .#josh
+home-manager switch --flake .#<user>
 ```
 
 ## 5) Verify Clawdis
 
 ```bash
-launchctl print gui/$UID/com.joshp123.clawdis.gateway | grep state
+launchctl print gui/$UID/com.nix-clawdis.gateway | grep state
 tail -n 50 ~/.clawdis/logs/clawdis-gateway.log
 ```
 

nix/modules/home-manager/clawdis.nix

@@ -141,7 +141,7 @@ in {
     launchd.agents."clawdis.gateway" = lib.mkIf cfg.launchd.enable {
       enable = true;
       config = {
-        Label = "com.joshp123.clawdis.gateway";
+        Label = "com.nix-clawdis.gateway";
         ProgramArguments = [ "${cfg.package}/bin/clawdis" ];
         RunAtLoad = true;
         KeepAlive = true;