jskelet 0.5.5 → 0.6.1

package/AGENTS.md

@@ -1,8 +1,11 @@
 # AGENTS.md
 
-Bu depo **JSkelet** framework'ünün kaynağıdır: Express 5 + EJS sunucu render,
-vanilla JS island'lar, Tailwind v4 ve süreç belleğinde yaşayan HTML TTL cache.
-React ve TypeScript yok; düz JavaScript + JSDoc.
+Bu depo **JSkelet** framework'ünün kaynağıdır: Express 5 + build-time `.jsk`
+sunucu render (EJS opsiyonel legacy peer), vanilla JS island'lar, Tailwind v4
+ve süreç belleğinde yaşayan HTML TTL cache. React yok; framework kaynağı düz
+JavaScript + JSDoc. Uygulama client island/entry'leri `.ts` olabilir; paket
+`types/` altında `.d.ts` yayınlar. Sunucu route/hook/config hâlâ Node ESM
+`.js`/`.mjs`.
 
 Bir JSkelet **uygulamasında** çalışıyorsan (framework'ün kendisinde değil), aynı
 kuralların uygulama tarafı karşılıkları için [docs/](./docs/README.md) yeterli;
@@ -26,8 +29,7 @@ zaten tartışılmış:
 
 Belgeler iki dilde: Türkçesi `docs/`, İngilizcesi `docs/en/` altında ve
 dosyalar birebir eşlenik. Bir belgeyi değiştirdiysen karşılığını da güncelle;
-pazarlama sitesi (`examples/marketing`) bu dosyaları doğrudan `/docs` altında
-servis ettiği için eksik kalan çeviri kullanıcıya görünür.
+eksik kalan çeviri kullanıcıya görünür.
 
 ## Doğrulama
 
@@ -96,16 +98,18 @@ parçalar ayrı ve `no-store` işaretli fragment uçlarında.
   yalnızca `exports` haritasındaki belirteçler kullanılır (`jskelet`,
   `jskelet/client`, `jskelet/html`, `jskelet/tags`).
 
-## EJS tuzakları
+## `.jsk` tuzakları
 
-- `include` **async**'tir: `await include('partials/x')` yalnızca şablonun kendi
-  gövdesinde çalışır. Bir `forEach` callback'i içinde derleme hatası verir —
-  `for` döngüsü kullan.
-- `views/components/**` altındaki her named export otomatik olarak şablon local'i
-  olur; import gerekmez. Bileşenler EJS değil, HTML string döndüren
-  fonksiyonlardır.
-- Şablona giden her kullanıcı verisi `<%= %>` ile ya da `esc()` üzerinden
-  geçmeli; `<%- %>` yalnızca güvenli bildiğin HTML için.
+- İfade dilinde fonksiyon çağrısı, object/array literal ve atama yok — mantık
+  controller veya `views/components/*.js` içinde kalır. Layout’ta `asset()` /
+  `hasAsset()` için yerleşik `<Stylesheets />` / `<BodyScripts />` /
+  `<JsonLd />` kullan.
+- `{#include "partials/x"}` aynı `data` nesnesini geçer; EJS’teki ikinci-argüman
+  locals yok — veriyi controller’da hazırla.
+- `views/components/**` named export’ları PascalCase etiket olur; import yok.
+- Kullanıcı verisi `{{ }}` ile kaçar; `{{{ }}}` yalnızca güvendiğin HTML için.
+- Legacy EJS hâlâ varsa: `include` async’tir (`forEach` içinde `await` yok);
+  `<%= %>` / `<%- %>` ayrımına dikkat et; `ejs` opsiyonel peer olarak kurulmalı.
 
 ## Tailwind
 
@@ -118,7 +122,7 @@ sessizce çıktıdan düşer.
 
 Framework'ün genel yüzeyini değiştirdiysen (`route()` imzası, hook adları,
 config alanları, client API'si) `examples/minimal`, `examples/blog` ve
-`examples/marketing`'i de güncelle. Örnekler belgelerdeki kod parçalarının kaynağı; kaymaları en hızlı
+`examples/dashboard`'i de güncelle. Örnekler belgelerdeki kod parçalarının kaynağı; kaymaları en hızlı
 fark edilen yer orası.
 
 ## Windows notları

package/CHANGELOG.md

@@ -10,26 +10,175 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
-- Local flat `icons/` directory as the exclusive SVG sprite source when present
-  (`icons.dir`, default `"icons"`): `house.svg` / `house-bold.svg` file names,
-  XOR with `@phosphor-icons/core` (Phosphor only when the directory is absent).
-  The hashed sprite still lands under `public/assets/` and is precompressed.
+- `robots.txt` responses gain a trailing JSkelet note that disallows framework
+  endpoints (`/_jskelet/`, `/__jskelet/`, `/_fragment/`, plus a custom admin,
+  image, handoff, or dev path when it sits outside those prefixes). Every
+  user-agent already named in the file is repeated in that block, so a
+  crawler-specific group still sees the rules.
+
+### Breaking
+
+- Dev gate is opt-in
+  `DEV_TOKEN` in the environment no longer locks the site. Require the token
+  only with `devGate: true` or `DEV_GATE=1`. `DEV_GATE=0` turns the gate off
+  even when config enabled it.
+- Cache ceilings
+  `cache().maxEntries` above 800, `cache().data.maxEntries` above 20,000, and
+  `prewarm.onVisit` above `perPage` 20, `rps` 2, or `concurrency` 2 are clamped
+  at load with a warning. `onVisit` `rps: 0` is no longer unlimited. The HTML
+  cache also stops growing past 256 MB of stored HTML plus compressed bodies;
+  a single page larger than that is not stored.
 
 ### Fixed
 
-- Open Graph routes with a `.png` suffix (`/og/…/:slug.png`) now escape the
-  dot for Express 5 / path-to-regexp, so the handler matches again instead of
-  falling through to the HTML 404.
+- Visit warming skips pages that are already fresh when the cache key has a
+  vary prefix or a trailing `?`. With `vary.host`, warm requests stay on
+  loopback and send the public host as `x-forwarded-host`, so a second
+  `127.0.0.1` HTML entry is not created. The onVisit queue holds at most 64
+  paths.
+
+### Removed
+
+- `examples/marketing` — the marketing site now lives as a standalone app
+  outside this repository (`jskelet-marketing`).
+
+## [0.6.0] - 2026-09-21
+
+### Added
+
+- Port reclaim with `--murder`
+  `jskelet dev --murder` and `jskelet start --murder` kill whatever already
+  holds the listen port and bind in its place. Without the flag the CLI still
+  refuses to start, but now with a clear error (pid + hint) instead of a bare
+  `EADDRINUSE`.
+- Layout built-ins for `.jsk`
+  `<Stylesheets />`, `<BodyScripts />`, and `<JsonLd />` emit the asset /
+  script / JSON-LD loops from layout without calling helpers in the expression
+  language.
+- Framework default layout as `.jsk`
+  Ships as `src/templates/layout.jsk` with a checked-in `layout.render.js`
+  (`node scripts/compile-framework-layout.mjs`, `--check` for drift).
+  `jskelet/layout` points at the `.jsk` source; the legacy EJS copy remains at
+  `jskelet/layout/ejs`.
+- JSK editor tooling
+  The VS Code / Cursor JSK extension (v0.2.0) reports diagnostics in Problems
+  on open/save and offers PascalCase component completions from
+  `views/components`.
+- `<!DOCTYPE>` parsing in `.jsk`
+  Doctype and other `<!…>` declarations parse correctly instead of hanging the
+  template compiler.
+- `jskelet migrate` for Next.js App Router
+  Codemod with `scan` inventory, `apply` (JSX pages → controller + `.jsk`,
+  presentational components → HTML string helpers, `"use client"` → island
+  stubs), and `config` draft from `next.config`. Ships with `@babel/parser` /
+  `@babel/types`.
+- Published TypeScript declarations
+  `.d.ts` files under `types/` for `jskelet`, `jskelet/client`, `jskelet/html`,
+  `jskelet/tags`, `jskelet/cookies`, and `jskelet/log` (`npm run types`).
+- TypeScript client entries and islands
+  The client build accepts `.ts` / `.mts` entries and islands via esbuild;
+  manifest keys stay `*.js`. Conflicting stems (`main.js` + `main.ts`) fail the
+  build. Icon usage scan includes `.ts` / `.mts`.
+- Local `icons/` sprite source
+  When a flat `icons/` directory is present (`icons.dir`, default `"icons"`),
+  it is the exclusive SVG sprite source (`house.svg` / `house-bold.svg`).
+  Phosphor is used only when that directory is absent. The hashed sprite still
+  lands under `public/assets/` and is precompressed.
+- Auth handoff hardening
+  `allowedCookieNames` allowlist, pending-ticket and per-IP mint limits, plus
+  RFC 6265 cookie-name validation on `serializeCookie` (`isValidCookieName`).
+
+### Fixed
+
+- Clearer `jskelet dev` startup failures
+  The CLI prints the real server failure (for example port already in use /
+  `--murder` hint) instead of only `server exited (code 1)` when the child
+  dies during startup.
+- Marketing trust-bar icons after `.jsk` migration
+  `icons.scan` now covers `routes/`, so names declared in controllers
+  (`Package`, `TextT`, `ShieldCheck`, …) land in the sprite again.
+- Open Graph routes with a `.png` suffix
+  Paths like `/og/…/:slug.png` escape the dot for Express 5 / path-to-regexp,
+  so the handler matches instead of falling through to the HTML 404.
+- Safer remote image optimizer redirects
+  Redirects are no longer followed blindly; each hop is re-checked against
+  `allowHosts`, blocked private addresses, and DNS resolution (open-redirect
+  SSRF).
+
+### Breaking
+
+- `ejs` is an optional peer
+  Apps that only use `.jsk` need not install it; apps that still have `.ejs`
+  views or layouts must `npm i ejs`. Missing EJS when an `.ejs` file is
+  rendered throws a clear install/migrate hint.
+- Default layout export is `.jsk`
+  `jskelet/layout` now resolves to `layout.jsk` (was `layout.ejs`). Use
+  `jskelet/layout/ejs` for the legacy file.
+- Auth handoff requires cookie allowlist
+  `auth.crossSubdomainHandoff` mint needs a non-empty `allowedCookieNames`
+  list; `true` alone no longer accepts arbitrary cookie names.
+- Production builds omit client sourcemaps
+  Development still emits them; production client bundles do not.
+- Secret-like `clientEnv` keys fail the build
+  Names that look like secrets are rejected instead of being inlined into the
+  client bundle.
 
 ### Changed
 
-- Marketing example copy (EN/TR) reflects 0.5.x cache surfaces: host `vary`,
-  early refresh, classic vs `onVisit` prewarm, local `icons/`, shared cookies,
-  and `opengraph-image` → `ogHandler` on the migrate table. Pages now serve
-  per-locale dynamic OG cards at `/og/:locale/:page.png`.
-- Marketing changelog page restyled like a release-notes browser: measured
-  summary cards, search and newest/oldest sort, paginated open release cards
-  with Latest / Released badges and GitHub links (still driven by `CHANGELOG.md`).
+- Marketing changelog as release notes
+  `/changelog` hides Unreleased, lists every published release without
+  pagination, and shows each note as a titled card with a short headline plus
+  a longer explanation (Keep-a-Changelog sections: Added / Changed / Fixed /
+  …).
+- Examples are `.jsk` only
+  `minimal`, `blog`, `dashboard`, and `marketing` use `.jsk` for layouts,
+  pages, and partials; EJS files were removed from those trees.
+- Stricter, clearer template compiler
+  Unknown PascalCase components fail the build. Errors for forbidden function
+  calls, unknown includes (with location), and unclosed `{#if}` / `{#each}` at
+  EOF are clearer; icon scan recognizes `<Icon name="…" />`.
+- Docs present `.jsk` as the default
+  Docs / AGENTS / README tell the build-time `.jsk` story first; EJS is
+  documented as an optional legacy peer.
+- Standalone JSK VSIX packaging
+  The VS Code / Cursor extension (`extensions/vscode-jsk`) uses the new 3D
+  `.jsk` mark as marketplace and explorer icon, and packages as a standalone
+  VSIX (vendors `src/compile`) for Marketplace publish.
+- Migrate peers are optional
+  `@babel/parser` and `@babel/types` are optional peers used only by migrate.
+  They are no longer installed with every `jskelet` install; missing peers
+  throw an install hint. Unused `@babel/traverse` was dropped.
+- Auth handoff sits after CSRF
+  Mint mounts after CSRF so origin checks apply to
+  `POST /_jskelet/auth/handoff`.
+- Stronger security docs
+  Docs (TR/EN) expand `trustProxy` / `csrf.token` guidance and include a
+  fuller security-headers example under `headers()`.
+- Marketing copy defaults to `.jsk`
+  EN/TR marketing and how-it-works examples present `.jsk` as the default
+  template surface; the compare column for hand-written Express + EJS stays as
+  a competitor. Scaffold and migrate mappings name `.jsk` pages and layouts.
+- New geometric brand mark
+  Framework and marketing logos live at `src/logo.png` (admin / devtools) and
+  `examples/marketing/public/logo.png`. Marketing serves local favicons via
+  metadata `extraTags`.
+- Development 5xx diagnostics
+  In `NODE_ENV=development`, 5xx responses show the error message and stack
+  instead of the polished 500 page / `hooks.error()`. Production still returns
+  the minimal status page with no internals.
+- Marketing fit copy for signed-in panels
+  EN/TR fit copy treats dashboards and per-visitor panels as a supported path
+  (`private: true`, fragments). The poor-fit column names SPA shells,
+  collaborative client trees, streaming/RSC, and built-in real-time transport.
+- Marketing copy for 0.5.x surfaces
+  EN/TR copy reflects host `vary`, early refresh, classic vs `onVisit`
+  prewarm, local `icons/`, shared cookies, and `opengraph-image` → `ogHandler`
+  on the migrate table. Pages serve per-locale OG cards at
+  `/og/:locale/:page.png`.
+- Marketing visual language
+  Dark cyan glass look with shared `glass-panel` surfaces, numbered lit feature
+  cards, a 3D stack illustration on the home hero, and rotating cyan border
+  beams on lit panels.
 
 ## [0.5.4] - 2026-09-18
 
@@ -408,7 +557,8 @@ Initial release.
 - Documentation under `docs/` and three examples: `minimal`, `blog`,
   `marketing`.
 
-[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.5.4...HEAD
+[Unreleased]: https://github.com/ayberkenis/jskelet/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ayberkenis/jskelet/compare/v0.5.4...v0.6.0
 [0.5.4]: https://github.com/ayberkenis/jskelet/compare/v0.5.3...v0.5.4
 [0.5.3]: https://github.com/ayberkenis/jskelet/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/ayberkenis/jskelet/compare/v0.5.1...v0.5.2

package/README.md

@@ -4,11 +4,13 @@
 the product.
 
 JSkelet renders **complete HTML** on an Express 5 server from build-time
-**`.jsk` templates** (EJS still works), adds interactivity through vanilla JS
-**islands**, compiles CSS into a **single Tailwind v4 stylesheet**, and instead
-of ISR keeps an in-process **HTML TTL cache** with stale-while-revalidate — plus
-optional Redis sharing and path-based invalidation. No React, no TypeScript —
-plain JavaScript with JSDoc.
+**`.jsk` templates** (optional EJS peer for legacy `.ejs`), adds interactivity
+through vanilla JS **islands**, compiles CSS into a **single Tailwind v4
+stylesheet**, and instead of ISR keeps an in-process **HTML TTL cache** with
+stale-while-revalidate — plus optional Redis sharing and path-based
+invalidation. No React — the framework source is plain JavaScript with JSDoc;
+apps can write client islands and entries in TypeScript, and the published
+package ships declaration files.
 
 [![npm version](https://img.shields.io/npm/v/jskelet)](https://www.npmjs.com/package/jskelet)
 [![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
@@ -282,9 +284,9 @@ The complete reference — every field, default and failure mode — is
 
 | Command | What it does |
 | --- | --- |
-| `jskelet dev` | Watch build plus server, live reload, devtools overlay |
+| `jskelet dev` | Watch build plus server, live reload, devtools overlay. `--murder` kills whatever already holds `PORT` and starts. |
 | `jskelet build` | Production build: templates → fonts → sprite → CSS → JS → images → manifest → precompress |
-| `jskelet start` | Production server; builds first if output is missing |
+| `jskelet start` | Production server; builds first if output is missing. `--murder` same as for `dev`. |
 | `jskelet init` | Scaffolds a feature-first `.jsk` skeleton into the current directory |
 | `jskelet generate` | Scaffolds a `feature` / `page` / `island` |
 
@@ -305,12 +307,13 @@ Anything reachable by a deeper path is internal and may change without notice.
 ## Deployment
 
 The server is a plain Express 5 app, so anything that can run a Node process
-works: a `Dockerfile` (see `examples/marketing/Dockerfile`), a systemd unit, or
-a PaaS. Run `jskelet build` at image build time, put a reverse proxy in front
-for TLS, and expose a health endpoint (the default dev gate bypass list already
-includes `/api/healthcheck`, so a route there is reachable in every mode).
-Details, including cache sizing behind multiple instances and the optional
-Redis tier, are in [docs/10-dagitim.md](./docs/10-dagitim.md) /
+works: a multi-stage `Dockerfile` (see [docs/10-dagitim.md](./docs/10-dagitim.md)),
+a systemd unit, or a PaaS. Run `jskelet build` at image build time, put a
+reverse proxy in front for TLS, and expose a health endpoint (the default
+dev gate bypass list already includes `/api/healthcheck`, so a route there is
+reachable in every mode). Details, including cache sizing behind multiple
+instances and the optional Redis tier, are in
+[docs/10-dagitim.md](./docs/10-dagitim.md) /
 [docs/en/10-deployment.md](./docs/en/10-deployment.md).
 
 ## Documentation
@@ -341,7 +344,6 @@ apply to this repository.
 ```bash
 npm --prefix examples/minimal   install && npm --prefix examples/minimal   run dev
 npm --prefix examples/blog      install && npm --prefix examples/blog      run dev
-npm --prefix examples/marketing install && npm --prefix examples/marketing run dev
 npm --prefix examples/dashboard install && npm --prefix examples/dashboard run dev
 ```
 
@@ -350,13 +352,6 @@ npm --prefix examples/dashboard install && npm --prefix examples/dashboard run d
 - **`examples/blog`** — dynamic routes, tag pages, every config section,
   fragment-loaded tabs, a form, prewarm, RSS and sitemap, four islands. It
   intentionally touches every surface of the framework.
-- **`examples/marketing`** — the framework's own marketing site: comparison
-  table, changelog and download pages, long TTLs, prewarm covering every page.
-  The byte counts on the page are measured from that site's own build output, the
-  version details are read from the installed package, and the latency numbers
-  are measured in the browser; there are no invented benchmarks. It is also
-  bilingual — English at the root, Turkish under `/tr` — which shows how to build
-  a multi-language site on a framework that ships no i18n of its own.
 - **`examples/dashboard`** — the opposite axis: per-visitor pages. A signed
   cookie session, a `private: true` page that never enters the HTML cache, a
   paginated table fragment, a CSRF-protected form that still works without

package/bin/jskelet.mjs

@@ -2,11 +2,12 @@
 /**
  * JSkelet CLI.
  *
- *   jskelet dev      build watch + sunucu, canlı yenileme, dev overlay
- *   jskelet build    tek seferlik prod build (fontlar, sprite, CSS, JS, görseller)
- *   jskelet start    prod sunucu (build eksikse önce üretir)
+ *   jskelet dev [--murder]   build watch + sunucu, canlı yenileme, dev overlay
+ *   jskelet build            tek seferlik prod build (fontlar, sprite, CSS, JS, görseller)
+ *   jskelet start [--murder] prod sunucu (build eksikse önce üretir)
  *   jskelet init       bulunduğun dizine minimal iskelet kurar
  *   jskelet generate   feature / page / island iskeleti
+ *   jskelet migrate    Next.js App Router → JSkelet codemod
  *
  * Alt komutlar ayrı süreçlerde çalışır. Sebep: `dev` iki uzun ömürlü süreci
  * (build watch + sunucu) yönetiyor ve sunucunun ESM resolve hook'larına
@@ -102,15 +103,28 @@ switch (command) {
     break;
   }
 
+  case "migrate": {
+    const { migrate } = await import("../src/migrate.mjs");
+    try {
+      await migrate(process.cwd(), rest);
+    } catch (error) {
+      process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+      process.exit(1);
+    }
+    break;
+  }
+
   default: {
     const known = command ? `unknown command: ${command}\n\n` : "";
     process.stderr.write(
-      `${known}usage: jskelet <dev|build|start|init|generate>\n\n` +
-        "  dev       build watch + server (live reload, dev overlay)\n" +
-        "  build     production build\n" +
-        "  start     production server\n" +
-        "  init      scaffold a minimal skeleton in the current directory\n" +
-        "  generate  scaffold feature | page | island\n",
+      `${known}usage: jskelet <dev|build|start|init|generate|migrate> [options]\n\n` +
+        "  dev [--murder]    build watch + server (live reload, dev overlay)\n" +
+        "  build             production build\n" +
+        "  start [--murder]  production server\n" +
+        "  init              scaffold a minimal skeleton in the current directory\n" +
+        "  generate          scaffold feature | page | island\n" +
+        "  migrate           Next.js App Router → JSkelet codemod (scan | apply | config)\n\n" +
+        "  --murder          if the listen port is busy, kill the listener and start\n",
     );
     process.exit(command ? 1 : 0);
   }

package/docs/01-baslangic.md

@@ -249,11 +249,12 @@ resolve hook'larına (`--import`) süreç başlangıcında ihtiyaç duyması.
 
 | Komut | Ne yapar |
 | --- | --- |
-| `jskelet dev` | Build watch + sunucu, tek terminalde. Canlı yenileme, CSS hot-swap, dev overlay. `NODE_ENV=development`. |
+| `jskelet dev` | Build watch + sunucu, tek terminalde. Canlı yenileme, CSS hot-swap, dev overlay. `NODE_ENV=development`. Port doluysa başlamaz; `--murder` dinleyiciyi öldürüp bağlar. |
 | `jskelet build` | Tek seferlik prod build: fontlar → ikon sprite → CSS → client JS → görseller → manifest → precompress. `NODE_ENV` verilmemişse `production`. |
-| `jskelet start` | Prod sunucu. Build çıktısı yoksa önce üretir. `NODE_ENV` verilmemişse `production`. |
+| `jskelet start` | Prod sunucu. Build çıktısı yoksa önce üretir. `NODE_ENV` verilmemişse `production`. Port davranışı `dev` ile aynı (`--murder`). |
 | `jskelet init` | Bulunduğun dizine feature-first `.jsk` iskeleti kurar; var olan dosyalara dokunmaz. |
 | `jskelet generate` | `feature` / `page` / `island` iskeleti üretir. |
+| `jskelet migrate` | Next.js App Router → JSkelet codemod (`scan` / `apply` / `config`). [11-tasima.md](./11-tasima.md). |
 
 Bilinmeyen bir komut ya da argümansız çağrı kullanım metnini basar.
 
@@ -280,7 +281,7 @@ yalnızca bu belirteçleri kullanın:
 | `jskelet/tags` | `link`, `image`, `icon`, `preloadImage`, `toKebab` |
 | `jskelet/log` | Konsol çıktısı yardımcıları (`banner`, `event`, `task`, `size`, `ms`, …) |
 | `jskelet/register` | `node --import jskelet/register` ile alias + uzantı hook'ları |
-| `jskelet/layout` | Framework'ün varsayılan `layout.ejs` dosyasının yolu |
+| `jskelet/layout` | Framework'ün varsayılan `layout.jsk` dosyasının yolu |
 
 ## Sırada ne var
 

package/docs/02-mimari.md

@@ -36,9 +36,10 @@ JSkelet bu gözlemi mimarinin merkezine alır:
  ├─ rewrites(beforeFiles)          config → proxy ya da req.url değişimi
  ├─ compression                    brotli/gzip pazarlığı (kalite 5)
  ├─ headers                        statik cache + config headers()
- ├─ devGate                        DEV_TOKEN varsa token yoksa 404
+ ├─ devGate                        gate açıksa ve token yoksa 404
  ├─ redirects                      config redirects(), ilk eşleşen kazanır
  ├─ trailingSlash                  config trailingSlash: true ise 308
+ ├─ robots.txt                     kullanıcının gövdesine framework Disallow'u ekler
  ├─ staticPrecompressed            build'de üretilmiş .br/.gz kopyalar (kalite 11)
  ├─ express.static                 public/ altındaki dosyalar
  ├─ (dev) devtools                 yalnızca NODE_ENV=development
@@ -51,7 +52,7 @@ JSkelet bu gözlemi mimarinin merkezine alır:
  │       └─ withHtmlCache          TTL + stale-while-revalidate
  │           └─ withUpstreamTracking
  │               └─ withRequestCache
- │                   └─ controller → renderPage → EJS
+ │                   └─ controller → renderPage → .jsk (veya legacy EJS)
  ├─ 404 → hooks.notFound()
  └─ hata yönetimi                  redirect/notFound + 500 fallback
 ```
@@ -71,6 +72,10 @@ sebebi var ve yer değiştirmek sessiz bozulmalara yol açıyor.
   bile dışarıya sızdırmamalı. `trailingSlash` config redirects'ten sonra durur,
   böylece açık kurallar istenen yolu önce görür; kanonik slash biçimi ikinci
   adımda dayatılır.
+- **`robots.txt`, statikten önce ve sıkıştırmanın içinde.** Uygulamanın
+  yazdığı gövde değişmez; framework kendi uçlarının `Disallow` kurallarını
+  sona ekler. Sıkıştırılmış bir kopyanın (`Content-Encoding`) üzerine
+  yazılmaz — ek düz metne konur, sıkıştırma dışarıda kalır.
 - **`staticPrecompressed`, `express.static`ten önce.** Build'de üretilmiş
   `.br`/`.gz` kopyalar varsa onlar servis edilir (brotli kalite 11); yoksa
   istek altındaki `static`e düşer ve middleware anında sıkıştırır (kalite 5).
@@ -254,8 +259,9 @@ teşhisi zor sorunlara dönüşüyor.
 
 ## Neden bu bağımlılık listesi
 
-Çalışma zamanı bağımlılıkları dörttür: `express`, `ejs`, `esbuild`,
-`tailwind-merge`. Geri kalan her şey (Tailwind, PostCSS, lightningcss, sharp,
+Çalışma zamanı bağımlılıkları üçtür: `express`, `esbuild`,
+`tailwind-merge`. `ejs` yalnızca legacy `.ejs` şablonları için opsiyonel peer'dır.
+Geri kalan her şey (Tailwind, PostCSS, lightningcss, sharp,
 Phosphor ikonları) **opsiyonel peer bağımlılığıdır** ve yoksa ilgili build adımı
 atlanır.
 

package/docs/03-routing.md

@@ -156,7 +156,9 @@ okuduğunda render önbelleğe yazılmaz), ama doğru yer bayrak. Ayrıntılar
 ## `fragment()` — layout'suz parça
 
 Bir bölgeyi tazeleyen uçlar için. Layout basılmaz, yanıt `private, no-store` ve
-ETag'siz gider, HTML önbelleğine hiç uğramaz.
+ETag'siz gider, HTML önbelleğine hiç uğramaz. `/_fragment/` öneki
+`robots.txt`'in altına eklenir; parça uçları dizine girmez
+([04](./04-render-ve-sablonlar.md#robotstxt)).
 
 ```js
 app.get(
@@ -210,7 +212,7 @@ Controller `async (ctx) => sayfa` biçimindedir ve şu alanları döndürebilir:
 
 | Alan | Tip | Varsayılan | Anlamı |
 | --- | --- | --- | --- |
-| `view` | `string` | — | `views/` altındaki şablon yolu, uzantısız: `"pages/home"` → `views/pages/home.ejs`. |
+| `view` | `string` | — | `views/` altındaki şablon yolu, uzantısız: `"pages/home"` → `views/pages/home.jsk` (yoksa legacy `.ejs`). |
 | `data` | `object` | `{}` | Şablona local olarak geçen veriler. |
 | `metadata` | `object` | `{}` | `<head>` etiketlerine çevrilir; `hooks.metadata()` çıktısının üzerine biner. Şema: [04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md). |
 | `status` | `number` | `200` | HTTP durum kodu. Yalnızca 200 önbelleğe yazılır. |
@@ -326,12 +328,17 @@ hata yöneticisi devreye girer, hatayı loglar ve framework'ün kendi hata sayfa
 `Cache-Control: no-store` ile döner. Durum kodu hatanın `statusCode` (ya da
 `status`) alanından okunur; 400–599 aralığında değilse 500 kullanılır.
 
-Framework'ün sayfası bilinçli olarak yalın: durum kodu, tek satır başlık ve tek
-satır açıklama. Marka adı, gezinme ya da hata ayrıntısı taşımaz — sunucunun içi
-ziyaretçiye açılmaz. Dil `brand.lang`ten gelir (`tr` ve `en` hazır, diğerleri
-`en`e düşer).
+**Development** (`NODE_ENV=development`, yani `jskelet dev`): 5xx yanıtlarında
+gömülü 500 sayfası ve `hooks.error()` atlanır; mesaj, yığın izi ve varsa
+`cause` zinciri içeren bir teşhis sayfası döner. 4xx (404 vb.) development'ta
+da her zamanki gibi durum sayfasıdır.
 
-Kendi sayfanı vermek için `hooks.error()`:
+**Production**: framework'ün sayfası bilinçli olarak yalın — durum kodu, tek
+satır başlık ve tek satır açıklama. Marka adı, gezinme ya da hata ayrıntısı
+taşımaz; sunucunun içi ziyaretçiye açılmaz. Dil `brand.lang`ten gelir (`tr` ve
+`en` hazır, diğerleri `en`e düşer).
+
+Kendi sayfanı vermek için `hooks.error()` (yalnızca production / 4xx):
 
 ```js
 // jskelet.config.mjs