sync-pi-setup

# Sync Pi Setup Keep this repo's `setup/` directory aligned with the user's current portable Pi setup without committing private/local state. ## Privacy boundary When inspecting credential-bearing local files such as `~/.pi/agent/auth.json`, `~/.pi/agent/mcp-adapter.json`, or `~/.pi/web-search.json`, use redacted/structural reads or targeted scripts. Never print, quote, summarize, or paste raw secret values, credential-bearing URLs, OAuth material, proxy IDs, or tokens into the transcript. Preserve only key names, provider/server shape, env-var names, and placeholder-worthy fields. ## Workflow 1. Inspect the repo first: read `README.md`, `setup/README.md`, `AGENTS.md`, `.gitignore`, and `scripts/verify-structure.mjs`. 2. Inspect local Pi config only as needed: - `~/.pi/agent/settings.json`, especially `packages`, default provider/model, enabled models, theme, and package-specific settings - the installed package list from local settings and, when useful, `pi list`; compare it to `setup/settings.example.json` and `setup/settings.local.example.json` - prompt/profile files such as `~/.pi/agent/AGENTS.md` and its `CODING_CONVENTIONS.md` companion, plus any local template-like setup files that correspond to files under `setup/` - non-secret extension configs that correspond to `setup/configs/*.json` - `~/.pi/agent/models.json` only if model-provider overrides are expected - `~/.pi/agent/mcp-adapter.json` and `~/.pi/web-search.json` only through redacted/structural inspection for shape, provider choice, and placeholder-worthy fields — never for copying or exposing secrets verbatim 3. Compare local values, package list, prompt/profile files, and template-like files to `setup/`. Update repo templates only for portable defaults the user wants preserved across machines. 4. For secrets, credential-bearing URLs, OAuth material, private endpoints, local absolute paths, proxy IDs, and user-specific tokens, keep or introduce placeholders/env references in the repo template. Do not ask the user to paste secrets into chat. 5. If a local value is ambiguous — personal preference vs machine-specific vs private/internal — ask before adopting it. Default to leaving it local. 6. If package/resource paths change, update all install surfaces together: root `package.json`, package READMEs, root docs, `setup/`, and `scripts/verify-structure.mjs`. `setup/AGENTS.md` and `setup/CODING_CONVENTIONS.md` are one pair: the posture file references the conventions by name, so a machine that gets one without the other loses the conventions with nothing failing to say so. `npm run verify:structure` checks the pairing, and other repos anchor a synced section on the conventions file's `# Coding Conventions` title — so keep that title when editing it. 7. Do not add a separate local-only setup layer. The repo uses templates with placeholders; filled files stay local. ## HQ doctrine is synced; the rest of HQ state is not The user's HQ global doctrine is part of this setup and is kept in the repo. Sync it mechanically rather than by reading and re-typing it, every time this skill runs, with no question asked: ```bash npm run sync:doctrine # ~/.pi/hq/doctrine/global.md -> setup/hq/doctrine.global.md npm run sync:doctrine:check # non-zero when the repo copy is stale ``` It is copied verbatim, at the user's explicit direction, in full knowledge that this repo is public. Do not redact it, do not summarise it, and do not ask again. If it ever contains something that is plainly a secret rather than a rule — a key, a token, a credential-bearing URL — say so and stop before committing; that is the only exception. Nothing else under `~/.pi/hq/` goes in the repo: not the project doctrine files (they are keyed by working directory and name whatever the user was working in), and not rulings, the audit and defect logs, queued or archived decisions, session rows, stop records, seat presence, or worker logs. That is live state. `~/.pi/agent/hq.json` is a non-secret extension config like the others; its template is `setup/configs/hq.json`. ## Never copy into the repo - raw `auth.json`, API keys, OAuth state, tokens, cookies, sessions, caches, logs, package caches, or `node_modules` - anything under `~/.pi/hq/` except the global doctrine file — see above - filled MCP URLs, proxy IDs, credential-bearing command args, or private/internal endpoints - live `web-search.json` keys - private/internal workflow instructions that are not part of the portable setup ## Verification After changing the repo, run targeted verification: ```bash npm run sync:doctrine:check npm run verify:structure ! rg "profiles/"'aviram' README.md docs setup packages AGENTS.md scripts .agents .claude find setup -name '*.json' -print0 | xargs -0 node -e 'for (const f of process.argv.slice(1)) JSON.parse(require("fs").readFileSync(f,"utf8"))' git status --short ``` Search tracked diffs and any untracked files for accidental secrets, filled credential-bearing URLs, private endpoints, proxy IDs, and runtime state. Treat placeholder hits like `<MCP_HOST>`, `<TAVILY_API_KEY>`, and `$OPENAI_API_KEY` as expected template values; treat filled values as blockers to remove before committing. Use `git add -N <new-file>` for new files before diff-based scans, or scan the untracked file contents directly. ```bash git diff -- . ':(exclude)package-lock.json' | rg -n "api[_-]?key|secret|token|oauth|cookie|https://[^<[:space:]]+|proxy/[A-Za-z0-9_-]+|sessions?|mcp-oauth|web-search\.json|auth\.json" || true git ls-files --others --exclude-standard -z | xargs -0 -r rg -n "api[_-]?key|secret|token|oauth|cookie|https://[^<[:space:]]+|proxy/[A-Za-z0-9_-]+|sessions?|mcp-oauth|web-search\.json|auth\.json" || true ``` If applying the setup to a local machine, also search copied local files for remaining placeholder markers and report them to the user instead of filling secrets in chat. Also inspect `git diff --stat` and `git diff` for accidental secrets or runtime state. Summarize: - which local files were compared; - which repo templates/docs changed; - which placeholders remain for the user to fill locally; - which verification commands passed or still need attention.