pi-personal — git save of a full pi setup (pi v1.3.0)

Snapshot of a working pi installation + personal configuration, taken 2026-10-19 from a Windows 11 machine (Node v24.13.1, npm 11.21.0, PowerShell 5.1, git 2.52).

Folder	Content
harness/	The pi program itself — npm package @earendil-works/pi-coding-agent v1.3.0 + its complete node_modules dependency tree (15 047 files, ~106 MB, 78 top-level deps), incl. the @earendil-works scoped packages (chord, pi-agent-core, pi-ai, pi-telemetry, pi-tui). This is the pristine published 1.3.0 (no local patches — see Notes).
dot-pi/agent/	The personal configuration (a copy of ~/.pi/agent): skills, agents, extensions, prompts, memory files, provider/model settings
dot-pi/rag/	The RAG process — config.json (the live ~/.pi/rag/config.json: ragEnabled, trackedPaths → what gets indexed, profiles, thresholds). The index itself is rebuilt, not shipped (see RAG)
dot-pi/npm-manifest/	package.json + package-lock.json + .npmrc (legacy-peer-deps=true — the flag the lock was generated under) of the pi package cache ~/.pi/agent/npm/ — npm ci reproduces the exact dependency tree (pi packages and the RAG native deps) without committing the 498 MB cache

Portable by design: no path in this project is hard-coded to the source user (connessn). Everything resolves relative to the installing user's profile: pi config under %USERPROFILE%\.pi\, optional doc trees under %USERPROFILE%\Datas\… (see Path conventions). The one file with source-machine paths is dot-pi/rag/config.json (trackedPaths), which you are told to edit in step 5.

Excluded by design (table at the bottom): session data, all API keys and credential stores, the pi package cache (dot-pi/agent/npm/, restored from the committed manifests), the RAG index ~/.pi/rag/rag.db and the embedding model (rebuilt/re-downloaded on demand), and the cross-encoder reranker model. The full current set of extensions, skills, agents, the RAG process config and the npm dependency lock are included.

Re-run this save later: the comit_pi subagent (in dot-pi/agent/agents/) automates the whole save-and-push. Ask pi to "run comit_pi" / "save the pi harness" and it rebuilds harness/ + dot-pi/agent/ from the live machine, refreshes the RAG config + the npm manifests including the legacy-peer-deps .npmrc, masks the key, checks the safety gates (G7/G8 cover the manifests + rag config), and pushes to origin/main.

---

Prerequisites (one-time, on the new machine)

• Windows 10/11 (PowerShell 5.1+ ships with the OS)
• Node.js LTS (source machine runs v24.13.1; npm 11.21.0)
• git

Install them (PowerShell, run as normal user — winget installs for the current user by default):

winget install OpenJS.NodeJS.LTS
winget install Git.Git
# make PowerShell behave like cmd for npm/node: PS resolves `npm` to the npm.ps1
# script shim (blocked by the default Restricted execution policy), cmd uses
# npm.cmd. One-time, per-user, no admin needed:
Set-ExecutionPolicy -Scope CurrentUser -Force RemoteSigned
# close and reopen PowerShell so the new PATH (node, npm, git) is picked up, then check:
node --version    # v24.x expected (any recent LTS works)
npm --version
git --version

If npm works in cmd but not in PowerShell: both shells see the same PATH, but they resolve npm to different shims — cmd runs npm.cmd, while PowerShell runs the npm.ps1 script, which the default Restricted execution policy blocks ("running scripts is disabled"). One-time fix, no admin needed:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Same result without changing the policy: type npm.cmd instead of npm in PowerShell. If the error is instead "npm is not recognized", it is a stale PATH, not a shim issue — the terminal was opened before the winget install; close it and reopen it.

Install — from the harness folder to a working session (all PowerShell)

All commands below are PowerShell and use the FIXED path C:\pi-personal — no variables, so every command works in any window (even a freshly opened one). If the repo is not there, run the one-time move in step 0.

# ── 0) Get this folder ─────────────────────────────────────────────────────────
# Option A — clone the repo (private repo: you need access + a git credential,
# e.g. `gh auth login` first, or a personal access token):
git clone https://github.com/Tithanium/pi-personal C:\pi-personal
# Option B — you already have the folder (USB, sync, …) at another path:
#            move it to C:\pi-personal ONCE (adapt the source path):
#            Move-Item "C:\where\you\put\pi-personal" C:\pi-personal

# ── 1) Install the EXACT same pi version from the saved harness ───────────────
# (harness/ contains the full package incl. node_modules, so the installed copy
#  is byte-identical to the source machine's)
cd C:\pi-personal\harness
npm install -g .
pi --version                 # expected: 1.3.0
# zero-install sanity check (the shipped bundle is self-contained):
node .\dist\bundle\cli.js --version   # also expected: 1.3.0

# ── 2) Restore the personal configuration into ~/.pi ──────────────────────────
# TWO CASES — the same three commands handle both:
#
#   CASE A — ~/.pi ALREADY EXISTS (pi was already used on this machine):
#            the copy MERGES into the existing ~/.pi; on file conflicts the
#            saved config (dot-pi) wins; your existing sessions stay untouched.
#            For a PRISTINE start instead, delete the old config FIRST:
#                Remove-Item $env:USERPROFILE\.pi -Recurse -Force
#
#   CASE B — ~/.pi DOES NOT EXIST (fresh machine):
#            the folder MUST be created BEFORE the copy. If you copy into a
#            non-existent destination, Copy-Item renames the single copied
#            folder (agent) TO .pi itself — the files then land one level too
#            high (.pi\settings.json instead of .pi\agent\settings.json).
#
# The New-Item line is what makes case B safe; it is a no-op in case A.
New-Item -ItemType Directory -Force $env:USERPROFILE\.pi | Out-Null
Copy-Item -Recurse -Force C:\pi-personal\dot-pi\* $env:USERPROFILE\.pi\
Test-Path $env:USERPROFILE\.pi\agent\settings.json   # expected: True (both cases)
Test-Path $env:USERPROFILE\.pi\rag\config.json       # expected: True (RAG process)

# ── 3) Restore the exact npm dependency cache (pi packages + RAG native deps) ─
# dot-pi/npm-manifest/ carries package.json + package-lock.json + .npmrc of the
# cache; npm ci rebuilds ~/.pi/agent/npm/node_modules at the LOCKED versions
# (pi-okf, pi-tps-live, pi-observational-memory, @nehlis/pi-effort,
#  better-sqlite3, sqlite-vec, @xenova/transformers, onnxruntime-node,
#  pdf-parse, mammoth, turndown, sharp, ignore, pi-llama-cpp, …).
#
# >> THE .npmrc IS NOT OPTIONAL: the lock was generated with legacy-peer-deps=true,
# >> so peer deps (e.g. @earendil-works/pi-coding-agent, the peer of pi-okf and
# >> @nehlis/pi-effort) were neither installed nor written into the lock. npm's
# >> default mode (legacy-peer-deps=false) re-validates the tree against strict
# >> peer rules and aborts with ~100 `Missing: … from lock file` errors
# >> (npm error code EUSAGE, exit 1) on any machine with default npm settings.
$npmDir = "$env:USERPROFILE\.pi\agent\npm"
New-Item -ItemType Directory -Force $npmDir | Out-Null
Copy-Item "$env:USERPROFILE\.pi\npm-manifest\package.json"     $npmDir\ -Force
Copy-Item "$env:USERPROFILE\.pi\npm-manifest\package-lock.json" $npmDir\ -Force
Copy-Item "$env:USERPROFILE\.pi\npm-manifest\.npmrc"            $npmDir\ -Force
# --legacy-peer-deps is belt-and-braces (same flag as the shipped .npmrc): step 3
# still succeeds if the .npmrc copy above was skipped or lost.
npm ci --legacy-peer-deps --prefix $npmDir   # fails loudly if the lock is broken
# npm 11 install-script gate: TODAY it only WARNs that better-sqlite3/sharp/
# protobufjs have install scripts "not yet covered by allowScripts", but a future
# npm (or strict-allow-scripts=true) turns that into a hard E/STRICTALLOWSCRIPTS
# failure. Approving once pins the three packages' scripts in package.json
# (skip the line if an older npm does not know `install-scripts` — it is advisory):
npm install-scripts approve --all --prefix $npmDir
Test-Path "$npmDir\node_modules\better-sqlite3"   # expected: True

# ── 4) Recreate the pi-local-rag dependency junction + register pi packages ───
# On the source machine extensions\pi-local-rag\node_modules is a JUNCTION into
# the cache above (one flat copy of the deps shared by pi and the extension).
# The junction itself is not committed — recreate it here, or the RAG extension
# cannot resolve better-sqlite3 & friends at startup.
$je = "$env:USERPROFILE\.pi\agent\extensions\pi-local-rag\node_modules"
if (-not (Test-Path $je)) {
  New-Item -ItemType Junction -Path $je -Target "$npmDir\node_modules" | Out-Null
}
Test-Path "$je\better-sqlite3"                # expected: True
# The packages key in settings.json [pi-okf, pi-tps-live, pi-observational-memory,
# @nehlis/pi-effort] points into the cache restored above; these calls re-register
# them with pi (idempotent, safe to run again after a pi upgrade):
pi install npm:pi-okf
pi install npm:pi-tps-live@1.0.1
pi install npm:pi-observational-memory
pi install npm:@nehlis/pi-effort

Why npm ci and not just pi install? pi install npm:<pkg> fetches one package at a time and lets versions drift; npm ci reproduces the locked tree, including the native modules the RAG index build needs (better-sqlite3, sqlite-vec, onnxruntime-node). The manifests are the committed half of that contract; the 498 MB node_modules is not committed. The .npmrc belongs to the manifests: npm ci validates the lock under the current peer-dep mode, and this lock was generated with legacy-peer-deps=true — without the committed .npmrc (or the explicit --legacy-peer-deps flag) the restore dies with ~100 Missing: … from lock file errors.

RAG — the process (config committed, index rebuilt)

The RAG pipeline (extensions/pi-local-rag/) is enabled in the shipped settings.json ("extensions": ["extensions/pi-local-rag/index.ts"]), and the process config ships in this repo as dot-pi/rag/config.json, restored by step 2 to ~/.pi/rag/config.json. What is shipped vs. rebuilt:

Piece	Shipped in this repo?	Restored by
Extension code (index.ts, indexing chunking, search, /rag commands, tools)	✅ dot-pi/agent/extensions/pi-local-rag/	step 2
Process config (ragEnabled, ragTopK, tracked paths to index, profiles)	✅ dot-pi/rag/config.json	step 2
npm deps of the index build	✅ manifests + the legacy-peer-deps .npmrc in dot-pi/npm-manifest/	step 3 (npm ci)
Dependency junction for the extension	❌ (a link, machine-local)	step 4
Embedding model Xenova/all-MiniLM-L6-v2 (~22 MB)	❌	downloaded to ~/.pi/rag-models/ on first index
The index itself ~/.pi/rag/rag.db (987 MB on the source box)	❌ (never — GitHub caps files at 100 MB, and the index embeds the source machine's doc trees)	rebuilt with /rag index, commands below
Cross-encoder reranker ms-marco-MiniLM-L-6-v2 (86.8 MB, optional reranking)	⚠️ only two unchanged test copies (tests/ab2/cache/…, tests/research/cache/…, committed before this save); the runtime cache research/cache/ is git-ignored by the extension	fetch the runtime copy: node $env:USERPROFILE\.pi\agent\extensions\pi-local-rag\research\download-reranker.mjs

5a) Point the config at YOUR documents

trackedPaths lists what gets indexed — the shipped values are the source machine's doc trees (they won't exist on your box):

$cfg = "$env:USERPROFILE\.pi\rag\config.json"
# NOTE: the file can carry a UTF-8 BOM — strip it before parsing:
(Get-Content $cfg -Raw) -replace "`uFEFF",'' | ConvertFrom-Json |
    Select-Object ragEnabled, ragProfile, trackedPaths
# EDIT trackedPaths in an editor (VS Code, or: notepad $cfg) so each entry is a
# folder you actually have, e.g.:
#   "C:\Users\<you>\Datas\02_RECHERCHE\00_Biblio\Doc_tech_fedoo"
#   "C:\Users\<you>\Datas\02_RECHERCHE\00_Biblio\Doc_tech_ANSYS"

Leaving the old paths in place is harmless but indexes nothing — /rag status shows tracked only for paths that exist.

5b) Build and maintain the index (inside an interactive pi session)

Start pi (pi) and run — in a TUI session, not with pi -p (print sessions skip the background refresh):

/rag index <path>     # FIRST RUN per tree: chunks + embeds everything into
                      # ~\.pi\rag\rag.db (creates the DB; downloads the 22 MB
                      # embedding model on the very first call — needs network)
/rag status           # index stats: tracked files, chunks, last refresh
/rag refresh          # incremental: only new/changed files since last run
/rag rebuild          # re-embed ALL tracked files (add --force = from scratch)
/rag rebuild --force  #   full rebuild when the DB or the schema changed
/rag search <query>   # hybrid BM25 + vector search (what rag_query uses)
/rag clear            # drop the index entirely (rebuild starts empty)
/rag help             # full command list (find/on/off/subagent/model/…)

Rules of thumb:

• Fresh machine: /rag index <path> once per tracked tree → done; the DB auto-refreshes in the background when it goes stale (24 h), and /rag refresh does the same on demand.
• After adding a doc tree: edit trackedPaths (5a), restart pi, then /rag index <newpath>.
• After changing the extension code or the embedding model: /rag rebuild --force.
• The same pipeline is reachable as tools: rag_index, rag_query, rag_status (used by the grep-all-rag / okf-agent-rag / okf-wiki-rag / rag-smoke subagents).

6) Start a working session

pi

Then, in the pi session:

/ALAN_connector <your ALAN API key>   # connect the ALAN provider (key saved)
/model                                 # pick a model

(details in the ALAN section below)

Verify the session is complete

• Footer shows a live tok/s line (pi-tps-live package, plus the local extension token-rate.ts)
• / completion offers: /okf-validate, /okf-inspect, /okf-diff, /okf-init, /okf-capture, /okf-update, /ALAN_connector, /model-ctx, /wsl2ps, /convert_pdf, /convert_jsonl_conv, /clear, /goal, /task, /git_it, /rag … (help|index|status|refresh|rebuild|search|clear), /skill:<name>, /agents:<name>
• Skills available: ALAN, ansys, creating-pi-tools, fedoo, github, goal, matplotlib, okf-agent-workflow, task (plus the okf skill that ships with the pi-okf package)
• Subagents available: ANSYS, FEDOO, coder, comit_pi, fedoo-example-runner, fedoo-okf-merger, fedoo-report-writer, fedoo-run-critic, grep-all-rag, injection-screen, okf-agent-rag, okf-wiki-rag, rag-smoke, researcher, reviewer, sum
• The bash tool runs PowerShell commands (extension bash-to-powershell.ts)
• /rag status on a freshly restored box reports an empty index — that is expected until 5b has been run

Troubleshooting — Test-Path from step 2 returned False: run Get-ChildItem $env:USERPROFILE\.pi -Force -Name. If the config files (settings.json, agents, skills, …) appear directly under .pi with no agent folder, the copy landed one level too high (case B trap). Redo step 2 case B: Remove-Item $env:USERPROFILE\.pi -Recurse -Force (only if .pi holds nothing of your own) → New-Item -ItemType Directory -Force $env:USERPROFILE\.pi | Out-Null → copy again → retest.

Troubleshooting — pi starts but /rag is missing or the RAG extension errors on better-sqlite3: the junction from step 4 is missing (it is a link, never committed). Re-run step 4's New-Item -ItemType Junction …, then check Test-Path "$env:USERPROFILE\.pi\agent\extensions\pi-local-rag\node_modules\better-sqlite3".

Troubleshooting — step 3 dies with ~100 Missing: … from lock file errors (npm error code EUSAGE, "package.json and package-lock.json are not in sync"): the committed .npmrc (legacy-peer-deps=true) did not land next to the manifests. The lock was generated with peer deps neither installed nor recorded, so npm's default strict peer mode can never validate it. Check:

Get-Content $env:USERPROFILE\.pi\agent\npm\.npmrc   # must print: legacy-peer-deps=true
Copy-Item "$env:USERPROFILE\.pi\npm-manifest\.npmrc" $env:USERPROFILE\.pi\agent\npm\ -Force
npm ci --legacy-peer-deps --prefix $env:USERPROFILE\.pi\agent\npm

(If even that fails, the flag is the whole fix — the one-liner is npm ci --legacy-peer-deps --prefix <dir>; --prefix is fine, npm reads the project .npmrc from the --prefix folder even when invoked from elsewhere.)

ALAN provider — the /ALAN_connector flow (key auto-save)

The ALAN (UGA) OpenAI-compatible service is wired through the ALAN_connector extension (~/.pi/agent/extensions/ALAN_connector/index.ts — a single, fully self-contained TypeScript file, shipped in dot-pi/). It uses no PowerShell scripts, probe_result.json, or external log files. In a pi session:

/ALAN_connector            # or: /ALAN_connector <your ALAN API key>

1. Probe: it calls GET https://alan.univ-grenoble-alpes.fr/api/models directly from Node. The base URL can be overridden with the ALAN_BASE_URL environment variable.
2. Key resolution (in order): (a) the argument /ALAN_connector <key>, (b) the ALAN_API_KEY environment variable, (c) api_config.json created next to index.ts after first use, (d) the existing providers.alan.apiKey in models.json, (e) an interactive prompt. The prompt only appears if the probe answers HTTP 401/403 (or no key was found at all).
3. Model picker: a scrollable list of the live models appears below the prompt (↑/↓ navigate, Enter select, Esc cancel).
4. Auto-save (no further questions): on select, the command
   • backs up ~/.pi/agent/models.json + settings.json (.bak_yyyyMMdd_HHmmss; skipped when the newest backup already has identical content),
   • merges providers.alan including the API key into models.json,
   • sets defaultProvider: alan + defaultModel: <picked> in settings.json,
   • hot-applies to the running session (catalog reload + model switch — no restart needed),
   • persists the key to api_config.json (next to index.ts) when it was supplied as an argument or entered interactively, so it is not needed again.
5. The key is never printed and never written to any log.

So on a fresh install: start pi → /ALAN_connector <your ALAN API key> → /model → pick a model → done.

Rollback after a bad write (no subcommand): the command always leaves models.json.bak_* / settings.json.bak_* next to the originals — copy the newest one back over the original in ~/.pi/agent/ and restart pi, or simply re-run /ALAN_connector <correct key> to rewrite the config.

Note: api_config.json is created at runtime and is git-ignored — it is never part of this repo. The committed models.json carries the masked placeholder sk-REMPLACEZ_PAR_VOTRE_CLE.

If the ALAN service is NOT reachable from your machine (it is the source user's institutional service), skip it and set defaultProvider/defaultModel in $env:USERPROFILE\.pi\agent\settings.json to any provider you have (see the ALAN provider note in Notes); the ALAN skill and extension remain inert but harmless.

Path conventions

• ~ = your user profile = %USERPROFILE% (e.g. C:\Users\<you>).
• pi config: %USERPROFILE%\.pi\agent\ (skills, agents, extensions, prompts, settings.json, models.json, memory files). All extensions/skills/agents in this save resolve their files from there — nothing is hard-coded to the source user.
• RAG process: %USERPROFILE%\.pi\rag\config.json (settings: tracked paths, thresholds, profiles), index %USERPROFILE%\.pi\rag\rag.db (local, rebuilt), embedding model cache %USERPROFILE%\.pi\rag-models\ (local, re-downloaded).
• Optional doc trees referenced by the ansys / fedoo skills and agents (ANSYS APDL documentation + examples, fedoo docs + examples + OKF bundles) live under %USERPROFILE%\Datas\02_RECHERCHE\00_Biblio\… on the source machine only — that research data is NOT part of this save. If the folders don't exist on your machine, the ANSYS/FEDOO advisers still load and work, but answer without local doc references (their OKF bundles start empty). They are also what the shipped trackedPaths points at — see step 5a. To restore full behavior, place the Doc_tech_ANSYS / Doc_tech_fedoo trees under %USERPROFILE%\Datas\02_RECHERCHE\00_Biblio\.
• The ALAN skill's documentation artifacts lived in the source machine's dev folder %USERPROFILE%\Datas\02_RECHERCHE\11_all_AI\00_Harnesses_launch_ALAN — dev tooling, not part of this save; all runnable behavior is in the ALAN_connector extension folder instead.

What is included

Extensions (dot-pi/agent/extensions/)

Item	Role
subagent/	The subagent tool — spawns the agents in dot-pi/agent/agents/ as fresh pi -p sessions
bash-to-powershell.ts	Reroutes pi's bash tool onto the PowerShell backend (WSL bash was dead on the source machine)
wsl-powershell.ts	Translates WSL commands to PowerShell with a byte-identical syntax check + curated verified mapping; /wsl2ps <cmd>
clear-command.ts	/clear — exact alias of the built-in /new
model-default-confirm.ts	Asks "y?" before persisting a new startup default model
model-context-picker.ts	Context-length-aware /model picker (Enter on /model); fallback command /model-ctx
token-rate.ts	Footer token-rate (overlaps pi-tps-live; source machine keeps pi-tps-live)
tool-name-case-fix.ts	Normalizes tool-name casing on the way in
validate-verified-facts.mjs	Lint of VERIFIED_FACTS.md (fact format)
git_it.ts	Git-workflow extension (/git_it --github …)
ALAN_connector/	/ALAN_connector — self-contained probe → key prompt (only on 401/403) → model picker → auto-save provider+key+default (see ALAN section). Runtime key file api_config.json is git-ignored
convert-pdf/	/convert_pdf <folder> [--force] [--out DIR] — recursive PDF→text via python pdf2text.py (needs Python + pymupdf)
convert-jsonl-conv/	/convert_jsonl_conv — python-free TS conversion port + golden_test.cjs regression test
pi-local-rag/	Local hybrid RAG pipeline (BM25 + vector, ONNX embeddings) — /rag … commands, rag_index/rag_query/rag_status tools, subagent injection hook. ENABLED in the shipped settings.json; process config committed at dot-pi/rag/config.json; index rebuilt per the RAG section

(The folder also contains dev leftovers that the snapshot faithfully keeps: output_fedoo_mesh_apis.md, .... — a directory literally named ...., which Windows path normalization mangles — plus per-extension .bak-* backups of the RAG source files. None of them are loaded by pi.)

Skills (dot-pi/agent/skills/)

ALAN (ALAN model-service wiring) · ansys (ANSYS APDL adviser, OKF-backed) · creating-pi-tools (authoring pi packages/extensions/commands — the harness skill) · fedoo (fedoo FEA-library adviser, OKF-backed) · github (GitHub/gh workflows) · goal (gauntlet-loop task bar) · matplotlib (plotting, needs Python 3.10+ / matplotlib 3.10.x) · okf-agent-workflow (wiring OKF into agents) · task (minimal-bar task loop)

Agents (dot-pi/agent/agents/)

ANSYS · FEDOO (domain advisers, OKF workflow per call) · researcher (read-only investigation) · sum (VERIFIED_FACTS consolidation, used by the memory workflow) · coder (code implementation) · reviewer (code review) · injection-screen (prompt-injection scan) · fedoo-example-runner / fedoo-okf-merger / fedoo-report-writer / fedoo-run-critic (fedoo example + report pipeline) · grep-all-rag, okf-agent-rag, okf-wiki-rag, rag-smoke (RAG fan-out subagents used by the memory/OKF workflows) · comit_pi (this repo's save-and-push runbook) · Storage_future_service/ (a dev workbench subfolder)

Memory & configuration (root of dot-pi/agent/)

AGENTS.md (session rules read by every pi session) · AGENTS2.md (longer variant) · VERIFIED_FACTS.md (verified environment facts — a history of the SOURCE machine, banner at the top; the live ALAN key prefix is scrubbed) · SAFE_LAUNCH.md (safe-launch procedure — source-machine provenance only, its launch script is not part of this save) · settings.json (provider/model/ packages/defaultTools; pi-local-rag enabled) · keybindings.json · models.json (ALAN provider, apiKey masked as sk-REMPLACEZ_PAR_VOTRE_CLE) · models.json.example · prompts/ (goal.md, task.md) · bin/ (fd.exe, rg.exe — used by pi's find/grep when present)

Pi npm packages + dependency lock

Registered in settings.json (packages key) and installed in step 4: npm:pi-okf (okf_* tools, /okf-* commands, okf skill) · npm:pi-tps-live@1.0.1 (footer tok/s) · npm:pi-observational-memory (observational memory / recall) · npm:@nehlis/pi-effort (per-model effort/thinking control).

The full locked tree (those four plus the RAG build deps better-sqlite3, sqlite-vec, @xenova/transformers, onnxruntime-node, pdf-parse, mammoth, turndown, sharp, ignore, pi-llama-cpp and their transitive deps) is committed as dot-pi/npm-manifest/{package.json,package-lock.json,.npmrc} and restored with npm ci in step 3. The .npmrc carries legacy-peer-deps=true — the mode the lock was generated under; without it npm ci fails with ~100 Missing: … from lock file errors (verified: with the file present the restore exits 0, without it EUSAGE/exit 1).

What was excluded, and why

Excluded	Why
sessions/ (~175 MB)	Private session history, regenerable
auth.json, models-store.json	Credential stores
models.json apiKey (masked as sk-REMPLACEZ_PAR_VOTRE_CLE), the live key prefix in VERIFIED_FACTS.md (scrubbed), ALAN_connector/api_config.json	API keys — masked/scrubbed; the runtime key file is git-ignored and simply absent
*.bak*, models_back.json, *.log	Backups and logs (globally git-ignored)
dot-pi/agent/npm/ (the 498 MB package cache)	Restored exactly from the committed manifests with npm ci (step 3) — only package.json/package-lock.json/.npmrc are shipped, in dot-pi/npm-manifest/ (the .npmrc must ship: the lock was generated under legacy-peer-deps=true)
dot-pi/agent/extensions/pi-local-rag/node_modules	Not a real folder on the source machine — it is a junction into the npm cache above; the cache would be committed twice. Recreated as a junction in step 4
~/.pi/rag/rag.db (987 MB index) + ~/.pi/rag-models/ (~22 MB ONNX embedding model) + the runtime cross-encoder reranker cache pi-local-rag/research/cache/ (87 MB)	The index embeds the source user's doc trees AND blows past GitHub's 100 MB per-file cap — it is rebuilt with /rag index / /rag rebuild (step 5b); the embedding model is re-downloaded on first use; the reranker cache is git-ignored by the extension's own .gitignore ("re-downloadable via research/download-reranker.mjs" — its two frozen tests/ bench copies are already tracked). The RAG process (extension + config.json + dep lock) is committed

Note on dev tools: an earlier save (2026-10-01) deliberately excluded a set of development tools (skills creating-pi-tools, github, okf-agent-workflow; agents coder, reviewer, injection-screen, ps, shell, Storage_future_service/; extension git_it.ts). This save is a faithful snapshot of the current harness, so all of them are now included. To re-exclude any of them later: delete the file/folder from dot-pi/agent/… — top-level .ts extensions, agent .md files and skill folders are auto-discovered on the next pi start.

Notes

• The saved harness is the pristine published 1.3.0 — no local patches. The earlier 0.86.1 save carried a local /skill: autocomplete fix in the bundle and in pi-tui; that fix was dropped when the source machine upgraded past 0.86.1 and is not part of 1.3.0. harness/node_modules also ships the per-platform @esbuild/* binaries (needed by pi's toolchain; the win32-x64 one is the one actually used).
• pi-local-rag is ENABLED by default in this save (settings.json carries "extensions": ["extensions/pi-local-rag/index.ts"], i.e. the positive include line — an earlier save had it disabled with a - exclusion). The full procedure to get a working index on a new machine is the RAG section: restore config → npm ci → junction → edit trackedPaths → /rag index <path>.
• ALAN provider: models.json points at https://alan.univ-grenoble-alpes.fr/api — the source user's institutional OpenAI-compatible model service. If it is not reachable from your machine, set defaultProvider/defaultModel in $env:USERPROFILE\.pi\agent\settings.json to any provider you have access to (e.g. after pi login), or edit/replace the alan entry in models.json.
• Update cycle from this repo: the comit_pi subagent does the whole job (rebuild harness/ + dot-pi/agent/, refresh dot-pi/rag/config.json and dot-pi/npm-manifest/{package.json,package-lock.json,.npmrc}, mask the key, run the gates G1-G8, push). Manually it is: change something in the live ~/.pi/agent/ or upgrade pi → ask pi to run comit_pi. The repo is private — keep it that way; it carries private configuration even though it holds no live keys.