create-ginko 0.0.0-stage → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# create-ginko
+
+## 0.5.0
+
+### Minor Changes
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add the blog template (`--template blog`): posts with tags, authors, reading time, older and newer links, and an RSS feed per language. The company and nonprofit news pages gain the same tag pages, reading time and older/newer links.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add `--template <name>` and `--locales <codes>`: a complete starter site from Ginko's templates, with the languages you pick (the first is the main one) and its sample dates moved to the current week; `--preset` and `--locale` still work and print that they are deprecated.
+
+### Patch Changes
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix the example command after the list of templates: it names the starter, the template to begin with.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `--template`: a restaurant site now opens with the current lunch week, since the lunch `weekOf` date moves with the other sample dates.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `--template` sites on Nuxt 5: the font preload plugin and the news feed now type-check, because they use `useServerHooks()` and a relative import of `ginko.config.ts`.
+
+- [#23](https://github.com/lupinum-dev/ginko/pull/23) [`7b165c2`](https://github.com/lupinum-dev/ginko/commit/7b165c25e17ed2f4fb50e8054febf618a6af10d7) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `--locales` with a new main language for content whose translation has no frontmatter (only text): the main file's fields, such as a changelog's version and date, now move to the new main file instead of failing the build.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `--locales` with another main language: an image keeps its file when only its alt text is translated.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `--locales` with another main language: a nested content field it cannot read now stops the copy with the file and field named, instead of being swapped whole and failing the site's build later.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix `--locales` with another main language: a translated photo text or list (gallery, lunch days, closures) now keeps its photo, prices and dates in the new main file instead of failing the build.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix the gastro starter's menu page: it leaves out a dish turned off with "onMenu" and marks a dish sold out today, by the preset's `dishOn` rule.
+
+- [#21](https://github.com/lupinum-dev/ginko/pull/21) [`80f93a4`](https://github.com/lupinum-dev/ginko/commit/80f93a4f6bd171e1146b929913254039becdd991) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Fix --locales with a new main language: fields only the main file has move to the new main file, and the old main page keeps its address.
+
+## 0.4.0
+
+### Minor Changes
+
+- [`ea2ea13`](https://github.com/lupinum-dev/ginko/commit/ea2ea133997f2011ad0d43f77a0f1dc75605923e) Thanks [@Mat4m0](https://github.com/Mat4m0)! - Add Ginko 0.4, the first release: one content system for Nuxt websites, from Markdown files in Git to a hosted platform.
+  
+  Owners, staff and AI agents edit the same content. All seven packages release together under one version. It starts at 0.4 because `@lupinum/ginko-content` and `@lupinum/ginko-docs` already published an older, unrelated line up to 0.3. Until 1.0, a minor version (0.4 → 0.5) may contain breaking changes; the changelog names each one and how to update.
+  
+  Requirements: Node 22.18+, 24 or 26, and Nuxt 4.6+ or Nuxt 5 (tested on its nightly until it is released). Start a site with `npm create ginko@latest my-site`; the documentation explains every step.
+  
+  **Public API**
+  
+  - `@lupinum/ginko`: `defineSite`, `single`, `collection`, `f`, `defineComponents`, `formatMoney`, `plainText`, `safeHref`, `startOfWeek` and the documented types. Imported, not auto-imported.
+  - `@lupinum/ginko/nuxt`: the module, the `useGinko*` composables (everything that needs a Nuxt app starts with `useGinko`), `<GinkoMarkdown>` and `<GinkoImage>`. `@lupinum/ginko/vue`: `<GinkoMarkdown>` for any Vue app. `@lupinum/ginko/search`: `loadIndex` and `search`.
+  - `@lupinum/ginko/internal` and `@lupinum/ginko/internal/search` are for Ginko's own packages and have no stability promise.
+  - The `ginko` CLI: `check [--offline]`, `release` and `export [folder]`, plus `--version`. Every command run prints one JSON line, `{ "ok": true, … }` or `{ "ok": false, "error": { code, message } }` (`--help` and `--version` print plain text), and ends with exit code 0 (ok), 1 (fix the code), 2 (usage), 3 (platform unreachable, retry) or 4 (key not allowed). CI deploys the site only when `release` prints `"deploy": true` (a superseded run exits 0 with `"deploy": false`). The CLI reads `GINKO_PLATFORM` (or `NUXT_PUBLIC_GINKO_PLATFORM`), `GINKO_KEY`, `GINKO_COMMIT` (or `GITHUB_SHA`), `GINKO_BRANCH` and `GINKO_REMOTE`; it does not read `.env` files. `ginko-i18n --json` uses the same output shape, error codes (`USAGE`, `INVALID`) and exit codes.
+  - Config names: `f.ref` (one entry) and `f.refs` (several); `visible: { mode: 'until', field, days?, deleteExpired? }`; prefill tokens `@today`, `@workWeek`, `@nextWorkWeek`; `firstDayOfWeek`, `linkCheck`, `untranslated`, `maxBytes`, `Migration.compute`, `retired` rule `{ drop: true }`. Options and defaults are typed per field, and an unknown top-level key fails the build.
+  - Markdown components: `embed`, `frame` (`none`, `card`, `border`, …), `background` (`none`, `muted`, `tint`), `appearance` (`quiet`, `tint`), `quiz-question{mode}`, `code-tree{file}`.
+  
+  **Content (`@lupinum/ginko`, `@lupinum/ginko-content`)**
+  
+  - One text format: Markdown (comark 0.7) everywhere, with field profiles that limit what a field may contain. Footnotes, emoji, alerts, Shiki code, task lists, route links (`$blog.my-post`), reusable snippets and heading anchors.
+  - Data files: YAML and JSON (one file, one entry) and CSV (one file, many entries), checked against the field schema; every error names the file and field, and the line for CSV rows and unreadable files. Entries with `draft: true` stay out of production builds.
+  - Query engine in the site, over the loaded bundle: `where`, `order`, `limit`, pagination with totals, field selection, `include` for references, previous/next and facet counts.
+  - References (`f.ref`, `f.refs`), navigation trees and breadcrumbs, and a URL for every entry in every language; two entries on one URL fail the build.
+  - Link check before any HTML exists: route links, anchors, snippets and redirected paths, in the build, the dev terminal, `ginko check` and the agent tools. On the platform a save, a new entry or a scheduled publish that adds a broken link is stopped, and History says why. External links are checked on request (`linkCheck.external`), at build and in `ginko check` (never in dev), with a 7-day cache.
+  - Images: WebP copies at 480, 960 and 1600 px, made at upload on the platform and at build for files. `<GinkoImage>` and Markdown images get `srcset` and `sizes`.
+  - Redirects from `redirectFrom` (301) and site rules in `redirects` (301 by default, `status` 302/307/308 per rule).
+  - SEO from the bundle, with no other module: title template, canonical, Open Graph with `og:url`, `<html lang>`, hreflang with `x-default`, sitemap with `lastmod`, images and alternates, robots.txt with `noindex` on preview hosts, JSON-LD. With `nuxt-og-image` (in every starter), every page gets a generated share card in the brand colour `seo.color`, with the site's logo and the page's image.
+  - Works with the Nuxt SEO modules (`@nuxtjs/seo` or single ones, in any order): Ginko leaves them sitemap, robots.txt and JSON-LD defaults and hands them its pages with hreflang, the site's address, name and languages, and `noindex` on preview hosts. `nuxt-ai-ready` stays off while Ginko serves `/llms.txt`. Requires `nuxt-og-image` 7.
+  - Search index built in plain JS at build time, one record per heading section, loaded lazily per language.
+  - Agent output: `/llms.txt`, `/llms-full.txt`, a `.md` twin for every entry page (collections with a `route`), and a Markdown 404 that suggests pages. The normal address always answers with HTML.
+  - Render modes: Git-only sites prerender everything; platform sites refresh changed pages after a publish; previews render with `noindex`.
+  - In dev, `nuxt dev` restarts when `ginko.config.ts` changes, and a brick that cannot reach the platform names itself and the fix.
+  - CLI `ginko`: `check` (schema, links and the share image, for every site; `--offline` without the platform) and `release` for CI, `export` for backups; `pnpm local:dev|import|pull` run only in the Ginko monorepo.
+  
+  **Languages (`@lupinum/ginko-i18n`)**
+  
+  - The only locale authority: routes, alternates, hreflang, messages with plurals, and formatters for dates, ranges, relative time, numbers, currency and lists, each in the site's time zone.
+  - Works on its own in any Nuxt 4.6+ or Nuxt 5 app, without the rest of Ginko.
+  
+  **Components and docs (`@lupinum/ginko-components`, `@lupinum/ginko-docs`)**
+  
+  - Content components with props defined as Ginko fields: callouts, tabs, code groups, steps, cards, accordion, figures, embeds (click to load), timeline, quiz and more. Each one can also be copied into an app with the shadcn-vue CLI, from a registry the docs build generates.
+  - Docs layer (`@lupinum/ginko-docs`; `npm create ginko@latest my-docs -- --preset docs` starts a site with it): navigation, section tabs, breadcrumbs, table of contents with scroll spy, previous/next, ⌘K search with heading results, blog with authors and RSS, changelog, copy page as Markdown, dark mode. A guide for switching from Nuxt Content and `@nuxtjs/i18n`. Math (KaTeX) and mermaid diagrams render and load only on pages that use them.
+  
+  **Platform and Studio (hosted by Lupinum)**
+  
+  The platform is a hosted service, not an npm package. A site connects to it with one setting; without it, the site reads its content from files.
+  
+  - Quick tasks for the jobs owners do most ("Heute geschlossen", "Preis ändern"), phone first, with the full form behind "Alles bearbeiten".
+  - Files library: All, Recent, Unused, Missing alt text, Duplicates and folders; icon and list views; "used in" with links; replace a file and keep its references; a used file cannot be removed by mistake. Alt text set in the library is the default for every use, per language.
+  - Approvals, off by default: a task or agent key can need a yes. Reviewers see the change, approve, approve for a time, or reject with a sentence; the author sees the reason. Releases publish several changes together.
+  - History with "show changes", "back to this version" and undo; drafts and scheduled publishing; trash with restore; translation status per language; "why is this not on the website?".
+  - Team and invitations with per-task rights, sign-in with an emailed code, AI agent keys with an MCP tool catalog derived from the operations, and weekly reminder mails.
+  - Long forms group their fields under headings or in tabs (`group` on a field, `layout: 'tabs'` on a brick); phones always show headings.
+  - A rich text editor (TipTap 3) that writes Markdown, where untouched text stays byte for byte. Headings, lists, task lists, quotes, code blocks, tables, images from the library, embeds, registry components with prop forms, slash and bubble menus, Markdown shortcuts and paste, source mode, find and replace (⌘F), a drag handle and Alt+↑/↓ to move blocks, character counter, a link card for pasted URLs, uploads with progress, and a formatting bar above the phone keyboard.
+  - Delete a site, with seven days to cancel, and delete your own account. The last owner of a site must hand it over or delete it first.
+  - Studio in German, English and Spanish (beta), light and dark.
+  
+  **Presets (`@lupinum/ginko-preset-gastro`, `create-ginko`)**
+  
+  - Gastro: opening hours with exceptions, seasons, holidays and new hours from a date; lunch week with planning ahead and an optional PDF; menu with prices from a date; notices that expire; events; JSON-LD for Restaurant, Menu, opening hours and Event; a printable lunch sheet.
+  - `create-ginko` starts a new site, plain or with `--preset gastro|docs`. Starters install with npm, pnpm 11 and bun, carry a `typecheck` script, a page description and share cards (`nuxt-og-image` with Takumi, Nuxt 4.6.1 or later; set `NUXT_APP_SECRET` where the site runs, `.env` has one), and create-ginko warns on an unsupported Node.
+  
+  **Not in 0.4**
+  
+  Real-time co-editing comes next. Also not included: an agency preset, the editor UI as a shadcn-vue registry, OAuth for agent connectors, and a Google Business sync.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Lupinum OG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# create-ginko
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Start a Nuxt site with [Ginko](https://github.com/lupinum-dev/ginko/tree/main/packages/ginko):
+
+```bash
+npm create ginko@latest my-site
+cd my-site
+npm install
+npm run dev
+```
+
+The new site reads its content from Markdown in `content/` and needs no platform. To let an owner
+edit a brick on the Ginko platform instead, remove `source: 'files'` from it in `ginko.config.ts`,
+and give the single's required fields a `default` or make them optional (`f.markdown`, `f.image` and `f.file` cannot have a default, so set `optional: true` on them). See
+[Platform and CLI](https://github.com/lupinum-dev/ginko/blob/main/sites/docs/content/docs/12.plattform-und-cli.en.md).
+
+Without options it creates the plain starter in English; `--locales de` creates it in German.
+
+The site id (`site` in `ginko.config.ts`) comes from the folder name: lower case, every run of other characters
+becomes `-`, at most 40 characters, and it must start with a letter. When the id differs from the folder name, the
+command says so. Change `site` in `ginko.config.ts` if you want another id.
+
+## Options
+
+Write the options after `--`. npm keeps options before `--` for itself and passes on only their values; the
+command then stops and shows the right form. pnpm, yarn and bun accept the same command.
+
+```bash
+npm create ginko@latest my-site -- --template starter
+npm create ginko@latest my-site -- --locales de
+```
+
+| Option | Values | Default |
+|---|---|---|
+| `--template <name>` (or `--template=<name>`) | a bundled template: `starter` | the plain starter |
+| `--locales <codes>` (or `--locales=<codes>`) | the languages to keep, comma-separated; the first is the main language. A template offers its own languages (`--help` and the end of each run list them); the plain starter has `en` or `de`, one at a time. | all of the template's languages; `en` for the plain starter |
+| `--preset <name>` | deprecated, use `--template`: `gastro`, `docs` | |
+| `--locale <code>` | deprecated, use `--locales`: `en`, `de` | |
+| `-h`, `--help` | | |
+
+With `--template`, the command copies the template, keeps only the languages of `--locales` (their content files,
+`i18n/<code>.json` and their entries in the route maps), moves the dates of upcoming sample entries (such as events and notices) by
+whole weeks to this week, sets the site id and writes a `.env` with `NUXT_APP_SECRET`.
+
+The command always says which starter and languages it used. An unknown option, template, preset or locale stops
+with exit code 2 (a usage error, as in the `ginko` CLI) and creates nothing. A folder that exists and is not
+empty stops with exit code 1.
+
+## Presets (deprecated)
+
+`--preset` still works for now and prints a note; use `--template` instead.
+
+| Preset | Package | What the starter shows | Platform needed? |
+|---|---|---|---|
+| `gastro` | `@lupinum/ginko-preset-gastro` | Opening hours and a menu, both read from files | Only for the preset's other bricks (notices, lunch, events, gallery) and the owner's quick tasks. The starter itself runs without it. |
+| `docs` | `@lupinum/ginko-docs` | The docs layer (navigation, search) with two pages in `content/docs/` | No |
+
+Each preset is a small folder in `presets/` that is copied over `template/`; `presets/<name>-de` is its German
+version. `template-de/` holds the German sample text of the plain starter.
+
+## License
+
+MIT © Lupinum OG

package/index.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// npm create ginko <folder> [-- --template <name>] [--locales a,b]: copies a template into a new folder and sets the
+// site id and the Ginko versions. The Ginko packages release together, so they get this package's own version.
+// --template: a complete site from templates/<name> (bundled by build.mjs from the repository's templates/). Its
+// languages are pruned to --locales (template-files.mjs), its sample dates move to this week, and its site id is set.
+// Without --template: the plain starter in template/ (German: template-de/ over it). --preset (deprecated) copies a
+// small folder from presets/ over the plain starter and adds the preset's packages; `<preset>-de` is its German one.
+import { randomBytes } from 'node:crypto'
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { supportsNode } from './node-version.mjs'
+import { pruneLocales, shiftDates, weeksShift } from './template-files.mjs'
+
+// preset name -> the packages it adds (its own package, then the Ginko peers of that package that the base template
+// lacks; test/create-ginko.test.ts checks this against the packages' metadata), and what the next steps say about it
+const presets = {
+  gastro: { packages: ['@lupinum/ginko-preset-gastro'], note: 'Hours and menu read from files. The preset\'s other bricks (notices, lunch, events, gallery) and the owner\'s quick tasks need the Ginko platform.' },
+  docs: { packages: ['@lupinum/ginko-docs'], note: 'Pages are Markdown files in content/docs. No platform needed.' },
+}
+const langs = { en: 'English', de: 'German' }
+// The templates bundled into this package (build.mjs); none in a repository checkout before `pnpm build`.
+const templatesDir = new URL('./templates/', import.meta.url)
+const templates = existsSync(templatesDir) ? readdirSync(templatesDir).filter((name) => statSync(new URL(name, templatesDir)).isDirectory()).sort() : []
+/** Each bundled template's languages, from its manifest (build.mjs). */
+const templateLocales = Object.fromEntries(templates.map((name) => [name, JSON.parse(readFileSync(new URL(`${name}.json`, templatesDir), 'utf8')).locales]))
+const command = 'npm create ginko@latest'
+const usage = `Usage: ${command} <folder> -- [--template <name>] [--locales <codes>]
+
+Creates a Nuxt site with Ginko that reads its content from Markdown files.
+
+  --template <name>   start from a template: ${templates.join(', ') || '(none bundled)'}
+  --locales <codes>   the languages to keep, comma-separated; the first is the main language
+                      (default: all of the template's; without --template: en or de)
+  --preset <name>     deprecated: the older starters gastro (restaurant) and docs (documentation)
+  --locale <code>     deprecated: use --locales
+  -h, --help          show this help
+
+With npm, write -- before the options. Without it, npm keeps them for itself.`
+
+/** Prints the problem and the usage, and stops without creating anything. Exit 2 is a usage error, as in `ginko`. */
+function fail(message) {
+  console.error(`${message}\n\n${usage}`)
+  process.exit(2)
+}
+
+const args = process.argv.slice(2)
+const options = { '--template': undefined, '--locales': undefined, '--preset': undefined, '--locale': undefined }
+let target
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]
+  // pnpm and yarn may pass the `--` of `pnpm create ginko my-site -- --template starter` through.
+  if (arg === '--') continue
+  if (arg === '-h' || arg === '--help') { console.log(usage); process.exit(0) }
+  const [name, inline] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined]
+  if (Object.hasOwn(options, name)) {
+    const value = inline ?? args[++i]
+    if (!value || value.startsWith('-')) fail(`${name} needs a value.`)
+    options[name] = value
+  }
+  else if (arg.startsWith('-')) fail(`Unknown option "${arg}".`)
+  else if (target === undefined) target = arg
+  // npm drops an option written without `--` and passes only its value, so a second name is almost always that.
+  else if (templates.includes(arg)) fail(`Unexpected argument "${arg}". npm drops --template when it comes before --. Write:\n  ${command} ${target} -- --template ${arg}`)
+  else if (Object.hasOwn(presets, arg)) fail(`Unexpected argument "${arg}". npm drops --preset when it comes before --. Write:\n  ${command} ${target} -- --preset ${arg}`)
+  else if (Object.hasOwn(langs, arg)) fail(`Unexpected argument "${arg}". npm drops --locales when it comes before --. Write:\n  ${command} ${target} -- --locales ${arg}`)
+  else fail(`Unexpected argument "${arg}". Give one folder name.`)
+}
+const { '--template': template, '--preset': preset } = options
+// The old flags still work for one minor release; each says what replaces it.
+if (preset !== undefined) console.warn(`Note: --preset is deprecated and will be removed; use --template <name> (${templates.join(', ')}).`)
+if (options['--locale'] !== undefined) console.warn('Note: --locale is deprecated and will be removed; use --locales.')
+if (options['--locale'] !== undefined && options['--locales'] !== undefined) fail('Use --locales, not both --locales and --locale.')
+if (template !== undefined && preset !== undefined) fail('Use --template or --preset, not both.')
+const locales = (options['--locales'] ?? options['--locale'])?.split(',').map((code) => code.trim()).filter((code, i, all) => code && all.indexOf(code) === i)
+if (locales?.length === 0) fail('--locales needs at least one language code.')
+if (template !== undefined && !templates.includes(template)) {
+  fail(templates.length ? `Unknown template "${template}". Choose one of: ${templates.join(', ')}.` : 'This copy of create-ginko has no templates. In the Ginko repository, run `pnpm build` first.')
+}
+const manifest = template && JSON.parse(readFileSync(new URL(`${template}.json`, templatesDir), 'utf8'))
+if (manifest) {
+  const unknown = (locales ?? []).filter((code) => !manifest.locales.includes(code))
+  if (unknown.length) fail(`Unknown locale ${unknown.map((code) => `"${code}"`).join(', ')}. The ${template} template has: ${manifest.locales.join(', ')}.`)
+}
+if (preset !== undefined && !Object.hasOwn(presets, preset)) {
+  fail(`Unknown preset "${preset}". Choose one of: ${Object.keys(presets).join(', ')}.`)
+}
+// The plain starter and the presets have one language each.
+const lang = template ? undefined : locales?.[0] ?? 'en'
+if (!template && locales && locales.length > 1) fail(`The ${preset ? `${preset} preset` : 'plain starter'} has one language. Choose one of: ${Object.keys(langs).join(', ')}, or use a --template.`)
+if (lang !== undefined && !Object.hasOwn(langs, lang)) fail(`Unknown language "${lang}". Choose one of: ${Object.keys(langs).join(', ')}.`)
+const presetDir = preset && (lang === 'en' ? preset : `${preset}-${lang}`)
+if (presetDir && !existsSync(new URL(`./presets/${presetDir}`, import.meta.url))) {
+  fail(`The ${preset} preset has no ${langs[lang]} version yet. Leave out --locales ${lang}.`)
+}
+if (!target) fail('Give the name of the folder to create.')
+const dir = resolve(target)
+if (existsSync(dir) && readdirSync(dir).length) {
+  console.error(`The folder ${target} exists and is not empty. Choose another name.`)
+  process.exit(1)
+}
+const site = basename(dir).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'my-site'
+if (!/^[a-z]/.test(site)) {
+  console.error(`The site id "${site}" must start with a letter. Choose another folder name.`)
+  process.exit(1)
+}
+const own = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+// A warning, not an error: the site is still created, and the user may run it on another Node.
+if (!supportsNode(process.versions.node, own.engines.node)) {
+  console.warn(`Warning: Ginko needs Node ${own.engines.node}, but this is Node ${process.versions.node}. The site is created, but install and dev may fail or print warnings. Switch to a supported Node version before you run "install".\n`)
+}
+/** A language's English name (`de` → German), for the messages. */
+const languageName = (code) => langs[code] ?? new Intl.DisplayNames(['en'], { type: 'language' }).of(code) ?? code
+const writeJson = (path, value) => writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`)
+let chosen = lang ? [lang] : manifest.locales
+let moved = 0
+if (template) {
+  cpSync(new URL(template, templatesDir), dir, { recursive: true })
+  if (existsSync(join(dir, 'gitignore'))) renameSync(join(dir, 'gitignore'), join(dir, '.gitignore'))
+  chosen = locales ?? manifest.locales
+  if (chosen.join() !== manifest.locales.join()) {
+    try {
+      pruneLocales(dir, manifest.locales, chosen)
+    } catch (error) {
+      rmSync(dir, { recursive: true, force: true })
+      console.error(`Could not set the languages: ${error.message}`)
+      process.exit(1)
+    }
+  }
+  const config = join(dir, 'ginko.config.ts')
+  writeFileSync(config, readFileSync(config, 'utf8').replace(/(\bsite:\s*)(['"])[^'"]*\2/, `$1'${site}'`))
+  const path = join(dir, 'package.json')
+  const pkg = JSON.parse(readFileSync(path, 'utf8'))
+  pkg.name = site
+  for (const field of ['dependencies', 'devDependencies']) {
+    for (const name of Object.keys(pkg[field] ?? {})) if (name.startsWith('@lupinum/ginko')) pkg[field][name] = `^${own.version}`
+  }
+  // Sample dates move by whole weeks to today (spec T10), so a new site does not open with past events.
+  const anchor = pkg.ginko?.sampleAnchor
+  if (anchor) {
+    const days = weeksShift(anchor, new Date().toISOString().slice(0, 10))
+    moved = shiftDates(dir, manifest.shift, days).length
+    pkg.ginko.sampleAnchor = new Date(Date.parse(`${anchor}T00:00:00Z`) + days * 864e5).toISOString().slice(0, 10)
+  }
+  // Which shared sources the template uses matters only inside the Ginko repository.
+  if (pkg.ginko) delete pkg.ginko.features
+  writeJson(path, pkg)
+}
+else {
+  cpSync(new URL('./template', import.meta.url), dir, { recursive: true })
+  // npm drops .gitignore from published packages, so the template carries it as `gitignore`.
+  renameSync(join(dir, 'gitignore'), join(dir, '.gitignore'))
+  if (presetDir) {
+    // The base page and sample text give way to the preset's own.
+    rmSync(join(dir, 'content/start.md'))
+    rmSync(join(dir, 'app/pages/index.vue'))
+    cpSync(new URL(`./presets/${presetDir}`, import.meta.url), dir, { recursive: true })
+  }
+  else if (lang !== 'en') cpSync(new URL(`./template-${lang}`, import.meta.url), dir, { recursive: true })
+  for (const file of ['package.json', 'ginko.config.ts']) {
+    const path = join(dir, file)
+    writeFileSync(path, readFileSync(path, 'utf8').replaceAll('{{SITE}}', site).replaceAll('{{VERSION}}', own.version))
+  }
+  if (preset) {
+    const path = join(dir, 'package.json')
+    const pkg = JSON.parse(readFileSync(path, 'utf8'))
+    for (const name of presets[preset].packages) pkg.dependencies[name] = `^${own.version}`
+    pkg.dependencies = Object.fromEntries(Object.entries(pkg.dependencies).sort(([a], [b]) => a.localeCompare(b)))
+    writeJson(path, pkg)
+  }
+}
+
+// The share cards (nuxt-og-image) sign their URLs with this secret; `nuxt dev` and `nuxt preview` read .env.
+writeFileSync(join(dir, '.env'), `# Signs the share card URLs. Set the same variable where the site runs.\nNUXT_APP_SECRET=${randomBytes(32).toString('hex')}\n`)
+
+// The next steps name the package manager that ran us (npm, pnpm, yarn or bun), and quote a folder a shell would split.
+const agent = (process.env.npm_config_user_agent ?? '').split('/')[0]
+const pm = ['pnpm', 'yarn', 'bun'].includes(agent) ? agent : 'npm'
+const cd = /^[\w./-]+$/.test(target) ? target : `'${target.replaceAll('\'', '\'\\\'\'')}'`
+const from = template ? `the ${template} template` : preset ? `the ${preset} preset` : 'the plain starter'
+console.log(`Created ${target} from ${from} in ${chosen.map(languageName).join(' and ').replace(/ and (?=.* and )/g, ', ')}.`)
+if (site !== basename(dir)) console.log(`The site id is "${site}": the folder name in lower case, with other characters replaced by "-", at most 40 characters. Change \`site\` in ginko.config.ts to use another one.`)
+if (moved) console.log(`The sample dates in ${moved} content file${moved === 1 ? '' : 's'} moved to this week.`)
+if (preset) console.log(presets[preset].note)
+// npm keeps options for itself unless they come after --; pnpm, yarn and bun pass them on.
+// The example names the starter, the neutral start, also when other templates sort before it.
+const sample = templates.includes('starter') ? 'starter' : templates[0] ?? 'starter'
+const example = pm === 'npm' ? `${command} my-site -- --template ${sample}` : `${pm} create ginko my-site --template ${sample}`
+console.log(`Templates (languages for --locales): ${templates.map((name) => `${name} (${templateLocales[name].join(', ')})`).join(', ')}.${pm === 'npm' ? ' With npm, put -- before the options:' : ''}
+  ${example}
+
+Next:
+
+  cd ${cd}
+  ${pm} install
+  ${pm} run dev
+
+Before you deploy, set NUXT_APP_SECRET where the site runs (any 32 or more random characters, .env has one).
+Without it, the share cards of a server-rendered site answer with an error; a static build needs none.
+`)

package/node-version.mjs

@@ -0,0 +1,10 @@
+// Is this Node version inside an `engines.node` range of caret alternatives ("^22.18.0 || ^24.0.0")?
+// Only that shape is supported: it is what all Ginko packages declare.
+export function supportsNode(version, range) {
+  const [major, minor, patch] = version.split('.').map(Number)
+  return range.split('||').some((alternative) => {
+    const [wantMajor, wantMinor = 0, wantPatch = 0] = alternative.trim().replace(/^\^/, '').split('.').map(Number)
+    if (major !== wantMajor) return false
+    return minor > wantMinor || (minor === wantMinor && patch >= wantPatch)
+  })
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "create-ginko",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.0",
+  "type": "module",
+  "description": "Start a Ginko site: npm create ginko my-site",
+  "bin": {
+    "create-ginko": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "node-version.mjs",
+    "template-files.mjs",
+    "template",
+    "template-de",
+    "presets",
+    "templates",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "author": "Lupinum OG <info@lupinum.com> (https://lupinum.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lupinum-dev/ginko.git",
+    "directory": "packages/create-ginko"
+  },
+  "homepage": "https://github.com/lupinum-dev/ginko",
+  "bugs": {
+    "url": "https://github.com/lupinum-dev/ginko/issues"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs"
+  }
 }

package/presets/docs/app/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/presets/docs/content/docs/1.getting-started.md

@@ -0,0 +1,12 @@
+---
+title: Getting started
+description: What this site is and how to add a page.
+---
+
+## Add a page
+
+Every page is a Markdown file in `content/docs/`. The number before the name sets the order in the side navigation.
+
+## Next
+
+Read [Writing pages]($docs.writing-pages) to see the frontmatter fields.

package/presets/docs/content/docs/2.writing-pages.md

@@ -0,0 +1,14 @@
+---
+title: Writing pages
+description: The frontmatter fields of a docs page.
+---
+
+## Frontmatter
+
+- `title` and `description` appear at the top of the page and in search.
+- `section` groups pages in the side navigation.
+- `parent` nests a page under another one.
+
+::callout
+Change a file, save, and the page updates.
+::

package/presets/docs/ginko.config.ts

@@ -0,0 +1,21 @@
+// A documentation site: the layout, side navigation and search come from @lupinum/ginko-docs.
+// Every page is a Markdown file in content/docs/.
+import { defineSite } from '@lupinum/ginko'
+import { components, docsCollection } from '@lupinum/ginko-docs/config'
+
+const locales = ['en'] as const
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // change for your country
+  locales,
+  currency: 'EUR', // change for your country
+  pages: { home: '/' },
+  // Shown in search results and link previews. Replace it with one sentence about your site.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'Documentation for our product.', color: '#047857' },
+  components, // the Markdown components (::callout, ::tabs …) and their checked props
+  bricks: { docs: docsCollection({ locales }) },
+})

package/presets/docs/nuxt.config.ts

@@ -0,0 +1,9 @@
+import ginko from './ginko.config.ts'
+
+export default defineNuxtConfig({
+  compatibilityDate: '2026-10-01',
+  extends: ['@lupinum/ginko-docs'],
+  // nuxt-og-image draws a share card for every page (Ginko passes title, image, logo and `seo.color`).
+  modules: ['@lupinum/ginko/nuxt', 'nuxt-og-image'],
+  ginko,
+})

package/presets/docs-de/app/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/presets/docs-de/content/docs/1.einstieg.md

@@ -0,0 +1,12 @@
+---
+title: Einstieg
+description: Was diese Seite ist und wie du eine Seite ergänzt.
+---
+
+## Eine Seite ergänzen
+
+Jede Seite ist eine Markdown-Datei in `content/docs/`. Die Zahl vor dem Namen legt die Reihenfolge in der Seitennavigation fest.
+
+## Weiter
+
+Lies [Seiten schreiben]($docs.seiten-schreiben), um die Felder im Frontmatter zu sehen.

package/presets/docs-de/content/docs/2.seiten-schreiben.md

@@ -0,0 +1,14 @@
+---
+title: Seiten schreiben
+description: Die Felder im Frontmatter einer Doku-Seite.
+---
+
+## Frontmatter
+
+- `title` und `description` stehen oben auf der Seite und in der Suche.
+- `section` fasst Seiten in der Seitennavigation zu Gruppen zusammen.
+- `parent` hängt eine Seite unter eine andere.
+
+::callout
+Ändere eine Datei, speichere sie, und die Seite aktualisiert sich.
+::

package/presets/docs-de/ginko.config.ts

@@ -0,0 +1,21 @@
+// Eine Doku-Seite: Layout, Seitennavigation und Suche kommen aus @lupinum/ginko-docs.
+// Jede Seite ist eine Markdown-Datei in content/docs/.
+import { defineSite } from '@lupinum/ginko'
+import { components, docsCollection } from '@lupinum/ginko-docs/config'
+
+const locales = ['de'] as const
+
+export default defineSite({
+  site: '{{SITE}}',
+  name: '{{SITE}}',
+  url: 'https://example.com',
+  timeZone: 'Europe/Vienna', // für dein Land ändern
+  locales,
+  currency: 'EUR', // für dein Land ändern
+  pages: { home: '/' },
+  // Steht in Suchergebnissen und Link-Vorschauen. Ersetze es durch einen Satz über deine Website.
+  // `color`: the brand colour of the generated share cards.
+  seo: { description: 'Dokumentation zu unserem Produkt.', color: '#047857' },
+  components, // die Markdown-Komponenten (::callout, ::tabs …) und ihre geprüften Props
+  bricks: { docs: docsCollection({ locales }) },
+})

package/presets/docs-de/nuxt.config.ts

@@ -0,0 +1,9 @@
+import ginko from './ginko.config.ts'
+
+export default defineNuxtConfig({
+  compatibilityDate: '2026-10-01',
+  extends: ['@lupinum/ginko-docs'],
+  // nuxt-og-image draws a share card for every page (Ginko passes title, image, logo and `seo.color`).
+  modules: ['@lupinum/ginko/nuxt', 'nuxt-og-image'],
+  ginko,
+})

package/presets/gastro/app/pages/index.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { formatMoney } from '@lupinum/ginko'
+import { dishOn, priceOn, timesOf, weekdayNames, type Weekday } from '@lupinum/ginko-preset-gastro'
+
+const hours = useGinko('hours')
+const menu = useGinko('menu')
+const today = useGinkoToday()
+const { language } = useI18n()
+// A dish turned off with "onMenu" is left out; one sold out today stays, marked (dishOn).
+const dishes = computed(() => menu.value.items.map((i) => ({ ...i, ...dishOn(i.data, today.value) })).filter((i) => i.shown))
+const categories = [['starters', 'Starters'], ['soups', 'Soups'], ['mains', 'Mains'], ['desserts', 'Desserts'], ['drinks', 'Drinks']] as const
+useGinkoSeo({ title: 'Menu and opening hours' })
+</script>
+
+<template>
+  <main>
+    <h1>Opening hours</h1>
+    <table>
+      <tbody>
+        <tr v-for="d in hours.data.week" :key="d.day">
+          <th scope="row">{{ weekdayNames.en[d.day as Weekday] }}</th>
+          <td>{{ d.closed ? 'Closed' : timesOf(d, 'and') }}</td>
+        </tr>
+      </tbody>
+    </table>
+    <h1>Menu</h1>
+    <section v-for="[key, title] in categories.filter(([k]) => dishes.some((i) => i.data.category === k))" :key="key">
+      <h2>{{ title }}</h2>
+      <ul>
+        <li v-for="dish in dishes.filter((i) => i.data.category === key)" :key="dish.id">
+          <strong>{{ dish.data.name }}</strong><template v-if="dish.soldOut"> (sold out today)</template>, {{ formatMoney(priceOn(dish.data, today), language) }}
+          <br>{{ dish.data.description }}
+        </li>
+      </ul>
+    </section>
+  </main>
+</template>