# Sync Pi Setup

> Syncs the current local Pi setup back into this repo's portable setup templates. Use when the user says to sync, refresh, or update this repo from their installed Pi config, extensions, models, MCP template, or agent instructions.

- Skill: `doodledood/sync-pi-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add doodledood/sync-pi-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/doodledood/sync-pi-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: doodledood (https://skillmd.com/u/doodledood)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/doodledood/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.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.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.