jskelet 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -27,6 +27,17 @@ one is listed under a **Breaking** heading.
 
 ### Added
 
+- VS Code / Cursor extension skeleton under `extensions/vscode-jsk`: `.jsk`
+  language id, TextMate highlighting (`{{ }}` / `{#if}` / `{#each}` /
+  components), language config, and snippets. Install from that folder or
+  launch **JSK: Extension** from the repo root. Bound attrs on HTML tags
+  (`:src="… + '/path'"`) highlight nested single-quoted strings.
+- Compile-time known components are discovered from **named exports** in
+  `views/components/**/*.js` (plus `.jsk` component files), not from the file
+  basename — so `<SectionHead />` resolves when `sectionHead` lives in
+  `ui.js` without a stub re-export. Docs cover the `.jsk` template-vs-component
+  boundary and a `{ items, error }` loader / `LoadErrorState` pattern so
+  upstream failures are not mistaken for empty data.
 - Build-time `.jsk` templates: declarative HTML-like syntax compiled to ESM
   render modules under `.jskelet/templates/` (no request-time parse, `eval`, or
   `new Function`). Coexists with EJS; compiled `.jsk` wins when both exist.
@@ -36,7 +47,8 @@ one is listed under a **Breaking** heading.
 - Feature-first conventions: `paths.features` / `paths.shared`, multi-root
   views and components, `features/<name>/index.js` route registration after
   `routes/`. CLI: `jskelet generate feature|page|island`. `jskelet init`
-  scaffolds `.jsk` pages.
+  scaffolds a feature-first `.jsk` skeleton (`features/home/` with route,
+  page, component and island; global `views/pages/not-found.jsk`).
 - Template compile step in `jskelet build`; icon scan and Tailwind docs cover
   `.jsk` / `features` / `shared`. Bench: `node scripts/bench-templates.mjs`.
 - Top-level `logs` config for persistent sinks: daily NDJSON files
@@ -127,8 +139,19 @@ one is listed under a **Breaking** heading.
 
 ### Changed
 
+- README rewritten for the current surface: build-time `.jsk` as the default
+  template story (EJS still supported), feature-first `init` examples, `mount`
+  island contract, path-based `invalidateHtmlCache` (replacing the outdated
+  “no targeted invalidation” claim), Redis / admin / data-cache callouts, and
+  bilingual doc links under `docs/` and `docs/en/`.
+- Duplicate component named exports (or the same PascalCase tag in two files)
+  now **fail** at build and at server startup instead of warning and letting
+  the second definition win. Overwriting `components/index.js` barrel exports
+  remains allowed.
 - `examples/minimal` pages moved to `.jsk`; adds `features/demo` as a
   co-located route + view sample.
+- Marketing compare/FAQ copy no longer claims targeted invalidation is missing;
+  it points at `invalidateHtmlCache()` (and Redis pub/sub for multi-instance).
 
 - An adaptive per-host rate limit for upstream calls, `cache().upstream`. It sits
   in the `fetch` wrapper rather than in the prewarm pass, because what spends the

package/README.md

@@ -3,11 +3,12 @@
 **A framework that feels like no framework** — for sites where SEO and speed are
 the product.
 
-JSkelet renders **complete HTML** on an Express 5 server with 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. No React, no TypeScript — plain JavaScript
-with JSDoc.
+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.
 
 [![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)
@@ -46,19 +47,17 @@ Requirements:
 - **Node.js 22 or newer.**
 - Everything else is an **optional peer dependency**: `postcss`,
   `@tailwindcss/postcss`, `tailwindcss` and `lightningcss` for styles,
-  `@phosphor-icons/core` for the icon sprite, `sharp` for image optimization. If
-  a package is missing, the matching build step is skipped with a warning and
-  the site keeps working.
+  `@phosphor-icons/core` for the icon sprite, `sharp` for image optimization,
+  `ioredis` for the shared Redis cache tier. If a package is missing, the
+  matching step is skipped with a warning and the site keeps working.
 
 ## What it looks like
 
-A route module receives the app and returns page descriptions. Nothing is
-inferred from the file system — URLs are written out.
+A feature (or route) module receives the app and registers URLs explicitly.
+Nothing is inferred from the file system.
 
 ```js
-// routes/10-pages.mjs
-import { getPost, getPosts } from "../lib/posts.js";
-
+// features/home/index.js
 export default function register(app, { route, notFound }) {
   app.get("/", route(
     async () => ({
@@ -66,7 +65,7 @@ export default function register(app, { route, notFound }) {
       metadata: { title: "Home", canonical: "/" },
       data: { posts: getPosts() },
     }),
-    { revalidate: 60 }, // keep this HTML for 60 seconds
+    { revalidate: 60 },
   ));
 
   app.get("/blog/:slug", route(async ({ params }) => {
@@ -77,28 +76,28 @@ export default function register(app, { route, notFound }) {
 }
 ```
 
-Templates are EJS. Every named export under `views/components/**` becomes a
-template local automatically, so components need no imports — they are plain
-functions returning HTML strings.
+Templates are `.jsk`: compiled to ESM at build time (no request-time parse or
+`eval`). Named exports under `views/components/**` become PascalCase tags —
+plain functions that return HTML strings.
 
 ```html
-<!-- views/pages/home.ejs -->
+<!-- features/home/views/pages/home.jsk -->
 <section class="wrapper">
   <h1 class="text-3xl font-bold">Latest posts</h1>
-  <% posts.forEach(function (post) { %>
-  <%- postCard({ post }) %>
-  <% }); %>
+  {#each posts as post}
+    <PostCard :post="post" />
+  {/each}
 
-  <!-- downloaded and wired up once visible -->
   <div data-island="newsletter"></div>
 </section>
 ```
 
-Islands are modules with a default export that receives their root element.
+Islands export a named `mount(element, props)` and are registered from the
+client entry as dynamic imports.
 
 ```js
-// client/islands/newsletter.js
-export default function newsletter(el) {
+// features/home/client/newsletter.js
+export function mount(el) {
   const form = el.querySelector("form");
   form.addEventListener("submit", async (event) => {
     event.preventDefault();
@@ -114,20 +113,22 @@ numbered comment at the top of `src/server/create-app.js`; changing that order
 causes silent breakage.
 
 1. **Config** (`jskelet.config.mjs`) is loaded once and exposed through
-   `getConfig()`. `redirects()`, `rewrites()`, `headers()` and `cache()` follow
-   the subset of `next.config` syntax people actually use. A broken config, a
-   throwing `headers()` or a failing hook logs a warning and falls back to
-   defaults — it never takes the site down.
-2. **Static assets** are served from `public/` with hashed filenames and
-   long-lived cache headers, and precompressed `.br` / `.gz` variants are picked
+   `getConfig()`. `redirects()`, `rewrites()`, `headers()`, `cache()` and
+   `admin()` follow the subset of `next.config` syntax people actually use. A
+   broken config, a throwing `headers()` or a failing hook logs a warning and
+   falls back to defaults — it never takes the site down.
+2. **Build** turns `.jsk` into modules under `.jskelet/templates/`, bundles
+   islands, compiles Tailwind, hashes assets and optionally precompresses them.
+3. **Static assets** are served from `public/` with hashed filenames and
+   long-lived cache headers; precompressed `.br` / `.gz` variants are picked
    automatically.
-3. **`route()`** wraps your controller. It builds a cache key, checks the HTML
+4. **`route()`** wraps your controller. It builds a cache key, checks the HTML
    TTL cache, and on a miss renders the page. When a cached entry is stale it is
    returned immediately while revalidation runs in the background.
-4. **Render** composes metadata, layout context and your view into one HTML
+5. **Render** composes metadata, layout context and your view into one HTML
    document. Hooks (`metadata`, `layoutContext`, `notFound`, `prewarmPaths`)
    are where application knowledge lives — the framework itself carries none.
-5. **Hydration** happens in the browser: the island registry finds
+6. **Hydration** happens in the browser: the island registry finds
    `data-island` elements and dynamically imports the matching chunk when it
    becomes visible (or eagerly / on idle, if asked).
 
@@ -141,21 +142,35 @@ client.
 - **Full HTML from the server.** First paint does not wait for JavaScript, and
   crawlers see the complete document because content is never assembled in the
   browser.
+- **Build-time `.jsk` templates.** Declarative HTML-like syntax compiled to ESM
+  before the server starts; EJS remains supported where both exist, `.jsk`
+  wins. A VS Code / Cursor extension under `extensions/vscode-jsk` covers
+  highlighting and snippets.
+- **Feature-first layout.** `features/<name>/` co-locates routes, views,
+  components and islands; `jskelet generate feature|page|island` scaffolds the
+  next slice. URLs stay explicit.
 - **Islands.** Interactivity attaches to elements carrying `data-island`.
   Modules are dynamically imported on visibility by default;
   `data-island-eager` and `data-island-idle` pick a different strategy. A small
   store handles sharing state between islands.
 - **HTML TTL cache.** Per-route `revalidate`, stale-while-revalidate on expiry,
-  and prewarm that fills the cache at boot so the first visitor is not the one
-  who pays for rendering.
+  query allowlists, dependency tracking from `withDataCache`, and prewarm that
+  fills the cache at boot. `invalidateHtmlCache()` stales a path, pattern or
+  RegExp without flushing everything.
+- **Optional Redis tier.** With `ioredis`, replicas share HTML/data and
+  broadcast invalidation over pub/sub so a webhook reaches every process.
+- **Admin panel.** Opt-in at `/_jskelet/admin` (`admin()` or `JSKELET_ADMIN=1`):
+  cache inventory, targeted purge, Cloudflare CDN controls, live logs, routes
+  and system meters — password printed once per process start.
 - **Fast navigation.** The `navigation` config section emits Speculation Rules
   to prefetch or prerender links and enables view transitions — without adding
   any client runtime.
 - **Familiar configuration.** `redirects()`, `rewrites()`, `headers()`,
-  `cache()`, plus `brand`, `images`, `security` and `hooks` sections.
-- **A real build pipeline.** Fonts, an SVG sprite generated from the icons you
-  actually use, Tailwind v4 CSS, esbuild bundles with code splitting, webp
-  variants, hashed output and brotli/gzip precompression.
+  `cache()`, `admin()`, plus `brand`, `images`, `security`, `logs`,
+  `trailingSlash` and `hooks`.
+- **A real build pipeline.** Fonts, an SVG sprite from the icons you use,
+  Tailwind v4 CSS, esbuild bundles with code splitting, webp variants, hashed
+  output and brotli/gzip precompression.
 - **Developer experience.** One command, one terminal: watch build plus server,
   CSS hot-swap, automatic restart, and a devtools overlay on Alt+D showing
   requests, errors, upstream calls, a cache dump and Web Vitals.
@@ -168,8 +183,9 @@ client.
 - **No file-system routing.** Paths are written explicitly in route modules.
 - **No streaming or RSC.** A page is flushed as one document; slow sections are
   fetched from separate fragment endpoints.
-- **No targeted cache invalidation.** There is TTL and there is "clear
-  everything".
+- **No Next.js-style cache tags.** Invalidation is by path, pattern or RegExp
+  (`invalidateHtmlCache`), plus data-cache dependency tracking — not arbitrary
+  tag graphs.
 - **No global state management** beyond the small island store.
 
 An app-shaped interface behind a login — a dashboard, an editor, an admin panel
@@ -177,10 +193,12 @@ An app-shaped interface behind a login — a dashboard, an editor, an admin pane
 framework. It is supported rather than recommended: `route(fn, { private: true })`
 keeps per-visitor pages out of the cache, and signed cookies, CSRF, fragment
 endpoints and region swapping cover the rest
-([docs/12-panel-ve-oturum.md](./docs/12-panel-ve-oturum.md)). Live data
-transport is deliberately left to you; pick SSE, WebSocket or polling yourself.
-A feature-by-feature comparison with Next.js is in
-[docs/11-tasima.md](./docs/11-tasima.md).
+([docs/12-panel-ve-oturum.md](./docs/12-panel-ve-oturum.md) /
+[docs/en/12-dashboards-and-sessions.md](./docs/en/12-dashboards-and-sessions.md)).
+Live data transport is deliberately left to you; pick SSE, WebSocket or polling
+yourself. A feature-by-feature comparison with Next.js is in
+[docs/11-tasima.md](./docs/11-tasima.md) /
+[docs/en/11-migration.md](./docs/en/11-migration.md).
 
 ## Project layout
 
@@ -189,18 +207,20 @@ the `paths` section of the config:
 
 ```
 my-site/
-├── jskelet.config.mjs   # config, hooks, headers, redirects
-├── routes/              # loaded in filename order (10-, 20-, …)
-├── views/
-│   ├── pages/           # EJS pages
-│   ├── partials/        # header, footer, …
-│   └── components/      # named exports become template locals
-├── client/
-│   ├── entries/main.js  # registers islands, calls start()
-│   └── islands/         # one module per island
-├── styles/globals.css   # Tailwind entry with @source directives
-├── lib/                 # your data access
-└── public/              # build output plus static files
+├── jskelet.config.mjs      # config, hooks, headers, redirects
+├── features/               # feature-first slices (optional but default in init)
+│   └── home/
+│       ├── index.js        # register(app, api) — URLs stay explicit
+│       ├── views/pages/    # .jsk pages for this feature
+│       ├── views/components/
+│       ├── client/         # islands; register from client/entries
+│       └── server/
+├── routes/                 # optional; loaded before features (10-, 20-, …)
+├── views/                  # shared / app-wide pages (e.g. 404)
+├── shared/                 # cross-feature server/views/client
+├── client/entries/main.js  # registers islands, calls start()
+├── styles/globals.css      # Tailwind entry with @source directives
+└── public/                 # build output plus static files
 ```
 
 Two things bite newcomers:
@@ -209,9 +229,8 @@ Two things bite newcomers:
   `styles/globals.css`, because automatic detection is turned off with
   `source(none)`. A new directory that uses classes needs an `@source` line, or
   its classes silently vanish from the stylesheet.
-- **`include` in EJS is async.** `await include('partials/x')` only works in a
-  template's own body; inside a `forEach` callback it is a compile error, so use
-  a `for` loop there.
+- **`.jsk` expression language is intentionally narrow.** Formatting and object
+  literals belong in JS components (`views/components/**`), not in the template.
 
 ## Configuration
 
@@ -220,7 +239,7 @@ Two things bite newcomers:
 ```js
 export default {
   brand: { name: "My Site", lang: "en" },
-  icons: { scan: ["views", "client"] },
+  icons: { scan: ["views", "features", "client"] },
 
   // Speculation Rules plus @view-transition, with no client runtime.
   navigation: { prefetch: "moderate", prerender: "conservative", viewTransition: true },
@@ -236,10 +255,17 @@ export default {
   async cache() {
     return {
       html: { "/": 3600, "/pricing": 3600 },
+      query: { "/search": ["q"] }, // only these params enter the cache key
       prewarm: { enabled: true, max: 50, concurrency: 4 },
+      // redis: { enabled: true, url: process.env.REDIS_URL },
     };
   },
 
+  // Opt-in production panel at /_jskelet/admin (password in the server log).
+  async admin() {
+    return { enabled: false };
+  },
+
   hooks: {
     metadata: () => ({ titleTemplate: "%s · My Site", siteUrl: "https://example.com" }),
     layoutContext: ({ pathname }) => ({ pathname, year: new Date().getFullYear() }),
@@ -249,16 +275,18 @@ export default {
 ```
 
 The complete reference — every field, default and failure mode — is
-[docs/07-yapilandirma.md](./docs/07-yapilandirma.md).
+[docs/07-yapilandirma.md](./docs/07-yapilandirma.md) /
+[docs/en/07-configuration.md](./docs/en/07-configuration.md).
 
 ## CLI
 
 | Command | What it does |
 | --- | --- |
 | `jskelet dev` | Watch build plus server, live reload, devtools overlay |
-| `jskelet build` | Production build: fonts → sprite → CSS → JS → images → manifest → precompress |
+| `jskelet build` | Production build: templates → fonts → sprite → CSS → JS → images → manifest → precompress |
 | `jskelet start` | Production server; builds first if output is missing |
-| `jskelet init` | Scaffolds a minimal skeleton into the current directory |
+| `jskelet init` | Scaffolds a feature-first `.jsk` skeleton into the current directory |
+| `jskelet generate` | Scaffolds a `feature` / `page` / `island` |
 
 ## Public API
 
@@ -266,7 +294,7 @@ Only the specifiers in the `exports` map are supported:
 
 | Specifier | Contents |
 | --- | --- |
-| `jskelet` | `route`, `fragment`, `createApp`, `startServer`, `notFound`, `redirect`, `seeOther`, `cache`, `asset`, `getConfig`, cookie helpers, HTML cache and prewarm helpers |
+| `jskelet` | `route`, `fragment`, `createApp`, `startServer`, `notFound`, `redirect`, `seeOther`, `cache`, `asset`, `getConfig`, cookie helpers, HTML/data cache and prewarm helpers, Redis/Cloudflare status and purge helpers |
 | `jskelet/client` | `register`, `registerAll`, `hydrate`, `unmount`, `start`, `swap`, `startForms`, `createStore`, DOM helpers |
 | `jskelet/html` | `attrs`, `cn`, `cx`, `esc`, `jsonScript` |
 | `jskelet/tags` | `icon`, `image`, `link`, `preloadImage`, `csrfField` |
@@ -281,28 +309,29 @@ 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, are in [docs/10-dagitim.md](./docs/10-dagitim.md).
+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
 
-The full reference lives under [docs/](./docs/README.md). It is currently
-written in Turkish; translations are a welcome contribution.
+Full reference in Turkish under [docs/](./docs/README.md) and in English under
+[docs/en/](./docs/en/README.md). Both editions are kept in sync.
 
-| Document | Topic |
+| Document (TR / EN) | Topic |
 | --- | --- |
-| [01-baslangic](./docs/01-baslangic.md) | Installation, first route, first island, directory layout, CLI |
-| [02-mimari](./docs/02-mimari.md) | Decisions and their reasoning, middleware order |
-| [03-routing](./docs/03-routing.md) | Route modules, controller contract, load order |
-| [04-render-ve-sablonlar](./docs/04-render-ve-sablonlar.md) | Layout, components, helpers, metadata |
-| [05-islands](./docs/05-islands.md) | Island contract, hydration, store, DOM helpers |
-| [06-cache](./docs/06-cache.md) | TTL, stale-while-revalidate, keys, prewarm |
-| [07-yapilandirma](./docs/07-yapilandirma.md) | Complete `jskelet.config.mjs` reference |
-| [08-build](./docs/08-build.md) | Build pipeline, manifest, Tailwind `@source`, sprite |
-| [09-dev-araclari](./docs/09-dev-araclari.md) | Dev workflow, overlay, report page, dev gate |
-| [10-dagitim](./docs/10-dagitim.md) | Production, Docker, reverse proxy, health checks |
-| [11-tasima](./docs/11-tasima.md) | Migrating from Next.js: mapping table and plan |
-| [12-panel-ve-oturum](./docs/12-panel-ve-oturum.md) | Per-visitor pages: `private: true`, sessions, CSRF, fragments, swapping |
+| [01-baslangic](./docs/01-baslangic.md) / [getting-started](./docs/en/01-getting-started.md) | Installation, first route, first island, directory layout, CLI |
+| [02-mimari](./docs/02-mimari.md) / [architecture](./docs/en/02-architecture.md) | Decisions and their reasoning, middleware order |
+| [03-routing](./docs/03-routing.md) / [routing](./docs/en/03-routing.md) | Route modules, controller contract, load order |
+| [04-render](./docs/04-render-ve-sablonlar.md) / [rendering](./docs/en/04-rendering.md) | `.jsk` / EJS, layout, components, helpers, metadata |
+| [05-islands](./docs/05-islands.md) / [islands](./docs/en/05-islands.md) | Island contract, hydration, store, DOM helpers |
+| [06-cache](./docs/06-cache.md) / [caching](./docs/en/06-caching.md) | TTL, SWR, keys, prewarm, Redis, invalidation, admin |
+| [07-yapilandirma](./docs/07-yapilandirma.md) / [configuration](./docs/en/07-configuration.md) | Complete `jskelet.config.mjs` reference |
+| [08-build](./docs/08-build.md) / [build](./docs/en/08-build.md) | Build pipeline, manifest, Tailwind `@source`, sprite |
+| [09-dev](./docs/09-dev-araclari.md) / [dev-tools](./docs/en/09-dev-tools.md) | Dev workflow, overlay, report page, dev gate |
+| [10-dagitim](./docs/10-dagitim.md) / [deployment](./docs/en/10-deployment.md) | Production, Docker, reverse proxy, health checks |
+| [11-tasima](./docs/11-tasima.md) / [migration](./docs/en/11-migration.md) | Migrating from Next.js: mapping table and plan |
+| [12-panel](./docs/12-panel-ve-oturum.md) / [dashboards](./docs/en/12-dashboards-and-sessions.md) | Per-visitor pages: `private: true`, sessions, CSRF, fragments |
 
 If you work with AI agents, [AGENTS.md](./AGENTS.md) summarizes the rules that
 apply to this repository.
@@ -316,8 +345,8 @@ npm --prefix examples/marketing install && npm --prefix examples/marketing run d
 npm --prefix examples/dashboard install && npm --prefix examples/dashboard run dev
 ```
 
-- **`examples/minimal`** — two routes, one component, one island. The smallest
-  thing that runs.
+- **`examples/minimal`** — two routes, one component, one island, plus a
+  co-located `features/demo` slice. The smallest thing that runs.
 - **`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.

package/bin/jskelet.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * JSkelet CLI.
  *

package/docs/01-baslangic.md

@@ -2,7 +2,7 @@
 
 Bu belge JSkelet'i sıfırdan çalıştırmayı anlatır: paket kurulumu, `jskelet init`
 ile iskeletin oluşturulması, ilk route ve ilk island'ın yazılması, oluşan dizin
-yapısının ne anlama geldiği ve CLI'ın dört komutu. Sonunda tarayıcıda sunucuda
+yapısının ne anlama geldiği ve CLI komutları. Sonunda tarayıcıda sunucuda
 render edilmiş, önbelleğe alınmış ve island'ı görünürlükte hidre olan bir sayfa
 olacak. Kararların *nedenleri* için [02-mimari.md](./02-mimari.md)'ye, buradaki
 her config alanının tam referansı için
@@ -56,21 +56,24 @@ tamamlar, atlanan dosyaların sayısını uyarı olarak basar. Amaç, "kurulumu
 yaptım ama hiçbir şey çalışmıyor" aşamasını tamamen atlamak — `jskelet dev`
 hemen ardından çalışır.
 
-Oluşturulan dosyalar:
+Oluşturulan dosyalar (feature-first + `.jsk`):
 
 ```
-jskelet.config.mjs          config: brand, preconnect, cache(), hooks
-routes/10-pages.mjs         "/" route'u
-views/pages/home.ejs        ana sayfa şablonu
-views/pages/not-found.ejs   404 şablonu
-views/components/button.js  örnek bileşen (HTML string döndüren fonksiyon)
-client/entries/main.js      island bootstrap'ı
-client/islands/counter.js   örnek island
-styles/globals.css          Tailwind girişi + @source direktifleri
-jsconfig.json               checkJs + "@/*" alias'ı
-.gitignore                  node_modules/, .jskelet/, public/assets/, .env
+jskelet.config.mjs                       config: brand, preconnect, cache(), hooks
+features/home/index.js                   "/" route'u
+features/home/views/pages/home.jsk       ana sayfa şablonu
+features/home/views/components/button.js örnek bileşen (<Button />)
+features/home/client/counter.js          örnek island
+features/home/server/.gitkeep
+views/pages/not-found.jsk                uygulama geneli 404
+client/entries/main.js                   island bootstrap'ı
+styles/globals.css                       Tailwind girişi + @source direktifleri
+jsconfig.json                            checkJs + "@/*" alias'ı
+.gitignore                               node_modules/, .jskelet/, public/assets/, .env
 ```
 
+Büyümek için: `npx jskelet generate feature <name>` (veya `page` / `island`).
+
 Sonra:
 
 ```bash
@@ -88,44 +91,44 @@ ile ezilebilir. Aşağıdaki değerler varsayılanlardır (`src/config/defaults.
 
 | Dizin | Varsayılan | İçeriği |
 | --- | --- | --- |
-| `views` | `views` | EJS layout, sayfalar ve bileşenler |
+| `views` | `views` | Uygulama geneli layout, sayfalar ve bileşenler |
+| `features` | `features` | Feature dilimleri (`<name>/{server,views,client}`) |
+| `shared` | `shared` | Feature'lar arası paylaşılan server/views/client |
 | `public` | `public` | Statik dosyalar; build çıktısı da buraya yazılır |
 | `client` | `client` | Island runtime kaynakları ve entry'ler |
-| `routes` | `routes` | Route modülleri |
+| `routes` | `routes` | Route modülleri (feature'lardan önce yüklenir) |
 | `styles` | `styles/globals.css` | Tailwind/PostCSS giriş **dosyası** |
-| `generated` | `.jskelet` | Build ara çıktıları: `manifest.json`, `metafile.json`, `images.json` |
+| `generated` | `.jskelet` | Build ara çıktıları: `manifest.json`, `metafile.json`, `images.json`, `templates/` |
 
 Bunlara ek olarak framework iki yolu her zaman türetir ve ayrı ayar kabul
 etmez: `public/assets` (hash'li build çıktısı) ve `public/fonts` (self-host
 fontlar).
 
-Tipik bir proje:
+Tipik bir proje (`jskelet init` çıktısına yakın):
 
 ```
 benim-sitem/
 ├── jskelet.config.mjs
 ├── jsconfig.json
-├── routes/
-│   ├── 10-pages.mjs
-│   └── 90-catch-all.mjs
+├── features/
+│   └── home/
+│       ├── index.js
+│       ├── server/
+│       ├── views/
+│       │   ├── pages/home.jsk
+│       │   └── components/button.js
+│       └── client/counter.js
 ├── views/
-│   ├── layout.ejs
-│   ├── pages/
-│   │   ├── home.ejs
-│   │   └── not-found.ejs
-│   └── components/
-│       └── card.js
+│   └── pages/not-found.jsk
 ├── client/
-│   ├── entries/
-│   │   └── main.js
-│   └── islands/
-│       └── counter.js
+│   └── entries/main.js
 ├── styles/
 │   └── globals.css
 ├── public/
 │   └── (statik dosyalar; build → public/assets)
 └── .jskelet/
-    └── manifest.json
+    ├── manifest.json
+    └── templates/
 ```
 
 ## İlk route
@@ -135,7 +138,7 @@ kendi yollarını `app.get(...)` ile açıkça yazar. Modül sözleşmesi: defau
 export ya da `register` adlı named export, `(app, api)` imzasıyla.
 
 ```js
-// routes/10-pages.mjs
+// features/home/index.js
 export default function register(app, { route }) {
   app.get(
     "/",
@@ -143,7 +146,7 @@ export default function register(app, { route }) {
       async () => ({
         view: "pages/home",
         metadata: { title: "Ana sayfa" },
-        data: { heading: "JSkelet çalışıyor", items: ["Bir", "İki"] },
+        data: { message: "JSkelet çalışıyor" },
       }),
       { revalidate: 60 },
     ),
@@ -157,25 +160,26 @@ yapmak zorunda kalmaz. `route()` controller'ı sarar: HTML cache'i,
 notFound/redirect kontrol akışı, sıkıştırma ve `X-JSkelet-Cache` başlığı ondan
 gelir. Controller'ın tek işi bir sayfa tanımı döndürmektir.
 
-Dosya adındaki `10-` öneki yükleme sırasını belirler. `routes/` alfabetik
-tarandığı için `/:slug` gibi yakalayıcı route'ları daha yüksek numaralı bir
-dosyaya koymalısınız; aksi hâlde `/hakkinda` bir slug sanılır. Ayrıntı:
-[03-routing.md](./03-routing.md).
+`routes/` kullanıyorsanız dosya adındaki `10-` öneki yükleme sırasını belirler;
+`/:slug` gibi yakalayıcı route'ları daha yüksek numaralı bir dosyaya koyun.
+Feature `index.js` dosyaları `routes/` tarandıktan sonra alfabetik eklenir.
+Ayrıntı: [03-routing.md](./03-routing.md).
 
-Şablon tarafı düz EJS:
+Şablon tarafı `.jsk` (build-time derlenir):
 
-```ejs
-<%# views/pages/home.ejs %>
+```html
+{# features/home/views/pages/home.jsk #}
 <section class="wrapper">
-  <h1 class="text-3xl font-bold"><%= heading %></h1>
-  <%- list({ items }) %>
-  <div data-island="counter" data-island-props='{"start":5}'></div>
+  <h1>{{ metadata.title }}</h1>
+  <p>{{ message }}</p>
+  <Button text="Örnek bileşen" />
+  <div data-island="counter" data-island-props='{"start":0}'></div>
 </section>
 ```
 
-`list` burada `views/components/list.js` içinde tanımlı bir fonksiyondur ve
-import edilmemiştir: `views/components/**` altındaki her named export otomatik
-olarak şablon local'i olur ([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)).
+`Button`, `features/home/views/components/button.js` içindeki `button` named
+export'undan gelir — PascalCase etiket; import gerekmez
+([04-render-ve-sablonlar.md](./04-render-ve-sablonlar.md)).
 
 ## İlk island
 
@@ -193,7 +197,7 @@ iki parçadan oluşur.
 verir.
 
 ```js
-// client/islands/counter.js
+// features/home/client/counter.js
 /**
  * @param {HTMLElement} element
  * @param {{ start?: number }} props
@@ -225,7 +229,7 @@ runtime'ı başlatır.
 import { registerAll, start } from "jskelet/client";
 
 registerAll({
-  counter: () => import("../islands/counter.js"),
+  counter: () => import("../../features/home/client/counter.js"),
 });
 
 start();
@@ -239,7 +243,7 @@ haritayı büyütmek ilk yükü büyütmez. Hidrasyon stratejileri
 
 ## CLI komutları
 
-`bin/jskelet.mjs` dört alt komut sunar. Her biri ayrı bir Node sürecinde
+`bin/jskelet.mjs` şu alt komutları sunar. Her biri ayrı bir Node sürecinde
 çalışır; sebebi `dev`in iki uzun ömürlü süreci yönetmesi ve sunucunun ESM
 resolve hook'larına (`--import`) süreç başlangıcında ihtiyaç duyması.
 
@@ -248,7 +252,8 @@ resolve hook'larına (`--import`) süreç başlangıcında ihtiyaç duyması.
 | `jskelet dev` | Build watch + sunucu, tek terminalde. Canlı yenileme, CSS hot-swap, dev overlay. `NODE_ENV=development`. |
 | `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 init` | Bulunduğun dizine minimal iskelet kurar; var olan dosyalara dokunmaz. |
+| `jskelet init` | Bulunduğun dizine feature-first `.jsk` iskeleti kurar; var olan dosyalara dokunmaz. |
+| `jskelet generate` | `feature` / `page` / `island` iskeleti üretir. |
 
 Bilinmeyen bir komut ya da argümansız çağrı kullanım metnini basar.