pruff-skills 0.3.0 → 0.4.0

package/dist/cli.mjs

@@ -5,7 +5,7 @@ import { Ie, M, Me, Se, Y, be, fe, he, ve, xe, ye } from "./_chunks/libs/@clack/
 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";
@@ -6126,16 +6126,495 @@ async function sweepLine(text, { slow = false, indent = "  " } = {}) {
 		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"
+	url: "https://github.com/Pruff-Tech/Pruff-server",
+	installCmd: "bun",
+	installArgs: ["install"]
 }, {
 	name: "Pruff-Client",
-	url: "https://github.com/Pruff-Tech/Pruff-Client"
+	url: "https://github.com/Pruff-Tech/Pruff-Client",
+	installCmd: "yarn",
+	installArgs: ["install"]
 }];
 const CORE_SKILLS = [
 	"commit",
@@ -6161,12 +6640,16 @@ async function runOnboarding(args) {
 	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.name, repo.url, 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.`);
 }
@@ -6176,12 +6659,30 @@ function has(cmd) {
 		stdio: "ignore"
 	}).status === 0;
 }
-function run(cmd, args, cwd) {
+function run(cmd, args, cwd, env) {
 	return spawnSync(cmd, args, {
 		stdio: "inherit",
-		cwd
+		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;
 }
@@ -6223,6 +6724,19 @@ function ensureObsidian() {
 		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);
@@ -6266,7 +6780,8 @@ function cloneKnowledge(workspace) {
 	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(name, url, workspace) {
+function cloneRepo(repo, workspace) {
+	const { name, url } = repo;
 	const target = join(workspace, name);
 	if (existsSync(join(target, ".git"))) {
 		M.success(`${name} already cloned`);
@@ -6284,6 +6799,33 @@ function cloneRepo(name, url, workspace) {
 		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…");
@@ -6302,6 +6844,272 @@ async function installCatalog(workspace) {
 		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 });
@@ -6311,10 +7119,11 @@ async function showGuidance(workspace) {
 	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"],
-		["Pruff-Client/", "frontend"],
+		["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;
@@ -6326,9 +7135,8 @@ async function showGuidance(workspace) {
 	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.")} Backend:  ${import_picocolors.default.dim("cd Pruff-server && npm i && npm run local")}`);
-	line(`${import_picocolors.default.dim("4.")} Frontend: ${import_picocolors.default.dim("cd Pruff-Client && yarn && yarn start-local")}`);
-	line(`${import_picocolors.default.dim("5.")} Clone any serverless service into this folder with ${import_picocolors.default.dim("git clone <repo>")}.`);
+	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) {
@@ -6445,60 +7253,68 @@ async function showLogo(slow = false) {
 		process.stdout.write("\x1B[?25h");
 	}
 }
-const TAGLINE_BLOCKS = [[
+const BUILDING_LINES = [
 	"██████╗ ██╗   ██╗██╗██╗     ██████╗ ██╗███╗   ██╗ ██████╗ ",
 	"██╔══██╗██║   ██║██║██║     ██╔══██╗██║████╗  ██║██╔════╝ ",
 	"██████╔╝██║   ██║██║██║     ██║  ██║██║██╔██╗ ██║██║  ███╗",
 	"██╔══██╗██║   ██║██║██║     ██║  ██║██║██║╚██╗██║██║   ██║",
 	"██████╔╝╚██████╔╝██║███████╗██████╔╝██║██║ ╚████║╚██████╔╝",
 	"╚═════╝  ╚═════╝ ╚═╝╚══════╝╚═════╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝ "
-], [
+];
+const FINTECHS_LINES = [
 	"███████╗██╗███╗   ██╗████████╗███████╗ ██████╗██╗  ██╗███████╗",
 	"██╔════╝██║████╗  ██║╚══██╔══╝██╔════╝██╔════╝██║  ██║██╔════╝",
 	"█████╗  ██║██╔██╗ ██║   ██║   █████╗  ██║     ███████║███████╗",
 	"██╔══╝  ██║██║╚██╗██║   ██║   ██╔══╝  ██║     ██╔══██║╚════██║",
 	"██║     ██║██║ ╚████║   ██║   ███████╗╚██████╗██║  ██║███████║",
 	"╚═╝     ╚═╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝ ╚═════╝╚═╝  ╚═╝╚══════╝"
-]];
-const TAGLINE_INDENT = "  ";
-function renderTaglineRow(line, row, pos, band) {
+];
+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);
-	let out = TAGLINE_INDENT;
-	let mode = "";
-	for (let c = 0; c < chars.length; c++) {
-		const color = c >= pos && c < pos + band ? SWEEP : BLUES[row];
-		if (color !== mode) {
-			out += color;
-			mode = color;
-		}
-		out += chars[c];
+	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 renderTaglineFrame(pos, band) {
-	return TAGLINE_BLOCKS.map((block) => block.map((line, row) => renderTaglineRow(line, row, pos, band)).join("\n")).join("\n");
+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_BLOCKS.reduce((n, b) => n + b.length, 0);
-	const width = Math.max(...TAGLINE_BLOCKS.flat().map((l) => Array.from(l).length));
-	const band = 7;
-	const step = slow ? 3 : 4;
-	const sweepMs = slow ? 34 : 18;
+	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(renderTaglineFrame(-1, 0));
+		console.log(renderTaglineReveal(width));
 		return;
 	}
 	process.stdout.write("\x1B[?25l");
 	try {
 		let first = true;
-		for (let pos = -7; pos <= width; pos += step) {
+		for (let cols = 0; cols <= width; cols += step) {
 			if (!first) process.stdout.write(`\x1b[${rows}A`);
-			process.stdout.write("\r" + renderTaglineFrame(pos, band) + "\n");
+			process.stdout.write("\r" + renderTaglineReveal(cols) + "\n");
 			first = false;
-			await sleep(sweepMs);
+			await sleep(ms);
 		}
-		process.stdout.write(`\x1b[${rows}A\r` + renderTaglineFrame(-1, 0) + "\n");
+		process.stdout.write(`\x1b[${rows}A\r` + renderTaglineReveal(width) + "\n");
 		if (slow) await sleep(500);
 	} finally {
 		process.stdout.write("\x1B[?25h");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruff-skills",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The official Pruff agent skills CLI",
   "type": "module",
   "bin": {