claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/skills/nextjs-supabase-auth/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: nextjs-supabase-auth
+description: Expert integration of Supabase Auth with Next.js App Router — server/client boundary, middleware for session refresh, Server Components, Server Actions, RLS. Use when the task mentions Supabase auth, Next.js auth, login, signup, OAuth, protected routes, or auth middleware
+tokens: 2155
+user-invocable: false
+---
+
+# Next.js + Supabase Auth
+
+Expert in integrating Supabase Auth with Next.js App Router: the server/client boundary, session refresh in middleware, Server Components, Client Components, and Server Actions.
+
+## Use this skill when
+
+- Wiring Supabase Auth into a Next.js App Router project (`@supabase/ssr`)
+- Setting up login, signup, signout, OAuth, or magic-link / email-OTP flows
+- Protecting routes or reading the authenticated user server-side
+- Refreshing sessions in middleware
+- Writing Row-Level Security (RLS) policies for authenticated tables
+
+## Do not use this skill when
+
+- The project uses the Pages Router or the deprecated `@supabase/auth-helpers-nextjs`
+- Auth is handled by another provider (NextAuth/Auth.js, Clerk, Firebase)
+- The task is Supabase database design with no auth surface
+
+## Hard Rules
+
+1. Use `@supabase/ssr` for App Router integration. NEVER use `@supabase/auth-helpers-nextjs` (deprecated).
+2. Refresh the session in middleware on every request; the matcher MUST exclude static assets.
+3. Read the user with `getUser()` in server code, NEVER `getSession()` — `getUser()` re-validates with the auth server; `getSession()` reads cookies only and is forgeable.
+4. NEVER expose `SUPABASE_SERVICE_ROLE_KEY` to the client or any `NEXT_PUBLIC_*` var — it bypasses RLS.
+5. Prefer Server Actions for auth operations (login, signup, signout).
+6. Enable RLS on every table the anon key can reach — non-negotiable for production.
+
+## Workflow
+
+1. Create the browser and server clients (`lib/supabase/client.ts`, `lib/supabase/server.ts`) with the cookie handlers below. Done when both `createClient` helpers compile.
+2. Wire `middleware.ts` to refresh the session and redirect unauthenticated users off protected paths. Done when the matcher excludes static assets.
+3. Add the OAuth callback route (`app/auth/callback/route.ts`) if using OAuth or magic links. Done when it calls `exchangeCodeForSession`.
+4. Build auth operations as Server Actions (login / signup / signout) with `revalidatePath` + `redirect`.
+5. Read the user in Server Components with `getUser()`; redirect when it is null.
+6. Enable RLS and add SELECT/INSERT policies on every table the anon key can reach.
+
+## Stack
+
+- `@supabase/ssr` — official SSR helper
+- `@supabase/supabase-js` — base client (peer dependency)
+- Next.js 14+ App Router
+
+## Client Setup — Three Contexts
+
+### Browser Client (`lib/supabase/client.ts`)
+
+```typescript
+import { createBrowserClient } from '@supabase/ssr';
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  );
+}
+```
+
+Used in Client Components for realtime, file uploads, or direct client mutations.
+
+### Server Client (`lib/supabase/server.ts`)
+
+```typescript
+import { createServerClient } from '@supabase/ssr';
+import { cookies } from 'next/headers';
+
+export async function createClient() {
+  const cookieStore = await cookies();
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return cookieStore.getAll(); },
+        setAll(cookies) {
+          try {
+            cookies.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            );
+          } catch { /* Server Component — middleware handles refresh */ }
+        },
+      },
+    }
+  );
+}
+```
+
+Used in Server Components, Server Actions, Route Handlers.
+
+### Middleware Client (`middleware.ts`)
+
+```typescript
+import { createServerClient } from '@supabase/ssr';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function middleware(request: NextRequest) {
+  let response = NextResponse.next({ request });
+
+  const supabase = createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() { return request.cookies.getAll(); },
+        setAll(cookies) {
+          cookies.forEach(({ name, value, options }) => {
+            request.cookies.set(name, value);
+            response.cookies.set(name, value, options);
+          });
+        },
+      },
+    }
+  );
+
+  const { data: { user } } = await supabase.auth.getUser();
+
+  // Protect specific routes
+  const isProtected = request.nextUrl.pathname.startsWith('/dashboard');
+  if (isProtected && !user) {
+    const url = request.nextUrl.clone();
+    url.pathname = '/login';
+    return NextResponse.redirect(url);
+  }
+
+  return response;
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg)).*)'],
+};
+```
+
+## OAuth Callback Route
+
+`app/auth/callback/route.ts` — required for OAuth flows (Google, GitHub, etc.):
+
+```typescript
+import { createClient } from '@/lib/supabase/server';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function GET(request: NextRequest) {
+  const { searchParams, origin } = new URL(request.url);
+  const code = searchParams.get('code');
+  const next = searchParams.get('next') ?? '/dashboard';
+
+  if (code) {
+    const supabase = await createClient();
+    const { error } = await supabase.auth.exchangeCodeForSession(code);
+    if (!error) return NextResponse.redirect(`${origin}${next}`);
+  }
+
+  return NextResponse.redirect(`${origin}/auth/error`);
+}
+```
+
+## Server Action — Login / Signup
+
+```typescript
+'use server';
+import { createClient } from '@/lib/supabase/server';
+import { revalidatePath } from 'next/cache';
+import { redirect } from 'next/navigation';
+
+export async function login(formData: FormData) {
+  const supabase = await createClient();
+  const { error } = await supabase.auth.signInWithPassword({
+    email: formData.get('email') as string,
+    password: formData.get('password') as string,
+  });
+  if (error) return { error: error.message };
+  revalidatePath('/', 'layout');
+  redirect('/dashboard');
+}
+```
+
+## Magic Link / Email OTP
+
+```typescript
+await supabase.auth.signInWithOtp({
+  email,
+  options: { emailRedirectTo: `${origin}/auth/callback?next=/dashboard` },
+});
+```
+
+## Reading the User in a Server Component
+
+```typescript
+// app/dashboard/page.tsx
+import { createClient } from '@/lib/supabase/server';
+import { redirect } from 'next/navigation';
+
+export default async function Dashboard() {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) redirect('/login');
+  return <h1>Hi, {user.email}</h1>;
+}
+```
+
+Always `getUser()` here, never `getSession()` (Hard Rule 3).
+
+## RLS (Row-Level Security)
+
+Always enable RLS for tables touched by authenticated clients:
+
+```sql
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users can read their own posts"
+  ON posts FOR SELECT
+  USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert their own posts"
+  ON posts FOR INSERT
+  WITH CHECK (auth.uid() = user_id);
+```
+
+Without RLS, the anon key gives full access to any table. RLS is a non-negotiable for production.
+
+## Anti-Patterns to Avoid
+
+### `getSession()` in server code
+Forgeable — reads cookies without validation. Use `getUser()` (Hard Rule 3).
+
+### Storing tokens manually
+Don't `localStorage.setItem('token', ...)`. `@supabase/ssr` handles cookies for you.
+
+### Hardcoding `service_role` key
+`SUPABASE_SERVICE_ROLE_KEY` bypasses RLS and must NEVER be in client code or `NEXT_PUBLIC_*` env vars.
+
+### Forgetting to revalidate after login
+After a Server Action login, call `revalidatePath('/', 'layout')` so cached UI reflects the new user.
+
+### Auth in client without listener
+If you read user state on mount, also subscribe to `supabase.auth.onAuthStateChange` so sign-out in another tab updates UI.
+
+## Common Production Issues
+
+| Symptom | Fix |
+|--------|-----|
+| User logs in but Server Components see no session | Middleware not refreshing cookies — check matcher excludes static files |
+| OAuth redirect loops | Mismatch between Supabase project's "Site URL" and your origin |
+| RLS error "permission denied for table" | Policy missing or auth.uid() returning null |
+| Cookies set in Server Component throw | Expected — let middleware handle it, wrap in try/catch |
+
+## Recap — non-negotiables
+
+- `@supabase/ssr` only; never the deprecated auth-helpers package.
+- Middleware refreshes the session every request; matcher excludes static assets.
+- Server code reads the user via `getUser()`, never `getSession()`.
+- `SUPABASE_SERVICE_ROLE_KEY` never reaches the client; RLS is enabled on every anon-reachable table.
+
+Adapted from vibeship-spawner-skills via VKirill/codex-starter-kit (Apache 2.0).

package/packages/core/skills/postgresql-optimization/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: postgresql-optimization
+description: PostgreSQL optimization — query tuning, indexing, EXPLAIN analysis, configuration, maintenance, and monitoring. Use when slow queries, missing indexes, vacuum lag, or performance bottlenecks are suspected
+tokens: 1994
+user-invocable: false
+---
+
+# PostgreSQL Optimization
+
+Diagnose and fix PostgreSQL performance: query tuning, indexing, EXPLAIN analysis, server configuration, maintenance, and monitoring. The core discipline is measure-before-and-after — one change per cycle, validated with `EXPLAIN ANALYZE`.
+
+## Use this skill when
+
+- Optimizing slow PostgreSQL queries
+- Designing or reviewing indexing strategies
+- Analyzing performance and identifying bottlenecks
+- Tuning server configuration
+- Managing production maintenance (VACUUM, ANALYZE, bloat)
+- Setting up monitoring and alerting
+
+## Do not use this skill when
+
+- You need schema / data-model design — that is out of scope here; this skill tunes an existing schema. For Drizzle ORM schema and migration work, use the `drizzle-orm-expert` skill.
+- The bottleneck is at the application layer, not the database.
+- You need a database-agnostic optimization guide — this is PostgreSQL-specific.
+
+## Hard Rules
+
+- Measure with `EXPLAIN ANALYZE` BEFORE and AFTER every change — never tune from a guess.
+- Change ONE layer at a time (index / query / config / maintenance), then re-measure.
+- Use `CONCURRENTLY` for every `CREATE INDEX` and `REINDEX` on live tables — the plain form locks writes.
+- NEVER disable autovacuum in production.
+- NEVER run `VACUUM FULL` during business hours — it takes an ACCESS EXCLUSIVE lock on the whole table.
+- Test config changes on staging first; treat each as a hypothesis to confirm with monitoring.
+
+## Steps
+
+Follow in order. Change one thing, re-measure, then move on.
+
+1. **Identify** — Pin the specific slow query and its bottleneck category. Note the PostgreSQL version and key config (`shared_buffers`, `work_mem`, `effective_cache_size`, `autovacuum`); find the worst queries via `pg_stat_statements` or the slow-query log; check CPU / memory / disk I/O; classify the bottleneck as scan type, join strategy, I/O, locking, or vacuum lag. **Done when:** you have one target query and a suspected category.
+2. **Measure the baseline** — Run `EXPLAIN (ANALYZE, BUFFERS)` on the target query before any change. Read the node types; compare estimated vs actual rows (large mismatch = stale statistics → run `ANALYZE`); locate the highest-cost node, highest actual-row node, or largest loop. Use the EXPLAIN Output Interpretation table below. **Done when:** you have a baseline plan and the specific expensive node.
+3. **Apply one targeted fix** — Change exactly ONE layer, chosen from the bottleneck: missing index → Indexing Strategy; bad plan or query shape → Query Optimization; memory / checkpoint limits → Configuration Tuning; bloat or stale stats → Maintenance. Validate autovacuum is running before recommending a manual VACUUM; check for stale statistics before rewriting a query. **Done when:** exactly one change is applied.
+4. **Verify** — Re-run `EXPLAIN ANALYZE`. Confirm the plan changed as intended and timing dropped. If it did not improve, revert the change and return to Step 2 with a different hypothesis. **Done when:** the second plan shows the expected improvement, or the change is reverted.
+5. **Monitor** — Confirm the fix holds under real load using `pg_stat_statements`, `pg_stat_user_tables`, and `pg_stat_user_indexes` over time. Treat every config change as a hypothesis until monitoring confirms it. **Done when:** metrics are stable under production load.
+
+## EXPLAIN Output Interpretation
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
+```
+
+Node types to know: `Seq Scan`, `Index Scan`, `Index Only Scan`, `Hash Join`, `Nested Loop`, `Merge Join`. A `Seq Scan` on a small table is fine; on a large table it signals a missing or unused index.
+
+| Output sign | Meaning |
+|-------------|---------|
+| Seq Scan on large table | Missing or unused index |
+| Index Scan but slow | Index not selective; high row count returned |
+| Nested Loop with large outer | Consider Hash Join (`enable_nestloop=off` for testing) |
+| Hash Join with disk batches | `work_mem` too low |
+| Sort with `external merge Disk` | `work_mem` too low for this sort |
+| Estimated 1, actual 1M | Stale statistics → `ANALYZE table` |
+| Estimated 1M, actual 1 | Histogram bucket too small → increase `ALTER TABLE ... ALTER COLUMN ... SET STATISTICS 1000` |
+
+## Indexing Strategy
+
+| Pattern | Index type |
+|---------|-----------|
+| Equality + range on 1 column | B-tree |
+| Multi-column equality | Composite B-tree, most selective first |
+| JSONB containment | GIN |
+| Full-text search | GIN on `tsvector` |
+| Range overlap, scheduling | GiST on range type |
+| Hot subset (`WHERE status='active'`) | Partial index |
+| Avoid heap reads for extra columns | Covering index with `INCLUDE` |
+| Time-series, naturally ordered | BRIN |
+
+Review `pg_stat_user_indexes` — unused indexes waste write performance and bloat.
+
+```sql
+-- Always CONCURRENTLY in production:
+CREATE INDEX CONCURRENTLY idx_users_email_active
+  ON users (email) WHERE active = true;
+
+-- Covering index for index-only scans:
+CREATE INDEX CONCURRENTLY idx_orders_user_created
+  ON orders (user_id, created_at) INCLUDE (status, total);
+```
+
+## Query Optimization
+
+- Rewrite subqueries as JOINs where the planner struggles
+- Use CTEs (`WITH ...`) for readability; add `AS MATERIALIZED` when you need an optimization fence — PostgreSQL 12+ inlines plain CTEs
+- Cursor-based pagination for large feeds (offset is O(n))
+- Use `LIMIT` in subqueries to bound work
+- Avoid functions on indexed columns in `WHERE` — prevents index use
+- Avoid implicit type casts (`WHERE id = '123'` when id is integer)
+
+## Configuration Tuning
+
+| Setting | Default | Recommendation |
+|---------|---------|----------------|
+| `shared_buffers` | 128MB | 25% of RAM (dedicated DB server) |
+| `work_mem` | 4MB | 16-64MB per connection; multiply by max_connections for peak |
+| `effective_cache_size` | 4GB | 50-75% of RAM |
+| `checkpoint_completion_target` | 0.9 | Keep 0.9 to spread checkpoint I/O |
+| `max_wal_size` | 1GB | Increase if checkpoint frequency too high |
+| `autovacuum_vacuum_scale_factor` | 0.2 | 0.01-0.05 for large tables |
+
+## Maintenance
+
+- Regular `VACUUM` reclaims dead tuples from updates/deletes
+- `VACUUM ANALYZE` after large data changes updates planner stats
+- Monitor bloat: `pg_stat_user_tables`, `pg_total_relation_size`, `pgstattuple`
+- Check `pg_stat_user_tables.last_autovacuum`, `n_dead_tup`
+- `REINDEX CONCURRENTLY` for bloated indexes (no table lock)
+
+## Partitioning (very large tables)
+
+- Declarative partitioning `PARTITION BY RANGE | LIST | HASH` splits a huge table so the planner prunes irrelevant partitions.
+- Range-partition time-series data by date and pair each partition with a BRIN index; drop old partitions instead of `DELETE` to avoid bloat.
+
+## Monitoring
+
+| Tool | Purpose |
+|------|---------|
+| `pg_stat_statements` | Most time-consuming queries |
+| `pg_stat_user_tables` | Table access patterns, dead tuples, vacuum timing |
+| `pg_stat_user_indexes` | Index usage; identify unused indexes |
+| `pg_locks` | Lock contention slowing queries |
+| `pg_stat_activity` | Currently running queries, idle-in-transaction sessions |
+| `postgres_exporter` + Grafana | Ongoing visibility |
+
+## Common Anti-Patterns
+
+- `WHERE LOWER(email) = ?` without expression index
+- Implicit type cast: `WHERE id = '123'` when id is integer
+- `SELECT *` on wide tables (prevents index-only scans)
+- `OFFSET 1000000 LIMIT 10` — scans all preceding rows
+- `IN (...)` with hundreds of values — consider `ANY(ARRAY[...])` or temp table
+- Unnecessary `ORDER BY` in subqueries
+- Correlated subqueries executing once per outer row
+
+## Recap — non-negotiables
+
+- Measure with `EXPLAIN ANALYZE` before and after; change one layer per cycle.
+- Use `CONCURRENTLY` for every `CREATE INDEX` / `REINDEX` on live tables.
+- Never disable autovacuum; never `VACUUM FULL` during business hours.
+- Test config on staging first, then confirm with monitoring.
+
+Adapted from VKirill/codex-starter-kit (personal skill, MIT).

package/packages/core/skills/project-architecture/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: project-architecture
+description: Project architecture reference — modules, layers, data flow
+tokens: 277
+user-invocable: false
+---
+
+# YOUR_PROJECT Architecture Reference
+
+Auto-loaded template. Fill each section with real project details when you run `/superkit-init`, or by hand. While a section still reads `TODO`, this skill is unconfigured — agents must NEVER report a placeholder as a project fact.
+
+Fill a count by running the example command and pasting the number. Keep example commands as plain inline code; do not prefix a command with a bang before its backtick (that would run it on load).
+
+## Current Scale
+- Services: TODO — count with `ls services/ | wc -l`
+- Migrations: TODO — count with `ls migrations/*.up.sql | wc -l`
+
+## System Overview
+TODO: high-level component map / system diagram.
+
+## Module Map
+TODO: modules or services, and what each one owns.
+
+## Data Flow
+TODO: main request/response paths and background job flows.
+
+## UI Components & Styling
+TODO: component library and styling approach — design tokens, spacing scale, breakpoints, dark-mode support. Read by the visual-reviewer agent. Write "N/A — no frontend" if the project has no UI.
+
+## Key Configuration
+TODO: config files and what each one controls.

package/packages/core/skills/project-scanner/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: project-scanner
+description: Project introspection — detect languages, frameworks, database, structure, scale, auth, CI/CD
+tokens: 1509
+user-invocable: false
+---
+
+# Project Scanner
+
+Static reference for project introspection: file markers, import signals, and bash snippets that identify a repo's languages, frameworks, database, infrastructure, structure, components, and scale. Read the tables and apply them to the project in front of you — this file holds no per-project data.
+
+## Use when
+- You need to identify an unfamiliar project's stack, structure, or scale from its files alone.
+- Building a project summary (languages, frameworks, DB, infra, components, auth, CI/CD) before deeper work.
+
+## Do not use when
+- The project is already described in `CLAUDE.md` / `AGENTS.md` — read that first; only re-detect what it omits.
+- You already know the one fact you need from a file you have read (e.g. framework stated in `package.json`).
+
+## Hard Rules
+1. Detect from files actually present — read or grep the marker; never infer a stack from the project's name.
+2. Report EVERY detected language, not just the first — polyglot repos are common.
+3. Multiple structure matches → choose the most specific (see Tie-breaks) and name the signals that fired.
+4. No marker matches a category → report `UNKNOWN` for it. Never guess a value.
+
+## Scan procedure
+1. Languages — match file markers (Languages table); read each hit's version source. Report all matches.
+2. Frameworks — for each detected language, grep dependencies against the Frameworks table.
+3. Database & infrastructure — check docker-compose, `.env`, and schema files (Database + Infrastructure tables).
+4. Structure — classify the repo against the Structure Patterns table, applying Tie-breaks.
+5. Components — scan top-level and second-level directories (Component Detection table).
+6. Scale — run the Scale Estimation snippets for approximate counts.
+
+Done when: every category above has a concrete value or `UNKNOWN`.
+
+## Detection Patterns
+
+### Languages
+
+| File Marker | Language | Version Source |
+|-------------|----------|---------------|
+| `go.mod` | Go | First line: `go X.Y` |
+| `package.json` + `tsconfig.json` | TypeScript | `package.json` → `typescript` version |
+| `package.json` (no tsconfig) | JavaScript | `package.json` → `engines.node` |
+| `pyproject.toml` | Python | `[project]` → `requires-python` |
+| `requirements.txt` | Python | None (check `python --version`) |
+| `Cargo.toml` | Rust | `[package]` → `edition` |
+| `pom.xml` | Java | `<java.version>` |
+| `build.gradle` / `build.gradle.kts` | Kotlin/Java | `sourceCompatibility` |
+
+### Frameworks
+
+| Language | Detection | Popular Frameworks |
+|----------|-----------|-------------------|
+| Go | `go.mod` requires | chi, gin, echo, fiber, gorilla/mux |
+| TypeScript | `package.json` deps | react, vue, svelte, angular, next, nuxt, express, fastify, nestjs |
+| Python | `pyproject.toml` / `requirements.txt` | fastapi, django, flask, starlette |
+| Rust | `Cargo.toml` deps | actix-web, axum, rocket, warp |
+
+### Database
+
+| Signal | Database | Driver |
+|--------|----------|--------|
+| `postgres` in docker-compose | PostgreSQL | Read go.mod/package.json for driver |
+| `mysql` in docker-compose | MySQL | Read go.mod/package.json for driver |
+| `mongo` in docker-compose | MongoDB | Read go.mod/package.json for driver |
+| `DATABASE_URL` in .env | Parse URL scheme | From URL |
+| `schema.prisma` | From `datasource.provider` | Prisma |
+
+### Infrastructure (cache, storage, auth, CI/CD)
+
+| Category | Signal |
+|----------|--------|
+| Cache | `redis` in docker-compose; imports `go-redis`, `ioredis`, `redis-py` |
+| Storage | `minio` / `s3` in docker-compose; imports `minio-go`, `@aws-sdk/client-s3` |
+| Auth | grep for `jwt`, `session`, `oauth`, `passport`, `auth middleware` |
+| CI/CD | `.github/workflows/`, `Dockerfile`, `docker-compose*.yml`, `.gitlab-ci.yml` |
+
+### Structure Patterns
+
+| Pattern | Classification |
+|---------|---------------|
+| Multiple `go.mod` or `package.json` (not in node_modules) | Monorepo |
+| Single root `go.mod` + `cmd/` | Go standard layout |
+| Single `package.json` + `src/` | Single app |
+| `apps/` or `packages/` with workspace config | Monorepo (workspace) |
+| `services/` with multiple subdirs each with own main | Microservices |
+
+### Component Detection
+
+Scan top-level and second-level directories:
+
+| Directory Pattern | Component Type |
+|-------------------|---------------|
+| `backend/`, `server/`, `api/` | Backend |
+| `frontend/`, `web/`, `client/`, `app/` | Frontend |
+| `admin/`, `adminpanel/`, `dashboard/` | Admin UI |
+| `bot*/`, `tgbot*/` | Bots |
+| `worker*/`, `jobs/`, `queue/` | Background workers |
+| `infra/`, `deploy/`, `terraform/` | Infrastructure |
+| `mobile/`, `ios/`, `android/` | Mobile |
+| `docs/` | Documentation |
+
+### Tie-breaks (ambiguous detection)
+
+- Several languages match → report all; there is no single "primary" language.
+- Repo matches both Monorepo and Microservices → classify as Microservices only when `services/` holds ≥2 subdirs each with its own entrypoint (`main.go` / `package.json` / `main.py`); otherwise Monorepo.
+- Several structure rows match → take the most specific (workspace or microservices over plain monorepo).
+- No marker matches a category → `UNKNOWN`; do not infer a value from directory names alone.
+
+### Scale Estimation
+
+```bash
+# Files by language
+find . -name "*.go" | grep -v vendor | wc -l
+find . \( -name "*.ts" -o -name "*.tsx" \) | grep -v node_modules | wc -l
+
+# Migrations
+find . -path "*/migrations/*" -name "*.up.sql" | wc -l
+
+# API endpoints (approximate) — ERE, works with grep -E and ripgrep
+grep -rE "router\.(Get|Post|Put|Delete|Patch)" --include="*.go" . | wc -l
+grep -rE "app\.(get|post|put|delete|patch)" --include="*.ts" . | wc -l
+
+# LOC estimate
+find . \( -name "*.go" -o -name "*.ts" -o -name "*.py" \) | grep -v vendor | grep -v node_modules | xargs wc -l 2>/dev/null | tail -1
+```
+
+## Recap — non-negotiables
+- Detect from real files; report every language; never infer a stack from the project name.
+- Ambiguous structure → most specific match, and state which signals fired.
+- No marker for a category → `UNKNOWN`, never a guess.