fix: mata o painel Skill conflicts + avisos de update com marca imp

Skills: o Pi >=0.84 varre .agents/skills/ nativamente (mesmo gate de trust,
interativo e headless), então a cópia em .pi/skills/ (perna `skills add -a pi`)
duplicava cada skill oficial por realpath e abria toda sessão com ~40 colisões.
installProjectSkills faz UMA invocação (-a claude-code cursor);
backfillPiSkills vira prunePiSkillCopies (lock-driven, nunca toca
.pi/skills/fia/), rodando no step FIA e no --update-runtime para migrar
projetos antigos; o --verify inverte o check (cópia = warning de duplicata).

Branding: imp lança o Pi com PI_SKIP_VERSION_CHECK=1 e imprime aviso próprio
("Run imp update") após a sessão — probe collectUpdateNotices em background,
nada em saída piped. Os 3 pacotes Pi entram com pin exato (o check do Pi pula
pacote pinado → banner "pi update --extensions" some) e imp update agora
re-resolve e re-pina os 3 (antes nem os atualizava, o banner voltava sempre).
isNewer entende prerelease (impactus vive em 2.0.0-alpha.N).

Novos: CLAUDE.md (mapa do sistema) e lessons.md (log vivo de problemas
recorrentes, semeado com as duas lições de hoje). Versão 2.0.0-alpha.4.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: elberrd

CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md — impactus (the IAI installer)
+
+## What this is
+
+`impactus` is the IAI installer CLI, published on npm. Students run
+`npx impactus` (or the `imp` brand launcher) to stamp a project with the agent
+harness plus the FIA — the IAI Agent Factory: Pi as the interactive agent,
+deterministic FDAs (fully-automated dev agents), and subscription-based auth
+(Claude only through the official `claude` CLI, Codex through Pi — never API
+keys or extra usage).
+
+- `bin/create-iai.js` — the installer entry (`npx impactus`, `imp init`).
+- `bin/imp.js` — the `imp` launcher: a thin brand wrapper over the real `pi`
+  binary, **not a Pi fork**. `init`/`update`/`tui`/`help` are imp commands;
+  everything else passes straight through to `pi` (stdout must stay
+  byte-identical for piped runs).
+- `src/steps/` — the install pipeline, one step per file (preflight, template,
+  clerk, convex, stack, fia, verify, update-runtime, finish…).
+- `src/lib/` — shared helpers (proc, ui, skills, pi-auth, args…).
+- `fia-templates/` — the `imp/` runtime stamped into projects (FDA scripts,
+  sequencers, TUI, gates).
+- `pi-templates/` — the project `.pi/` (prompts, the `fia` skill + cookbooks,
+  extensions).
+- `harness/`, `live1/`, `live2/` — the harness and the two live templates
+  (separate repos checked out here; the harness is the single source of truth
+  for skills/commands — templates never carry their own copies).
+- `test/` — `node:test` suite. `docs/` + `DOCS.md` — the deep documentation.
+
+## Commands
+
+```bash
+npm test          # full suite (node test/run.mjs)
+npm run lint      # eslint
+npm run sync:skills   # regenerates .cursor/skills mirrors (never edit those by hand)
+```
+
+## Hard rules
+
+- Node floor is **>= 22.12** everywhere (repo, templates, generated projects).
+- Everything that ships (CLI output, templates, prompts, docs) is **English**.
+  Commit messages are Portuguese, matching the history.
+- Nothing about optional extras (skills, Impeccable, addons) may ever abort an
+  install — degrade with a warning and print the manual command.
+- Skills topology: the canonical copy lives in `.agents/skills/<name>/`;
+  Claude Code symlinks it, Cursor and Pi read it directly. Never reintroduce
+  copies in `.pi/skills/` (Pi dedupes by realpath — a copy means a "Skill
+  conflicts" panel at every launch).
+- A new student-facing command must be registered everywhere it is listed
+  (prompt file, `fia` SKILL.md routing, `finish.js` panels, README, DOCS).
+- Run `npm test` and `npm run lint` before committing. Commit/push only when
+  the user asks.
+
+## Lessons
+
+`lessons.md` at the repo root is the living log of recurring problems and
+their fixes. **Check it before debugging a symptom that feels familiar**, and
+append a new entry (symptom → cause → fix → guard) whenever a notable bug is
+identified and corrected.

DOCS.md

@@ -358,28 +358,27 @@ On disk, per engine:
 | ------ | ---- | ----------------- |
 | Cursor | `.agents/skills/<name>/SKILL.md` | the canonical store, read directly ("universal") |
 | Claude Code | `.claude/skills/<name>` | symlink to the store |
-| Pi (FIA agents) | `.pi/skills/<name>` | a copy — Pi does not follow the symlink |
+| Pi (FIA agents) | `.agents/skills/<name>` | native `.agents/` discovery — no copy of its own |
 
 `skillsAddArgs(spec, agents)` builds the argv and `installProjectSkills` runs it
-**twice**: `-a claude-code cursor`, then `-a pi`. Measured against
-skills@1.5.22 (Aug 2026), that is the only combination that covers the three
-engines: `-a claude-code` alone never creates `.agents/skills/` (Cursor gets
-nothing); `-a claude-code cursor pi` installs the first two and silently drops
-pi; the comma form `-a a,b,c` is rejected and installs nothing. The `-a` stays
-last in the argv so the variadic cannot swallow the `-y`. The second run is
-best-effort and only happens when the project has a `.pi/` — a `--no-fia`
-install has none, and a failure there warns without failing the step (as ever,
-nothing about skills aborts an install; the manual command for **both** groups
-is printed).
-
-Ordering matters here: every step that installs skills (storage, integrations,
-stack docs) runs BEFORE the FIA step that stamps `.pi/`, so on a fresh install
-that second run would find no `.pi/` and skip. That is what
-`backfillPiSkills(dir)` closes — called by `src/steps/fia.js` right after the
-stamp, it reads `skills-lock.json`, groups the entries by `source` and replays
-one `skills add … -a pi` per source. Best-effort as well: a failed source warns
-with its manual command, and an install re-run in an existing project (where
-`.pi/` is already there) simply does the copy twice, harmlessly.
+**once**, with `-a claude-code cursor`. Measured against skills@1.5.22
+(Aug 2026): `-a claude-code` alone never creates `.agents/skills/` (Cursor gets
+nothing), and the comma form `-a a,b` is rejected and installs nothing. The
+`-a` stays last in the argv so the variadic cannot swallow the `-y`. A failure
+warns without failing the step (as ever, nothing about skills aborts an
+install; the manual command is printed).
+
+Pi needs no leg of its own: it scans the project's `.agents/skills/` natively
+(behind the same project-trust gate as `.pi/skills/`, in interactive and
+headless runs alike), so one canonical copy serves the three engines. Older
+CLI versions DID run a second `skills add … -a pi` per source — and since Pi
+dedupes discovered skills by realpath, that real copy made every skill load
+twice and opened each Pi session with a "Skill conflicts" panel listing all of
+them. `prunePiSkillCopies(dir)` cleans those leftovers: lock-driven (so
+harness-owned skills like `.pi/skills/fia/` are never touched) and
+conservative (a copy is only removed when its `.agents/skills/` canonical
+exists). It runs in the FIA step and in `--update-runtime`, which is how
+projects stamped by the old flow heal on their next update.
 
 The install is recorded in `skills-lock.json` (v1: `{version, skills: {<name>:
 {source, sourceType, skillPath, computedHash}}}`), which the project commits —

README.md

@@ -18,7 +18,7 @@ Academy launcher):
 npm i -g impactus
 imp init     # installs the harness/FIA in the current folder (same as npx impactus)
 imp          # starts Pi here — IMPACTUS banner, installs Pi if it's missing
-imp update   # updates impactus + Pi
+imp update   # updates impactus + Pi + the Pi extension packages
 ```
 
 `imp` is a thin brand wrapper, **not a Pi fork**: anything that isn't
@@ -826,16 +826,14 @@ each engine reads them from:
 | ------ | ---- | ----------------- |
 | Cursor | `.agents/skills/<name>/SKILL.md` | the canonical copy — Cursor reads this folder directly |
 | Claude Code | `.claude/skills/<name>` | symlink to the canonical copy |
-| Pi (FIA agents) | `.pi/skills/<name>` | a **copy** — Pi does not follow the symlink |
-
-The installer therefore runs `skills add` **twice**: once for
-`-a claude-code cursor`, then once for `-a pi`. Passing the three at once makes
-the CLI silently skip Pi, and the comma form (`-a a,b,c`) installs nothing at
-all. The Pi run needs a `.pi/` folder, which only exists once the FIA is
-stamped — so on a fresh install the FIA step replays the sources from
-`skills-lock.json` into `.pi/skills/` right after stamping. Without the FIA
-(`--no-fia`) there is no Pi copy, and nothing about skills ever fails an
-install.
+| Pi (FIA agents) | `.agents/skills/<name>` | Pi discovers the `.agents/` store natively — no copy |
+
+The installer runs `skills add` once, with `-a claude-code cursor` (the comma
+form `-a a,b` installs nothing at all). One canonical copy serves the three
+engines — a separate `.pi/skills/` copy would make Pi load every skill twice
+and open each session with a "Skill conflicts" panel, which is exactly what
+older installer versions did; updated projects clean those leftovers
+automatically. Nothing about skills ever fails an install.
 
 In the project, day to day:
 

bin/imp.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 // imp — the IMPACTUS Academy launcher. A thin brand wrapper, NOT a Pi fork:
 //   imp init …  → runs the impactus installer (bin/create-iai.js) in-place
-//   imp update  → updates impactus + Pi
+//   imp update  → updates impactus + Pi + the Pi extension packages
 //   imp [args]  → hands everything else to the real `pi` binary (stdio
 //                 inherited), installing Pi first if it is missing.
 // Keeping Pi as the actual agent means `pi update`, Codex login and the
-// project-level .pi/ config all keep working unchanged.
+// project-level .pi/ config all keep working unchanged. The only Pi behavior
+// imp touches is the startup update notice: it is pi-branded ("Run pi
+// update"), so imp suppresses it (PI_SKIP_VERSION_CHECK) and prints its own
+// imp-branded one after the session ends — see collectUpdateNotices.
 
 // Node version gate — the `engines` field doesn't block `npx` execution, so
 // enforce it here with a clear message (before importing anything modern).
@@ -56,7 +59,7 @@ Usage:
   imp                    Start Pi in the current folder (installs Pi if missing)
   imp init [options]     Install the harness/FIA here (same as npx impactus;
                          all impactus flags work — see \`imp init --help\`)
-  imp update             Update impactus and Pi to the latest versions
+  imp update             Update impactus, Pi and the Pi extension packages
   imp tui                Terminal dashboard — tasks, specs and runs (same as npm run tui)
   imp help               Show this help
   imp --version          Print the impactus version
@@ -95,7 +98,7 @@ if (cmd === 'init') {
 if (cmd === 'update') {
   banner();
   const { runInherit } = await import('../src/lib/proc.js');
-  const { hasPi, ensurePiReady } = await import('../src/lib/pi-auth.js');
+  const { hasPi, ensurePiReady, installPiPackages } = await import('../src/lib/pi-auth.js');
 
   console.log(`Updating impactus (npm install -g ${pkg.name}@latest)…`);
   const up = await runInherit('npm', ['install', '-g', `${pkg.name}@latest`]);
@@ -115,6 +118,17 @@ if (cmd === 'update') {
     console.error(err?.message || String(err));
     process.exit(1);
   }
+
+  // The Pi extension packages are exact-pinned (that pin is what keeps Pi's
+  // pi-branded "Package Updates Available" panel away) — move the pins here.
+  // Best-effort: an offline refresh must not fail the whole update.
+  try {
+    console.log('Updating the Pi extension packages (subagents + MCP + web access)…');
+    await installPiPackages(process.cwd());
+  } catch (err) {
+    console.error(`Could not refresh the Pi extension packages: ${err?.message || String(err)}`);
+    console.error('Run `imp update` again when back online.');
+  }
   console.log('Done.');
   process.exit(up.ok ? 0 : 1);
 }
@@ -139,9 +153,9 @@ if (cmd === 'tui') {
 // must arrive exactly as `pi` would produce it.
 if (process.stdout.isTTY) banner();
 const { runInherit } = await import('../src/lib/proc.js');
-const { hasPi, ensurePiReady } = await import('../src/lib/pi-auth.js');
+const { hasPi, ensurePiReady, collectUpdateNotices } = await import('../src/lib/pi-auth.js');
 
-// Only install when missing — no network version check on every launch
+// Only install when missing — the launch itself never blocks on the network
 // (`imp update` and the installer already keep Pi fresh).
 if (!(await hasPi())) {
   try {
@@ -153,6 +167,23 @@ if (!(await hasPi())) {
   console.log(pc.dim('Tip: inside Pi, type /login openai-codex to connect your ChatGPT subscription.'));
 }
 
+// The update probe runs in the background WHILE the session is open and is
+// only printed after Pi exits — zero launch latency, and nothing for piped
+// runs (`imp -p … > file` must carry exactly Pi's output).
+const notices = process.stdout.isTTY ? collectUpdateNotices(pkg.version).catch(() => []) : null;
+
 const args = cmd === undefined ? [] : [cmd, ...rest];
-const r = await runInherit('pi', args);
+const r = await runInherit('pi', args, { env: { PI_SKIP_VERSION_CHECK: '1' } });
+
+if (notices) {
+  // Race, don't wait: if the probe is still mid-flight after a short
+  // one-shot session, skip it rather than hold the student's terminal.
+  const lines = await Promise.race([notices, new Promise((res) => setTimeout(res, 400, []))]);
+  if (lines.length > 0) {
+    console.log('');
+    console.log(pc.bold(pc.yellow('Updates available')));
+    for (const line of lines) console.log(pc.yellow(`  - ${line}`));
+    console.log(pc.yellow('Run `imp update` to bring everything current.'));
+  }
+}
 process.exit(r.exitCode);

lessons.md

@@ -0,0 +1,47 @@
+# Lessons — problemas identificados e como foram corrigidos
+
+Log vivo dos problemas que aparecem com frequência neste sistema. Formato
+simples: um bloco por lição, o mais novo no topo. Antes de investigar um bug
+"novo", confira se ele já está aqui; depois de corrigir um bug notável,
+registre a lição.
+
+---
+
+## 2026-08-13 — Painel "Skill conflicts" no primeiro `imp` do projeto
+
+- **Sintoma:** logo após o install, `imp` abre com ~40 colisões de skills
+  (`"convex" collision: … skipped`), uma por skill oficial instalada.
+- **Causa:** o instalador copiava cada skill para `.pi/skills/` (segunda
+  invocação `skills add … -a pi`). O Pi ≥0.84 já varre `.agents/skills/`
+  nativamente e dedupa por realpath — a cópia real fazia cada skill ser
+  descoberta duas vezes, e cada duplicata vira uma linha do painel.
+- **Correção:** perna `-a pi` removida (`src/lib/skills.js` — uma invocação
+  só, `-a claude-code cursor`); `backfillPiSkills` substituído por
+  `prunePiSkillCopies` (lock-driven, roda no step FIA e no
+  `--update-runtime`, migra projetos antigos); `--verify` agora acusa cópia
+  duplicada em vez de exigi-la.
+- **Guarda:** `test/skills.test.js` (prune) e `test/verify.test.js`
+  (warning de duplicata). Colisão residual = skill global do usuário em
+  `~/.pi/agent/skills/` ou `~/.agents/skills/` — informacional, projeto ganha.
+
+## 2026-08-13 — Avisos de update com a marca errada ("Run pi update")
+
+- **Sintoma:** o Pi mostra "Update Available — Run **pi** update" e "Package
+  Updates Available — Run **pi** update --extensions"; o aluno só conhece
+  `imp`. Pior: `imp update` não atualizava os pacotes de extensão, então o
+  segundo banner voltava sempre.
+- **Causa:** os textos usam `APP_NAME` lido do package.json do próprio pacote
+  Pi (`piConfig.name`) — rebrandear exigiria fork. E `imp update` rodava só
+  `npm i -g impactus` + `pi update`, nunca `pi update --extensions`.
+- **Correção (sem fork, wrapper continua fino):**
+  1. `imp` lança o Pi com `PI_SKIP_VERSION_CHECK=1` e imprime aviso próprio
+     ("Run `imp update`") DEPOIS da sessão — probe em `collectUpdateNotices`
+     (`src/lib/pi-auth.js`), roda em background, nunca em saída piped.
+  2. Os 3 pacotes Pi (pi-subagents, pi-mcp-adapter, pi-web-access) são
+     instalados com **pin exato** (`npm:<pkg>@x.y.z`) — o check de update do
+     Pi pula pacote pinado, então o banner de pacotes não existe mais.
+  3. `imp update` agora re-resolve e re-pina os 3 (o `pi install` substitui a
+     entry quando o nome bate).
+- **Guarda:** `test/pi-auth.test.js` (isNewer com prerelease) e
+  `test/imp-smoke.test.js` (stdout piped continua idêntico ao do `pi`).
+  Nunca editar o package.json global do Pi — `pi update` sobrescreve.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "impactus",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.4",
   "description": "impactus — the IAI installer: agent harness + FIA (the IAI Agent Factory) with Pi, deterministic FDAs and Claude/Codex subscription auth.",
   "type": "module",
   "bin": {