@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/marketing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: marketing
-description: "Use when writing the WORDS for a landing page, marketing site, or launch — value proposition, hero/headline, section-by-section landing copy, microcopy, CTAs, email and launch sequences, channel-adapted messaging (X/LinkedIn/newsletter), SEO-aware copy structure, and SEO/GEO optimization (technical SEO, JSON-LD schema, and getting cited by AI engines like ChatGPT/Perplexity/Gemini/Claude). Grounds every output in the project's brand study under 02-DOCS; if that study is missing or incomplete, it STOPS and interviews the user first. Triggers: 'write the landing copy', 'write the hero', 'value proposition', 'rewrite this CTA', 'write the launch emails', 'turn features into benefits', 'adapt this for LinkedIn/X', 'this copy sounds like AI', 'marketing copy', 'seo', 'geo', 'ai search', 'schema', 'json-ld', 'get cited by ChatGPT', 'rank on Google', 'keyword research', 'meta description', 'AI Overview'. NOT the pixels (that's `design`) and NOT the build (that's `nextjs`)."
+description: "Use when the words span a marketing surface — value proposition, section copy, microcopy, launch and email sequences, channel adaptation, SEO-aware structure — grounded in the brand study, which it stops and builds if missing. NOT one conversion page (that is `landing-copy`), NOT tone rules (that is `brand-voice`), NOT pixels (that is `design`)."
 tags: [marketing, copywriting, landing, content]
 recommends: [presentations, design]
 origin: risco
@@ -10,26 +10,7 @@ origin: risco
 
 *The words, not the pixels. Ground in the brand study first, then write copy that is specific, benefit-led, and unmistakably this brand.*
 
-This skill owns **conversion copywriting**: value proposition, headlines, section-by-section landing copy, microcopy, CTAs, email/launch sequences, channel adaptation, and SEO-aware copy structure. The sibling `design` skill owns the visual/UX (type, color, layout, motion); `nextjs` owns the build. When asked for "a landing page", you write the copy; defer composition and tokens to `design` and rendering to `nextjs`.
-
-## When to use / When NOT to use
-
-Use when:
-
-- Writing or rewriting a landing page, marketing site, or pricing page — the copy.
-- Crafting a value proposition or positioning statement.
-- Writing headlines, subheads, section copy, microcopy, or CTAs.
-- Building an email sequence, launch announcement, or nurture flow.
-- Adapting one message across channels (X, LinkedIn, newsletter, ads).
-- Rescuing copy that "sounds like AI" or reads generic.
-
-Do NOT use when (delegate or decline):
-
-- Choosing type/color/spacing/layout/motion, or the section visual anatomy → `design`.
-- Implementing the page in React/Next.js (Metadata API, rendering, components) → `nextjs`.
-- Implementing schema/Metadata in React/Next.js code → `nextjs` (this skill specifies the title/description/JSON-LD; `nextjs` renders it). Technical SEO, GEO, schema, and keyword research themselves are owned here → `references/seo-geo.md`.
-- Capturing or persisting a project's brand/voice profile → that is THIS skill's brand-grounding step, persisted under `02-DOCS` per `harness`.
-- Long-form articles, blog posts, or social content systems with no landing/web surface → that is a content job, not landing copy; this skill stays on landings, web pages, and the launch/email/channel copy around them.
+This skill owns **conversion copywriting**: value proposition, headlines, section-by-section landing copy, microcopy, CTAs, email/launch sequences, channel adaptation, and SEO-aware copy structure. The sibling `design` skill owns the visual/UX (type, color, layout, motion); `nextjs` owns the build — including rendering in React the Metadata and JSON-LD this skill specifies. Long-form articles, blog posts, or social content systems with no landing/web surface are a content job, not landing copy. When asked for "a landing page", you write the copy.
 
 ## Brand grounding (read this first)
 
@@ -42,30 +23,15 @@ Run this gate before writing a single line of copy:
 2. **Check completeness** against the checklist in `references/brand-grounding.md`. The study is complete only when every dimension is filled: brand name & one-line positioning; ICP / audience & their pains & desires; value proposition & differentiation; tone & voice WITH do/don't word lists and 3–5 voice samples pasted from the user's real writing; proof/credibility; offers & primary CTA; channels; SEO keywords. **Any empty dimension = INCOMPLETE.**
 
 3. **If ABSENT or INCOMPLETE, STOP and interview the user.** Ask the targeted questions from `references/brand-grounding.md`, **one focused batch at a time** (do not dump all questions at once; ask, wait, then continue). Voice samples are mandatory — request 3–5 pieces of the user's real writing; never fabricate a voice. Then:
-   - **a.** Write/update the brand study into `02-DOCS/wiki/brand/` as wiki articles (one article per dimension or a single `index.md` plus per-dimension articles), following the wiki article format in `references/brand-grounding.md`. Save any raw text the user pastes verbatim into `02-DOCS/raw/brand/` and link to it from the article's `> Raw:` line. Create the directories if they do not exist.
-   - **b.** Add or update a `## Brand & voice` section in the root `CLAUDE.md` linking to the brand study. Create `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet to insert is in `references/brand-grounding.md`.
+   - **a.** Write/update the brand study into `02-DOCS/wiki/brand/` as wiki articles (one article per dimension or a single `index.md` plus per-dimension articles), following the wiki article format in `references/brand-grounding.md`, and index it in `02-DOCS/wiki/index.md` (the Knowledge map). Save any raw text the user pastes verbatim into `02-DOCS/raw/brand/` and link to it from the article's `> Raw:` line. Create the directories if they do not exist.
+   - **b.** Add or update a `## Brand & voice` section in the root `CLAUDE.md` linking to the brand study — a short pointer only. Create `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet to insert is in `references/brand-grounding.md`.
 
-4. **Only once the study exists and is complete, proceed.** Cite which brand articles you used (e.g. "grounded in `02-DOCS/wiki/brand/value-proposition.md` and `voice.md`") so the user can trace every claim back to the study.
+4. **Only once the study exists and is complete, proceed.** Cite which brand articles you used (e.g. "grounded in `02-DOCS/wiki/brand/value-proposition.md` and `voice.md`") so the user can trace every claim back to the study. Every line you then write must plausibly come from the brand's own writing; if it reads like a different author, rewrite.
 
 If the user explicitly says "skip the brand study, just draft something rough", you may produce a clearly-labelled `DRAFT (ungrounded — not brand-checked)` and still recommend running the gate before anything ships. That is the only exception, and it must be labelled.
 
 Full completeness checklist, the exact question script (batched), and the persistence format → `references/brand-grounding.md`.
 
-## The non-negotiables
-
-These are constraints, not preferences. Violating any one is a defect.
-
-1. **Brand study first.** No copy before the grounding gate passes (above). Cite the articles you used.
-2. **5-second value-prop test.** A stranger reads the hero and can say *what it is, who it's for, why it's better* — within 5 seconds. If not, rewrite before anything else.
-3. **Specificity beats adjectives.** Replace "fast", "powerful", "seamless" with a number, a mechanism, or a receipt. "Fast" is a claim; "30 seconds" is evidence.
-4. **Benefit-led, climbing feature → benefit → proof.** Stop at the rung the reader cares about (the benefit) and back it with proof.
-5. **One primary CTA per viewport**, value on the button ("Start free", not "Submit"). Pair it with friction-reducing microcopy ("No credit card required").
-6. **One claim per asset.** A post, an email, a section each carry one real claim — not five hedged ones.
-7. **Match the voice samples.** Every line must plausibly come from the brand's own writing. If it reads like a different author, rewrite.
-8. **The ban-list is enforced everywhere.** Hype words and AI tells are defects, not style. (See ban-list below; `scripts/verify.sh` greps for them.)
-9. **No invented proof.** Never fabricate metrics, customers, quotes, or credentials. Mark `[[NEEDS PROOF]]` and ask.
-10. **SEO-aware structure, not keyword stuffing.** One `<h1>`, scannable subheads that answer queries, benefit in the first 160 chars. Keyword stuffing *lowers* AI citation — full technical SEO/GEO is in `references/seo-geo.md`.
-
 ## Copy workflow (the one pass)
 
 Run in order. Each step feeds the next; skipping one shows up as vague copy downstream.
@@ -74,13 +40,13 @@ Run in order. Each step feeds the next; skipping one shows up as vague copy down
 2. **Lock the value proposition.** Fill the value-proposition canvas (jobs / pains / gains → pain-relievers / gain-creators → headline). → `references/copy-frameworks.md`.
 3. **Pick the framework** by traffic temperature and funnel position: PAS for pain-aware cold traffic; AIDA for broad top-of-funnel; FAB/JTBD for feature → benefit; BAB for transformation/case-study. → `references/copy-frameworks.md`.
 4. **Write section by section.** Each landing section has one job and one framework. Map your copy to the design skill's section anatomy. → `references/landing-copy.md`.
-5. **Write the microcopy and CTAs.** Value verbs on buttons, reassurance under them, human empty/loading/error states. → `references/copy-frameworks.md`.
+5. **Write the microcopy and CTAs.** One primary CTA per viewport — choice kills conversion — with a value verb on the button ("Start free", not "Submit"), reassurance under it ("No credit card required"), and human empty/loading/error states. → `references/copy-frameworks.md`.
 6. **Adapt for channels** if the task spans more than the page (email sequence, launch, X/LinkedIn/newsletter). → `references/campaigns-and-channels.md`.
 7. **Run the QA gate** (below) and `scripts/verify.sh`. Fix every flag or justify it.
 
 ## Headlines & value proposition in 60 seconds
 
-The headline is the highest-leverage copy on the page. Build it from the canvas, not from a thesaurus.
+The headline is the highest-leverage copy on the page. Build it from the canvas, not from a thesaurus. It has one test: a stranger reads the hero and can say *what it is, who it's for, why it's better* — within 5 seconds. If it fails, rewrite it before anything else on the page.
 
 ```text
 VALUE-PROP CANVAS (fill before writing the headline)
@@ -98,7 +64,7 @@ Headline formula slots (pick one, fill with brand specifics):
 - **Outcome + timeframe** — "Preview every branch in 30 seconds".
 - **X without Y** — "Live previews without a staging queue".
 - **JTBD** — "When you open a PR, get a live URL automatically".
-- **Specificity** — replace an adjective with a number: "Cut review setup from 20 min to 30 sec".
+- **Specificity** — replace an adjective with a number. "Fast" is a claim; "30 seconds" is evidence: "Cut review setup from 20 min to 30 sec".
 
 ```text
 Bad  — "Revolutionize your workflow with our seamless, cutting-edge platform"
@@ -109,7 +75,7 @@ Full canvas walk-through, PAS/AIDA/FAB/BAB/JTBD with Bad→Good rewrites, headli
 
 ## Landing copy by section
 
-Each section earns its place by doing one job. Cut any section with no job. This maps 1:1 to the `design` skill's section anatomy — `design` owns the visual treatment, this skill owns the words inside it.
+Each section earns its place by doing one job. Cut any section with no job. This maps 1:1 to the `design` skill's section anatomy — `design` owns the visual treatment, this skill owns the words inside it. Within every section, climb feature → benefit → proof, stop at the rung the reader cares about (the benefit), and back it with proof.
 
 | Section | Copy job | Framework |
 | --- | --- | --- |
@@ -133,21 +99,20 @@ Full per-section copy patterns, hero variants, social-proof formats, pricing cop
 
 ## Campaigns & channels
 
-When the task is bigger than the page — a launch, an email sequence, cross-channel messaging.
+When the task is bigger than the page — a launch, an email sequence, cross-channel messaging. One claim per asset: a post, an email, a section each carry one real claim, not five hedged ones.
 
 - **Email sequences:** welcome email inside 5 minutes of opt-in (highest open rate of the whole flow); 4-touch starter cadence Day 1 welcome → Day 4 educational → Day 8 case study → Day 12 soft pitch; nurture runs 7–10 emails every 1–2 weeks. One purpose per email. Hold promo language ("free", "limited time") out of early emails to protect deliverability and trust.
 - **Launch:** sequence the beats (tease → reveal → proof → urgency → recap), one claim per beat, every claim traceable to the brand study's proof.
 - **Channel adaptation:** adapt the *format* to the platform, never resize the same copy. X opens with the sharpest claim; LinkedIn expands just enough for outsiders; newsletter does real work in the first screen.
-- **SEO-aware structure:** one `<h1>`, scannable subheads as query answers, benefit in the first 160 chars; full technical SEO/GEO in `references/seo-geo.md`.
 
 Full email templates, subject-line patterns, launch arc, X/LinkedIn/newsletter adaptation, SEO-aware structure → `references/campaigns-and-channels.md`.
 
 ## SEO & GEO
 
-The skill body keeps copy *SEO-aware* (one `<h1>`, query-answering subheads, benefit in the first
-160 chars). When the task is the visibility layer itself — ranking on Google/Bing **and getting
-cited by AI engines** — go to `references/seo-geo.md`. It owns technical + on-page SEO, JSON-LD
-schema, per-engine GEO, and keyword/SERP research.
+Keep copy *SEO-aware* by default: one `<h1>`, scannable subheads that answer queries, benefit in the
+first 160 chars. Keyword stuffing *lowers* AI citation. When the task is the visibility layer itself
+— ranking on Google/Bing **and getting cited by AI engines** — go to `references/seo-geo.md`. It owns
+technical + on-page SEO, JSON-LD schema, per-engine GEO, and keyword/SERP research.
 
 - **SEO** = rank in traditional results (**Google, Bing**). **GEO** (Generative Engine
   Optimization) = get *cited* inside an AI answer (**ChatGPT, Perplexity, Gemini/AI Overviews,
@@ -157,9 +122,9 @@ schema, per-engine GEO, and keyword/SERP research.
   attributed*, not clicked.
 - **GEO and this skill agree.** The top GEO moves (Princeton, KDD 2024) are *cite sources, add
   statistics, add quotations, authoritative tone* — the same "specificity beats adjectives, no
-  invented proof, one claim per asset" discipline already enforced above. Keyword stuffing *lowers*
-  AI citation (~−10%). The proof rule is absolute: **never fabricate the stat or quote that earns
-  the lift** — mark `[[NEEDS PROOF]]` and source it.
+  invented proof, one claim per asset" discipline this skill enforces everywhere else. Keyword
+  stuffing lowers AI citation (~−10%). The proof rule is absolute: **never fabricate the stat or
+  quote that earns the lift** — mark `[[NEEDS PROOF]]` and source it.
 - **Audit first, free, no API:** `python3 scripts/seo_audit.py "https://yoursite.com"` reports
   title/description lengths, single-`<h1>`, JSON-LD count, load time, robots/AI-bot access, sitemap.
 - **Crawler reality (2026):** `OAI-SearchBot`/`Claude-SearchBot`/`PerplexityBot` (+ the `*-User`
@@ -171,7 +136,7 @@ and SEO/GEO QA gate → `references/seo-geo.md`. Implementing schema/Metadata in
 
 ## The ban-list
 
-State once, enforce everywhere. These signal AI-template copy and erode trust. `scripts/verify.sh` greps for them.
+State once, enforce everywhere. These are defects, not style: they signal AI-template copy and erode trust. `scripts/verify.sh` greps for them.
 
 `revolutionary` · `game-changer` · `cutting-edge` · `world-class` · `unlock` · `seamless` · `elevate` · `supercharge` · `next-level` · "In today's landscape" · "In today's fast-paced world" · bait questions ("Tired of slow deploys?") · "not X, just Y" / "not just X" · forced lowercase as a style · "Excited to share" · hollow proof ("thousands trust us") · generic CTAs ("Learn more", "Click here", "Submit") · fake urgency with no real deadline.
 
@@ -182,19 +147,19 @@ Good — "We rebuilt deploys around one CLI step. Here's what changed: 22 min
 
 The brand study's do/don't word lists EXTEND this list per project — always apply both.
 
-## Anti-patterns / rationalizations → STOP
+## Anti-patterns
 
-| Rationalization | Reality / Fix |
+| Anti-pattern | Why it fails / the fix |
 | --- | --- |
-| "I know the brand, I'll skip the study" | Your default voice is AI-median. Run the gate; cite the articles. |
-| "The image sells it, the copy can be vague" | Copy carries the value prop. Pass the 5s test in words. |
-| "Adjectives make it sound premium" | They make it sound generic. Replace with a number or mechanism. |
-| "List every feature so they see the value" | Feature dumps bury the benefit. Climb to benefit, back with proof. |
-| "Add a few testimonials, any will do" | A vague rave < one hard number. Quantify and attribute. |
-| "Five CTAs give them options" | Choice kills conversion. One primary action per viewport. |
-| "Hype words test well" | They erode trust and trip the ban-list. Specificity converts. |
-| "I'll invent a plausible metric to fill the gap" | Never. Mark `[[NEEDS PROOF]]` and ask the user. |
-| "Same copy works on X and LinkedIn" | Resize ≠ adapt. Different format per platform, same claim. |
+| Skipping the brand study because "I know the brand" | Your default voice is AI-median. Run the gate; cite the articles. |
+| Leaning on the image and letting the copy stay vague | Copy carries the value prop. Pass the 5s test in words. |
+| Reaching for adjectives to sound premium | They make it sound generic. Replace with a number or mechanism. |
+| Listing every feature "so they see the value" | Feature dumps bury the benefit. Climb to benefit, back with proof. |
+| Dropping in any testimonial to fill the proof slot | A vague rave < one hard number. Quantify and attribute. |
+| Five CTAs "to give them options" | Choice kills conversion. One primary action per viewport. |
+| Hype words because "they test well" | They erode trust and trip the ban-list. Specificity converts. |
+| Inventing a plausible metric to fill a gap | Never. Mark `[[NEEDS PROOF]]` and ask the user. |
+| Reusing the same copy on X and LinkedIn | Resize ≠ adapt. Different format per platform, same claim. |
 
 ## Copy QA gate
 
@@ -206,6 +171,7 @@ Run before claiming done. `scripts/verify.sh` automates the greppable subset.
 - [ ] Every claim is specific (number / mechanism / receipt), not an adjective.
 - [ ] Copy climbs feature → benefit → proof; lands on the benefit.
 - [ ] One primary CTA per viewport; value on the button; reassurance microcopy present.
+- [ ] One claim per asset — no post, email, or section carrying five hedged ones.
 - [ ] No invented proof; every gap marked `[[NEEDS PROOF]]`.
 - [ ] Voice matches the brand study's samples and do/don't lists.
 - [ ] Ban-list words absent (global list + brand don't-words).
@@ -215,19 +181,3 @@ Run before claiming done. `scripts/verify.sh` automates the greppable subset.
 - [ ] Title 50–60 chars, meta description 120–160, benefit in the first 160 chars.
 
 Automate → `scripts/verify.sh` (read-only grep gate; warns by default, `--strict` to gate CI).
-
-## Project grounding (02-DOCS + CLAUDE.md)
-
-This skill's 02-DOCS record is the **brand & voice study** at `02-DOCS/wiki/brand/` — a hard
-gate (see "Brand grounding" above): if the root `CLAUDE.md` lacks the link or the study is
-incomplete (no voice samples, positioning, do/don't lists), ask until complete, persist it, and
-index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short
-pointer to it). Read it first on every use and ground all copy in it. Site and visual conventions
-belong to the sibling `design` and `nextjs` articles in the same Knowledge map index.
-
-## See Also
-
-- `../design/SKILL.md` — the pixels: visual system, layout, section anatomy, motion, design QA.
-- `../nextjs/SKILL.md` — the build: App Router, Metadata API, React 19 rendering.
-- `../harness/SKILL.md` — the `02-DOCS` Karpathy-wiki convention this skill persists the brand study into.
-- References: `references/brand-grounding.md`, `references/copy-frameworks.md`, `references/landing-copy.md`, `references/campaigns-and-channels.md`, `references/seo-geo.md` (technical SEO + GEO + schema + keyword research).

package/skills/nextjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nextjs
-description: "Use when building, reviewing, testing, securing, or optimizing a Next.js App Router app (Next.js 15/16, React Server Components, \"use client\"/\"use server\", server actions, route handlers, layouts, streaming/Suspense, the App Router caching model, TypeScript, Auth.js, Vitest/Playwright, CSP/security headers). Triggers on `app/` directory work, `next.config.ts`, `proxy.ts`/`middleware.ts`, server actions, route handlers, `use cache`, `useActionState`, RSC boundary questions, hydration errors, and Next.js perf/Core Web Vitals."
+description: "Use when building, reviewing, testing, securing, or optimizing a Next.js App Router app: Server vs Client boundaries, `use server` actions, route handlers, the v15 vs v16 `use cache` caching model, metadata/SEO, auth, and Core Web Vitals. NOT framework-agnostic React or a Vite SPA (that is `react`), and NOT visual/UI design (that is `design`)."
 tags: [nextjs, react, frontend, web, seo, ssr]
 recommends: [design, secure-coding, deployment]
 origin: risco
@@ -8,28 +8,19 @@ origin: risco
 
 # Next.js App Router — RSC, Server Actions, React 19, TypeScript
 
-> Build, review, test, secure, and optimize Next.js App Router apps with correct handling of
-> both the Next.js 15 (uncached-by-default) and Next.js 16 (`use cache`) caching models.
+> Build, review, test, secure and optimize App Router apps, handling both the Next.js 15 (uncached-by-default) and Next.js 16 (`use cache`) caching models correctly.
 
-## When to use / When NOT to use
+> **SDD gate — read before writing code.** If this fired on a **new, non-trivial feature or
+> behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP and
+> hand off to `../specify/SKILL.md` (brainstorm → spec → plan → tasks); it routes back here once the
+> plan is approved. Build directly only for a genuinely one-line / low-risk change. Method:
+> `../sdd/SKILL.md`.
 
-> **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
-
-**Use when:**
-
-- Editing or creating files under `app/` (pages, layouts, `route.ts`, server actions).
-- Deciding Server vs Client Component, or fixing an RSC boundary / hydration mismatch.
-- Writing server actions or route handlers; wiring `useActionState` + zod forms.
-- Configuring caching/revalidation (either model), auth, middleware/`proxy.ts`, or CSP.
-- Diagnosing waterfalls, bundle bloat, or Core Web Vitals regressions.
-- Writing Vitest/Playwright tests for Next.js code.
-
-**Do NOT use when (redirect target each):**
-
-- Pages Router (`pages/`) work → note the difference, defer to the Next.js Pages docs.
-- Pure React SPA (Vite/CRA) or React Native / Expo → use a generic React skill; out of scope here.
-- Non-Next backend (FastAPI/Go) → see `../fastapi/SKILL.md`, `../go/SKILL.md`.
-- Generic React-shape questions with no Next/RSC dimension → keep brief, point to `references/react.md`.
+**Not this skill:** Pages Router (`pages/`) — note the difference, defer to the Next.js Pages docs.
+A pure React SPA (Vite/CRA) → `../react/SKILL.md`; React Native / Expo → `../react-native/SKILL.md`;
+a generic React question with no Next/RSC dimension → keep it brief, from `references/react.md`.
+Non-Next backends → `../fastapi/SKILL.md`, `../go/SKILL.md`; the data layer behind the DAL →
+`../postgresdb/SKILL.md`; framework-agnostic security → `../secure-coding/SKILL.md`, complemented here, never duplicated.
 
 ## First: detect the project's version & caching model
 
@@ -120,17 +111,15 @@ export async function renameProject(_prev: RenameResult | null, formData: FormDa
 }
 ```
 
-Two invocation modes:
-
-- `<form action={renameProject}>` — progressive enhancement, works without JS.
-- Imperative from a client handler wrapped in `startTransition(() => renameProject(null, fd))`.
-
-Deep dives: `references/security.md` (auth/CSRF) and `references/data-and-caching.md` (mutations).
+Two invocation modes: `<form action={renameProject}>` — progressive enhancement, works without JS —
+or imperative from a client handler wrapped in `startTransition(() => renameProject(null, fd))`.
 
 ## Route Handlers (`route.ts`)
 
 Use a Route Handler for: webhooks, a public JSON API, OAuth callbacks, streaming responses, and
-non-form clients. Use a **Server Action instead** for internal form mutations.
+non-form clients. Use a **Server Action instead** for internal form mutations. GET handlers are
+uncached by default on v15 (control with `export const dynamic` / `runtime`), and every handler —
+GET included — runs its own `auth()` check and scopes reads to the session user.
 
 ```ts
 // app/api/projects/route.ts
@@ -139,14 +128,6 @@ import { z } from "zod";
 import { auth } from "@/auth";
 import { db } from "@/lib/db";
 
-// GET handlers are uncached by default on v15. Control with: export const dynamic / runtime.
-export async function GET(_req: NextRequest) {
-  const session = await auth();
-  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-  const projects = await db.project.findMany({ where: { ownerId: session.user.id } });
-  return NextResponse.json({ projects });
-}
-
 const CreateSchema = z.object({ name: z.string().min(1).max(120) });
 
 export async function POST(req: NextRequest) {
@@ -170,19 +151,8 @@ export async function POST(req: NextRequest) {
 | `not-found.tsx`    | Rendered by `notFound()` and unmatched routes                 |
 | `global-error.tsx` | Replaces the root layout when the root throws                 |
 
-```tsx
-// app/projects/error.tsx — Good: error boundaries are Client Components
-"use client";
-export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
-  return (
-    <div role="alert">
-      <h2>Could not load projects</h2>
-      <p>{error.message}</p>
-      <button onClick={() => reset()}>Try again</button>
-    </div>
-  );
-}
-```
+An `error.tsx` is always `"use client"`, receives `{ error: Error & { digest?: string }, reset }`,
+and should render `role="alert"` plus a button calling `reset()`.
 
 ```tsx
 // app/dashboard/page.tsx — Good: stream the shell, Suspense the slow part
@@ -203,11 +173,10 @@ export default function Page() {
 
 ## Routing: groups, parallel, intercepting, dynamic, metadata
 
-- Route groups `(marketing)/` — organize without affecting the URL.
-- Dynamic `[id]`, catch-all `[...slug]`, optional `[[...slug]]`.
+- Route groups `(marketing)/` organize without affecting the URL; dynamic `[id]`, catch-all
+  `[...slug]`, optional `[[...slug]]`.
 - **`params` and `searchParams` are Promises on v15+ — `await` them.**
-- Parallel routes `@modal` + `default.tsx`.
-- Intercepting `(.)photo` — modal-on-navigation.
+- Parallel routes `@modal` + `default.tsx`; intercepting `(.)photo` — modal-on-navigation.
 - `generateMetadata` (async) + `generateStaticParams`.
 
 ```tsx
@@ -225,8 +194,9 @@ async function PageGood({ params }: { params: Promise<{ id: string }> }) {
 ## Metadata & SEO
 
 The App Router emits `<title>`, `<meta>`, OpenGraph/Twitter tags, `sitemap.xml`, and `robots.txt`
-from code (identical API on v15/v16). Build-side patterns → `references/metadata.md`; the
-strategy/content side — JSON-LD, GEO, keyword research → `../marketing/references/seo-geo.md`.
+from code (identical API on v15/v16). Build-side patterns → `references/metadata.md`; the strategy
+side — JSON-LD, GEO, keyword research — is `../marketing/SKILL.md`'s
+(`../marketing/references/seo-geo.md`): this skill emits the tags, that one picks the content.
 
 - `metadata`/`generateMetadata` are **Server-Component-only** — one or the other per file (static
   object when known at build; async `generateMetadata` when it depends on `params`/data, wrapped in
@@ -261,8 +231,8 @@ export async function generateMetadata({ params }: { params: Promise<{ slug: str
 
 ## Caching & data fetching (both models)
 
-Which block applies is decided by the detection gate above. Deep dive →
-`references/data-and-caching.md`.
+Which block applies is decided by the detection gate above. Optimistic UI, `useActionState` + zod
+forms and the full mutation patterns are in `references/data-and-caching.md`.
 
 **v15 model** — `fetch` is uncached by default; opt in explicitly.
 
@@ -275,7 +245,7 @@ const products = await fetch("https://api.example.com/products", {
   next: { revalidate: 3600, tags: ["products"] },
 }).then((r) => r.json());
 
-// from a Server Action: invalidate the tag
+// from a Server Action: invalidate the tag (or a route with revalidatePath)
 import { revalidateTag } from "next/cache";
 revalidateTag("products");
 
@@ -319,9 +289,6 @@ export async function getCart(cartId: string) {
 }
 ```
 
-For optimistic UI, `useActionState` + zod forms, and full mutation patterns →
-`references/data-and-caching.md`.
-
 ## React 19 in the App Router (essentials)
 
 The Next-relevant deltas (full discipline, hooks, state-location tree, composition →
@@ -380,9 +347,10 @@ on every review:
 - Secure cookies: `httpOnly`, `secure`, `sameSite: "lax"`; rotate the session on any privilege change.
 - CSRF: Server Actions verify `Origin`/`Host`; never expose a mutation as an unauthenticated GET;
   set `serverActions.allowedOrigins` in `next.config.ts`.
-- **Never put secrets in `NEXT_PUBLIC_*`** — they ship to the browser; proxy via a Route Handler.
+- **Never put secrets in `NEXT_PUBLIC_*`** — they ship to the browser; proxy via a Route Handler and
+  mark server-only modules with `import 'server-only'`.
 - SSRF: allowlist host/scheme before `fetch` in Route Handlers; block internal/metadata ranges.
-- CSP with a nonce via `proxy.ts`/headers. See also `secure-coding`.
+- CSP with a nonce via `proxy.ts`/headers. See also `../secure-coding/SKILL.md`.
 
 ## Performance (deep dive → references/performance.md)
 
@@ -393,9 +361,9 @@ on every review:
 - Long lists: `content-visibility: auto` + virtualize (`@tanstack/react-virtual`) past ~50 rows; warm assets with `react-dom` `preload`/`preconnect`; narrow store selectors (Zustand) cut re-renders. Full lever→metric map in `references/performance.md`.
 - Core Web Vitals targets: **LCP < 2.5s, CLS < 0.1, INP < 200ms** (INP replaced FID).
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization                                            | Reality / STOP                                                             |
+| Common belief                                               | Reality / STOP                                                             |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------- |
 | "The client already checks the user, the action is safe"   | Server Actions are public POST endpoints — authenticate inside the action  |
 | "`fetch` caches by default, skip `revalidate`"             | v15: `fetch` is uncached by default; that's the v13/14 mental model        |
@@ -408,27 +376,6 @@ on every review:
 | "Middleware protects my dashboard, the data fetch is safe" | Middleware is not a security boundary; check in the DAL                    |
 | "Snapshot-test the RSC page"                               | Async Server Components aren't jsdom-renderable; test data fns + Playwright |
 
-## Quick reference
-
-| Task                      | API / file                                       | Note                           |
-| ------------------------- | ------------------------------------------------ | ------------------------------ |
-| New mutation              | Server Action (`"use server"`)                   | auth + zod inside              |
-| Public JSON / webhook     | Route Handler (`route.ts`)                       | uncached GET on v15            |
-| Per-request dedupe        | `React.cache(fn)`                                | one query per render           |
-| Cache cross-request (v15) | `fetch tags` / `unstable_cache`                  | opt-in                         |
-| Cache (v16)               | `"use cache"` + `cacheTag`                       | opt-in, `cacheLife()`          |
-| Invalidate                | `revalidateTag` / `updateTag` / `revalidatePath` | from an action                 |
-| Loading UI                | `loading.tsx` / `<Suspense>`                     | stream the shell               |
-| Error UI                  | `error.tsx`                                      | `"use client"`, gets `reset()` |
-| Form                      | `useActionState` + zod                           | `isPending`, `role="alert"`    |
-| Optimistic UI             | `useOptimistic`                                  | auto-revert on error           |
-| Client island             | `"use client"` leaf                              | keep small, push down          |
-| Secrets                   | server-only env (`import 'server-only'`)         | never `NEXT_PUBLIC_*`          |
-| Image                     | `next/image` + `priority`                        | LCP image                      |
-| Page metadata             | `generateMetadata` / static `metadata`           | server-only; set `metadataBase`|
-| Sitemap / robots          | `app/sitemap.ts` / `app/robots.ts`               | `MetadataRoute.*`              |
-| Protect route             | middleware redirect + DAL `auth()`               | DAL is the real boundary       |
-
 ## Verify
 
 Run `bash scripts/verify.sh` from the Next.js project root. It runs ESLint, `tsc --noEmit`,
@@ -438,37 +385,16 @@ a failure). It reads the installed Next.js major version and only falls back to
 never a false failure. The lint/type/test steps are read-only; the final `next build` writes the
 `.next/` output directory. No installs, no network mutations. Safe to re-run.
 
-## References
-
-- `references/react.md` — React 19 discipline for the App Router (hooks, boundaries, forms, state).
-- `references/data-and-caching.md` — both caching models, mutations, end-to-end zod forms.
-- `references/metadata.md` — `generateMetadata`, `sitemap.ts`, `robots.ts`, OpenGraph + `next/og`.
-- `references/testing.md` — Vitest 3 + RTL + MSW 2 + Playwright; RSC testing reality.
-- `references/performance.md` — Core Web Vitals, images, fonts, bundles, streaming.
-- `references/security.md` — auth, CSRF, XSS, CSP, env leakage, SSRF.
+Test strategy — Vitest 3 + RTL + MSW 2 for units, Playwright for pages, and the RSC testing reality
+behind that last anti-pattern row: `references/testing.md`.
 
 ## Project grounding (02-DOCS + CLAUDE.md)
 
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's app decisions there and index them from the root `CLAUDE.md`, so the next
-agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/nextjs.md`, indexed in `02-DOCS/wiki/index.md` (the
-   Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — the caching model in use (v15 fetch-cache vs v16 `use cache`), the auth approach, server-action and data-fetching conventions, runtime choices (edge/node), and the design-system hookup —
-   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a
-   short pointer to it).
-3. **Read it first on every use** and stay consistent; when a convention changes, update the
-   article (bump its `Updated` date) in the same change.
-
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
+In a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), this
+project's app decisions live in `02-DOCS/wiki/stack/nextjs.md`, indexed from `02-DOCS/wiki/index.md`
+(the Knowledge map; root `CLAUDE.md` keeps only a pointer). Read it first on every use and stay
+consistent. Missing or stale → write the project's real choices there — caching model in use (v15
+fetch-cache vs v16 `use cache`), auth approach, server-action and data-fetching conventions, runtime
+(edge/node), design-system hookup — index it, and bump its `Updated` date in the same change as any
+convention change. No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
 brand study, technical conventions are *recorded, not gated* — never block the task on this.
-
-## See Also
-
-- `../secure-coding/SKILL.md` — generic security; this skill complements, does not duplicate it.
-- `../fastapi/SKILL.md` and `../go/SKILL.md` — the backend APIs the frontend calls.
-- `../postgresdb/SKILL.md` — the data layer behind the DAL.
-- `../marketing/SKILL.md` — SEO/GEO strategy, JSON-LD, AI-engine citation (`../marketing/references/seo-geo.md`); this skill emits the tags, that one decides the content.
-- `../harness/SKILL.md` — workspace conventions.

package/skills/orient/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orient
-description: "Always-on. The brújula: after every action keep the human oriented — situate them on the project map, say what just happened, teach the why at their level, and propose the next step as a question. NEVER end a turn in seco (dead-end). Reads technical_level + accompaniment_level from 02-DOCS/wiki/harness/user-profile.md and calibrates how much it explains; rewrites the dial when the user asks for more/less ('explícame más', 'explícame menos', 'no me expliques tanto', 'enséñame'). Complements suggest (which installs missing skills) — orient guides the person, not the toolbox. Fires on every turn that finishes an action, reaches a decision fork, or leaves the user unsure what to do next."
+description: "Always-on. The brújula: close every turn by situating the person — where they are, what just happened, why it mattered, and the next step as a question, never a dead end. Reads the accompaniment and technical dials from 02-DOCS and calibrates how much it explains, rewriting the dial when the user asks for more or less. NOT the missing-skill installer (that is `suggest`)."
 tags: [orient, guide, compass, dial, meta, always-on]
 recommends: []
 profiles: [minimal, core, full]
@@ -9,49 +9,54 @@ origin: risco
 
 # orient — the brújula that never leaves the user lost
 
-You are always loaded. Your one job: **after anything happens, keep the human oriented.** A tool executes and falls silent; a mentor walks alongside. You make the harness a mentor.
+You are always loaded. Your one job: **after anything happens, keep the human oriented.** A tool
+executes and falls silent; a mentor walks alongside. You are what makes the harness a mentor.
 
-`suggest` keeps the *session* equipped ("you're missing a skill, install it?"). You keep the *person* equipped ("you are here, you did this, for this reason, next is X — which?"). Never duplicate `suggest`'s install prompt; that is its job.
+`suggest` keeps the *session* equipped ("you're missing a skill, install it?"). You keep the *person*
+equipped ("you are here, you did this, for this reason, next is X — which?"). The install prompt is
+its job, never yours.
 
 ## The one rule
 
-**No turn ends in seco.** Every turn that finishes an action, reaches a fork, or could leave the user unsure closes with the brújula block, calibrated to the dial.
+**No turn ends in seco.** Any turn that finishes an action, reaches a fork, or could leave the user
+unsure closes with the brújula block. One block, at the end — never interrupt mid-work to orient.
 
 ## The brújula block
 
-Close the turn with these four intents (the wording adapts; the intents are fixed):
+Four intents. The wording adapts to the person; the intents do not.
 
-```
+```text
 📍 Dónde estás — the project phase/state (the map)
 ✅ Qué acabas de hacer — one line, in the user's language
 🧭 Por qué — the technical why, scaled to the dial
-➡️ Siguiente — 1-3 concrete options, ending in a question. Never in seco.
+➡️ Siguiente — 1-3 concrete options, ending in a question
 ```
 
+Situate them from what is **actually** built. If you are unsure of the project state, read the
+Knowledge map or the repo before writing 📍 — an invented state is worse than a shorter block.
+
 ## Calibrate to the dial
 
-Read `02-DOCS/wiki/harness/user-profile.md` before you write the block. Two fields combine: `accompaniment_level` (how deep the block goes) and `technical_level` (the vocabulary).
+Read `02-DOCS/wiki/harness/user-profile.md` before writing the block. Two fields combine:
+`accompaniment_level` sets the depth, `technical_level` sets the vocabulary.
 
 | accompaniment_level | How the block behaves |
 |---------------------|-----------------------|
 | L0 — cavernícola | Only `✅` + `➡️`. One next option, a yes/no question. |
 | L1 — breve | The four lines; `🧭` is one line of why. |
 | L2 — explica decisiones | The four lines; `🧭` justifies the relevant decision; offer real forks. |
-| L3 — acompañamiento total | The four lines, full why, many orienting questions, each option explained in plain language. |
-
-`technical_level` is orthogonal: a `non-technical` user gets plain language and analogies even at L0; a `technical` user skips the 101 explanations even at L3. If the profile is missing, assume `non-technical` + **L3** (the non-technical-first default) and offer to set the dial.
-
-## Spoken dial config
+| L3 — acompañamiento total | The four lines, full why, each option explained in plain language. |
 
-When the user says "explícame más / menos", "no me expliques tanto", or "enséñame", update `accompaniment_level` in `02-DOCS/wiki/harness/user-profile.md`, confirm the change in one line, and apply the new depth from this turn on.
+`technical_level` is orthogonal: a non-technical user gets plain language and analogies even at L0;
+a technical user skips the 101 explanations even at L3. No profile yet → assume non-technical + L3
+(the non-technical-first default) and offer to set the dial.
 
-## Rules
+The dial is spoken, not configured: when the user says "explícame más / menos", "no me expliques
+tanto" or "enséñame", update `accompaniment_level` in the profile, confirm in one line, and apply
+the new depth from this turn on.
 
-- Adapt tone to the dial — you are a **flexible** skill, not a rigid template.
-- One brújula block per turn, at the end. Do not interrupt mid-work to orient.
-- Ask before deciding at any real fork; do not decide alone when the user can choose.
-- Never invent project state — situate the user from what is actually built (read the Knowledge map / repo if unsure).
-- Defer the "install a missing skill?" prompt to `suggest`.
+At a real fork, ask. Deciding alone is faster and wrong — the fork is the moment the person's
+judgment is worth more than yours.
 
 ## See Also