feat: layout imp/ — runtime, HARNESS.md e iai.config.json numa pasta só

O instalador agora carimba tudo em imp/ (era fia/): FDAs, módulos, viewer,
dados, imp/HARNESS.md e imp/iai.config.json. ai-docs/ permanece na raiz.
Projetos legados migram automaticamente (migrateLegacyFiaLayout): rename,
reescrita de caminhos em imp/, .pi/, .claude/, .cursor/, package.json e
.gitignore, rechaveamento do manifest preservando shas, retomada pós-crash
e merge quando o pipeline criou imp/ antes (addons). v2.0.0-alpha.2.

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

Author: elberrd

DOCS.md

@@ -56,6 +56,17 @@ if (flags.verify) {
   process.exit(ok ? 0 : 1);
 }
 
+// --update-runtime: re-stamps the FIA/Pi runtime of an already-installed
+// project from this package version and exits (config/data/local edits kept).
+if (flags.updateRuntime) {
+  const { runUpdateRuntime } = await import('../src/steps/update-runtime.js');
+  const ok = await runUpdateRuntime(flags).catch((err) => {
+    console.error(err?.stack || String(err));
+    return false;
+  });
+  process.exit(ok ? 0 : 1);
+}
+
 // The TERMINAL assistant is the default entry point: `npx impactus`
 // asks every decision right there and then executes. The web UI (building the
 // command by clicking in the browser) is opt-in via --ui — see lib/pipeline.js.

README.md

@@ -0,0 +1,143 @@
+#!/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 [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.
+
+// Node version gate — the `engines` field doesn't block `npx` execution, so
+// enforce it here with a clear message (before importing anything modern).
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 20 || (major === 20 && minor < 9)) {
+  console.error(`imp requires Node.js >= 20.9 (you are on ${process.versions.node}).`);
+  console.error('Update at https://nodejs.org and try again.');
+  process.exit(1);
+}
+
+const { readFile } = await import('node:fs/promises');
+const { fileURLToPath } = await import('node:url');
+const pc = (await import('picocolors')).default;
+
+const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+const INSTALLER = fileURLToPath(new URL('./create-iai.js', import.meta.url));
+
+// ANSI Shadow "IMPACTUS" — 64 columns wide.
+const ART = [
+  '██╗███╗   ███╗██████╗  █████╗  ██████╗████████╗██╗   ██╗███████╗',
+  '██║████╗ ████║██╔══██╗██╔══██╗██╔════╝╚══██╔══╝██║   ██║██╔════╝',
+  '██║██╔████╔██║██████╔╝███████║██║        ██║   ██║   ██║███████╗',
+  '██║██║╚██╔╝██║██╔═══╝ ██╔══██║██║        ██║   ██║   ██║╚════██║',
+  '██║██║ ╚═╝ ██║██║     ██║  ██║╚██████╗   ██║   ╚██████╔╝███████║',
+  '╚═╝╚═╝     ╚═╝╚═╝     ╚═╝  ╚═╝ ╚═════╝   ╚═╝    ╚═════╝ ╚══════╝',
+];
+const ART_WIDTH = 64;
+
+function banner() {
+  const columns = process.stdout.columns ?? 80;
+  if (process.stdout.isTTY && columns >= ART_WIDTH + 2) {
+    console.log('');
+    for (const line of ART) console.log(pc.cyan(line));
+    const sub = 'A  C  A  D  E  M  Y';
+    console.log(pc.bold(pc.cyan(' '.repeat(Math.floor((ART_WIDTH - sub.length) / 2)) + sub)));
+    console.log(pc.dim(`imp v${pkg.version} — Pi + the IAI harness, one command`));
+    console.log('');
+  } else {
+    console.log(`IMPACTUS Academy — imp v${pkg.version}`);
+  }
+}
+
+function helpText() {
+  return `
+imp — the IMPACTUS Academy CLI (Pi + the IAI harness)
+
+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 help               Show this help
+  imp --version          Print the impactus version
+
+Anything else is passed straight to Pi, e.g.:
+  imp -p "prompt"        One-shot prompt (headless)
+  imp --continue         Resume the last session
+
+First time? In your project folder run \`imp init\`, then \`imp\` and type
+/login openai-codex to connect your ChatGPT subscription. Never log in to
+Anthropic inside Pi — Claude runs through the official \`claude\` CLI.
+`.trimStart();
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+// --version stays banner-free and machine-readable, same as the installer.
+if (cmd === '--version' || cmd === '-v') {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  banner();
+  console.log(helpText());
+  process.exit(0);
+}
+
+if (cmd === 'init') {
+  banner();
+  const { runInherit } = await import('../src/lib/proc.js');
+  const r = await runInherit(process.execPath, [INSTALLER, ...rest]);
+  process.exit(r.exitCode);
+}
+
+if (cmd === 'update') {
+  banner();
+  const { runInherit } = await import('../src/lib/proc.js');
+  const { hasPi, ensurePiReady } = 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`]);
+  if (!up.ok) {
+    console.error(`Could not update impactus. Run it manually:  npm install -g ${pkg.name}@latest`);
+    console.error('If npm printed EACCES, reinstall Node.js in your user account (https://nodejs.org) — never use sudo.');
+  }
+
+  try {
+    if (await hasPi()) {
+      console.log('Updating Pi (pi update)…');
+      await runInherit('pi', ['update']);
+    } else {
+      await ensurePiReady(); // installs Pi with the friendly EACCES guidance
+    }
+  } catch (err) {
+    console.error(err?.message || String(err));
+    process.exit(1);
+  }
+  console.log('Done.');
+  process.exit(up.ok ? 0 : 1);
+}
+
+// Default: launch Pi with every argument passed through untouched.
+// Banner only when a human is watching: with stdout piped/captured
+// (`imp -p … > file`, scripts, another process driving imp) Pi's output
+// 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');
+
+// Only install when missing — no network version check on every launch
+// (`imp update` and the installer already keep Pi fresh).
+if (!(await hasPi())) {
+  try {
+    await ensurePiReady();
+  } catch (err) {
+    console.error(err?.message || String(err));
+    process.exit(1);
+  }
+  console.log(pc.dim('Tip: inside Pi, type /login openai-codex to connect your ChatGPT subscription.'));
+}
+
+const args = cmd === undefined ? [] : [cmd, ...rest];
+const r = await runInherit('pi', args);
+process.exit(r.exitCode);

bin/create-iai.js

@@ -0,0 +1,167 @@
+# Specialists — analysis and plan
+
+> **Decision taken (Aug 13, 2026) — the first concrete instance of this plan.**
+> The `frontend-design` skill (anthropics/skills) that rode into both template
+> lockfiles undecided was the "third design authority" conflict below. Instead
+> of keeping it installed as a competing skill, its general rules were
+> **absorbed** into the house `design-system` skill as
+> `references/design-direction.md` (adapted to our registry/theme system, with
+> golden rule 8 pointing at it), and the entry was removed from
+> `live1/skills-lock.json` + `live2/skills-lock.json`. The absorption follows
+> the CLI's differentiator — markdown states the rule, code checks it: the new
+> `theme_tokens` warn in `fia-launch-check.mjs` flags hardcoded hex in UI
+> components, which is the enforceable core of that skill's guidance. This is
+> the template for future cases: **vendor-specific knowledge stays an official
+> skill; general-taste/process knowledge gets absorbed into a house skill (as a
+> `references/` file) plus a deterministic check where one exists.** One-off
+> needs use `npx skills use <pkg>@<skill>` — load without installing.
+
+Question raised after studying Specsfy: they ship "especialistas" — optional
+knowledge packs for a technology (Laravel, React, Postgres, Docker, security,
+observability…), living in a GitHub catalog, installed on demand. Do we have
+something equivalent, and would adding it collide with what already exists?
+
+**Short answer: we have the substance, we lack the discovery — and the standard
+we already use solves it, so there is nothing to invent.** What needs designing
+is curation and precedence, not machinery.
+
+## What Specsfy's specialists actually are
+
+- ~25 technology skills in their own catalog, grouped by domain (backend/data,
+  frontend, interface, platform, quality, technical design, engineering).
+- `specsfy skills detect` scans the project and *recommends* without installing;
+  the user then picks explicitly with `specsfy skills add`; installs are
+  recorded in `skills-lock.json`.
+- They plug into workflow stages (backlog identifies the need, tasks applies the
+  checklist, implement executes to the stack) but — their own docs are explicit
+  — a specialist "does not create specs nor approve gates". They add knowledge,
+  never authority.
+
+That last constraint is the good part of the idea and the part worth copying.
+
+## What we already have
+
+| Layer | What it is | How it arrives |
+|---|---|---|
+| **House skills** | 5 harness skills — `tdd`, `frontend-profissional`, `backend-profissional`, `design-system`, `security` | Always installed, from the harness. Process and quality standards, opinionated for our stack. |
+| **Official vendor skills** | Convex, Clerk, Cloudflare/wrangler, Stripe, Sentry, Resend | `npx skills add <source>` per chosen tech/addon, recorded in `skills-lock.json` |
+| **Generated tech docs** | `ai-docs/apis/<tech>.md` (with a Production section) | `/stack`, for technologies with no official skill |
+| **Project skills** | e.g. the Asaas skill shipped in the template | Ships with the template |
+
+So the "specialist" role is filled three times over. Where it overlaps, **ours
+is better**: an official Stripe or Sentry skill written by the vendor beats a
+third party's summary of the same product, and it is versioned by whoever owns
+the API.
+
+What we genuinely lack:
+
+1. **Discovery** — no way for a student to see what packs exist, or to ask "is
+   there something for Playwright?". `/stack` decides for the stack layers and
+   nothing else.
+2. **Update** — installs are recorded in `skills-lock.json` and then frozen. No
+   student ever runs `skills update`.
+3. **Off-stack knowledge** — a pack that is not tied to a stack layer (a11y,
+   performance, observability, testing-in-CI) has no entry point at all.
+4. **Restore** — after a fresh clone, nothing re-installs from the lock file.
+
+## The mechanism already exists — measured, not assumed
+
+The `skills` CLI we already invoke covers every one of those gaps:
+
+| Gap | Command |
+|---|---|
+| Discovery | `npx skills find <query>` · `npx skills find react --owner vercel` |
+| See what's installed | `npx skills list --json` |
+| Update | `npx skills update [name]` |
+| Restore after clone | `npx skills experimental_install` |
+| **Load without installing** | `npx skills use <pkg>@<skill>` — emits the prompt for ONE skill, nothing written to disk |
+
+That last one is precisely the shape the idea described — knowledge that lives
+in GitHub and is *loaded* when needed rather than permanently installed. It is
+already there; we have never told a student it exists.
+
+So: **do not build a specialists subsystem.** Build curation and a door.
+
+## Conflicts to respect (the actual analysis)
+
+Five real ones, in order of how much damage they do if ignored.
+
+**1. Skills run with full agent permissions.** The CLI itself prints "Review
+skills before use; they run with full agent permissions" after every install.
+Our students are beginners on a paid course; pointing them at open community
+search is a supply-chain surface with their credentials and their repo behind
+it. **Rule: we ship a curated allowlist. `skills find` is shown as an advanced
+escape hatch, with the warning repeated in our own words, never as the default
+path.**
+
+**2. Context bloat.** Every installed skill's `description` is loaded so the
+agent can decide whether to open it. Fifteen specialists is fifteen
+descriptions competing with our own routing table on every turn — and our
+harness already spends that budget on 5 house skills plus the workflow routers.
+**Rule: recommend, never bulk-install; cap what we suggest per project; prefer
+`skills use` for one-off questions over a permanent install.**
+
+**3. Authority collision with the house skills.** `backend-profissional` and
+`security` are opinionated for Convex/Clerk. A Postgres or Laravel pack will
+contradict them, and an agent has no way to know which wins. AGENTS.md already
+carries the seed of the rule ("the professional skills assume the recommended
+stack; on other stacks the reference is `ai-docs/apis/<tech>.md`"). **Rule to
+make explicit: house skills win on process, quality and security posture;
+external packs win on the API details of their own technology. A pack never
+approves a gate, never changes the task flow, never overrides the design-system
+registry or the spec/coverage gates.** (Same boundary Specsfy draws, and for
+the same reason.)
+
+**4. Writes during an FDA are reverted.** Installing a skill writes
+`.agents/skills/`, `.claude/skills/`, `.pi/skills/` and `skills-lock.json`. The
+FDA permission gate attributes any external change to the running phase and
+rolls it back. **Rule: skill installation is interactive-only — never inside a
+`/task`, `/goal` or any FDA run.** Verified safe on the other side:
+`--update-runtime` only touches `.pi/skills/fia/`, so a third-party pack in
+`.pi/skills/<other>` is never clobbered.
+
+**5. Name collisions with the harness.** Our house skills are the single source
+([[harness-fonte-unica]]); a pack publishing a skill called `security` or
+`design-system` would land beside ours with the same name in different
+directories. **Rule: before installing, check the name against the house set
+and refuse with an explanation rather than shadowing.**
+
+## The plan
+
+Four pieces, small, in order. None of them is a new subsystem.
+
+**1. A curated catalog** (`src/config.js`, data only — same shape as
+`OPTIONAL_SKILLS`): recommended packs grouped by domain, each with source,
+skill names, one line on when it helps, and which stack it assumes. Seeded from
+what we can vouch for: the official vendor packs we already install, plus
+`vercel-labs/agent-skills` for the deploy/perf side. Growing it is a data edit,
+not code.
+
+**2. `/skills` — the door** (harness + Pi). Read-only by default: shows what is
+installed (`skills list`), what the catalog recommends **for this project's
+stack manifest** — we already know the stack from `ai-docs/stack.md`, so we do
+not need Specsfy's scanner — and what is out of date. Installing is an explicit
+confirmation per pack, with conflicts 1/3/5 checked first. Never runs inside an
+FDA (conflict 4).
+
+**3. Precedence written down**: one AGENTS.md convention encoding the rule from
+conflict 3, plus a line in each house skill saying it outranks external packs on
+its own subject.
+
+**4. Restore + update in the lifecycle**: `npx skills experimental_install` in
+the post-clone instructions, and a `skills update` suggestion in `/status` when
+the lock file is older than N days. Cheap, and it is the gap Specsfy actually
+closed that we did not.
+
+## What NOT to do
+
+- Do not fork or re-host other people's skills into our templates — the
+  `skills-lock.json` hash is the integrity story; copying breaks it and makes us
+  responsible for content we do not maintain.
+- Do not auto-install on detection. The choice is the student's, and the
+  permission surface (conflict 1) is the reason.
+- Do not give packs any authority in the workflow: no gate approval, no
+  registry override, no task-flow changes.
+- Do not write our own competing knowledge docs for a technology that already
+  publishes an official skill — `ai-docs/apis/<tech>.md` exists exactly for the
+  technologies that do not.