pruff-skills 0.2.0 → 0.4.0

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { __toESM } from "./_chunks/rolldown-runtime.mjs";
 import { pD, require_picocolors } from "./_chunks/libs/@clack/core.mjs";
-import { Ie, M, Me, Se, Y, be, fe, ve, xe, ye } from "./_chunks/libs/@clack/prompts.mjs";
+import { Ie, M, Me, Se, Y, be, fe, he, ve, xe, ye } from "./_chunks/libs/@clack/prompts.mjs";
 import { esm_default } from "./_chunks/libs/simple-git.mjs";
 import { xdgConfig } from "./_chunks/libs/xdg-basedir.mjs";
 import { require_dist } from "./_chunks/libs/@vercel/detect-agent.mjs";
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs";
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { stripVTControlCharacters } from "node:util";
@@ -16,7 +16,7 @@ import { promisify } from "util";
 import { execFile, execSync, spawn, spawnSync } from "child_process";
 import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpath, rm, stat, symlink, writeFile } from "fs/promises";
 import { parse } from "yaml";
-import { createHash } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import { createHash as createHash$1 } from "node:crypto";
 import { gunzipSync, inflateRawSync } from "node:zlib";
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
@@ -555,7 +555,7 @@ function buildGitHubAuthError(url, repo, message) {
 	if (repo) return `Authentication failed for ${url}.\n  - For private repos, ensure you have access\n  - Retry with SSH: npx pruff-skills add ${repo.sshUrl}\n  - Check access with: gh auth status -h github.com or ssh -T git@github.com`;
 	return `Authentication failed for ${url}.\n  - For private repos, ensure you have access\n  - For SSH: Check your keys with 'ssh -T git@github.com'\n  - For HTTPS: Run 'gh auth login' or configure git credentials`;
 }
-async function cloneRepo(url, ref) {
+async function cloneRepo$1(url, ref) {
 	const tempDir = await mkdtemp(join(tmpdir(), "skills-"));
 	const cloneOptions = ref ? [
 		"--depth",
@@ -3467,7 +3467,7 @@ async function runAdd(args, options = {}) {
 				spinner.stop(`Found ${import_picocolors.default.green(skills.length)} skill${skills.length > 1 ? "s" : ""}`);
 			} else {
 				spinner.start("Cloning repository...");
-				tempDir = await cloneRepo(parsed.url, parsed.ref);
+				tempDir = await cloneRepo$1(parsed.url, parsed.ref);
 				spinner.stop("Repository cloned");
 				spinner.start("Discovering skills...");
 				skills = await discoverSkills(tempDir, parsed.subpath, {
@@ -3477,7 +3477,7 @@ async function runAdd(args, options = {}) {
 			}
 		} else {
 			spinner.start("Cloning repository...");
-			tempDir = await cloneRepo(parsed.url, parsed.ref);
+			tempDir = await cloneRepo$1(parsed.url, parsed.ref);
 			spinner.stop("Repository cloned");
 			spinner.start("Discovering skills...");
 			skills = await discoverSkills(tempDir, parsed.subpath, {
@@ -4020,7 +4020,7 @@ async function fetchAgentFile(source, name) {
 		return null;
 	}
 	try {
-		const file = join(await cloneRepo(source), rel);
+		const file = join(await cloneRepo$1(source), rel);
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	} catch {
 		return null;
@@ -4134,7 +4134,7 @@ async function fetchFromCatalog(source, rel) {
 		return null;
 	}
 	try {
-		const file = join(await cloneRepo(source), rel);
+		const file = join(await cloneRepo$1(source), rel);
 		return existsSync(file) ? readFile(file, "utf8") : null;
 	} catch {
 		return null;
@@ -5466,7 +5466,7 @@ async function updateGlobalSkills(options = {}) {
 				}
 				continue;
 			}
-			tempDir = await cloneRepo(sourceUrl, firstEntry.ref);
+			tempDir = await cloneRepo$1(sourceUrl, firstEntry.ref);
 			const discoveredPaths = (await discoverSkills(tempDir)).map((skill) => {
 				return join(relative(tempDir, skill.path), "SKILL.md").split(sep).join("/");
 			});
@@ -5622,7 +5622,7 @@ async function updateProjectSkills(options = {}) {
 		let tempDir = null;
 		let deletedSkills = [];
 		try {
-			tempDir = await cloneRepo(sourceUrl, ref);
+			tempDir = await cloneRepo$1(sourceUrl, ref);
 			const discoveredPaths = (await discoverSkills(tempDir)).map((s) => {
 				return join(relative(tempDir, s.path), "SKILL.md").split(sep).join("/");
 			});
@@ -5841,14 +5841,14 @@ async function runUse(sourceArgs, options = {}, parseErrors = []) {
 				});
 				if (blobResult) skills = blobResult.skills;
 				else {
-					cloneTempDir = await cloneRepo(parsed.url, parsed.ref);
+					cloneTempDir = await cloneRepo$1(parsed.url, parsed.ref);
 					skills = await discoverSkills(cloneTempDir, parsed.subpath, {
 						includeInternal,
 						fullDepth: options.fullDepth
 					});
 				}
 			} else {
-				cloneTempDir = await cloneRepo(parsed.url, parsed.ref);
+				cloneTempDir = await cloneRepo$1(parsed.url, parsed.ref);
 				skills = await discoverSkills(cloneTempDir, parsed.subpath, {
 					includeInternal,
 					fullDepth: options.fullDepth
@@ -6071,6 +6071,1099 @@ function fail(message) {
 	process.exit(1);
 }
 var UseCommandError = class extends Error {};
+const RESET = "\x1B[0m";
+const DIM = "\x1B[38;5;102m";
+const BLUES = [
+	"\x1B[38;2;110;139;255m",
+	"\x1B[38;2;91;118;249m",
+	"\x1B[38;2;72;97;242m",
+	"\x1B[38;2;53;77;236m",
+	"\x1B[38;2;34;56;229m",
+	"\x1B[38;2;15;35;223m"
+];
+const SWEEP = "\x1B[38;2;214;226;255m";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function canAnimate() {
+	return !!process.stdout.isTTY && !process.env.CI && !process.env.NO_COLOR && !process.env.PRUFF_SKILLS_NO_ANIM;
+}
+function columnColor(col, width) {
+	return BLUES[Math.min(BLUES.length - 1, Math.floor(col / Math.max(1, width - 1) * BLUES.length))];
+}
+function renderSweepLine(chars, indent, pos, band) {
+	let out = indent;
+	let mode = "";
+	for (let c = 0; c < chars.length; c++) {
+		const color = c >= pos && c < pos + band ? SWEEP : columnColor(c, chars.length);
+		if (color !== mode) {
+			out += color;
+			mode = color;
+		}
+		out += chars[c];
+	}
+	return out + RESET;
+}
+async function sweepLine(text, { slow = false, indent = "  " } = {}) {
+	const chars = Array.from(text);
+	const width = chars.length;
+	const band = 5;
+	const step = slow ? 2 : 3;
+	const ms = slow ? 42 : 24;
+	if (!canAnimate()) {
+		console.log(renderSweepLine(chars, indent, -1, 0));
+		return;
+	}
+	process.stdout.write("\x1B[?25l");
+	try {
+		let first = true;
+		for (let pos = -5; pos <= width; pos += step) {
+			if (!first) process.stdout.write("\x1B[1A");
+			process.stdout.write("\r" + renderSweepLine(chars, indent, pos, band) + "\n");
+			first = false;
+			await sleep(ms);
+		}
+		process.stdout.write("\x1B[1A\r" + renderSweepLine(chars, indent, -1, 0) + "\n");
+	} finally {
+		process.stdout.write("\x1B[?25h");
+	}
+}
+const WORKSPACE_CLAUDE_TEMPLATE = `# Pruff — Working Directory
+
+This folder is the working directory for Pruff's frontend and backend. The two main git repos are:
+
+- **\`Pruff-Client/\`** — React frontend
+- **\`Pruff-server/\`** — Node.js/Express backend
+
+Other directories (\`sls-*/\`, \`slsl-*/\`, \`AWS-Tools/\`, etc.) are serverless microservices and tooling —
+clone them into this workspace as you need them, and don't modify them unless explicitly asked.
+
+Each repo has its own \`CLAUDE.md\` and \`.claude/rules/\` with repo-specific patterns. This file covers
+workspace-level context only.
+
+---
+
+## Workspace Layout
+
+### Main applications (modify freely when asked)
+
+| Folder | What it is |
+|---|---|
+| \`Pruff-Client/\` | React 18 + Vite + MUI frontend. React Query + Redux Toolkit. |
+| \`Pruff-server/\` | Node.js 22 / Express / Prisma backend. Multi-tenant (DB-per-tenant). |
+
+### Serverless microservices (\`sls-*/\`, \`slsl-*/\` — clone as needed, don't modify unless asked)
+
+All live in the same AWS account, share the \`lambda-sqs\` IAM role, and most use a shared
+\`prisma-client-layer\` Lambda layer so they can reach tenant databases. They talk to \`Pruff-server\`
+over HTTPS with an \`x-api-key\`.
+
+| Folder | Role |
+|---|---|
+| \`sls-SII-Services/\` | **SII (Chilean tax authority) scrapers & orchestrators.** Invoice generation, certificate validation, cession execution, F29/IVA extraction, credit-note references, cron orchestrators. Talks heavily to \`slsl-Data-Injection-Syncronizer\`. |
+| \`sls-TGR-Extraction/\` | **TGR (treasury) scrapers.** Extracts tax collections, debts, payment agreements. Pushes results into the data-injection pipeline. |
+| \`sls-TGR-Services/\` | **TGR-adjacent business logic.** Smaller sibling to \`sls-TGR-Extraction\`. |
+| \`sls-Public-Market/\` | **Mercado Público (Chilean public tenders) pipeline.** Awarded-tender fetcher, tender analyzer, lead generator. |
+| \`slsl-Data-Injection-Syncronizer/\` | **Fan-out hub between scrapers and Pruff-server.** Receives scraped data, resolves interested tenants, forwards per-tenant writes. Also hosts the \`ReflexOrchestrator\` change-detection pipeline. |
+| \`sls-Decision-Engine/\` | **Risk / Motor de Riesgo executor.** Three-stage SQS pipeline: \`prepare\` → \`delayedPrepare\` → \`executor\`. |
+| \`sls-Notification-Service/\` | **Outbound notifications** (email, in-app, collections). |
+| \`sls-Pruff-Webhooks/\` | **Outbound webhook delivery** to client integrations. |
+| \`sls-Pruff-Workers/\` | **Async background jobs for Pruff-server** (PDF rendering, tenant document/summary sync crons). |
+
+### Tooling & utilities
+
+| Folder | What it is |
+|---|---|
+| \`AWS-Tools/\` | Standalone Node/TypeScript scripts for AWS ops — not deployed; run locally with AWS creds. |
+
+### Cross-service data flow (mental model)
+
+\`\`\`
+sls-SII-Services ─┐
+sls-TGR-Extraction ├─► slsl-Data-Injection-Syncronizer ─► Pruff-server (per-tenant DBs)
+sls-Public-Market ─┘                          │
+                                              ▼
+                                    sls-Decision-Engine ──► Pruff-server
+                                              │
+                                              ▼
+                    sls-Notification-Service / sls-Pruff-Webhooks (outbound)
+\`\`\`
+
+\`sls-Pruff-Workers\` sits beside \`Pruff-server\` handling async/scheduled jobs that would block the API.
+
+---
+
+## What is Pruff
+
+Pruff is a **multi-tenant B2B fintech platform** for Latin American financing institutions (factorings,
+credit companies, investment funds). It centralizes the full lifecycle of financial operations through
+three integrated modules:
+
+\`\`\`
+DataHub (data ingestion) → Motor de Riesgo (risk/decision engine) → Core (operations)
+         ↑_________________________retroalimentación_________________________↓
+\`\`\`
+
+- **DataHub** — Consolidates client, debtor, and market data from external sources (SII, TGR, Bureau, banks).
+- **Motor de Riesgo** — Applies configurable scoring rules, compliance checks, exposure limits, and alerts.
+- **Core (FinancingHub)** — Executes approved operations: cesiones, disbursements, payment schedules,
+  collections, reconciliation, and double-entry accounting.
+
+### Financial Products
+
+| Product | What It Does |
+|---------|-------------|
+| **Factoring** | Client sells unpaid invoices for immediate liquidity. Core product. |
+| **Credits** | Structured financing with cuotas (installments) |
+| **Confirming** | Accelerated supplier payments (accounts payable) |
+| **Credit Lines** | Pre-approved revolving credit with partial draws |
+| **Funds** | Real-time visibility for investment funds over factoring portfolios |
+
+---
+
+## Multi-Tenancy Architecture
+
+**Critical concept:** Pruff is **database-per-tenant**. Every tenant has its own MySQL database.
+
+1. User authenticates via JWT → \`secretId\` extracted from company
+2. \`PrismaClientManager.getTenantClient(secretId)\` returns a tenant-scoped Prisma client
+3. **Every service that needs DB access receives \`prisma\` (tenant-scoped) as its first parameter**
+4. Use \`prismaGlobal\` only when the use case requires cross-tenant or shared data
+
+---
+
+## Pruff-server (Backend)
+
+**Stack:** Node.js 22, Express 4, TypeScript 5, Prisma 5, MySQL 8, AWS (S3, SQS, SNS, Lambda, DynamoDB)
+**Package manager:** \`bun\` — \`bun.lock\` is the canonical lockfile. Use \`bun install\` / \`bun add <pkg>\`,
+never \`npm install\` or \`yarn\` (Docker/CI install with \`bun install --frozen-lockfile\`, so an
+npm/yarn-only change goes stale). \`npm run <script>\` still works for running scripts.
+
+### Commands
+
+\`\`\`bash
+cd Pruff-server
+
+npm run local              # Run locally (uses local.env)
+npm run dev                # Run against dev environment (uses dev.env)
+npm run build              # Compile TypeScript (tsc + tsc-alias)
+npm run test               # Jest tests (uses test.env, sequential with 1 worker)
+npm run test:file <name>   # Run single jest test by file name (not path)
+npm run lint               # ESLint
+
+# Database (Prisma)
+npm run db-update-local    # prisma migrate dev (create + apply migration, local)
+npm run db-migrate-local   # prisma migrate deploy (apply existing migrations, local)
+npm run db-migrate-tenants-local  # Migrate all tenant databases
+npm run db-seed-tenants-local     # Seed all active tenant databases
+\`\`\`
+
+### Source Structure
+
+\`\`\`
+src/
+  controllers/     # Thin — validate input, call service, return response
+  services/        # All business logic, organized by domain
+  routes/
+    api.ts         # Main router
+    internal/      # Staff endpoints (JWT auth)
+    clients/       # Customer-facing endpoints (API key)
+    external/      # Scraper/lambda endpoints (API key)
+    public/        # No auth
+  modules/         # Infrastructure wrappers (S3, SQS, SII, GoFirmex, etc.)
+  middlewares/     # Auth, tenant resolution, rate limiting, error handling
+  jobs/            # Cron jobs (iterate over all tenants)
+  types/           # Shared TypeScript types
+  lib/             # Utility functions
+\`\`\`
+
+### API Tiers
+
+| Tier | Base Route | Auth | Middleware |
+|------|-----------|------|-----------|
+| Internal | \`/api/internal\` | JWT | \`authenticateJWT\` + \`attachUserPermissions\` |
+| External | \`/api/external\` | API Key | \`authenticateWithApiKey\` |
+| Clients | \`/api/clients\` | Client API Key | \`authenticateClientsWithApiKey\` |
+| Public | \`/api/public\` | None | — |
+
+### Service Pattern — Result\\<T\\>
+
+All services return \`Result<T>\`. Never throw from services.
+
+\`\`\`typescript
+type Result<T> = { ok: true; value: T } | { ok: false; error: AppError };
+
+return { ok: true, value };
+return { ok: false, error: { status: APP_CODES.NOT_FOUND, message: 'NOT_FOUND', service: 'MyService', displayMessage: 'No encontrado' } };
+\`\`\`
+
+### Controller Pattern — handleApiOutput / handleApiError
+
+\`\`\`typescript
+async someAction(req: UserRequest, res: Response) {
+  try {
+    const result = await SomeService.execute(req.prisma, req.body);
+    return handleApiOutput('SomeService', req, res, result);
+  } catch (error) {
+    handleApiError('SomeService', req, res, error);
+  }
+}
+\`\`\`
+
+### Naming Conventions
+
+- **Services:** \`PascalCase\` + \`Service\` suffix → \`CreateFactoringRequestService.ts\`
+- **DTOs/interfaces:** \`PascalCase\` + \`Dto\` suffix → \`CreateFactoringRequestDto\`
+- **Controllers:** \`camelCase\` + \`Controller\` suffix → \`invoicesController.ts\`
+- **Services are singletons:** \`export default new MyService();\`
+- **\`prisma\` is always the first parameter** when the service needs DB access
+
+### Accounting Rules
+
+- Every financial state change generates double-entry accounting entries automatically
+- \`SUM(debit) === SUM(credit)\` always — imbalanced entries are rejected
+- Entries use \`sourceKey\` to prevent duplicates and \`checkSum\` (SHA256) for audit integrity
+- Periods must be OPEN to accept entries
+
+### Environment Files
+
+- \`local.env\` — local MySQL, mocked AWS services
+- \`dev.env\` — connects to \`api.dev.pruff.com\` dependencies
+- \`test.env\` — for Jest tests
+
+---
+
+## Pruff-Client (Frontend)
+
+**Stack:** React 18, TypeScript, Vite, MUI v5, Redux Toolkit, TanStack React Query v5, Axios
+**Package manager:** \`yarn\` — \`yarn.lock\` is the canonical lockfile.
+
+### Commands
+
+\`\`\`bash
+cd Pruff-Client
+
+yarn start-local  # Dev server → backend at http://localhost:80
+yarn start-dev    # Dev server → backend at https://api.dev.pruff.com
+yarn start-prod   # Dev server → backend at https://api.pruff.com
+yarn build        # Production build
+yarn lint         # ESLint
+yarn test         # Jest + React Testing Library
+\`\`\`
+
+### Source Structure
+
+\`\`\`
+src/
+  pages/           # Feature modules
+  lib/
+    api/           # Axios API integration modules
+    designSystem/  # Shared MUI-based components
+    mobileDesignSystem/  # Mobile-specific components
+    common/        # Domain-specific shared components
+    hooks/         # Custom React hooks
+    functions/     # Business logic functions (utils.ts, permission checks)
+    types/         # TypeScript type definitions
+  services/        # Redux store + API configuration (requestHandler)
+  layouts/         # Layout components
+  assets/          # Images, fonts, icons
+\`\`\`
+
+### State Management
+
+- **React Query v5** — All server data (fetching, caching, mutations)
+- **Redux Toolkit** — Auth state, global alerts, client branding config only
+- **Redux Persist** — Persists auth across sessions
+
+### API Client
+
+All HTTP goes through \`requestHandler\` (Axios wrapper in \`src/lib/api.ts\`). Import from the relevant
+module in \`src/lib/api/<domain>/\`.
+
+### Permission System
+
+RBAC via \`user.roles[].permissions[].name\`. Key utilities in \`src/lib/functions/utils.ts\`:
+- \`validatePermissions(user, permission)\` — single check
+- \`hasAnyPermissions(user, permissions[])\` — OR logic
+- \`validateCompanyTypes(user, type)\` — product/feature gating
+
+---
+
+## Code Style (Both Repos)
+
+- **Prettier:** \`printWidth: 80\`, \`singleQuote: true\`, \`trailingComma: 'all'\`, \`semi: true\`
+- **ESLint:** TypeScript strict, \`simple-import-sort\` enforced, \`no-console\` (warn/error)
+- **Import order** (enforced): external packages → absolute imports → relative imports, alphabetically sorted
+
+---
+
+## Chile-Specific Concepts
+
+| Term | Meaning |
+|------|---------|
+| **RUT** | Chilean tax ID (e.g., \`12.345.678-9\`) |
+| **DTE** | Electronic tax document (33=factura, 34=exenta, 61=nota de crédito) |
+| **SII** | Servicio de Impuestos Internos — tax authority, source of invoices, F22, F29 |
+| **F22/F29** | Annual/monthly tax returns |
+| **TGR** | Tesorería General de la República — state treasury, tax debts |
+| **UF** | Unidad de Fomento — daily inflation-adjusted unit (CMF publishes value) |
+| **CMF** | Comisión para el Mercado Financiero — financial markets regulator |
+| **SGR** | Sociedad de Garantía Recíproca — mutual guarantee society for SMEs |
+| **Cedente** | Client selling receivables (factoring seller) |
+| **Deudor** | Invoice payer / debtor |
+| **Cesión** | Transfer of collection rights on an invoice |
+| **Giro/Desembolso** | Cash disbursement |
+| **Cobranza** | Collection management |
+| **Mora** | Payment delinquency |
+| **Conciliación** | Reconciling bank movements with operations |
+| **Provisión** | Recognized expected loss |
+| **Castigo** | Write-off of uncollectible amounts |
+| **Bureau** | Credit bureau with RUT-level payment history |
+| **Spread** | Profit margin between funding cost and lending rate |
+
+---
+
+## Pruff Knowledge
+
+Durable, versioned knowledge (standards, architecture, how things work) lives in the \`Pruff Knowledge/\`
+repo cloned alongside this workspace by onboarding (\`Pruff-Tech/pruff-knowledge\`). Read it for context
+beyond this CLAUDE.md. Roadmap, releases, meeting notes, and tickets stay in Notion/Linear, not here.
+
+**Start at a MOC** (\`_moc/\` — Maps of Content): the curated entry index per area. From there, follow the
+\`[[wikilinks]]\` to the concrete notes, or jump straight into the folder you need.
+
+| Folder | What it covers |
+|---|---|
+| \`architecture/\` | Patterns and standards already implemented (SSE, error handling, multi-tenancy, database gateway…) |
+| \`infrastructure/\` | AWS services, ECS, Lambdas, and how they connect |
+| \`design-system/\` | UI components, tokens, and conventions |
+| \`operations/\` | Operational flow, modules, and how they fit together |
+| \`integrations/\` | Existing integrations and how they're used |
+| \`repos/\` | One doc per repository — what it does and how it connects |
+| \`guides/\` | How-tos (internal and external) |
+| \`glossary/\` | Domain terms — folio, cesión, RUT, mora, etc. |
+| \`postmortems/\` | Incidents — root cause and durable learnings (operational detail stays in Linear) |
+
+Notes are frontmatter/filenames in English (\`kebab-case\`), body in Spanish. See the repo's own
+\`AGENTS.md\` for the agent-facing contract.
+
+---
+
+## Workflow
+
+- **Always use \`/commit\`** — invoke the \`commit\` skill for all git commits. Never run \`git commit\` manually.
+- **Always use \`/create-pr\`** — invoke the \`create-pr\` skill for all pull requests. Never run \`gh pr create\` manually.
+- **Commits are authored to the human running Claude Code** — never set \`--author\` to Claude or any co-author.
+- **In \`sls-*/\` and \`slsl-*/\` repos, branch from \`origin/main\`** — verify this against each repo's actual
+  \`dev\` vs \`main\` state before assuming; it has drifted before. Exception: \`Pruff-server\` and
+  \`Pruff-Client\` branch from \`dev\` (their deploy flow promotes \`dev → main\`).
+- **Branch names embed the Linear issue code; PRs map 1:1 with Linear issues** — name branches so they
+  contain the issue code (e.g. \`pru-1355-...\`) for Linear's git automation. When splitting work, plan
+  the PR grouping first, create one Linear issue per PR (1:1), and stack dependent PRs
+  (\`dev ← group-1 ← group-2 ← …\`) instead of one mega-PR. If more than one linear issue is in one PR, name of the branch
+  should be the linear issue code of each issue.
+- **Be straightforward and concise** — lead with the core message, then the minimum supporting detail.
+  Cut preamble and narration. When asked for a table or diagram, render real markdown, never a bullet
+  list dressed up as one.
+- **Propose options and confirm before acting** — for any non-trivial design, format, or refactor choice,
+  present alternatives with their tradeoffs in chat and wait for a pick before writing code or running
+  commands. Gather context → confirm the plan → build.
+- **Explain the rationale, not just the diff** — when a change touches a non-obvious file (a new
+  middleware, a \`Dockerfile\` edit, a cap/limit) or you're proposing an approach, explain in chat *why*
+  it's needed and surface the cons/tradeoffs before adopting it.
+- **Numbers are verified facts, not estimates** — before stating a count, rate, latency, or cost, confirm
+  it from the source (logs, metrics, a query) and cite the source + window inline. If you can't verify
+  it, label it an estimate or omit it. Package-manager conventions, canonical branches, and other
+  "what does this repo actually do" questions belong in this bucket too — check \`origin/main\`, not a
+  possibly-stale local checkout or this file.
+- **Register out-of-scope findings in \`.claude/smell-findings/\`** — whenever you or a subagent spots a
+  code smell, an unrelated bug, or an improvement opportunity outside the current task's scope, record
+  it as a markdown file there instead of fixing it inline or dropping it.
+- Delegate context gathering to codebase-navigator agent if present, and implementation to implementer agent if present.
+
+---
+
+## Code Review
+
+When reviewing PRs, always scope scans to the PR's changed files (never the whole repo). For
+react-doctor/diff tools, use PR-scoped diffs and manually verify risky logic.
+
+---
+
+## Critical Rules
+
+1. **Every backend service takes \`prisma\` as its first parameter** — tenant isolation depends on it.
+   Never import or use a global Prisma instance inside a service.
+2. **Services return \`Result<T>\`, never throw** — controllers handle the Result pattern.
+3. **Accounting entries must balance** — debit total must equal credit total.
+4. **Financial operations are fully auditable** — CloudWatch logs and approval chains must not be skipped.
+5. **SII/RUT data is sensitive** — Credentials are encrypted via \`encryptionModule\`.
+6. **Never modify \`prisma/schema.prisma\` without confirmation** — schema changes affect every tenant database.
+7. **Never run DB migrations automatically** — propose the change and let the developer run it.
+8. **Never push directly to \`dev\` or \`main\`** — all changes must go through a PR. No exceptions.
+`;
+const CONTROL_PLANE_PRESEED_SCRIPT = `import { PrismaClient } from '@prisma/client';
+
+import seedRoles from './prisma/seeds/roles';
+import seedPermissions from './prisma/seeds/permissions';
+import seedRolesWithPermissions from './prisma/seeds/permissionsToRole';
+import seedCompanyTypes from './prisma/seeds/companyTypes';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  if ((await prisma.role.count()) === 0) await seedRoles();
+  if ((await prisma.permission.count()) === 0) await seedPermissions();
+  await seedRolesWithPermissions();
+  await seedCompanyTypes();
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  })
+  .finally(() => process.exit(0));
+`;
+const TENANT_USER_BACKFILL_SCRIPT = `import PrismaClientManager from './src/modules/prismaClient';
+import EncryptionModule from './src/modules/encryptionModule';
+
+async function main() {
+  const email = process.argv[2];
+  const password = process.argv[3];
+  const clientId = process.env.CLIENT_ID;
+  if (!clientId) throw new Error('CLIENT_ID is required');
+
+  const tenantPrisma = PrismaClientManager.getGlobalClient();
+  const existing = await tenantPrisma.user.findFirst({ where: { email } });
+  if (existing) {
+    console.log('tenant user already present: ' + email);
+    return;
+  }
+
+  const globalPrisma = PrismaClientManager.getGlobalClientFromTenantBase(clientId);
+  const globalUser = await globalPrisma.user.findFirstOrThrow({ where: { email } });
+  const encryptedPassword = await EncryptionModule.encrypt(password);
+
+  await tenantPrisma.user.create({
+    data: {
+      id: globalUser.id,
+      email,
+      name: email.split('@')[0],
+      password: encryptedPassword,
+      active: true,
+      companyId: globalUser.companyId,
+      roles: { connect: [{ id: 4 }] },
+    },
+  });
+  console.log('tenant user created: ' + email + ' (id=' + globalUser.id + ')');
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  })
+  .finally(() => process.exit(0));
+`;
+function renderLocalEnv(v) {
+	const q = (value) => `"${value.replace(/"/g, "\\\"")}"`;
+	return `DATABASE_URL=${q(`mysql://root@localhost:3306/pruff-local?connection_limit=5`)}
+NODE_ENV="local"
+IS_LOCAL_ENV="true"
+CLIENT_ID=${q(v.clientId)}
+CLIENT_RUT=${q(v.clientRut)}
+CLIENT_NAME=${q(v.clientName)}
+ADMIN_PASSWORD=${q(v.adminPassword)}
+JWT_SECRET=${q(v.jwtSecret)}
+API_KEY=${q(v.apiKey)}
+SECRET_SII_KEY=${q(v.siiKey)}
+SECRET_USER_REGISTRATION=${q(v.registrationSecret)}
+SECRET_PFX_CERTIFICATE=${q(v.pfxSecret)}
+USER_FORM_KEY=${q(v.userFormKey)}
+POSTHOG_ENABLED="false"
+
+# --- Third-party integrations -------------------------------------------------
+# Left blank on purpose. Fill with real sandbox credentials from your team /
+# 1Password when you need the feature. The app boots and serves local data
+# without them.
+SII_SERVICE_URL=""
+SII_SERVICE_APIKEY=""
+TGR_SERVICE_URL=""
+TGR_SERVICE_APKEY=""
+AWS_ACCESS_KEY_ID=""
+AWS_SECRET_ACCESS_KEY=""
+POSTHOG_API_KEY=""
+POSTHOG_HOST=""
+BURO_USERNAME=""
+BURO_PASSWORD=""
+BURO_API_URL=""
+CMF_API_KEY=""
+MCP_OAUTH_PUBLIC_KEY=""
+MCP_ALLOWED_TENANTS=""
+`;
+}
+const CLAUDE_CODE_PKG = "@anthropic-ai/claude-code";
+const KNOWLEDGE_REPO = "https://github.com/Pruff-Tech/pruff-knowledge";
+const KNOWLEDGE_DIR = "Pruff Knowledge";
+const DEFAULT_WORKSPACE = join(homedir(), "pruff");
+const MAIN_REPOS = [{
+	name: "Pruff-server",
+	url: "https://github.com/Pruff-Tech/Pruff-server",
+	installCmd: "bun",
+	installArgs: ["install"]
+}, {
+	name: "Pruff-Client",
+	url: "https://github.com/Pruff-Tech/Pruff-Client",
+	installCmd: "yarn",
+	installArgs: ["install"]
+}];
+const CORE_SKILLS = [
+	"commit",
+	"create-pr",
+	"linear",
+	"start-issue",
+	"handoff",
+	"pruff-logs",
+	"pruff-pr-review",
+	"review-pr-comments",
+	"react-doctor"
+];
+const CORE_AGENTS = [
+	"codebase-navigator",
+	"db-query-reviewer",
+	"pruff-logs-investigator"
+];
+async function runOnboarding(args) {
+	if (process.platform !== "darwin") {
+		M.error(`${import_picocolors.default.bold("onboarding")} currently supports macOS only (detected ${import_picocolors.default.cyan(process.platform)}).`);
+		return;
+	}
+	Ie(import_picocolors.default.bold("Pruff onboarding"));
+	installClaudeCode();
+	ensureObsidian();
+	ensureBun();
+	const workspace = await resolveWorkspace(args);
+	mkdirSync(workspace, { recursive: true });
+	M.success(`Workspace ${import_picocolors.default.cyan(workspace)}`);
+	cloneKnowledge(workspace);
+	for (const repo of MAIN_REPOS) cloneRepo(repo, workspace);
+	for (const repo of MAIN_REPOS) installDeps(repo, workspace);
+	writeWorkspaceClaudeMd(workspace);
+	await installCatalog(workspace);
+	if (await shouldSetupDatabase(args)) await setupLocalEnvironment(join(workspace, "Pruff-server"));
+	await showGuidance(workspace);
+	Se(`${import_picocolors.default.green("Done.")} Welcome to Pruff — happy building.`);
+}
+function has(cmd) {
+	return spawnSync("command", ["-v", cmd], {
+		shell: true,
+		stdio: "ignore"
+	}).status === 0;
+}
+function run(cmd, args, cwd, env) {
+	return spawnSync(cmd, args, {
+		stdio: "inherit",
+		cwd,
+		env: env ? {
+			...process.env,
+			...env
+		} : void 0
+	}).status === 0;
+}
+function capture(cmd, args, cwd, env) {
+	const r = spawnSync(cmd, args, {
+		encoding: "utf-8",
+		cwd,
+		env: env ? {
+			...process.env,
+			...env
+		} : void 0
+	});
+	return {
+		ok: r.status === 0,
+		out: (r.stdout ?? "").trim()
+	};
+}
+function expandHome(input) {
+	return input.startsWith("~") ? join(homedir(), input.slice(1)) : input;
+}
+function installClaudeCode() {
+	if (has("claude")) {
+		M.success("Claude Code already installed");
+		return;
+	}
+	const s = Y();
+	s.start("Installing Claude Code…");
+	if (run("npm", [
+		"install",
+		"-g",
+		CLAUDE_CODE_PKG
+	])) s.stop("Claude Code installed");
+	else {
+		s.stop(import_picocolors.default.yellow("Claude Code install failed"));
+		M.warn(`Install it manually: ${import_picocolors.default.cyan(`npm i -g ${CLAUDE_CODE_PKG}`)}`);
+	}
+}
+function ensureObsidian() {
+	if (existsSync("/Applications/Obsidian.app")) {
+		M.success("Obsidian already installed");
+		return;
+	}
+	if (!has("brew")) {
+		M.warn(`Obsidian not found and Homebrew is unavailable.\n  Install it from ${import_picocolors.default.cyan("https://obsidian.md")} and re-run.`);
+		return;
+	}
+	const s = Y();
+	s.start("Installing Obsidian (brew)…");
+	if (run("brew", [
+		"install",
+		"--cask",
+		"obsidian"
+	])) s.stop("Obsidian installed");
+	else {
+		s.stop(import_picocolors.default.yellow("Obsidian install failed"));
+		M.warn(`Install manually: ${import_picocolors.default.cyan("brew install --cask obsidian")}`);
+	}
+}
+function ensureBun() {
+	if (has("bun")) {
+		M.success("Bun already installed");
+		return;
+	}
+	const s = Y();
+	s.start("Installing Bun…");
+	if (run("bash", ["-c", "curl -fsSL https://bun.sh/install | bash"])) s.stop("Bun installed");
+	else {
+		s.stop(import_picocolors.default.yellow("Bun install failed"));
+		M.warn(`Install it manually: ${import_picocolors.default.cyan("curl -fsSL https://bun.sh/install | bash")} (or ${import_picocolors.default.cyan("brew install oven-sh/bun/bun")})`);
+	}
+}
+async function resolveWorkspace(args) {
+	const fromArg = args.find((a) => !a.startsWith("-"));
+	if (fromArg) return expandHome(fromArg);
+	if (!process.stdout.isTTY) return DEFAULT_WORKSPACE;
+	const answer = await he({
+		message: "Where should the Pruff workspace live?",
+		placeholder: DEFAULT_WORKSPACE,
+		defaultValue: DEFAULT_WORKSPACE
+	});
+	if (pD(answer)) {
+		xe("Onboarding cancelled.");
+		process.exit(0);
+	}
+	return expandHome((answer || DEFAULT_WORKSPACE).trim());
+}
+function cloneKnowledge(workspace) {
+	const vaultPath = join(workspace, KNOWLEDGE_DIR);
+	const s = Y();
+	if (existsSync(join(vaultPath, ".git"))) {
+		s.start("Updating Pruff knowledge…");
+		const ok = run("git", [
+			"-C",
+			vaultPath,
+			"pull",
+			"--ff-only"
+		]);
+		s.stop(ok ? "Pruff knowledge up to date" : import_picocolors.default.yellow("git pull failed (keeping local copy)"));
+		registerVault(vaultPath);
+		return;
+	}
+	s.start("Cloning Pruff knowledge…");
+	if (run("git", [
+		"clone",
+		KNOWLEDGE_REPO,
+		vaultPath
+	])) {
+		s.stop(`Cloned knowledge to ${import_picocolors.default.dim(vaultPath)}`);
+		registerVault(vaultPath);
+		return;
+	}
+	s.stop(import_picocolors.default.yellow("Knowledge clone failed"));
+	M.warn(`Could not clone ${import_picocolors.default.cyan(KNOWLEDGE_REPO)}.\n  It's private — authenticate first with ${import_picocolors.default.cyan("gh auth login")} (or an SSH key), then re-run.`);
+}
+function cloneRepo(repo, workspace) {
+	const { name, url } = repo;
+	const target = join(workspace, name);
+	if (existsSync(join(target, ".git"))) {
+		M.success(`${name} already cloned`);
+		return;
+	}
+	const s = Y();
+	s.start(`Cloning ${name}…`);
+	if (run("git", [
+		"clone",
+		url,
+		target
+	], workspace)) s.stop(`Cloned ${import_picocolors.default.cyan(name)}`);
+	else {
+		s.stop(import_picocolors.default.yellow(`${name} clone failed`));
+		M.warn(`Could not clone ${name}. Authenticate with ${import_picocolors.default.cyan("gh auth login")} then run:\n  ${import_picocolors.default.dim(`git clone ${url}`)}  (inside ${workspace})`);
+	}
+}
+function installDeps(repo, workspace) {
+	const { name, installCmd, installArgs } = repo;
+	const target = join(workspace, name);
+	if (!existsSync(join(target, ".git"))) return;
+	if (!has(installCmd)) {
+		M.warn(`${import_picocolors.default.cyan(installCmd)} not found — skipping ${name} dependency install.\n  Run manually once installed: ${import_picocolors.default.dim(`cd ${name} && ${installCmd} ${installArgs.join(" ")}`)}`);
+		return;
+	}
+	const s = Y();
+	s.start(`Installing ${name} dependencies (${installCmd})…`);
+	const ok = run(installCmd, installArgs, target);
+	if (ok && existsSync(join(target, "node_modules"))) s.stop(`${name} dependencies installed`);
+	else {
+		s.stop(import_picocolors.default.yellow(`${name} dependency install failed`));
+		if (ok) M.warn(`${installCmd} exited 0 but ${name}/node_modules is missing — install likely no-opped.`);
+		M.warn(`Run manually: ${import_picocolors.default.dim(`cd ${name} && ${installCmd} ${installArgs.join(" ")}`)}`);
+	}
+}
+function writeWorkspaceClaudeMd(workspace) {
+	const target = join(workspace, "CLAUDE.md");
+	if (existsSync(target)) {
+		M.success("Workspace CLAUDE.md already present — leaving it untouched");
+		return;
+	}
+	writeFileSync(target, WORKSPACE_CLAUDE_TEMPLATE, "utf-8");
+	M.success("Wrote workspace CLAUDE.md");
+}
+async function installCatalog(workspace) {
+	const prevCwd = process.cwd();
+	M.step("Installing Pruff rules, agents and skills into the workspace…");
+	try {
+		process.chdir(workspace);
+		await runRules(["add", "--all"]);
+		await runAgents(["add", ...CORE_AGENTS]);
+		await runAdd([PRUFF_CATALOG], {
+			skill: CORE_SKILLS,
+			agent: ["claude-code"],
+			yes: true
+		});
+	} catch (error) {
+		M.warn(`Catalog install hit an error: ${error instanceof Error ? error.message : String(error)}\n  Re-run once authenticated: ${import_picocolors.default.cyan("npx pruff-skills onboarding")}`);
+	} finally {
+		process.chdir(prevCwd);
+	}
+}
+async function setupLocalEnvironment(serverPath) {
+	if (!existsSync(join(serverPath, ".git"))) {
+		M.warn("Pruff-server not cloned — skipping local database setup.");
+		return;
+	}
+	if (!ensureMysql()) return;
+	ensureDbeaver();
+	generateLocalEnv(serverPath);
+	const env = parseEnvFile(join(serverPath, "local.env"));
+	if (!env.DATABASE_URL || !env.CLIENT_ID) {
+		M.warn("local.env is missing DATABASE_URL / CLIENT_ID — skipping database setup.");
+		return;
+	}
+	setupLocalDatabase(serverPath, env);
+}
+async function shouldSetupDatabase(args) {
+	if (args.includes("--no-db")) return false;
+	if (args.includes("--db")) return true;
+	if (!process.stdout.isTTY) return false;
+	const answer = await ye({
+		message: "Set up the local Pruff-server database now? (installs MySQL + DBeaver, migrates both DBs, seeds a local \"pruff\" tenant)",
+		initialValue: true
+	});
+	if (pD(answer)) return false;
+	return answer === true;
+}
+function ensureMysql() {
+	if (!has("mysql")) {
+		if (!has("brew")) {
+			M.warn(`MySQL not found and Homebrew is unavailable.\n  Install MySQL, then re-run: ${import_picocolors.default.cyan("npx pruff-skills onboarding --db")}`);
+			return false;
+		}
+		const s = Y();
+		s.start("Installing MySQL (brew)…");
+		const ok = run("brew", ["install", "mysql"]);
+		s.stop(ok ? "MySQL installed" : import_picocolors.default.yellow("MySQL install failed"));
+		if (!ok) return false;
+	} else M.success("MySQL already installed");
+	if (mysqlRunning()) {
+		M.success("MySQL already running");
+		return true;
+	}
+	const s = Y();
+	s.start("Starting MySQL…");
+	run("brew", [
+		"services",
+		"start",
+		"mysql"
+	]);
+	for (let i = 0; i < 30 && !mysqlRunning(); i++) spawnSync("sleep", ["1"]);
+	const up = mysqlRunning();
+	s.stop(up ? "MySQL running" : import_picocolors.default.yellow("MySQL did not come up"));
+	if (!up) M.warn(`Start it manually: ${import_picocolors.default.cyan("brew services start mysql")}, then re-run with --db.`);
+	return up;
+}
+function mysqlRunning() {
+	return spawnSync("mysqladmin", [
+		"ping",
+		"-u",
+		"root",
+		"--silent"
+	], { stdio: "ignore" }).status === 0;
+}
+function ensureDbeaver() {
+	if (existsSync("/Applications/DBeaver.app")) {
+		M.success("DBeaver already installed");
+		return;
+	}
+	if (!has("brew")) {
+		M.warn(`DBeaver not found. Install it from ${import_picocolors.default.cyan("https://dbeaver.io")}.`);
+		return;
+	}
+	const s = Y();
+	s.start("Installing DBeaver (brew)…");
+	const ok = run("brew", [
+		"install",
+		"--cask",
+		"dbeaver-community"
+	]);
+	s.stop(ok ? "DBeaver installed" : import_picocolors.default.yellow("DBeaver install failed"));
+}
+function generateLocalEnv(serverPath) {
+	const target = join(serverPath, "local.env");
+	if (existsSync(target)) {
+		M.success("local.env already present — leaving it untouched");
+		return;
+	}
+	const secret = () => randomBytes(16).toString("hex");
+	writeFileSync(target, renderLocalEnv({
+		clientId: "pruff",
+		clientRut: "99.999.999-9",
+		clientName: "Pruff Local",
+		adminPassword: "pruff-local-1234",
+		jwtSecret: secret(),
+		apiKey: secret(),
+		siiKey: secret(),
+		registrationSecret: secret(),
+		pfxSecret: secret(),
+		userFormKey: secret()
+	}), "utf-8");
+	M.success("Wrote local.env (minimal bootable — fill third-party keys when needed)");
+}
+function parseEnvFile(path) {
+	if (!existsSync(path)) return {};
+	const out = {};
+	for (const raw of readFileSync(path, "utf-8").split("\n")) {
+		const line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		const key = line.slice(0, eq).trim();
+		let value = line.slice(eq + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		out[key] = value;
+	}
+	return out;
+}
+function decideTenantAction(tenantDbExists, adminUserExists) {
+	if (tenantDbExists && adminUserExists) return "already-provisioned";
+	if (tenantDbExists) return "reset-and-seed";
+	return "create-and-seed";
+}
+function parseMysqlUrl(url) {
+	const u = new URL(url);
+	return {
+		host: u.hostname || "localhost",
+		port: u.port || "3306",
+		user: decodeURIComponent(u.username) || "root",
+		password: u.password ? decodeURIComponent(u.password) : void 0
+	};
+}
+function dbNameFromUrl(url) {
+	return new URL(url).pathname.replace(/^\//, "");
+}
+function swapDbName(url, name) {
+	const u = new URL(url);
+	u.pathname = `/${name}`;
+	return u.toString();
+}
+function mysqlArgs(conn) {
+	const args = [
+		"-h",
+		conn.host,
+		"-P",
+		conn.port,
+		"-u",
+		conn.user
+	];
+	if (conn.password) args.push(`-p${conn.password}`);
+	return args;
+}
+function mysqlQuery(conn, sql) {
+	return capture("mysql", [
+		...mysqlArgs(conn),
+		"-N",
+		"-B",
+		"-e",
+		sql
+	]);
+}
+function mysqlExec(conn, sql) {
+	return run("mysql", [
+		...mysqlArgs(conn),
+		"-e",
+		sql
+	]);
+}
+function dbExists(conn, name) {
+	const { out } = mysqlQuery(conn, `SELECT SCHEMA_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = '${name}'`);
+	return out.length > 0;
+}
+function tableExists(conn, db, table) {
+	const { out } = mysqlQuery(conn, `SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = '${db}' AND TABLE_NAME = '${table}'`);
+	return out.length > 0;
+}
+function adminUserExists(conn, db, email) {
+	if (!tableExists(conn, db, "User")) return false;
+	const { ok, out } = mysqlQuery(conn, `SELECT COUNT(*) FROM \`${db}\`.\`User\` WHERE email = '${email}'`);
+	return ok && parseInt(out, 10) > 0;
+}
+function migrateDeploy(serverPath, url) {
+	return run("npx", [
+		"prisma",
+		"migrate",
+		"deploy"
+	], serverPath, { DATABASE_URL: url });
+}
+function runDisposableScript(serverPath, fileName, contents, env, extraArgs = []) {
+	const scriptPath = join(serverPath, fileName);
+	writeFileSync(scriptPath, contents, "utf-8");
+	try {
+		return run("npx", [
+			"ts-node",
+			"--transpile-only",
+			"-r",
+			"tsconfig-paths/register",
+			scriptPath,
+			...extraArgs
+		], serverPath, env);
+	} finally {
+		rmSync(scriptPath, { force: true });
+	}
+}
+function setupLocalDatabase(serverPath, env) {
+	const controlPlaneUrl = env.DATABASE_URL;
+	const clientId = env.CLIENT_ID;
+	const adminPassword = env.ADMIN_PASSWORD;
+	if (!controlPlaneUrl || !clientId || !adminPassword) {
+		M.warn("local.env is missing DATABASE_URL / CLIENT_ID / ADMIN_PASSWORD — skipping database setup.");
+		return;
+	}
+	const conn = parseMysqlUrl(controlPlaneUrl);
+	const controlPlaneName = dbNameFromUrl(controlPlaneUrl);
+	const tenantName = `tenant-${clientId}`;
+	const tenantUrl = swapDbName(controlPlaneUrl, tenantName);
+	const adminEmail = `admin@${clientId}.com`;
+	M.step(`Setting up local databases (${controlPlaneName} + ${tenantName})…`);
+	mysqlExec(conn, `CREATE DATABASE IF NOT EXISTS \`${controlPlaneName}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
+	if (!migrateDeploy(serverPath, controlPlaneUrl)) {
+		M.warn("Control-plane migration failed — skipping the rest of database setup.");
+		return;
+	}
+	runDisposableScript(serverPath, ".pruff-onboarding-preseed.ts", CONTROL_PLANE_PRESEED_SCRIPT, {
+		...env,
+		DATABASE_URL: controlPlaneUrl
+	});
+	const action = decideTenantAction(dbExists(conn, tenantName), adminUserExists(conn, tenantName, adminEmail));
+	if (action === "already-provisioned") {
+		M.success(`Tenant "${clientId}" already provisioned — skipping seed.`);
+		printLoginHint(clientId, adminEmail, adminPassword);
+		return;
+	}
+	if (action === "reset-and-seed") {
+		M.warn(`Tenant "${clientId}" partially provisioned — resetting (Pruff-server seed is not idempotent).`);
+		mysqlExec(conn, `DROP DATABASE IF EXISTS \`${tenantName}\``);
+	}
+	mysqlExec(conn, `CREATE DATABASE IF NOT EXISTS \`${tenantName}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`);
+	if (!migrateDeploy(serverPath, tenantUrl)) {
+		M.warn("Tenant migration failed — skipping seed.");
+		return;
+	}
+	const s = Y();
+	s.start(`Seeding tenant "${clientId}"…`);
+	const seeded = run("npx", [
+		"prisma",
+		"db",
+		"seed"
+	], serverPath, {
+		...env,
+		DATABASE_URL: tenantUrl
+	});
+	s.stop(seeded ? `Tenant "${clientId}" seeded` : import_picocolors.default.yellow("Tenant seed failed"));
+	if (!seeded) return;
+	if (!runDisposableScript(serverPath, ".pruff-onboarding-tenant-user.ts", TENANT_USER_BACKFILL_SCRIPT, {
+		...env,
+		DATABASE_URL: tenantUrl
+	}, [adminEmail, adminPassword])) {
+		M.warn("Tenant admin-user backfill failed — you may need to create the user manually.");
+		return;
+	}
+	M.success(`Local tenant "${clientId}" ready.`);
+	printLoginHint(clientId, adminEmail, adminPassword);
+}
+function printLoginHint(clientId, email, password) {
+	M.info(`Log in locally with:\n  ${import_picocolors.default.dim("secretId:")} ${import_picocolors.default.cyan(clientId)}\n  ${import_picocolors.default.dim("email:   ")} ${import_picocolors.default.cyan(email)}\n  ${import_picocolors.default.dim("password:")} ${import_picocolors.default.cyan(password)}`);
+}
+async function showGuidance(workspace) {
+	console.log();
+	await sweepLine("W O R K S P A C E   R E A D Y", { slow: true });
+	console.log();
+	const line = (s) => console.log(`  ${s}`);
+	line(import_picocolors.default.bold("Recommended structure") + import_picocolors.default.dim("  (keep everything under one parent)"));
+	line("");
+	line(`${import_picocolors.default.cyan(workspace)}/`);
+	const tree = [
+		["CLAUDE.md", "workspace-level context — repo map, conventions, critical rules"],
+		[".claude/", "rules · agents · skills (apply to every repo below)"],
+		[`${KNOWLEDGE_DIR}/`, "Obsidian vault — open it in Obsidian"],
+		["Pruff-server/", "backend (bun)"],
+		["Pruff-Client/", "frontend (yarn)"],
+		["sls-*/", "serverless services — clone as you need them"]
+	];
+	const labelWidth = Math.max(...tree.map(([label]) => label.length)) + 2;
+	tree.forEach(([label, desc], i) => {
+		const connector = i === tree.length - 1 ? "└──" : "├──";
+		line(`${import_picocolors.default.dim(connector)} ${label.padEnd(labelWidth)}${import_picocolors.default.dim(desc)}`);
+	});
+	line("");
+	line(import_picocolors.default.bold("Next steps"));
+	line(`${import_picocolors.default.dim("1.")} Open ${import_picocolors.default.bold("Obsidian")} → the ${import_picocolors.default.cyan(KNOWLEDGE_DIR)} vault is registered and ready.`);
+	line(`${import_picocolors.default.dim("2.")} Start Claude Code from ${import_picocolors.default.cyan(workspace)} so the shared ${import_picocolors.default.dim(".claude/")} applies everywhere.`);
+	line(`${import_picocolors.default.dim("3.")} Dependencies are installed — ${import_picocolors.default.dim("cd Pruff-server && npm run local")} / ${import_picocolors.default.dim("cd Pruff-Client && yarn start-local")}.`);
+	line(`${import_picocolors.default.dim("4.")} Clone any serverless service into this folder with ${import_picocolors.default.dim("git clone <repo>")}.`);
+	console.log();
+}
+function registerVault(vaultPath) {
+	const dir = join(homedir(), "Library", "Application Support", "obsidian");
+	const configPath = join(dir, "obsidian.json");
+	let config = { vaults: {} };
+	if (existsSync(configPath)) try {
+		config = JSON.parse(readFileSync(configPath, "utf-8"));
+		if (!config.vaults) config.vaults = {};
+	} catch {
+		M.warn(`Could not parse ${import_picocolors.default.dim(configPath)} — leaving it untouched.`);
+		return;
+	}
+	else mkdirSync(dir, { recursive: true });
+	if (Object.values(config.vaults).some((v) => v.path === vaultPath)) {
+		M.success("Vault already registered in Obsidian");
+		return;
+	}
+	const id = randomBytes(8).toString("hex");
+	config.vaults[id] = {
+		path: vaultPath,
+		ts: Date.now(),
+		open: true
+	};
+	writeFileSync(configPath, JSON.stringify(config), "utf-8");
+	M.success("Registered vault in Obsidian");
+}
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function getVersion() {
 	try {
@@ -6081,9 +7174,7 @@ function getVersion() {
 	}
 }
 const VERSION = getVersion();
-const RESET = "\x1B[0m";
 const BOLD = "\x1B[1m";
-const DIM = "\x1B[38;5;102m";
 const TEXT = "\x1B[38;5;145m";
 const BLUE = "\x1B[38;2;110;139;255m";
 const LOGO_LINES = [
@@ -6094,16 +7185,6 @@ const LOGO_LINES = [
 	"██║     ██║  ██║╚██████╔╝██║     ██║     ",
 	"╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝     "
 ];
-const BLUES = [
-	"\x1B[38;2;110;139;255m",
-	"\x1B[38;2;91;118;249m",
-	"\x1B[38;2;72;97;242m",
-	"\x1B[38;2;53;77;236m",
-	"\x1B[38;2;34;56;229m",
-	"\x1B[38;2;15;35;223m"
-];
-const SWEEP = "\x1B[38;2;214;226;255m";
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function printStaticLogo() {
 	LOGO_LINES.forEach((line, i) => {
 		console.log(`${BLUES[i]}${line}${RESET}`);
@@ -6139,7 +7220,7 @@ function renderLogoFrame(pos, band) {
 		return out + RESET;
 	}).join("\n");
 }
-async function showLogo() {
+async function showLogo(slow = false) {
 	console.log();
 	if (!(!!process.stdout.isTTY && !process.env.CI && !process.env.NO_COLOR && !process.env.PRUFF_SKILLS_NO_ANIM)) {
 		printStaticLogo();
@@ -6148,6 +7229,9 @@ async function showLogo() {
 	const rows = LOGO_LINES.length;
 	const width = Math.max(...LOGO_LINES.map((l) => Array.from(l).length));
 	const band = 7;
+	const revealMs = slow ? 190 : 90;
+	const step = slow ? 3 : 4;
+	const sweepMs = slow ? 34 : 18;
 	process.stdout.write("\x1B[?25l");
 	try {
 		let first = true;
@@ -6155,15 +7239,83 @@ async function showLogo() {
 			if (!first) process.stdout.write(`\x1b[${rows}A`);
 			process.stdout.write("\r" + renderLogoReveal(cut, width) + "\n");
 			first = false;
-			await sleep(90);
+			await sleep(revealMs);
 		}
-		for (let pos = -7; pos <= width; pos += 4) {
+		for (let pos = -7; pos <= width; pos += step) {
 			process.stdout.write(`\x1b[${rows}A`);
 			process.stdout.write("\r" + renderLogoFrame(pos, band) + "\n");
-			await sleep(18);
+			await sleep(sweepMs);
 		}
 		process.stdout.write(`\x1b[${rows}A\r`);
 		process.stdout.write(LOGO_LINES.map((line, i) => `${BLUES[i]}${line}${RESET}`).join("\n") + "\n");
+		if (slow) await sleep(500);
+	} finally {
+		process.stdout.write("\x1B[?25h");
+	}
+}
+const BUILDING_LINES = [
+	"██████╗ ██╗   ██╗██╗██╗     ██████╗ ██╗███╗   ██╗ ██████╗ ",
+	"██╔══██╗██║   ██║██║██║     ██╔══██╗██║████╗  ██║██╔════╝ ",
+	"██████╔╝██║   ██║██║██║     ██║  ██║██║██╔██╗ ██║██║  ███╗",
+	"██╔══██╗██║   ██║██║██║     ██║  ██║██║██║╚██╗██║██║   ██║",
+	"██████╔╝╚██████╔╝██║███████╗██████╔╝██║██║ ╚████║╚██████╔╝",
+	"╚═════╝  ╚═════╝ ╚═╝╚══════╝╚═════╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝ "
+];
+const FINTECHS_LINES = [
+	"███████╗██╗███╗   ██╗████████╗███████╗ ██████╗██╗  ██╗███████╗",
+	"██╔════╝██║████╗  ██║╚══██╔══╝██╔════╝██╔════╝██║  ██║██╔════╝",
+	"█████╗  ██║██╔██╗ ██║   ██║   █████╗  ██║     ███████║███████╗",
+	"██╔══╝  ██║██║╚██╗██║   ██║   ██╔══╝  ██║     ██╔══██║╚════██║",
+	"██║     ██║██║ ╚████║   ██║   ███████╗╚██████╗██║  ██║███████║",
+	"╚═╝     ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝"
+];
+const TAGLINE_INDENT = "";
+const TAGLINE_ROWS = BUILDING_LINES.length + FINTECHS_LINES.length;
+const WHITES = [
+	"\x1B[38;2;255;255;255m",
+	"\x1B[38;2;228;230;236m",
+	"\x1B[38;2;201;205;216m",
+	"\x1B[38;2;174;180;196m",
+	"\x1B[38;2;148;155;176m",
+	"\x1B[38;2;122;131;156m"
+];
+function renderRevealRow(line, row, cols, fromLeft) {
+	const chars = Array.from(line);
+	const w = chars.length;
+	let out = TAGLINE_INDENT + WHITES[Math.min(WHITES.length - 1, row)];
+	for (let c = 0; c < w; c++) {
+		const shown = fromLeft ? c < cols : c >= w - cols;
+		out += shown ? chars[c] : " ";
+	}
+	return out + RESET;
+}
+function renderTaglineReveal(cols) {
+	const rows = [];
+	BUILDING_LINES.forEach((line, row) => rows.push(renderRevealRow(line, row, cols, true)));
+	FINTECHS_LINES.forEach((line, row) => rows.push(renderRevealRow(line, row, cols, false)));
+	return rows.join("\n");
+}
+async function showTagline(slow = false) {
+	console.log();
+	const rows = TAGLINE_ROWS;
+	const width = Math.max(...[...BUILDING_LINES, ...FINTECHS_LINES].map((l) => Array.from(l).length));
+	const step = slow ? 2 : 3;
+	const ms = slow ? 26 : 14;
+	if (!(!!process.stdout.isTTY && !process.env.CI && !process.env.NO_COLOR && !process.env.PRUFF_SKILLS_NO_ANIM)) {
+		console.log(renderTaglineReveal(width));
+		return;
+	}
+	process.stdout.write("\x1B[?25l");
+	try {
+		let first = true;
+		for (let cols = 0; cols <= width; cols += step) {
+			if (!first) process.stdout.write(`\x1b[${rows}A`);
+			process.stdout.write("\r" + renderTaglineReveal(cols) + "\n");
+			first = false;
+			await sleep(ms);
+		}
+		process.stdout.write(`\x1b[${rows}A\r` + renderTaglineReveal(width) + "\n");
+		if (slow) await sleep(500);
 	} finally {
 		process.stdout.write("\x1B[?25h");
 	}
@@ -6212,6 +7364,10 @@ ${BOLD}Rules:${RESET}
   rules add --scope <client|server|common>
                        Install a whole repo's rule set (client/server also pull in common)
 
+${BOLD}Onboarding:${RESET}
+  onboarding           Set up a new machine (macOS): install Claude Code,
+                       install Obsidian, and clone the Pruff knowledge vault
+
 ${BOLD}Updates:${RESET}
   update [skills...]   Update skills to latest versions (alias: upgrade)
 
@@ -6417,6 +7573,14 @@ async function main() {
 			if (!inAgent) await showLogo();
 			await runRules(restArgs);
 			break;
+		case "onboarding":
+		case "onboard":
+			if (!inAgent) {
+				await showLogo(true);
+				await showTagline(true);
+			}
+			await runOnboarding(restArgs);
+			break;
 		case "remove":
 		case "rm":
 		case "r":