@gitpagedocs/cli 1.1.61 → 1.1.62

package/README.md

@@ -17,7 +17,9 @@ npx @gitpagedocs/cli
 | Command | Description |
 |---|---|
 | `gitpagedocs` | Generate `gitpagedocs/` config + versioned docs (config-only) |
-| `gitpagedocs --layoutconfig` | Also emit local layout templates in `gitpagedocs/layouts/` |
+| `gitpagedocs --layoutconfig` | Also emit local layout templates in `gitpagelayouts/` |
+| `gitpagedocs --layouts-dir <dir>` | Folder for local layouts (default: `gitpagelayouts`) |
+| `gitpagedocs --no-interactive` / `-y` | Never prompt; use flags and defaults |
 | `gitpagedocs --push --owner <o> --repo <r> [--path <sub>]` | Generate, configure Pages, create workflow, commit + push |
 | `gitpagedocs --home` | Standalone distribution (`gitpagedocshome/`: static site + .env + Dockerfile) |
 | `gitpagedocs -i` / `--interactive` | Interactive prompts |

package/application/config-only/handler.mjs

@@ -24,6 +24,7 @@ export async function executeConfigOnly(params, runtime) {
 
   const artifacts = buildConfigArtifacts({
     useLocalLayoutConfig: options.useLocalLayoutConfig,
+    layoutsDir: options.layoutsDir,
     githubOwner: sanitizeSegment(options.githubOwner),
     githubRepo: sanitizeSegment(options.githubRepo),
     root,
@@ -33,6 +34,7 @@ export async function executeConfigOnly(params, runtime) {
     root,
     pkgRoot,
     outputDir: options.outputDir,
+    layoutsDir: options.layoutsDir,
     artifacts,
     useLocalLayoutConfig: options.useLocalLayoutConfig,
     layouts,

package/application/home/handler.mjs

@@ -41,6 +41,7 @@ export async function executeHome(params, runtime) {
 
   const artifacts = buildConfigArtifacts({
     useLocalLayoutConfig: false,
+    layoutsDir: options.layoutsDir,
     githubOwner: "",
     githubRepo: "",
     root,
@@ -50,6 +51,7 @@ export async function executeHome(params, runtime) {
     root,
     pkgRoot,
     outputDir: ARTIFACTS_DIR,
+    layoutsDir: options.layoutsDir,
     artifacts,
     useLocalLayoutConfig: false,
     layouts,

package/application/ports/cli-runtime-ports.ts

@@ -2,6 +2,8 @@ import type { CliOptions } from "../../domain/models/cli-options";
 
 export interface BuildArtifactsInput {
   useLocalLayoutConfig: boolean;
+  /** Repo-relative layouts home the generated config should reference. */
+  layoutsDir: string;
   githubOwner: string;
   githubRepo: string;
   root: string;
@@ -44,6 +46,8 @@ export interface ConfigOnlyOutputInput {
   root: string;
   pkgRoot: string;
   outputDir: string;
+  /** Repo-relative layouts home local layouts are written to. */
+  layoutsDir: string;
   artifacts: BuiltConfigArtifacts;
   useLocalLayoutConfig: boolean;
   layouts: LayoutDefinition[];

package/application/report/config-only-reporter.mjs

@@ -1,16 +1,17 @@
 /** Config-only command output messages - SRP: single place for all report messages */
 import { resolveRenderingUrl } from "../../builders/project-links.mjs";
+import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
 
 export function reportConfigOnlySuccess(options) {
   return [`Generated: ${options.outputDir}/ (config-only)`, "No index.html/index.js generated."];
 }
 
 export function reportLayoutConfig(options) {
+  const layoutsDir = normalizeLayoutsDir(options.layoutsDir);
   if (options.useLocalLayoutConfig) {
-    return ["Local layouts generated in gitpagedocs/layouts/ (--layoutconfig)."];
-  } else {
-    return ["Using official remote layouts config by default (no local gitpagedocs/layouts generated)."];
+    return [`Local layouts generated in ${layoutsDir}/ (--layoutconfig).`];
   }
+  return [`Using official remote layouts config by default (no local ${layoutsDir}/ generated).`];
 }
 
 export function reportRenderingUrl(options) {

package/builders/project-links.mjs

@@ -1,6 +1,8 @@
 /** Shared derivation of project URLs from CLI options (single source of truth
  * for root and version config builders). */
 
+import { layoutsArtifactPaths } from "../contracts/layouts-paths.mjs";
+
 export const DEFAULT_PROJECT_LINK = "https://github.com/Vidigal-code/git-page-docs";
 export const DEFAULT_RENDERING_URL = "https://vidigal-code.github.io/git-page-docs/";
 
@@ -16,6 +18,28 @@ export function resolveRenderingUrl(githubOwner, githubRepo) {
     : DEFAULT_RENDERING_URL;
 }
 
+/**
+ * Where the viewer should look for locally generated layouts.
+ *
+ * Mirrors resolveSourceViewerPath: user repositories use the symbolic HEAD ref
+ * so any default branch resolves. Without an owner/repo pair there is no URL to
+ * build, so the repo-relative path is returned - the viewer reads it directly in
+ * local mode and still discovers it by probing the repository otherwise.
+ *
+ * @param {string} githubOwner
+ * @param {string} githubRepo
+ * @param {string} layoutsDir Repo-relative layouts home.
+ * @returns {{ config: string, templates: string }}
+ */
+export function resolveLayoutsLinks(githubOwner, githubRepo, layoutsDir) {
+  const paths = layoutsArtifactPaths(layoutsDir);
+  if (!githubOwner || !githubRepo) {
+    return { config: paths.config, templates: paths.templates };
+  }
+  const base = `${resolveProjectLink(githubOwner, githubRepo)}/blob/HEAD`;
+  return { config: `${base}/${paths.config}`, templates: `${base}/${paths.templates}` };
+}
+
 export function resolveSourceViewerPath(githubOwner, githubRepo) {
   // User repositories use the symbolic HEAD ref so any default branch works
   // (github.com, the trees API and raw.githubusercontent all accept it);

package/builders/root-config-builder.d.mts

@@ -0,0 +1,16 @@
+/** Options that shape the generated root config. */
+export interface RootConfigOptions {
+  useLocalLayoutConfig?: boolean;
+  githubOwner?: string;
+  githubRepo?: string;
+  /** Repo-relative layouts home referenced by the generated config. */
+  layoutsDir?: string;
+}
+
+export interface RootConfig {
+  site: Record<string, unknown>;
+  VersionControl: { versions: Array<Record<string, unknown>> };
+  translations: Record<string, unknown>;
+}
+
+export declare function buildRootConfig(options?: RootConfigOptions): RootConfig;

package/builders/root-config-builder.mjs

@@ -1,6 +1,11 @@
 /** Build root config for gitpagedocs */
 import { OFFICIAL_LAYOUTS_CONFIG_URL, OFFICIAL_LAYOUTS_TEMPLATES_URL } from "../data/urls.mjs";
-import { resolveProjectLink, resolveRenderingUrl, resolveSourceViewerPath } from "./project-links.mjs";
+import {
+  resolveProjectLink,
+  resolveRenderingUrl,
+  resolveSourceViewerPath,
+  resolveLayoutsLinks,
+} from "./project-links.mjs";
 import { DOCS } from "../content/docs.mjs";
 import { DOC_VERSIONS } from "../data/version-constants.mjs";
 import { defaultLangMenu } from "../data/i18n-langmenu.mjs";
@@ -16,6 +21,7 @@ export function buildRootConfig(options = {}) {
   const renderingUrl = resolveRenderingUrl(githubOwner, githubRepo);
   const projectLink = resolveProjectLink(githubOwner, githubRepo);
   const sourceViewerPath = resolveSourceViewerPath(githubOwner, githubRepo);
+  const layoutsLinks = resolveLayoutsLinks(githubOwner, githubRepo, options.layoutsDir);
 
   const versionEntries = DOC_VERSIONS.map((id) => ({
     id,
@@ -39,6 +45,8 @@ export function buildRootConfig(options = {}) {
       layoutsConfigPathOficial: useOfficialLayouts,
       layoutsConfigPathTemplatesOficial: useOfficialLayouts ? OFFICIAL_LAYOUTS_TEMPLATES_URL : "",
       layoutsConfigPathOficialUrl: useOfficialLayouts ? OFFICIAL_LAYOUTS_CONFIG_URL : "",
+      layoutsConfigPath: useLocalLayoutConfig ? layoutsLinks.config : "",
+      layoutsConfigPathTemplates: useLocalLayoutConfig ? layoutsLinks.templates : "",
       repositorySearchHome,
       rendering: renderingUrl,
       AiChatEnabled: true,

package/content/docs-en.mjs

@@ -21,8 +21,8 @@ The runtime expects this structure:
 - \`gitpagedocs/docs/<lang>/*.md\`
 - \`gitpagedocs/docs/versions/<version>/config.json\`
 - \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
-- \`gitpagedocs/layouts/layoutsConfig.json\`
-- \`gitpagedocs/layouts/templates/*.json\`
+- \`gitpagelayouts/layoutsConfig.json\` (only with \`--layoutconfig\`)
+- \`gitpagelayouts/templates/*.json\` (only with \`--layoutconfig\`)
 
 ## Quick navigation
 
@@ -113,10 +113,11 @@ Complete reference of CLI options, configuration keys, and runtime features.
 | Command | Description |
 |---------|--------------|
 | \`gitpagedocs\` | Generate config and docs in \`gitpagedocs/\` |
-| \`gitpagedocs --layoutconfig\` | Also generate local layouts/templates |
+| \`gitpagedocs --layoutconfig\` | Also generate local layouts/templates in \`gitpagelayouts/\` |
 | \`gitpagedocs --home\` | Standalone distribution (\`gitpagedocshome/\`) |
 | \`gitpagedocs --push --owner X --repo Y\` | Setup workflow, commit, push |
-| \`gitpagedocs --interactive\` / \`-i\` | Interactive mode with prompts |
+| \`gitpagedocs --interactive\` / \`-i\` | Interactive mode with prompts (the default in a terminal) |
+| \`gitpagedocs --no-interactive\` / \`--yes\` / \`-y\` | Never prompt; use flags and defaults |
 | \`gitpagedocs ai\` | Interactive AI documentation generator |
 | \`gitpagedocs provider [id]\` / \`models [provider]\` | List AI providers / catalog models |
 | \`gitpagedocs document[:repo\\|:file\\|:folder]\` | Generate documentation with AI |
@@ -136,7 +137,8 @@ Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \
 | \`--path <subpath>\` | Docs subpath (e.g. \`docs\`); without it, base path = repo name for correct CSS/JS on project sites |
 | \`--output <dir>\` | Output directory (default: \`gitpagedocs\`) |
 | \`--search true|false\` | Enable/disable repository search (\`--home\`) |
-| \`--layoutconfig\` | Generate \`gitpagedocs/layouts/\` |
+| \`--layoutconfig\` | Generate local layouts in \`gitpagelayouts/\` |
+| \`--layouts-dir <dir>\` | Folder for local layouts (default: \`gitpagelayouts\`) |
 | \`--push\` | Create workflow, commit artifacts, push |
 | \`--home\` | Generate \`gitpagedocshome/\` (static + .env + Dockerfile) |
 
@@ -146,7 +148,7 @@ Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \
 - \`gitpagedocs/icon.svg\` – default icon
 - \`gitpagedocs/docs/versions/<ver>/config.json\` – per-version routes
 - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – markdown docs
-- \`gitpagedocs/layouts/\` – only with \`--layoutconfig\`
+- \`gitpagelayouts/\` – only with \`--layoutconfig\` (folder configurable with \`--layouts-dir\`)
 
 ## Content types
 
@@ -490,9 +492,11 @@ Themes are JSON templates mapped by \`layoutsConfig.json\`.
 
 ## Local layout files
 
-- \`gitpagedocs/layouts/layoutsConfig.json\`
-- \`gitpagedocs/layouts/layoutsFallbackConfig.json\`
-- \`gitpagedocs/layouts/templates/*.json\`
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/layoutsFallbackConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
+
+The legacy \`gitpagedocs/layouts/\` location is no longer generated. It is still read by the viewer, and the CLI offers to move it into the layouts home - only after you confirm.
 
 ## Template model
 

package/content/docs-es.mjs

@@ -19,8 +19,8 @@ El runtime espera esta estructura:
 - \`gitpagedocs/docs/<lang>/*.md\`
 - \`gitpagedocs/docs/versions/<version>/config.json\`
 - \`gitpagedocs/docs/versions/<version>/<lang>/*.md\`
-- \`gitpagedocs/layouts/layoutsConfig.json\`
-- \`gitpagedocs/layouts/templates/*.json\`
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
 
 ## Navegacion rapida
 
@@ -106,10 +106,11 @@ Referencia completa de opciones CLI, claves de configuracion y funciones del run
 | Comando | Descripcion |
 |---------|-------------|
 | \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
-| \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales |
+| \`npx @gitpagedocs/cli --layoutconfig\` | Tambien genera layouts/templates locales en \`gitpagelayouts/\` |
 | \`npx @gitpagedocs/cli --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
 | \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts |
+| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interactivo con prompts (por defecto en una terminal) |
+| \`npx @gitpagedocs/cli --no-interactive\` / \`-y\` | Nunca pregunta; usa flags y valores por defecto |
 
 ## Opciones CLI
 
@@ -120,7 +121,8 @@ Referencia completa de opciones CLI, claves de configuracion y funciones del run
 | \`--path <subpath>\` | Subruta de docs (ej: \`docs\`); sin ella, base path = nombre del repo para CSS/JS en project sites |
 | \`--output <dir>\` | Directorio de salida (default: \`gitpagedocs\`) |
 | \`--search true|false\` | Habilita/deshabilita busqueda de repositorio (\`--home\`) |
-| \`--layoutconfig\` | Genera \`gitpagedocs/layouts/\` |
+| \`--layoutconfig\` | Genera layouts locales en \`gitpagelayouts/\` |
+| \`--layouts-dir <dir>\` | Carpeta de layouts locales (por defecto: \`gitpagelayouts\`) |
 | \`--push\` | Crea workflow, commit de artefactos, push |
 | \`--home\` | Genera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
 
@@ -130,7 +132,7 @@ Referencia completa de opciones CLI, claves de configuracion y funciones del run
 - \`gitpagedocs/icon.svg\` – icono por defecto
 - \`gitpagedocs/docs/versions/<ver>/config.json\` – rutas por version
 - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs en markdown
-- \`gitpagedocs/layouts/\` – solo con \`--layoutconfig\`
+- \`gitpagelayouts/\` – solo con \`--layoutconfig\` (carpeta configurable con \`--layouts-dir\`)
 
 ## Tipos de contenido
 
@@ -400,9 +402,9 @@ Los temas son templates JSON mapeados por \`layoutsConfig.json\`.
 
 ## Archivos
 
-- \`gitpagedocs/layouts/layoutsConfig.json\`
-- \`gitpagedocs/layouts/layoutsFallbackConfig.json\`
-- \`gitpagedocs/layouts/templates/*.json\`
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/layoutsFallbackConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
 
 ## Modelo de template
 

package/content/docs-pt.mjs

@@ -19,8 +19,8 @@ O runtime espera esta estrutura:
 - \`gitpagedocs/docs/<lang>/*.md\`
 - \`gitpagedocs/docs/versions/<versao>/config.json\`
 - \`gitpagedocs/docs/versions/<versao>/<lang>/*.md\`
-- \`gitpagedocs/layouts/layoutsConfig.json\`
-- \`gitpagedocs/layouts/templates/*.json\`
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
 
 ## Navegacao rapida
 
@@ -106,10 +106,11 @@ Referencia completa de opcoes da CLI, chaves de configuracao e recursos do runti
 | Comando | Descricao |
 |---------|------------|
 | \`npx @gitpagedocs/cli\` | Gera config e docs em \`gitpagedocs/\` |
-| \`npx @gitpagedocs/cli --layoutconfig\` | Tambem gera layouts/templates locais |
+| \`npx @gitpagedocs/cli --layoutconfig\` | Tambem gera layouts/templates locais em \`gitpagelayouts/\` |
 | \`npx @gitpagedocs/cli --home\` | Distribuicao standalone (\`gitpagedocshome/\`) |
 | \`npx @gitpagedocs/cli --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interativo com prompts |
+| \`npx @gitpagedocs/cli --interactive\` / \`-i\` | Modo interativo com prompts (padrao em um terminal) |
+| \`npx @gitpagedocs/cli --no-interactive\` / \`-y\` | Nunca pergunta; usa flags e padroes |
 
 ## Opcoes da CLI
 
@@ -120,7 +121,8 @@ Referencia completa de opcoes da CLI, chaves de configuracao e recursos do runti
 | \`--path <subpath>\` | Subcaminho dos docs (ex: \`docs\`); sem ele, base path = nome do repo para CSS/JS em project sites |
 | \`--output <dir>\` | Diretorio de saida (padrao: \`gitpagedocs\`) |
 | \`--search true|false\` | Habilita/desabilita busca de repositorio (\`--home\`) |
-| \`--layoutconfig\` | Gera \`gitpagedocs/layouts/\` |
+| \`--layoutconfig\` | Gera layouts locais em \`gitpagelayouts/\` |
+| \`--layouts-dir <dir>\` | Pasta dos layouts locais (padrao: \`gitpagelayouts\`) |
 | \`--push\` | Cria workflow, commit de artefatos, push |
 | \`--home\` | Gera \`gitpagedocshome/\` (estatico + .env + Dockerfile) |
 
@@ -130,7 +132,7 @@ Referencia completa de opcoes da CLI, chaves de configuracao e recursos do runti
 - \`gitpagedocs/icon.svg\` – icone padrao
 - \`gitpagedocs/docs/versions/<ver>/config.json\` – rotas por versao
 - \`gitpagedocs/docs/versions/<ver>/{en,pt,es}/*.md\` – docs em markdown
-- \`gitpagedocs/layouts/\` – apenas com \`--layoutconfig\`
+- \`gitpagelayouts/\` – apenas com \`--layoutconfig\` (pasta configuravel com \`--layouts-dir\`)
 
 ## Tipos de conteudo
 
@@ -400,9 +402,9 @@ Temas sao templates JSON mapeados por \`layoutsConfig.json\`.
 
 ## Arquivos
 
-- \`gitpagedocs/layouts/layoutsConfig.json\`
-- \`gitpagedocs/layouts/layoutsFallbackConfig.json\`
-- \`gitpagedocs/layouts/templates/*.json\`
+- \`gitpagelayouts/layoutsConfig.json\`
+- \`gitpagelayouts/layoutsFallbackConfig.json\`
+- \`gitpagelayouts/templates/*.json\`
 
 ## Modelo de template
 

package/contracts/doc-versions.mjs

@@ -1,3 +1,3 @@
-export const PACKAGE_VERSION = "1.1.61";
+export const PACKAGE_VERSION = "1.1.62";
 
 export const DOC_VERSIONS = [PACKAGE_VERSION];

package/contracts/index.mjs

@@ -1 +1,11 @@
 export { DOC_VERSIONS } from "./doc-versions.mjs";
+export {
+  DEFAULT_LAYOUTS_DIR,
+  LAYOUTS_CONFIG_FILENAME,
+  LAYOUTS_FALLBACK_CONFIG_FILENAME,
+  LAYOUTS_TEMPLATES_DIRNAME,
+  LEGACY_LAYOUTS_SUBDIR,
+  normalizeLayoutsDir,
+  legacyLayoutsDir,
+  layoutsArtifactPaths,
+} from "./layouts-paths.mjs";

package/contracts/layouts-paths.d.mts

@@ -0,0 +1,17 @@
+/** Repo-relative paths owned by a layouts folder. */
+export interface LayoutsArtifactPaths {
+  root: string;
+  config: string;
+  fallbackConfig: string;
+  templates: string;
+}
+
+export declare const DEFAULT_LAYOUTS_DIR: string;
+export declare const LAYOUTS_CONFIG_FILENAME: string;
+export declare const LAYOUTS_FALLBACK_CONFIG_FILENAME: string;
+export declare const LAYOUTS_TEMPLATES_DIRNAME: string;
+export declare const LEGACY_LAYOUTS_SUBDIR: string;
+
+export declare function normalizeLayoutsDir(dir: string): string;
+export declare function legacyLayoutsDir(outputDir: string): string;
+export declare function layoutsArtifactPaths(layoutsDir: string): LayoutsArtifactPaths;

package/contracts/layouts-paths.mjs

@@ -0,0 +1,68 @@
+/**
+ * Canonical locations for layout artifacts.
+ *
+ * Local layouts are generated into the standalone `gitpagelayouts/` home at the
+ * project root. `<outputDir>/layouts/` is the legacy location that earlier
+ * versions wrote: the viewer still reads it, and the CLI offers to migrate it,
+ * but nothing is generated there any more.
+ *
+ * Every consumer derives its paths from here so the folder name exists in one
+ * place only.
+ */
+
+/** Standalone layouts home, relative to the project root. */
+export const DEFAULT_LAYOUTS_DIR = "gitpagelayouts";
+
+/** Index file listing every layout, inside a layouts folder. */
+export const LAYOUTS_CONFIG_FILENAME = "layoutsConfig.json";
+
+/** Fallback index used when a layout id cannot be resolved. */
+export const LAYOUTS_FALLBACK_CONFIG_FILENAME = "layoutsFallbackConfig.json";
+
+/** Folder holding one JSON template per layout, inside a layouts folder. */
+export const LAYOUTS_TEMPLATES_DIRNAME = "templates";
+
+/** Sub-folder of the docs output dir that older versions generated into. */
+export const LEGACY_LAYOUTS_SUBDIR = "layouts";
+
+/**
+ * Normalize a user-supplied folder name to a repo-relative POSIX path with no
+ * leading/trailing separators, so it can be joined and stored in config.json
+ * identically on every platform.
+ *
+ * @param {string} dir Raw folder name (may use either separator).
+ * @returns {string} Normalized path, or `DEFAULT_LAYOUTS_DIR` when empty.
+ */
+export function normalizeLayoutsDir(dir) {
+  const normalized = String(dir ?? "")
+    .replace(/[\\/]+/g, "/")
+    .replace(/^\/+|\/+$/g, "")
+    .trim();
+  return normalized || DEFAULT_LAYOUTS_DIR;
+}
+
+/**
+ * Legacy layouts folder for a given docs output dir.
+ *
+ * @param {string} outputDir Docs output dir (e.g. `gitpagedocs`).
+ * @returns {string} Repo-relative POSIX path (e.g. `gitpagedocs/layouts`).
+ */
+export function legacyLayoutsDir(outputDir) {
+  return `${normalizeLayoutsDir(outputDir)}/${LEGACY_LAYOUTS_SUBDIR}`;
+}
+
+/**
+ * Repo-relative paths of every artifact a layouts folder owns.
+ *
+ * @param {string} layoutsDir Layouts folder, repo-relative.
+ * @returns {{ root: string, config: string, fallbackConfig: string, templates: string }}
+ */
+export function layoutsArtifactPaths(layoutsDir) {
+  const root = normalizeLayoutsDir(layoutsDir);
+  return {
+    root,
+    config: `${root}/${LAYOUTS_CONFIG_FILENAME}`,
+    fallbackConfig: `${root}/${LAYOUTS_FALLBACK_CONFIG_FILENAME}`,
+    templates: `${root}/${LAYOUTS_TEMPLATES_DIRNAME}`,
+  };
+}

package/domain/models/cli-options.ts

@@ -1,11 +1,25 @@
 export type CliMode = "home" | "full" | "config-only" | "ai";
 
+/**
+ * Values the user supplied explicitly on the command line. Interactive mode
+ * only asks for what is missing, so an explicit flag is never re-asked.
+ */
+export interface CliExplicitFlags {
+  useLocalLayoutConfig: boolean;
+  layoutsDir: boolean;
+  githubOwner: boolean;
+  githubRepo: boolean;
+  outputDir: boolean;
+}
+
 export interface CliOptions {
   isBuild: boolean;
   isServe: boolean;
   mode: CliMode;
   aiCommand?: string;
   outputDir: string;
+  /** Standalone layouts home (repo-relative); local layouts are generated here. */
+  layoutsDir: string;
   useLocalLayoutConfig: boolean;
   shouldPush: boolean;
   githubOwner: string;
@@ -15,4 +29,5 @@ export interface CliOptions {
   repositorySearch?: boolean;
   isInteractive: boolean;
   hasArgs: boolean;
+  explicit: CliExplicitFlags;
 }

package/domain/services/layouts-migration.d.mts

@@ -0,0 +1,15 @@
+/** A planned move from the legacy layouts folder to the standalone home. */
+export interface LayoutsMigrationPlan {
+  required: boolean;
+  from: string;
+  to: string;
+  files: string[];
+  overwrites: string[];
+}
+
+export declare function planLayoutsMigration(options: {
+  outputDir: string;
+  layoutsDir: string;
+  legacyFiles?: string[];
+  targetFiles?: string[];
+}): LayoutsMigrationPlan;

package/domain/services/layouts-migration.mjs

@@ -0,0 +1,60 @@
+/**
+ * Legacy layouts migration — planning only.
+ *
+ * Deciding *what* should move is domain logic, so it stays free of prompts and
+ * filesystem writes: callers list the two folders, ask the user, and perform
+ * the move. That keeps the rule testable with plain arrays.
+ */
+import { legacyLayoutsDir, normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
+
+/**
+ * @typedef {Object} LayoutsMigrationPlan
+ * @property {boolean} required     True when the legacy folder holds files to move.
+ * @property {string}  from         Repo-relative legacy folder.
+ * @property {string}  to           Repo-relative destination folder.
+ * @property {string[]} files       Paths relative to `from`, sorted.
+ * @property {string[]} overwrites  Subset of `files` already present at `to`.
+ */
+
+/**
+ * Plan the move from the legacy layouts folder to the standalone home.
+ *
+ * @param {Object} options
+ * @param {string} options.outputDir     Docs output dir (owns the legacy folder).
+ * @param {string} options.layoutsDir    Destination layouts folder.
+ * @param {string[]} [options.legacyFiles] Paths relative to the legacy folder.
+ * @param {string[]} [options.targetFiles] Paths relative to the destination folder.
+ * @returns {LayoutsMigrationPlan}
+ */
+export function planLayoutsMigration(options = {}) {
+  const { outputDir, layoutsDir, legacyFiles, targetFiles } = options;
+
+  const from = legacyLayoutsDir(outputDir);
+  const to = normalizeLayoutsDir(layoutsDir);
+
+  const files = toSortedPaths(legacyFiles);
+  const present = new Set(toSortedPaths(targetFiles));
+
+  return {
+    required: files.length > 0 && from !== to,
+    from,
+    to,
+    files,
+    overwrites: files.filter((file) => present.has(file)),
+  };
+}
+
+/**
+ * Normalize, de-duplicate and sort a list of relative paths so a plan is
+ * deterministic regardless of directory-read order.
+ *
+ * @param {unknown} paths
+ * @returns {string[]}
+ */
+function toSortedPaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  const normalized = paths
+    .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+    .map((entry) => entry.replace(/[\\/]+/g, "/").replace(/^\/+/, ""));
+  return [...new Set(normalized)].sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "1.1.61",
+  "version": "1.1.62",
   "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
   "bin": {
     "gitpagedocs": "index.mjs"
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^1.1.61",
-    "@gitpagedocs/tools": "^1.1.61",
+    "@gitpagedocs/mcp": "^1.1.62",
+    "@gitpagedocs/tools": "^1.1.62",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/index.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { printBanner, printCredits } from "./ui/banner";
 import { resolveOptions } from "./options/resolver";
+import { migrateLegacyLayoutsInteractive } from "./ui/layouts-prompts";
 import { runNewCommand } from "./commands/run-command";
 import { dispatchMode } from "../application/use-cases/dispatch-mode";
 import type {
@@ -57,6 +58,13 @@ async function main(): Promise<void> {
   }
 
   const options = await resolveOptions(process.argv, process.env);
+
+  // Layouts moved out of <outputDir>/layouts/. Offer to relocate anything left
+  // behind before generating, so the config written next points at one folder.
+  if (options.mode === "config-only") {
+    await migrateLegacyLayoutsInteractive(root, options);
+  }
+
   const configOnlyRuntime = createConfigOnlyRuntime() as ConfigOnlyRuntimePort;
   const homeRuntime = createHomeRuntime() as HomeRuntimePort;
   await dispatchMode(options, params, {

package/presentation/options/parser.ts

@@ -1,5 +1,6 @@
 import type { CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "./schema";
+import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
 
 const KNOWN_FLAGS = new Set([
   "--build",
@@ -11,8 +12,12 @@ const KNOWN_FLAGS = new Set([
   "--search",
   "--path",
   "--output",
+  "--layouts-dir",
   "--interactive",
   "-i",
+  "--no-interactive",
+  "--yes",
+  "-y",
   "--ai",
   "--pages-actions",
 ]);
@@ -35,6 +40,7 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
   let githubRepo = readOptionValue(args, "--repo");
   const docsPath = readOptionValue(args, "--path");
   const outputDir = readOptionValue(args, "--output");
+  const layoutsDir = readOptionValue(args, "--layouts-dir");
   const searchRaw = readOptionValue(args, "--search");
 
   const fallbackDashedArgs = args
@@ -45,6 +51,7 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
     .filter((a) => !a.startsWith("--path"))
     .filter((a) => !a.startsWith("--home"))
     .filter((a) => !a.startsWith("--output"))
+    .filter((a) => !a.startsWith("--layouts-dir"))
     .filter((a) => !a.startsWith("--search"))
     .map((a) => a.replace(/^--/, "").trim())
     .filter(Boolean);
@@ -91,6 +98,7 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
     mode,
     aiCommand,
     outputDir: outputDir || (isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir),
+    layoutsDir: normalizeLayoutsDir(layoutsDir || DEFAULTS.layoutsDir),
     useLocalLayoutConfig,
     shouldPush,
     githubOwner,
@@ -100,5 +108,12 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
     repositorySearch,
     isInteractive,
     hasArgs: args.length > 0,
+    explicit: {
+      useLocalLayoutConfig,
+      layoutsDir: Boolean(layoutsDir),
+      githubOwner: Boolean(githubOwner),
+      githubRepo: Boolean(githubRepo),
+      outputDir: Boolean(outputDir),
+    },
   };
 }

package/presentation/options/resolver.ts

@@ -34,15 +34,13 @@ export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Pr
     return resolved;
   }
 
-  const runHomeInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "home");
-  if (runHomeInteractive && parsed.mode === "home") {
-    return promptHomeOptions(parsed);
-  }
+  // Every command prompts in a real terminal; shouldRunInteractive owns the
+  // CI / piped-stdin / --no-interactive opt-outs, and each prompt asks only for
+  // what the command line left unanswered.
+  if (!shouldRunInteractive(argv)) return parsed;
 
-  const runConfigInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "config-only");
-  if (runConfigInteractive && parsed.mode === "config-only") {
-    return promptConfigOnlyOptions(parsed);
-  }
+  if (parsed.mode === "home") return promptHomeOptions(parsed);
+  if (parsed.mode === "config-only") return promptConfigOnlyOptions(parsed);
 
   return parsed;
 }

package/presentation/options/schema.ts

@@ -1,5 +1,9 @@
+import { DEFAULT_LAYOUTS_DIR } from "../../contracts/layouts-paths.mjs";
+
 export const DEFAULTS = {
   outputDir: "gitpagedocs",
+  /** Standalone layouts home; local layouts are generated here, never in outputDir. */
+  layoutsDir: DEFAULT_LAYOUTS_DIR as string,
   repositorySearch: false,
   basePath: "",
   home: {

package/presentation/ui/layouts-prompts.ts

@@ -0,0 +1,124 @@
+/**
+ * Layout-related prompts: where layouts come from, where they are written, and
+ * the opt-in migration away from the legacy `<outputDir>/layouts/` folder.
+ */
+import path from "node:path";
+import { askConfirm, askSelect, askText, note } from "./clack";
+import { interactivePromptsAvailable } from "./tty";
+import {
+  DEFAULT_LAYOUTS_DIR,
+  normalizeLayoutsDir,
+  legacyLayoutsDir,
+} from "../../contracts/layouts-paths.mjs";
+import { planLayoutsMigration } from "../../domain/services/layouts-migration.mjs";
+import { listFilesRecursively, executeLayoutsMigration } from "../../runtime/layouts-migrator.mjs";
+
+type LayoutsSource = "official" | "local";
+
+/** Outcome of a completed migration, for the caller to report. */
+export interface LayoutsMigrationOutcome {
+  from: string;
+  to: string;
+  movedCount: number;
+}
+
+/** Ask whether layouts come from the official remote source or a local folder. */
+export async function askLayoutsSource(useLocal: boolean): Promise<boolean> {
+  const choice = await askSelect<LayoutsSource>(
+    "Layout source",
+    [
+      {
+        value: "official",
+        label: "Official layouts (remote)",
+        hint: "nothing is written to your repository",
+      },
+      {
+        value: "local",
+        label: "Local layouts",
+        hint: `generated into ${DEFAULT_LAYOUTS_DIR}/`,
+      },
+    ],
+    useLocal ? "local" : "official",
+  );
+  return choice === "local";
+}
+
+/** Ask which folder should hold the generated layouts. */
+export async function askLayoutsDir(current: string): Promise<string> {
+  const answer = await askText({
+    message: "Layouts folder:",
+    defaultValue: normalizeLayoutsDir(current),
+    validate: (value) => (value.trim() ? undefined : "A folder name is required."),
+  });
+  return normalizeLayoutsDir(answer);
+}
+
+function toAbsolute(root: string, repoRelative: string): string {
+  return path.join(root, ...repoRelative.split("/"));
+}
+
+/**
+ * Offer to move layouts left behind in the legacy folder.
+ *
+ * Nothing is moved without an explicit confirmation. Outside a TTY the legacy
+ * folder is reported and left alone — the viewer still reads it, so declining
+ * (or automating) never breaks an existing site.
+ *
+ * @returns The outcome when files were moved, otherwise `null`.
+ */
+export async function migrateLegacyLayoutsInteractive(
+  root: string,
+  options: { outputDir: string; layoutsDir: string },
+): Promise<LayoutsMigrationOutcome | null> {
+  const from = legacyLayoutsDir(options.outputDir);
+  const to = normalizeLayoutsDir(options.layoutsDir);
+
+  const plan = planLayoutsMigration({
+    outputDir: options.outputDir,
+    layoutsDir: to,
+    legacyFiles: listFilesRecursively(toAbsolute(root, from)),
+    targetFiles: listFilesRecursively(toAbsolute(root, to)),
+  });
+
+  if (!plan.required) return null;
+
+  if (!interactivePromptsAvailable()) {
+    note(
+      `${plan.files.length} layout file(s) still live in ${plan.from}/.\n` +
+        `The viewer still reads them. Run this in a terminal to move them to ${plan.to}/.`,
+      "Legacy layouts",
+    );
+    return null;
+  }
+
+  const overwriteWarning =
+    plan.overwrites.length > 0
+      ? `\n${plan.overwrites.length} file(s) already in ${plan.to}/ would be replaced.`
+      : "";
+  note(
+    `Found ${plan.files.length} layout file(s) in ${plan.from}/.\n` +
+      `Layouts are now generated in ${plan.to}/.${overwriteWarning}`,
+    "Legacy layouts",
+  );
+
+  const confirmed = await askConfirm(
+    `Move them to ${plan.to}/ now?`,
+    plan.overwrites.length === 0,
+  );
+  if (!confirmed) {
+    note(`Left untouched — the viewer still reads ${plan.from}/.`, "Legacy layouts");
+    return null;
+  }
+
+  const result = executeLayoutsMigration(root, plan);
+
+  if (result.failed.length > 0) {
+    note(
+      `${result.failed.length} file(s) could not be moved:\n` +
+        result.failed.map((entry) => `- ${entry.file}: ${entry.reason}`).join("\n"),
+      "Migration incomplete",
+    );
+  }
+
+  return { from: plan.from, to: plan.to, movedCount: result.moved.length };
+}

package/presentation/ui/prompts.ts

@@ -4,26 +4,19 @@ import { execSync } from "node:child_process";
 import type { CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "../options/schema";
 import { askText, askConfirm, note } from "./clack";
+import { interactivePromptsAvailable, promptingEnabled } from "./tty";
+import { askLayoutsSource, askLayoutsDir } from "./layouts-prompts";
 
-function isCiOrNonTty(): boolean {
-  if (process.env.CI === "true") return true;
-  if (process.env.GITHUB_ACTIONS === "true") return true;
-  if (process.stdin && !process.stdin.isTTY) return true;
-  return false;
-}
-
-/** True when clack prompts can run (interactive TTY, not CI). */
-export function interactivePromptsAvailable(): boolean {
-  return !isCiOrNonTty();
-}
+export { interactivePromptsAvailable };
 
+/**
+ * Every command prompts when it runs in a real terminal, so a bare invocation
+ * reflects what the user actually needs instead of silently taking defaults.
+ * CI, a piped stdin, and an explicit `--no-interactive` / `--yes` / `-y` opt out;
+ * `--interactive` / `-i` remains accepted and reads the same either way.
+ */
 export function shouldRunInteractive(argv: string[]): boolean {
-  if (isCiOrNonTty()) return false;
-  const args = argv.slice(2);
-  if (args.includes("--interactive") || args.includes("-i")) return true;
-  if (args.length === 0) return true;
-  if (args.length === 1 && args[0] === "--home") return true;
-  return false;
+  return promptingEnabled(argv.slice(2));
 }
 
 export async function promptHomeOptions(parsed: CliOptions): Promise<CliOptions> {
@@ -115,23 +108,38 @@ export async function ensureGitRepoInteractive(root: string): Promise<void> {
   }
 }
 
+/**
+ * Ask only for what the command line did not already answer, so an explicit
+ * flag is never second-guessed by a prompt.
+ */
 export async function promptConfigOnlyOptions(parsed: CliOptions): Promise<CliOptions> {
-  const useLocalLayoutConfig = await askConfirm(
-    "Generate local layout templates?",
-    parsed.useLocalLayoutConfig ?? false,
-  );
-  const githubOwner = await askText({
-    message: "GitHub owner (optional):",
-    defaultValue: parsed.githubOwner ?? "",
-  });
-  const githubRepo = await askText({
-    message: "GitHub repo (optional):",
-    defaultValue: parsed.githubRepo ?? "",
-  });
+  const useLocalLayoutConfig = parsed.explicit.useLocalLayoutConfig
+    ? parsed.useLocalLayoutConfig
+    : await askLayoutsSource(parsed.useLocalLayoutConfig ?? false);
+
+  const layoutsDir =
+    useLocalLayoutConfig && !parsed.explicit.layoutsDir
+      ? await askLayoutsDir(parsed.layoutsDir)
+      : parsed.layoutsDir;
+
+  const githubOwner = parsed.explicit.githubOwner
+    ? parsed.githubOwner
+    : await askText({
+        message: "GitHub owner (optional):",
+        defaultValue: parsed.githubOwner ?? "",
+      });
+
+  const githubRepo = parsed.explicit.githubRepo
+    ? parsed.githubRepo
+    : await askText({
+        message: "GitHub repo (optional):",
+        defaultValue: parsed.githubRepo ?? "",
+      });
 
   return {
     ...parsed,
     useLocalLayoutConfig,
+    layoutsDir,
     githubOwner: githubOwner?.trim() ?? "",
     githubRepo: githubRepo?.trim() ?? "",
   };

package/presentation/ui/tty.ts

@@ -0,0 +1,37 @@
+/**
+ * Terminal capability detection.
+ *
+ * Kept in its own module so every prompt module can ask "may I prompt?" without
+ * importing the prompt modules themselves (which would be circular).
+ */
+
+/** Environment variables that mark a non-interactive automated run. */
+const CI_ENV_FLAGS = ["CI", "GITHUB_ACTIONS"] as const;
+
+/** Flags that explicitly opt out of prompting. */
+export const NON_INTERACTIVE_FLAGS = ["--no-interactive", "--yes", "-y"] as const;
+
+function isCiOrNonTty(): boolean {
+  for (const flag of CI_ENV_FLAGS) {
+    if (process.env[flag] === "true") return true;
+  }
+  return Boolean(process.stdin && !process.stdin.isTTY);
+}
+
+/** True when clack prompts can run (interactive TTY, not CI). */
+export function interactivePromptsAvailable(): boolean {
+  return !isCiOrNonTty();
+}
+
+/** True when the user explicitly asked for a non-interactive run. */
+export function promptingOptedOut(args: readonly string[]): boolean {
+  return NON_INTERACTIVE_FLAGS.some((flag) => args.includes(flag));
+}
+
+/**
+ * True when prompts should run for this invocation: a real terminal, and no
+ * explicit opt-out.
+ */
+export function promptingEnabled(args: readonly string[]): boolean {
+  return interactivePromptsAvailable() && !promptingOptedOut(args);
+}

package/runtime/layouts-migrator.d.mts

@@ -0,0 +1,11 @@
+export interface LayoutsMigrationResult {
+  moved: string[];
+  failed: Array<{ file: string; reason: string }>;
+}
+
+export declare function listFilesRecursively(absoluteDir: string): string[];
+
+export declare function executeLayoutsMigration(
+  root: string,
+  plan: { from: string; to: string; files: string[] },
+): LayoutsMigrationResult;

package/runtime/layouts-migrator.mjs

@@ -0,0 +1,103 @@
+/**
+ * Filesystem side of the legacy layouts migration.
+ *
+ * The decision of *what* moves lives in the domain planner; this module only
+ * reads directories and performs the move, so both halves stay testable on
+ * their own.
+ */
+import {
+  existsSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  renameSync,
+  copyFileSync,
+  rmSync,
+} from "node:fs";
+import path from "node:path";
+
+/**
+ * List every file under a directory, as POSIX paths relative to it.
+ *
+ * @param {string} absoluteDir
+ * @returns {string[]} Empty when the directory is absent or unreadable.
+ */
+export function listFilesRecursively(absoluteDir) {
+  if (!absoluteDir || !existsSync(absoluteDir)) return [];
+
+  const found = [];
+  const walk = (currentDir, prefix) => {
+    let entries;
+    try {
+      entries = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const absolute = path.join(currentDir, entry);
+      const relative = prefix ? `${prefix}/${entry}` : entry;
+      let isDirectory = false;
+      try {
+        isDirectory = statSync(absolute).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDirectory) walk(absolute, relative);
+      else found.push(relative);
+    }
+  };
+
+  walk(absoluteDir, "");
+  return found.sort();
+}
+
+/**
+ * Move one file, falling back to copy + delete when rename is not possible
+ * (different volumes, or a locked handle on Windows).
+ *
+ * @param {string} fromAbsolute
+ * @param {string} toAbsolute
+ */
+function moveFile(fromAbsolute, toAbsolute) {
+  mkdirSync(path.dirname(toAbsolute), { recursive: true });
+  try {
+    renameSync(fromAbsolute, toAbsolute);
+  } catch {
+    copyFileSync(fromAbsolute, toAbsolute);
+    rmSync(fromAbsolute, { force: true });
+  }
+}
+
+/**
+ * Execute a migration plan produced by `planLayoutsMigration`.
+ *
+ * Files are moved one by one so a single failure is reported without aborting
+ * the rest; the legacy folder is removed only once it is genuinely empty.
+ *
+ * @param {string} root Project root the plan's paths are relative to.
+ * @param {{ from: string, to: string, files: string[] }} plan
+ * @returns {{ moved: string[], failed: Array<{ file: string, reason: string }> }}
+ */
+export function executeLayoutsMigration(root, plan) {
+  const moved = [];
+  const failed = [];
+
+  const fromRoot = path.join(root, ...plan.from.split("/"));
+  const toRoot = path.join(root, ...plan.to.split("/"));
+
+  for (const file of plan.files) {
+    const segments = file.split("/");
+    try {
+      moveFile(path.join(fromRoot, ...segments), path.join(toRoot, ...segments));
+      moved.push(file);
+    } catch (error) {
+      failed.push({ file, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  if (failed.length === 0 && listFilesRecursively(fromRoot).length === 0) {
+    rmSync(fromRoot, { recursive: true, force: true });
+  }
+
+  return { moved, failed };
+}

package/runtime/output.mjs

@@ -8,12 +8,7 @@ import {
   withVersionBadge,
   normalizeToOutputPath,
 } from "./doc-path-resolver.mjs";
-
-/** True when `child` is the same as, or nested inside, `parent` (path-safe). */
-function isWithin(parent, child) {
-  const rel = path.relative(parent, child);
-  return !rel.startsWith("..") && !path.isAbsolute(rel);
-}
+import { layoutsArtifactPaths } from "../contracts/layouts-paths.mjs";
 
 const DEFAULT_ICON_SVG = `<?xml version="1.0" encoding="utf-8"?>
 <svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
@@ -57,6 +52,29 @@ export async function writeText(root, relativePath, data) {
   await writeFile(absolutePath, data, "utf-8");
 }
 
+/**
+ * Write the local layout artifacts into the standalone layouts home.
+ *
+ * No layouts folder is ever deleted here. The legacy `<outputDir>/layouts/`
+ * folder can hold hand-edited templates and the viewer still reads it, so
+ * relocating it is an explicit, confirmed migration rather than a side effect of
+ * generating. Switching back to official layouts likewise leaves an existing
+ * layouts home in place: `layoutsConfigPathOficial` already decides which source
+ * the viewer uses, so the files are inert rather than harmful.
+ */
+async function writeLayoutArtifacts(options) {
+  const { root, layoutsDir, useLocalLayoutConfig, layouts, artifacts, createThemeTemplate } = options;
+
+  if (!useLocalLayoutConfig) return;
+
+  const paths = layoutsArtifactPaths(layoutsDir);
+  await writeJson(root, paths.config, artifacts.layoutsConfig);
+  await writeJson(root, paths.fallbackConfig, artifacts.fallbackLayoutsConfig);
+  for (const layout of layouts) {
+    await writeJson(root, `${paths.root}/${layout.file}`, createThemeTemplate(layout));
+  }
+}
+
 export async function writeConfigOnlyOutput(options) {
   const {
     root,
@@ -64,6 +82,7 @@ export async function writeConfigOnlyOutput(options) {
     outputDir,
     artifacts,
     useLocalLayoutConfig,
+    layoutsDir,
     layouts,
     createThemeTemplate,
   } = options;
@@ -78,20 +97,14 @@ export async function writeConfigOnlyOutput(options) {
 
   await writeJson(root, `${outputDir}/config.json`, artifacts.rootConfig);
   await writeText(root, `${outputDir}/icon.svg`, DEFAULT_ICON_SVG);
-  const layoutsPath = path.join(root, outputDir, "layouts");
-  if (useLocalLayoutConfig) {
-    await writeJson(root, `${outputDir}/layouts/layoutsConfig.json`, artifacts.layoutsConfig);
-    await writeJson(root, `${outputDir}/layouts/layoutsFallbackConfig.json`, artifacts.fallbackLayoutsConfig);
-    for (const layout of layouts) {
-      const template = createThemeTemplate(layout);
-      await writeJson(root, `${outputDir}/layouts/${layout.file}`, template);
-    }
-  } else if (existsSync(layoutsPath) && !isWithin(root, pkgRoot)) {
-    // Only clean a stale local layouts/ when the CLI runs from OUTSIDE the
-    // project (a real install) — never when pkgRoot is inside the project being
-    // generated (the gitpagedocs source repo), so committed layouts survive.
-    rmSync(layoutsPath, { recursive: true, force: true });
-  }
+  await writeLayoutArtifacts({
+    root,
+    layoutsDir,
+    useLocalLayoutConfig,
+    layouts,
+    artifacts,
+    createThemeTemplate,
+  });
 
   for (const [versionId, versionConfig] of Object.entries(artifacts.versionConfigs)) {
     await writeJson(root, `${outputDir}/docs/versions/${versionId}/config.json`, versionConfig);