@gitpagedocs/cli 1.1.60 → 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 |
@@ -28,7 +30,7 @@ npx @gitpagedocs/cli
 | `gitpagedocs deploy` / `pages [actions\|deploy]` | Configure GitHub Pages via Actions + push |
 | `gitpagedocs docs` | Refresh managed regions of README/CONTRIBUTING/SECURITY |
 | `gitpagedocs config clear` | Delete the stored `.gitpagedocsconfig` (wipes saved AI credentials) |
-| `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / update hint |
+| `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / registry update check |
 | `gitpagedocs mcp start` | Start the MCP server over stdio |
 
 The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the published package is self-contained).
@@ -114,7 +116,7 @@ Generated artifacts include:
 Example:
 
 ```bash
-npx gitpagedocs --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
+npx @gitpagedocs/cli --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
 ```
 
 Expected URL after deployment:
@@ -128,7 +130,7 @@ https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/
 The CLI now includes a dedicated interactive AI mode:
 
 ```bash
-npx gitpagedocs ai
+npx @gitpagedocs/cli ai
 ```
 
 ### What it does
@@ -162,7 +164,7 @@ permissions on POSIX systems:
 Set `GITPAGEDOCS_CONFIG_DIR` to override the directory; delete the stored file
 and its credentials with `gitpagedocs config clear`; a legacy
 `.gitpagedocsconfig` in the repository root is migrated automatically on the next
-run. You can create/edit this file manually and then run `npx gitpagedocs ai`:
+run. You can create/edit this file manually and then run `npx @gitpagedocs/cli ai`:
 
 ```json
 {

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
 
@@ -46,11 +46,11 @@ This guide configures your repository from zero to running docs.
 ## Install and generate
 
 1. Install package:
-   - \`npm install gitpagedocs\`
+   - \`npm install @gitpagedocs/cli\`
 2. Generate docs config and versions:
-   - \`npx gitpagedocs\`
+   - \`npx @gitpagedocs/cli\`
 3. Optional: generate local layouts/templates:
-   - \`npx gitpagedocs --layoutconfig\`
+   - \`npx @gitpagedocs/cli --layoutconfig\`
 
 ## Local run
 
@@ -62,7 +62,7 @@ This guide configures your repository from zero to running docs.
 
 ## CLI behavior
 
-\`npx gitpagedocs\` generates only artifacts in \`gitpagedocs/\`:
+\`npx @gitpagedocs/cli\` generates only artifacts in \`gitpagedocs/\`:
 
 - JSON + markdown docs assets
 - No \`index.html\`
@@ -85,7 +85,7 @@ Git Page Docs is a **pnpm + turborepo monorepo** that turns a repository's \`git
 ## Monorepo packages
 
 - **frontend/** — Next.js 15 (App Router, React 19) documentation viewer, static-exported for GitHub Pages.
-- **cli/** — the published \`gitpagedocs\` npm package (\`npm install -g gitpagedocs\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
+- **cli/** — the published \`@gitpagedocs/cli\` npm package (\`npm install -g @gitpagedocs/cli\`): scaffolds the docs contract, generates docs with AI, configures Pages, and runs the MCP server.
 - **tools/** — \`@gitpagedocs/tools\`, the shared business-logic core: the 14-provider AI system, the encrypted credential vault, the config loader, caches, and the logger.
 - **mcp/** — \`@gitpagedocs/mcp\`, a Model Context Protocol server (20 tools + 7 resources).
 - **gitpagedocs/** — the user contract: \`config.json\`, versioned docs, and layouts.
@@ -113,19 +113,20 @@ 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 |
 | \`gitpagedocs deploy\` / \`pages [actions\\|deploy]\` | Configure GitHub Pages via Actions + push |
 | \`gitpagedocs docs\` | Refresh README/CONTRIBUTING/SECURITY managed regions |
-| \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / update hint |
+| \`gitpagedocs doctor\` / \`version\` / \`update\` | Diagnostics / version / registry update check |
 | \`gitpagedocs mcp start\` | Start the MCP server over stdio |
 
-Install globally with \`npm install -g gitpagedocs\`, or run one-off with \`npx gitpagedocs\`.
+Install globally with \`npm install -g @gitpagedocs/cli\`, or run one-off with \`npx @gitpagedocs/cli\`.
 
 ## CLI options
 
@@ -136,7 +137,8 @@ Install globally with \`npm install -g gitpagedocs\`, or run one-off with \`npx
 | \`--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\`, or run one-off with \`npx
 - \`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
 
@@ -419,8 +421,8 @@ Provide owner + repository to load docs from repositories that contain \`gitpage
 ## Self-hosted GitHub Pages
 
 1. Generate docs:
-   - \`npx gitpagedocs\`
-   - or \`npx gitpagedocs --layoutconfig\` for local templates
+   - \`npx @gitpagedocs/cli\`
+   - or \`npx @gitpagedocs/cli --layoutconfig\` for local templates
 2. Set \`site.rendering\` in \`gitpagedocs/config.json\`:
    - \`https://<your-user>.github.io/<your-repo>/\`
 3. Build and validate:
@@ -485,14 +487,16 @@ Themes are JSON templates mapped by \`layoutsConfig.json\`.
 
 ## Strategy options
 
-- Default mode (\`npx gitpagedocs\`): use official layouts/templates from the upstream repository.
-- Local mode (\`npx gitpagedocs --layoutconfig\`): generate and use local templates from your repository.
+- Default mode (\`npx @gitpagedocs/cli\`): use official layouts/templates from the upstream repository.
+- Local mode (\`npx @gitpagedocs/cli --layoutconfig\`): generate and use local templates from your repository.
 
 ## 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
 
@@ -55,7 +55,7 @@ Esta guia lleva el proyecto desde cero hasta docs corriendo.
 
 ## Comportamiento de la CLI
 
-\`npx gitpagedocs\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
+\`npx @gitpagedocs/cli\` (o \`npm run gitpagedocs\`) genera artefactos en la carpeta oficial \`gitpagedocs/\`.
 
 - Genera solo markdown/json
 - No genera \`index.html\`
@@ -78,7 +78,7 @@ Git Page Docs es un monorepo pnpm + turborepo que convierte la carpeta \`gitpage
 ## Paquetes del monorepo
 
 - **frontend/** — visor Next.js 15 (App Router, React 19), exportado estaticamente para GitHub Pages.
-- **cli/** — el paquete npm publicado \`gitpagedocs\` (\`npm install -g gitpagedocs\`): genera la estructura de docs, documenta con IA, configura Pages y ejecuta el servidor MCP.
+- **cli/** — el paquete npm publicado \`@gitpagedocs/cli\` (\`npm install -g @gitpagedocs/cli\`): genera la estructura de docs, documenta con IA, configura Pages y ejecuta el servidor MCP.
 - **tools/** — \`@gitpagedocs/tools\`, el nucleo de logica compartido: sistema de IA con 14 proveedores, boveda de credenciales cifrada, cargador de config, caches y logger.
 - **mcp/** — \`@gitpagedocs/mcp\`, servidor Model Context Protocol (20 herramientas + 7 recursos).
 - **gitpagedocs/** — el contrato del usuario: \`config.json\`, docs versionados y layouts.
@@ -105,11 +105,12 @@ Referencia completa de opciones CLI, claves de configuracion y funciones del run
 
 | Comando | Descripcion |
 |---------|-------------|
-| \`npx gitpagedocs\` | Genera config y docs en \`gitpagedocs/\` |
-| \`npx gitpagedocs --layoutconfig\` | Tambien genera layouts/templates locales |
-| \`npx gitpagedocs --home\` | Distribucion standalone (\`gitpagedocshome/\`) |
-| \`npx gitpagedocs --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx gitpagedocs --interactive\` / \`-i\` | Modo interactivo con prompts |
+| \`npx @gitpagedocs/cli\` | Genera config y docs en \`gitpagedocs/\` |
+| \`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 (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
 
@@ -55,7 +55,7 @@ Este guia leva o projeto do zero ate docs rodando.
 
 ## Comportamento da CLI
 
-\`npx gitpagedocs\` (ou \`npm run gitpagedocs\`) gera os artefatos na pasta oficial \`gitpagedocs/\`.
+\`npx @gitpagedocs/cli\` (ou \`npm run gitpagedocs\`) gera os artefatos na pasta oficial \`gitpagedocs/\`.
 
 - Gera somente markdown/json
 - Nao gera \`index.html\`
@@ -78,7 +78,7 @@ Git Page Docs e um monorepo pnpm + turborepo que transforma a pasta \`gitpagedoc
 ## Pacotes do monorepo
 
 - **frontend/** — visualizador Next.js 15 (App Router, React 19), exportado estaticamente para o GitHub Pages.
-- **cli/** — o pacote npm publicado \`gitpagedocs\` (\`npm install -g gitpagedocs\`): gera a estrutura de docs, documenta com IA, configura o Pages e roda o servidor MCP.
+- **cli/** — o pacote npm publicado \`@gitpagedocs/cli\` (\`npm install -g @gitpagedocs/cli\`): gera a estrutura de docs, documenta com IA, configura o Pages e roda o servidor MCP.
 - **tools/** — \`@gitpagedocs/tools\`, o nucleo de logica compartilhado: sistema de IA com 14 provedores, cofre de credenciais criptografado, loader de config, caches e logger.
 - **mcp/** — \`@gitpagedocs/mcp\`, servidor Model Context Protocol (20 ferramentas + 7 recursos).
 - **gitpagedocs/** — o contrato do usuario: \`config.json\`, docs versionados e layouts.
@@ -105,11 +105,12 @@ Referencia completa de opcoes da CLI, chaves de configuracao e recursos do runti
 
 | Comando | Descricao |
 |---------|------------|
-| \`npx gitpagedocs\` | Gera config e docs em \`gitpagedocs/\` |
-| \`npx gitpagedocs --layoutconfig\` | Tambem gera layouts/templates locais |
-| \`npx gitpagedocs --home\` | Distribuicao standalone (\`gitpagedocshome/\`) |
-| \`npx gitpagedocs --push --owner X --repo Y\` | Configura workflow, commit, push |
-| \`npx gitpagedocs --interactive\` / \`-i\` | Modo interativo com prompts |
+| \`npx @gitpagedocs/cli\` | Gera config e docs em \`gitpagedocs/\` |
+| \`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 (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.60";
+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;