@nifrajs/skills 2.12.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "nifra",
+  "description": "Skills for building and verifying Nifra apps: contract-first APIs, full-stack SSR on five UI libraries, and the check/assure/capabilities gates. Prefers Nifra's live MCP server over model recall.",
+  "version": "2.11.0",
+  "homepage": "https://nifra.dev/docs/agents",
+  "repository": "https://github.com/nifrajs/nifra",
+  "license": "MIT",
+  "keywords": ["nifra", "typescript", "bun", "web-framework", "mcp"]
+}

package/README.md

@@ -0,0 +1,62 @@
+# @nifrajs/skills
+
+Portable agent skills for [Nifra](../../README.md) - one `SKILL.md` bundle, published to every agent
+surface that reads a `skills/` directory.
+
+A skill is loaded on demand: the agent sees only each skill's name and description until it decides
+one applies, then reads the body. That keeps Nifra's conventions out of the context window until they
+matter.
+
+```
+skills/
+  nifra/SKILL.md         entry point - MCP-first rule, the core loop, the non-negotiables
+  nifra-api/SKILL.md     typed routes, schemas, middleware, WebSockets, the never-throwing client
+  nifra-web/SKILL.md     file routing, loaders/actions, SSR, islands, the client/server boundary
+  nifra-verify/SKILL.md  check, assure, capabilities, manifest diff, the verification ladder
+```
+
+## Install
+
+**Pi**
+
+```sh
+pi install npm:@nifrajs/skills
+```
+
+**Claude Code**
+
+```sh
+/plugin marketplace add nifrajs/nifra
+/plugin install nifra@nifra
+```
+
+**Anything that reads a skills directory** (Cursor, `.agents/skills`, a project `.pi/skills`)
+
+```sh
+bun add -d @nifrajs/skills
+cp -R node_modules/@nifrajs/skills/skills/* .agents/skills/
+```
+
+## These skills are deliberately thin
+
+They teach shape and rules, not signatures. Signatures come from the MCP server, which is typechecked
+against the version installed in the project being edited:
+
+```sh
+bunx @nifrajs/cli init-agents      # register the MCP server in an existing app
+```
+
+Not in a Nifra project? The docs tools are hosted at `https://mcp.nifra.dev`.
+
+That split is the anti-drift design: a skill that restated the API would rot on the next release,
+while a skill that says "ask `nifra_types`" stays correct. Keep it that way when editing these files -
+if you find yourself pasting a signature in, reach for a tool reference instead.
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) - this package's contract card, one cheap read instead of the whole
+corpus. For the wider framework: the repo's [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick
+reference, and [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run
+`nifra check` as the done-gate, or `nifra mcp` to give the agent live project tools.
+
+MIT licensed.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nifrajs/skills",
+  "version": "2.12.0",
+  "description": "Agent skills for nifra - portable SKILL.md bundles that teach a coding agent Nifra's contracts, boundaries, and CI gates, and point it at the live MCP server instead of stale recall.",
+  "keywords": [
+    "pi-package",
+    "nifra",
+    "bun",
+    "typescript",
+    "ai-agent",
+    "agent-skills",
+    "skills",
+    "claude-code",
+    "cursor",
+    "mcp",
+    "agents-md",
+    "web-framework"
+  ],
+  "type": "module",
+  "files": [
+    "skills",
+    ".claude-plugin"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/skills"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://nifra.dev/docs/agents"
+}

package/skills/nifra/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: nifra
+description: Use when writing, reviewing, or debugging code in a Nifra project (@nifrajs/* packages, `nifra` CLI, server()/defineContract, loaders and actions, file routes under routes/). Explains how to reach Nifra's live MCP tools so signatures come from the installed version instead of memory, and which sibling skill to load for API, full-stack, or verification work.
+metadata:
+  homepage: https://nifra.dev
+  docs: https://nifra.dev/docs
+---
+
+# Nifra
+
+Nifra is a Bun-native, contract-first, framework-agnostic full-stack TypeScript framework. One schema
+drives runtime validation, TypeScript types, the typed client, and OpenAPI. The whole lifecycle is
+`app.fetch(Request): Promise<Response>`, so one app runs on Bun, Node, Deno, Cloudflare Workers, and
+Vercel Edge.
+
+## Rule zero: do not write Nifra from memory
+
+Nifra ships a verified MCP server. Its answers are typechecked against the version installed in the
+project you are editing, so they beat recall. Prefer it over guessing an API, and over reading
+`node_modules/@nifrajs/**/*.d.ts`.
+
+If the project already has `.mcp.json` or `.cursor/mcp.json`, the server is registered. If not:
+
+```sh
+bunx @nifrajs/cli init-agents      # writes .mcp.json, .cursor/mcp.json, AGENTS.md, CLAUDE.md
+```
+
+Not inside a Nifra project (answering a question, comparing frameworks, writing a snippet)? The docs
+tools are hosted at `https://mcp.nifra.dev` - same corpus, no checkout.
+
+Tools worth knowing, in the order you usually need them:
+
+| Tool | Use it for |
+|---|---|
+| `nifra_context` | This project's live route index, schemas, and conventions. Call first in unfamiliar code. |
+| `nifra_docs` | The prose doc for a concept, pinned to the installed version. |
+| `nifra_example` | A snippet that compiled against this version in CI. Never hand-write what this returns. |
+| `nifra_types` | The exact TypeScript of any `@nifrajs/*` symbol. |
+| `nifra_run` | Execute a real request against the app in-process to check behaviour. |
+| `nifra_check` | The done-gate. See `nifra-verify`. |
+| `nifra_assure` | Per-route security evidence. See `nifra-verify`. |
+
+No MCP available at all? Fall back to `https://nifra.dev/llms.txt` (index) or
+`https://nifra.dev/llms-full.txt` (every doc page inlined), and to each package's `LLM.md` contract
+card in `node_modules/@nifrajs/<pkg>/LLM.md`.
+
+## The core loop
+
+```ts
+// server.ts
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+export const app = server()
+  .get("/users/:id", (c) => ({ id: c.params.id }))
+  .post("/users", { body: t.object({ name: t.string() }) }, (c) => {
+    // c.body is validated and typed - invalid input became a structured 422 before this ran
+    return { id: crypto.randomUUID(), name: c.body.name }
+  })
+  .listen(3000)
+```
+
+```ts
+// anywhere.ts - inferred from the server, zero codegen
+import { client } from "@nifrajs/client"
+import type { app } from "./server"
+
+const api = client<typeof app>("http://localhost:3000")
+
+const res = await api.users({ id: "42" }).get()
+if (res.ok) res.data.id  // typed from the route
+else res.error           // failures are returned, never thrown
+```
+
+Change a route and every caller stops compiling. That property is the point: it is what keeps an
+agent-edited codebase correct.
+
+## Non-negotiables when you edit a Nifra project
+
+1. **Never hand-roll `fetch()` against this app's own API.** Use the typed client. `nifra check`
+   fails the build on hand-rolled calls, and it is right to.
+2. **Validate at the boundary, not in the handler.** Put the schema in the route options so invalid
+   input is a `422` before your code runs.
+3. **Failures are returned, not thrown.** Client results are `{ ok, data } | { ok: false, error }`.
+   Do not wrap client calls in try/catch expecting a throw.
+4. **Server-only code stays out of `routes/`.** A `node:` or native import reaching the client bundle
+   is a build error, not a warning.
+5. **Run the gate before you claim done.** `nifra check` (or the `nifra_check` tool). A failing check
+   means the work is not finished.
+
+## Which skill next
+
+- Typed JSON APIs, schemas, contracts, middleware, the client -> load `nifra-api`.
+- File routes, loaders, actions, SSR, islands, React/Vue/Solid/Svelte/Preact -> load `nifra-web`.
+- `nifra check`, `nifra assure`, capabilities, the manifest, CI gates -> load `nifra-verify`.
+
+## Starting from scratch
+
+```sh
+bun create nifra my-app                       # full-stack: pick framework, runtime, DB, auth, CI
+bun create nifra my-app --framework svelte    # react | vue | solid | preact | svelte
+bun add @nifrajs/core @nifrajs/schema @nifrajs/client   # just a typed API
+```

package/skills/nifra-api/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: nifra-api
+description: Use when building or changing a typed JSON API in Nifra - routes with server() or defineContract, request validation with @nifrajs/schema or any Standard Schema library, middleware and plugins, WebSockets, OpenAPI, and consuming the API from the zero-codegen @nifrajs/client. Load after the `nifra` skill.
+metadata:
+  docs: https://nifra.dev/docs/api
+---
+
+# Nifra: typed APIs and the typed client
+
+Fetch exact signatures with `nifra_types` and compiling snippets with `nifra_example` before writing
+anything non-trivial. This skill is the shape of the thing, not a substitute for either.
+
+## Two ways to declare routes
+
+**`server()`** - chainable, inference-first. Reach for this by default.
+
+```ts
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+export const app = server()
+  .get("/notes", () => listNotes())
+  .get("/notes/:id", { params: t.object({ id: t.string() }) }, (c) => getNote(c.params.id))
+  .post("/notes", { body: t.object({ title: t.string(), body: t.string() }) }, (c) =>
+    createNote(c.body),
+  )
+```
+
+**`defineContract`** - the same routes as a standalone, versionable artifact when the contract must
+be published, shared across repos, or evolved independently of the handlers. Ask `nifra_docs` for
+the contract page before choosing it; do not reach for it just because a route feels important.
+
+## Validation belongs in the route options
+
+`body`, `query`, `params`, `headers`, and `response` all take a schema. Anything that fails becomes a
+structured `422` before your handler runs, so a handler never defensively re-checks its own input.
+
+`@nifrajs/schema` (`t`) is TypeBox-backed and gives you JSON Schema and OpenAPI for free. Any
+[Standard Schema](https://standardschema.dev) library works too - Zod and Valibot slot into the same
+option with no adapter.
+
+```ts
+import { z } from "zod"
+app.post("/users", { body: z.object({ email: z.string().email() }) }, (c) => c.body.email)
+```
+
+Typed search params: declare `query` and read `c.query` typed. Do not parse `new URL(c.req.url)` by
+hand.
+
+## The client never throws
+
+```ts
+const res = await api.notes({ id }).get()
+if (!res.ok) return handle(res.error)   // transport and HTTP failures both land here
+res.data                                // typed from the route's return type
+```
+
+Three consequences worth internalising:
+
+- No `try`/`catch` around a client call for HTTP or network failure. Only genuinely exceptional code
+  throws.
+- The client is browser-safe. It carries the server's *types*, never its code.
+- Changing a route's shape breaks every caller at compile time. That is the feature. Fix the callers;
+  do not widen the type to silence `tsc`.
+
+## Middleware
+
+`@nifrajs/middleware` ships the production set: `requestId`, `logger`, `etag`, `bearer`, `apiKey`,
+`basicAuth`, `jwt`/`jwks`, `csrf`, `ipRestriction`, `bodyLimit`, `cors`, `securityHeaders`,
+`rateLimit`, `compression`, `cacheControl`, `cache`, `prettyJson`, `timing`, `methodOverride`,
+`trailingSlash`, `language`, `poweredBy`, `combine`, `openapi`, `healthcheck`, `idempotency`.
+
+Check that list before writing your own. Hand-rolled CORS, rate limiting, or CSRF is how a project
+acquires a security hole. Custom cross-cutting behaviour goes through `definePlugin` (typed context,
+idempotent registration), not a hand-patched handler wrapper.
+
+## WebSockets
+
+`app.ws(path, handler)` registers a typed WebSocket route: upgrade guard, portable socket,
+contract-validated messages, topic pub/sub. Served on Bun, Deno, Node, and Workers. Ask
+`nifra_example` for the current shape; the message-contract generics are easy to get wrong from memory.
+
+## Runtimes
+
+The app is `app.fetch(Request): Promise<Response>`. Bun is first-class; Node
+(`@nifrajs/node`), Deno (`@nifrajs/deno`), Workers (`@nifrajs/workers`), Lambda
+(`@nifrajs/aws-lambda`), and Vercel Edge are each one adapter import. Do not fork the app per target.
+
+## Common mistakes
+
+| Mistake | Do instead |
+|---|---|
+| `fetch("/api/notes")` inside the same project | `client<typeof app>()`, or `ctx.api` in a loader |
+| `try { await api.x.get() } catch` | Check `res.ok` |
+| Validating in the handler body | Put the schema in the route options |
+| Reading `c.req.headers.get("x-forwarded-for")` for the caller IP | Use the documented request helper; proxy headers are forgeable |
+| Hand-writing an OpenAPI document | `openapi` middleware derives it from the schemas |

package/skills/nifra-verify/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: nifra-verify
+description: Use before declaring Nifra work complete, when a Nifra CI gate fails, or when wiring Nifra checks into CI - `nifra check` drift gate, `nifra assure` route security evidence, `nifra capabilities check` effect provenance, `nifra manifest diff` deploy promotion, `nifra doctor`, the verification ladder, and contract-derived testing with @nifrajs/testing. Load after the `nifra` skill.
+metadata:
+  docs: https://nifra.dev/docs/verification
+---
+
+# Nifra: the gates
+
+Nifra turns "did you do this right" into build failures. The gates exist so an agent can check its own
+work instead of asserting success. Run them; do not route around them.
+
+## The done-gate
+
+```sh
+nifra check --json      # or the nifra_check MCP tool
+```
+
+`nifra check` typechecks the frontend/backend contract and flags drift: a hand-rolled `fetch()` at
+this app's own API, a server-only import inside `routes/`, a client call whose route changed shape.
+Findings carry the fix.
+
+**A failing check means the work is not done.** Do not suppress a finding, widen a type, or add a
+cast to make it pass. If a finding is genuinely wrong for this codebase, say so explicitly to the
+person you are working for rather than quietly silencing it.
+
+`nifra doctor` is the other half: environment and build-state problems (stale `dist/`, duplicate
+framework install, misconfigured adapter) that make correct code behave wrongly.
+
+## Security evidence per route
+
+```sh
+$ nifra assure
+✖ POST /notes (authenticated-write) is missing nifra.authenticated
+```
+
+A policy file classifies every route by reflection, then `assure` fails CI naming exactly which
+evidence is absent: authentication on a write, a rate limit, CSRF, a body cap. When you add a route,
+you add its evidence in the same change. When `assure` names a gap, add the real control - never
+reclassify the route to make the requirement disappear.
+
+## Effect provenance
+
+Routes declare the effects they perform:
+
+```ts
+app.post("/notes", { capabilities: ["db.write"] }, handler)
+```
+
+`nifra capabilities check` compares what a route *declares* against what its module graph can
+actually *reach*, pinned in a lockfile. A `GET` that can reach a domain write is an error.
+
+The common cause of a surprise failure is a barrel file: importing one helper from `./lib` drags the
+whole module graph's reach into the route. The fix is to narrow the import, not to widen the
+declaration.
+
+## Deploy promotion
+
+`nifra manifest diff` emits one hash-verified artifact - contracts, assurance, effects, response
+sensitivity - and fails closed on a breaking contract change, lost assurance, or a newly exposed
+sensitive field. Run it between environments, not just at merge.
+
+## Testing
+
+`@nifrajs/testing` derives tests from the contract rather than from your assumptions:
+adversarial/hostile input generation, response conformance, replay, shrinking, and a runtime-matrix
+check that the same app behaves identically on Bun, Node, Deno, and Workers.
+
+Prefer a contract-derived test to a hand-written one that re-asserts the schema. Hand-write the tests
+covering business rules the contract cannot express.
+
+## The verification ladder
+
+Five cumulative levels, from "has a typed contract" up to "has contract-derived invariant tests".
+`nifra levels` (or `nifra_levels`) reports where the project actually stands.
+
+Use it honestly: report the level the project holds, not the one it aspires to. Raising a level means
+adding the evidence, not editing the claim.
+
+## Suggested CI order
+
+```sh
+nifra check          # contract drift
+nifra assure         # route security evidence
+nifra capabilities check
+bun test             # incl. contract-derived tests
+nifra manifest diff  # promotion gate, between environments
+```
+
+Fail the build on each. A gate that only warns is a gate that gets ignored.

package/skills/nifra-web/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: nifra-web
+description: Use when building the full-stack side of a Nifra app - file routes, layouts, loaders and actions, forms, server functions, streaming SSR, islands, SSG and ISR, the query cache, and the React, Vue, Solid, Svelte, or Preact render adapters. Covers the client/server boundary rules and the hydration errors that boundary produces. Load after the `nifra` skill.
+metadata:
+  docs: https://nifra.dev/docs/routing
+---
+
+# Nifra: full-stack rendering
+
+`@nifrajs/web` is the framework-agnostic SSR core; `@nifrajs/web-react`, `-vue`, `-solid`,
+`-svelte`, and `-preact` are render adapters over the same routing, loaders, streaming, and islands.
+Switching UI library is an adapter import, not a rewrite.
+
+Call `nifra_context` first in an existing app: it returns the actual route tree and conventions, which
+beats inferring them from a directory listing.
+
+## Data flows one way
+
+```
+route file -> loader (server) -> component (server render, then hydrate) -> action (server) -> revalidate
+```
+
+- **Loader** - runs on the server for the matched route. Returns typed data to the component. Reach
+  your own API through `ctx.api` (an in-process client - no HTTP hop, no base URL, no auth replay).
+- **Action** - handles a mutation, then revalidation refreshes the loaders that matter.
+- **Component** - renders on the server, then hydrates. It must be safe to run in both places.
+
+Do not `fetch()` your own backend from a loader. `ctx.api` is the in-process path and it is typed.
+
+## The boundary is enforced, not advisory
+
+A server-only module that reaches the browser bundle is a **build error**. That is deliberate:
+leaking a DB client or a secret into client JS is the failure mode this prevents.
+
+Signals and their causes:
+
+| Error | Cause |
+|---|---|
+| `... reached the client bundle` | A `node:` or native import pulled in from a component or route module |
+| `server-only module reached the client bundle` | A module carrying the server-only marker was imported from client code |
+| `resolveDispatcher` / `Invalid hook call` | Two copies of the UI framework. The adapter dedupes it at build time - a stale `dist/` or a second install is the usual source |
+
+Fixes: move the server work into a loader, an action, or a server function; keep secrets in modules
+the client never imports; rebuild before blaming the code.
+
+**Server functions** are the escape hatch that stays safe: write the function on the server, call it
+from a component. The module body never ships, the arguments are validated, and the mounted function
+is an ordinary route - so assurance, capabilities, and the effect ledger still apply to it.
+
+## Forms work before hydration
+
+There is a window between HTML arriving and JS booting. Nifra keeps it usable: progressive-enhancement
+forms and links function during it, and a JS-only form whose native submit would break is guarded
+automatically. Do not disable a submit button until hydration; do not build a form that only works
+after JS. If you add `onSubmit` with `preventDefault`, make sure the action still handles a native
+POST.
+
+## Rendering modes
+
+- **SSR** - per-request render. The default.
+- **Streaming** - Suspense plus `defer()`, on every runtime including the edge. Stream the slow part;
+  do not block the shell on it.
+- **SSG / ISR** - prerender static routes, enumerate dynamic ones, cache with stale-while-revalidate.
+- **Islands** - ship interactivity for one component instead of the page.
+
+## Query cache
+
+`useQuery` / `createQuery` (naming follows the adapter's idiom): keyed cache, dedup, staleness,
+invalidation. Use it rather than a `useEffect` fetch. An action's revalidation and the query cache
+are the same invalidation story - do not run a second, hand-rolled one alongside them.
+
+## Dev loop
+
+```sh
+nifra dev      # Vite-backed HMR, state preserving
+nifra build
+nifra start
+```
+
+`@nifrajs/web/dev` is the Bun-native HMR loop with no Vite dependency. Production builds use Bun.
+
+If dev behaviour disagrees with a fresh build, suspect a stale `dist/` before suspecting the code -
+run `nifra doctor`.
+
+## Common mistakes
+
+| Mistake | Do instead |
+|---|---|
+| `fetch("/api/...")` in a loader | `ctx.api` |
+| Data fetching in `useEffect` | Loader, or the query cache |
+| Importing a DB client into a route component | Loader, action, or server function |
+| Blocking the whole page on one slow query | `defer()` plus Suspense |
+| Adding a second copy of React/Vue to fix a resolution error | Rebuild; the adapter dedupes at build time |