@inditextech/docouture-cli 0.1.0-SNAPSHOT.68.1 → 0.1.0-SNAPSHOT.74.1

package/build/bin.js

@@ -7,6 +7,7 @@ import { runBuild } from './commands/build.js';
 import { runDoctor } from './commands/doctor.js';
 import { runPublish } from './commands/publish.js';
 import { runUpgrade } from './commands/upgrade.js';
+import { runBranchModel } from './commands/branch-model.js';
 import { runEject } from './commands/eject.js';
 import { runTeardown } from './commands/teardown.js';
 import { runCompletion } from './commands/completion.js';
@@ -22,6 +23,7 @@ const COMMAND_ORDER = [
     'publish',
     'doctor',
     'upgrade',
+    'branch-model',
     'eject',
     'teardown',
     'completion',
@@ -31,7 +33,9 @@ const COMMAND_INFO = {
         usageLine: 'new <name>',
         summary: 'Scaffold a new documentation site',
         help: `Usage:
-  docouture new <name> [--dir <path>] [--title <title>] [--mode standalone|versioned] [--pm npm|pnpm] [--yes]
+  docouture new <name> [--dir <path>] [--title <title>] [--mode standalone|versioned]
+    [--flow trunk-based|git-flow] [--branch <name>] [--integration-branch <name>]
+    [--release-branch <name>] [--pm npm|pnpm] [--yes]
 
 Scaffold an Antora documentation site into docs/ (and its workflows into
 .github/workflows/), plus AGENTS.md and agent skills (.opencode/skills/,
@@ -47,6 +51,10 @@ Options:
   --dir <path>     Repository root to scaffold into (default: cwd, or its enclosing repo)
   --title <title>  Site title (default: title-cased from <name>)
   --mode <mode>    'standalone' (default) or 'versioned'
+  --flow <flow>    'trunk-based' (default) or 'git-flow' — see 'docouture branch-model --help'
+  --branch <name>  Trunk-based only: the one branch (default: main)
+  --integration-branch <name>  Git-flow only: the prerelease branch (default: develop)
+  --release-branch <name>      Git-flow only: the release branch (default: main)
   --pm <pm>        'npm' or 'pnpm' (default: auto-detected from a lockfile/packageManager
                    field, or how docouture itself was invoked)
   --yes            Skip the interactive wizard, use defaults for anything unset
@@ -127,7 +135,9 @@ Check that the environment and site configuration are healthy: Node
 version, the four names that must agree (component name, start page,
 content path, package name), git history, that antora is installed,
 and (advisory only) whether AGENTS.md and the scaffolded skills are
-still present.
+still present, whether the docs/release label exists, and whether the
+declared branching model (docs/package.json's docouture.branching)
+agrees with what antora-playbook.yml/docouture-release.yml actually say.
 
 Options:
   --dir <path>  Repository root (default: cwd, or its enclosing repo)
@@ -153,6 +163,45 @@ Options:
   --dir <path>   Repository root (default: cwd, or its enclosing repo)
   --title <title>  Override the title read back from docs/antora.yml
   --dry-run      List what would be written without changing anything
+`,
+    },
+    'branch-model': {
+        usageLine: 'branch-model <model>',
+        summary: 'Switch between trunk-based and git-flow branching',
+        help: `Usage:
+  docouture branch-model <trunk-based|git-flow> [--branch <name>]
+    [--integration-branch <name>] [--release-branch <name>] [--dir <path>] [--dry-run]
+
+Switch an already-scaffolded repository between the trunk-based and
+git-flow branching models — see docs/src/modules/main/pages/
+guides-branching-model.adoc for the full mechanism. Direction is
+inferred from the site's current branch names (read live from
+antora-playbook.yml/docouture-release.yml, never from a stored config)
+versus the <model> argument given here — the same command handles
+both directions.
+
+trunk-based -> git-flow: the current single branch becomes the release
+branch by default (least disruption to anything already tagged off
+it) — --integration-branch <name> (the new prerelease branch) is
+required, since there is nothing on disk to infer that name from.
+
+git-flow -> trunk-based: lossy — --branch <name> is required and must
+match one of the two current branches exactly; a third, invented name
+is refused.
+
+Re-renders .github/workflows/ (same machinery 'docouture upgrade' uses)
+and patches antora-playbook.yml's content.sources[0].branches and
+docs/package.json's docouture.branching field. Does NOT rename actual
+git branches, touch branch-protection/ruleset rules, or change GitHub's
+configured default branch — these stay manual steps, printed as a
+reminder after every real run.
+
+Options:
+  --branch <name>              Trunk-based target only
+  --integration-branch <name>  Git-flow target only: the prerelease branch
+  --release-branch <name>      Git-flow target only: the release branch
+  --dir <path>                 Repository root (default: cwd, or its enclosing repo)
+  --dry-run                    List what would be written without changing anything
 `,
     },
     eject: {
@@ -207,8 +256,8 @@ Examples:
 // 'docouture <command> --help' uses for a single command.
 const CLI_SUMMARY = 'Scaffold, build, and publish Antora documentation sites';
 // Left column width of the command table below, including the 2-space
-// indent — wide enough for the longest usageLine ('completion <shell>').
-const COMMAND_COLUMN_WIDTH = 22;
+// indent — wide enough for the longest usageLine ('branch-model <model>').
+const COMMAND_COLUMN_WIDTH = 24;
 const USAGE = `Usage: docouture <command> [options]
 
 Commands:
@@ -234,6 +283,7 @@ const RUNNERS = {
     publish: runPublish,
     doctor: runDoctor,
     upgrade: runUpgrade,
+    'branch-model': runBranchModel,
     eject: runEject,
     teardown: runTeardown,
     completion: async (argv) => runCompletion(argv),

package/build/commands/branch-model.js

@@ -0,0 +1,211 @@
+'use strict';
+import { execFileSync } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from '../lib/args.js';
+import { readCliInfo } from '../lib/cli-info.js';
+import { copyTemplate, exists } from '../lib/copy-template.js';
+import { detectPackageManager, packageManagerPlan } from '../lib/detect-package-manager.js';
+import { findRepoRoot } from '../lib/repo-root.js';
+import { readBranches, writeBranches } from '../lib/playbook-yml.js';
+import { cacheWarmBranchesYaml, detectBranches } from '../lib/branch-detect.js';
+const BRANCH_MODELS = ['trunk-based', 'git-flow'];
+// Same duplication precedent upgrade.ts's own isInsideGitWorkTree comment
+// documents (doctor-checks.ts already sets it) — a small piece of new.ts's
+// logic reused rather than importing the wizard-heavy module it lives in.
+function isInsideGitWorkTree(dir) {
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readAntoraField(content, key) {
+    const match = new RegExp(`^${key}:.*$`, 'm').exec(content);
+    if (!match)
+        return null;
+    const value = match[0].slice(key.length + 1).trim();
+    return value.length > 0 ? value : null;
+}
+// The one JSON write this command performs — a single field
+// (`docouture.branching`), read-modify-write rather than a regex patch
+// (unlike antora-playbook.yml/docouture-release.yml, package.json is
+// already JSON, so there is no comment-preservation reason to avoid
+// JSON.parse/stringify here the way playbook-yml.ts avoids a full YAML
+// round-trip). Re-serializes the whole file at 2-space indent — matching
+// every template's own style — rather than only touching the one line, so
+// key ordering is preserved (JSON.parse/stringify both preserve insertion
+// order) but incidental whitespace a human introduced is not.
+async function writeBranching(packageJsonFile, branching) {
+    const content = await readFile(packageJsonFile, 'utf8');
+    const pkg = JSON.parse(content);
+    pkg.docouture = { ...pkg.docouture, branching };
+    await writeFile(packageJsonFile, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+}
+export async function runBranchModel(argv) {
+    const { positional, flags } = parseArgs(argv);
+    const target = positional[0];
+    if (!target || !BRANCH_MODELS.includes(target)) {
+        console.error(`usage: docouture branch-model <trunk-based|git-flow> [--branch <name>] [--integration-branch <name>] [--release-branch <name>] [--dir <path>] [--dry-run]`);
+        console.error(`invalid target: '${target ?? ''}' — expected 'trunk-based' or 'git-flow'`);
+        return 1;
+    }
+    const targetModel = target;
+    const dryRun = flags['dry-run'] === true;
+    const branchFlag = typeof flags.branch === 'string' ? flags.branch : undefined;
+    const integrationBranchFlag = typeof flags['integration-branch'] === 'string' ? flags['integration-branch'] : undefined;
+    const releaseBranchFlag = typeof flags['release-branch'] === 'string' ? flags['release-branch'] : undefined;
+    const startDir = typeof flags.dir === 'string' ? resolve(flags.dir) : resolve(process.cwd());
+    if (!isInsideGitWorkTree(startDir)) {
+        console.error(`'${startDir}' is not inside a git repository`);
+        console.error('docouture branch-model re-configures an already-scaffolded repository — run it from your repo root, or pass --dir <path> to one');
+        return 1;
+    }
+    const repoRoot = await findRepoRoot(startDir);
+    const siteRoot = join(repoRoot, 'docs');
+    if (!(await exists(siteRoot))) {
+        console.error(`no site found at '${siteRoot}'`);
+        console.error('pass --dir <path> to a component root (the parent of docs/), or run docouture new first');
+        return 1;
+    }
+    // Always derived live, never read back from a stored config — see
+    // lib/branch-detect.ts's own comment on why. Falls back to nothing
+    // special for a site scaffolded before this feature existed: its
+    // antora-playbook.yml/docouture-release.yml already have the exact same
+    // shape (one literal branch, `main` in both places), so this is the only
+    // path, not a legacy-only fallback.
+    const detected = await detectBranches(siteRoot, repoRoot);
+    if (!detected.prerelease || !detected.release) {
+        console.error('could not determine this site\u2019s current branch names');
+        console.error(`  antora-playbook.yml content.sources[0].branches: ${detected.prerelease ?? '(not found)'}`);
+        console.error(`  docouture-release.yml checkout ref: ${detected.release ?? '(not found)'}`);
+        console.error('is this a docouture-scaffolded site? (run docouture new first, or check --dir)');
+        return 1;
+    }
+    const currentModel = detected.prerelease === detected.release ? 'trunk-based' : 'git-flow';
+    let newPrerelease;
+    let newRelease;
+    if (targetModel === 'trunk-based') {
+        if (currentModel === 'git-flow') {
+            if (!branchFlag) {
+                console.error('switching from git-flow to trunk-based requires --branch <name>');
+                console.error(`  must match one of the current two branches: '${detected.prerelease}' or '${detected.release}'`);
+                return 1;
+            }
+            if (branchFlag !== detected.prerelease && branchFlag !== detected.release) {
+                console.error(`--branch '${branchFlag}' does not match either current branch`);
+                console.error(`  current prerelease branch: '${detected.prerelease}'`);
+                console.error(`  current release branch: '${detected.release}'`);
+                console.error('refusing to invent a third branch name — collapsing two branches into one is lossy: pick one of the two that already exist');
+                return 1;
+            }
+            newPrerelease = branchFlag;
+            newRelease = branchFlag;
+        }
+        else {
+            const branch = branchFlag ?? detected.release;
+            newPrerelease = branch;
+            newRelease = branch;
+        }
+    }
+    else {
+        if (currentModel === 'trunk-based') {
+            // Least-disruption default (see the issue's own design note): the
+            // current single branch becomes *release* — whatever already got
+            // tagged off it keeps working unchanged — and a NEW name is required
+            // for the integration/prerelease branch, since there is nothing
+            // already on disk to infer that from.
+            if (!integrationBranchFlag) {
+                console.error('switching from trunk-based to git-flow requires --integration-branch <name>');
+                console.error(`  the current branch ('${detected.release}') becomes the release branch by default`);
+                console.error('  (override with --release-branch if you want a different name for it too)');
+                return 1;
+            }
+            newPrerelease = integrationBranchFlag;
+            newRelease = releaseBranchFlag ?? detected.release;
+        }
+        else {
+            newPrerelease = integrationBranchFlag ?? detected.prerelease;
+            newRelease = releaseBranchFlag ?? detected.release;
+        }
+    }
+    if (targetModel === currentModel && newPrerelease === detected.prerelease && newRelease === detected.release) {
+        console.log(`already ${currentModel} (${newPrerelease === newRelease ? newPrerelease : `${newPrerelease}/${newRelease}`}) — nothing to do`);
+        return 0;
+    }
+    const here = dirname(fileURLToPath(import.meta.url));
+    const templatesRoot = join(here, '..', 'templates');
+    const workflowsTemplateDir = join(templatesRoot, 'workflows');
+    const workflowsDir = join(repoRoot, '.github', 'workflows');
+    const { version: cliVersion } = await readCliInfo(import.meta.url, 2);
+    const pm = packageManagerPlan(detectPackageManager(repoRoot));
+    const descriptorPath = join(siteRoot, 'src', 'antora.yml');
+    let name = 'docs';
+    let title = 'Docs';
+    if (await exists(descriptorPath)) {
+        const content = await readFile(descriptorPath, 'utf8');
+        name = readAntoraField(content, 'name') ?? name;
+        title = readAntoraField(content, 'title') ?? title;
+    }
+    const values = {
+        name,
+        title,
+        // Same reasoning as upgrade.ts's own comment: neither placeholder
+        // appears in any file this command re-renders (workflows only), so
+        // there is nothing meaningful to compute either from.
+        componentName: 'unused-by-branch-model',
+        cliVersion,
+        pmName: pm.pm,
+        pmCacheName: pm.cacheName,
+        pmLockfile: pm.lockfile,
+        pmCiCmd: pm.ciCmd,
+        pmSetupStepYaml: pm.setupStepYaml,
+        pmPackageManagerField: 'unused-by-branch-model',
+        repoIgnoreGlob: 'unused-by-branch-model',
+        prereleaseBranch: newPrerelease,
+        releaseBranch: newRelease,
+        // docs/package.json is patched directly below (writeBranching), not via
+        // copyTemplate — this placeholder only ever appears in that file.
+        branching: 'unused-by-branch-model',
+        cacheWarmBranchesYaml: cacheWarmBranchesYaml(newPrerelease, newRelease),
+    };
+    const playbookFile = join(siteRoot, 'antora-playbook.yml');
+    const packageJsonFile = join(siteRoot, 'package.json');
+    if (dryRun) {
+        const plannedWorkflows = await copyTemplate(workflowsTemplateDir, workflowsDir, values, { dryRun: true });
+        console.log(`would switch ${currentModel} -> ${targetModel}`);
+        console.log(`  prerelease branch: '${detected.prerelease}' -> '${newPrerelease}'`);
+        console.log(`  release branch: '${detected.release}' -> '${newRelease}'`);
+        console.log('would write:');
+        for (const path of [...plannedWorkflows, playbookFile, packageJsonFile]) {
+            console.log(`  ${relative(repoRoot, path)}`);
+        }
+        return 0;
+    }
+    await copyTemplate(workflowsTemplateDir, workflowsDir, values);
+    const playbookContent = await readFile(playbookFile, 'utf8');
+    // Only rewritten if the prerelease branch actually changed and the line
+    // is still there in the shape readBranches/writeBranches expect —
+    // guards against a hand-edited playbook this regex can't safely touch.
+    if (newPrerelease !== detected.prerelease && readBranches(playbookContent)) {
+        await writeFile(playbookFile, writeBranches(playbookContent, newPrerelease), 'utf8');
+    }
+    await writeBranching(packageJsonFile, targetModel);
+    console.log(`switched ${currentModel} -> ${targetModel}`);
+    console.log(`  prerelease branch: '${detected.prerelease}' -> '${newPrerelease}'`);
+    console.log(`  release branch: '${detected.release}' -> '${newRelease}'`);
+    console.log(`updated ${relative(repoRoot, workflowsDir)}`);
+    console.log(`updated ${relative(repoRoot, playbookFile)}`);
+    console.log(`updated ${relative(repoRoot, packageJsonFile)}`);
+    console.log('');
+    console.log('this command does NOT:');
+    console.log('  - rename actual git branches');
+    console.log('  - touch branch-protection/ruleset rules');
+    console.log("  - change GitHub's configured default branch");
+    console.log('these are still manual steps — see docs/src/modules/main/pages/guides-branching-model.adoc');
+    return 0;
+}
+//# sourceMappingURL=branch-model.js.map

package/build/commands/completion.js

@@ -18,6 +18,7 @@ export const COMMANDS = [
     'publish',
     'doctor',
     'upgrade',
+    'branch-model',
     'eject',
     'teardown',
     'completion',

package/build/commands/doctor.js

@@ -7,7 +7,8 @@ import { findRepoRoot } from '../lib/repo-root.js';
 import { getContext } from '../lib/cli-context.js';
 import { theme } from '../lib/theme.js';
 import { readSourceUrl, readStartPageComponent, readStartPath } from '../lib/playbook-yml.js';
-import { checkAgentFilesPresent, checkAntoraAvailable, checkGitHasCommit, checkNamesAgree, checkNodeVersion, checkReleaseLabelExists, } from '../lib/doctor-checks.js';
+import { detectBranches, inferBranching } from '../lib/branch-detect.js';
+import { checkAgentFilesPresent, checkAntoraAvailable, checkBranchingAgrees, checkGitHasCommit, checkNamesAgree, checkNodeVersion, checkReleaseLabelExists, } from '../lib/doctor-checks.js';
 async function readJson(file) {
     try {
         return JSON.parse(await readFile(file, 'utf8'));
@@ -148,6 +149,15 @@ export async function runDoctor(argv) {
     record(report, 'release', releaseResult, 'warn');
     if (!json)
         printAdvisory(releaseResult);
+    log('branching');
+    const detectedBranches = await detectBranches(siteRoot, target);
+    const branchingResult = checkBranchingAgrees({
+        declaredBranching: pkg?.docouture?.branching ?? null,
+        actualBranching: inferBranching(detectedBranches),
+    });
+    record(report, 'branching', branchingResult, 'warn');
+    if (!json)
+        printAdvisory(branchingResult);
     if (json) {
         process.stdout.write(`${JSON.stringify({ status: status === 0 ? 'ok' : 'fail', checks: report }, null, 2)}\n`);
     }

package/build/commands/new.js

@@ -11,6 +11,7 @@ import { copyTemplate, exists, isEmptyOrMissing, renderTemplateFile, writeTempla
 import { detectPackageManager, packageManagerPlan, } from '../lib/detect-package-manager.js';
 import { findRepoRoot } from '../lib/repo-root.js';
 import { AGENTS_MD_FILENAME, hasManagedSection, mergeAgentsMd } from '../lib/agents-md.js';
+import { cacheWarmBranchesYaml } from '../lib/branch-detect.js';
 // Matches the rule an npm package name (and, not coincidentally, an Antora
 // component name — both end up as URL segments) can safely be: this is
 // stricter than npm's own rule, which also allows dots and a leading `@scope/`
@@ -30,6 +31,15 @@ const NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 // here: it only ever comes up as an ad-hoc `docouture dev` preview before a mode
 // is chosen, never as something worth releasing.)
 const MODES = ['standalone', 'versioned'];
+// The two branching models `docouture new` can scaffold for — see the
+// guides-branching-model guide, and GH #175. 'trunk-based' (the default):
+// one branch plays both roles (prerelease AND release) — the degenerate
+// case, not a second code path anywhere prereleaseBranch/releaseBranch are
+// used. 'git-flow': two independently-named branches, e.g. `develop`
+// (prerelease) and `main` (release) — see antora-playbook.yml's own comment
+// on what "prerelease branch" means, and docouture-release.yml's on
+// "release branch".
+const BRANCH_MODELS = ['trunk-based', 'git-flow'];
 const PACKAGE_MANAGERS = ['npm', 'pnpm'];
 // Filenames docouture-publish.yml / docouture-publish-prerelease.yml /
 // docouture-release.yml / docouture-release-preview.yml / docouture-pr-verify.yml /
@@ -229,6 +239,47 @@ async function promptWizard(io, initial, defaults) {
                 },
             ],
         }, context));
+    // Branching model — see BRANCH_MODELS' own comment. Unconditional, same
+    // as Versioning mode above; the follow-up branch-name question(s) below
+    // are this wizard's first CONDITIONAL prompt.
+    const branching = initial.branching ??
+        (await select({
+            message: 'Branching model:\n',
+            default: 'trunk-based',
+            choices: [
+                {
+                    name: 'Trunk-based',
+                    value: 'trunk-based',
+                    description: 'One long-lived branch plays both the prerelease and release roles — e.g. main.',
+                },
+                {
+                    name: 'Git-flow',
+                    value: 'git-flow',
+                    description: 'Two independently-named branches — an integration branch (e.g. develop) for prerelease, ' +
+                        'a release branch (e.g. main) for cutting releases.',
+                },
+            ],
+        }, context));
+    let prereleaseBranch;
+    let releaseBranch;
+    if (branching === 'git-flow') {
+        releaseBranch = (await input({
+            message: 'Release branch (docouture-release.yml checks this out and cuts tags from it):\n',
+            default: initial.releaseBranch ?? 'main',
+        }, context)).trim();
+        prereleaseBranch = (await input({
+            message: 'Integration/prerelease branch (antora-playbook.yml tracks this as the live prerelease version):\n',
+            default: initial.prereleaseBranch ?? 'develop',
+        }, context)).trim();
+    }
+    else {
+        const branch = (await input({
+            message: 'Branch (plays both the prerelease and release roles):\n',
+            default: initial.branch ?? 'main',
+        }, context)).trim();
+        prereleaseBranch = branch;
+        releaseBranch = branch;
+    }
     const pm = initial.pm ??
         (await select({
             message: 'Package manager:\n',
@@ -238,7 +289,16 @@ async function promptWizard(io, initial, defaults) {
                 { name: 'pnpm', value: 'pnpm' },
             ],
         }, context));
-    return { name, title: title.length > 0 ? title : defaultTitle, urlSegment, mode, pm };
+    return {
+        name,
+        title: title.length > 0 ? title : defaultTitle,
+        urlSegment,
+        mode,
+        branching,
+        prereleaseBranch,
+        releaseBranch,
+        pm,
+    };
 }
 export async function runNew(argv, io = defaultIO()) {
     const { positional, flags } = parseArgs(argv);
@@ -248,6 +308,12 @@ export async function runNew(argv, io = defaultIO()) {
     // already "off", so the only thing worth scripting is turning it on.
     let urlSegment = flags['url-segment'] === true ? true : undefined;
     let mode;
+    let branching;
+    let prereleaseBranch;
+    let releaseBranch;
+    const branchFlag = typeof flags.branch === 'string' ? flags.branch : undefined;
+    const integrationBranchFlag = typeof flags['integration-branch'] === 'string' ? flags['integration-branch'] : undefined;
+    const releaseBranchFlag = typeof flags['release-branch'] === 'string' ? flags['release-branch'] : undefined;
     let pmChoice;
     if (typeof flags.mode === 'string') {
         if (!MODES.includes(flags.mode)) {
@@ -256,6 +322,13 @@ export async function runNew(argv, io = defaultIO()) {
         }
         mode = flags.mode;
     }
+    if (typeof flags.flow === 'string') {
+        if (!BRANCH_MODELS.includes(flags.flow)) {
+            console.error(`invalid --flow: '${flags.flow}' — expected 'trunk-based' or 'git-flow'`);
+            return 1;
+        }
+        branching = flags.flow;
+    }
     if (typeof flags.pm === 'string') {
         if (!PACKAGE_MANAGERS.includes(flags.pm)) {
             console.error(`invalid --pm: '${flags.pm}' — expected 'npm' or 'pnpm'`);
@@ -275,19 +348,48 @@ export async function runNew(argv, io = defaultIO()) {
     // gets exactly today's non-interactive behaviour, defaults and all.
     const skipWizard = flags.yes === true || !io.isTTY;
     if (!skipWizard) {
-        const answers = await promptWizard(io, { name, title, urlSegment, mode, pm: pmChoice }, { pm: pmGuess });
+        const answers = await promptWizard(io, {
+            name,
+            title,
+            urlSegment,
+            mode,
+            branching,
+            branch: branchFlag,
+            prereleaseBranch: integrationBranchFlag,
+            releaseBranch: releaseBranchFlag,
+            pm: pmChoice,
+        }, { pm: pmGuess });
         name = answers.name;
         title = answers.title;
         urlSegment = answers.urlSegment;
         mode = answers.mode;
+        branching = answers.branching;
+        prereleaseBranch = answers.prereleaseBranch;
+        releaseBranch = answers.releaseBranch;
         pmChoice = answers.pm;
         io.output.write('\n');
     }
     mode = mode ?? 'standalone';
+    branching = branching ?? 'trunk-based';
     pmChoice = pmChoice ?? pmGuess;
     urlSegment = urlSegment ?? false;
+    // Non-interactive path (--yes, or no TTY): resolve from flags/defaults
+    // the same way the wizard would have, rather than leaving these unset —
+    // trunk-based collapses to one branch name playing both roles, same as
+    // BRANCH_MODELS' own comment describes.
+    if (branching === 'git-flow') {
+        prereleaseBranch = prereleaseBranch ?? integrationBranchFlag ?? 'develop';
+        releaseBranch = releaseBranch ?? releaseBranchFlag ?? 'main';
+    }
+    else {
+        const branch = branchFlag ?? 'main';
+        prereleaseBranch = prereleaseBranch ?? branch;
+        releaseBranch = releaseBranch ?? branch;
+    }
     if (!name) {
-        console.error('usage: docouture new <name> [--dir <path>] [--title <title>] [--url-segment] [--mode standalone|versioned] [--pm npm|pnpm]');
+        console.error('usage: docouture new <name> [--dir <path>] [--title <title>] [--url-segment] [--mode standalone|versioned] ' +
+            '[--flow trunk-based|git-flow] [--branch <name>] [--integration-branch <name>] [--release-branch <name>] ' +
+            '[--pm npm|pnpm]');
         return 1;
     }
     if (!NAME_PATTERN.test(name)) {
@@ -396,6 +498,10 @@ export async function runNew(argv, io = defaultIO()) {
         pmSetupStepYaml: pm.setupStepYaml,
         pmPackageManagerField: pm.packageManagerField,
         repoIgnoreGlob: repoIgnoreGlob(target),
+        prereleaseBranch,
+        releaseBranch,
+        branching,
+        cacheWarmBranchesYaml: cacheWarmBranchesYaml(prereleaseBranch, releaseBranch),
     };
     // The whole starter subtree — package.json, antora-playbook.yml, its own
     // nested src/antora.yml — lands under <repo-root>/docs/ as one piece,
@@ -418,7 +524,17 @@ export async function runNew(argv, io = defaultIO()) {
         await writeTemplateFile(join(starterDir, 'antora-playbook.versioned.yml'), join(docsDir, 'antora-playbook.yml'), values);
         await writeTemplateFile(join(starterDir, 'src', 'release-version.versioned'), join(docsDir, '.release-version'), values);
     }
-    printNextSteps({ mode, pm, target, docsDir, workflowsDir, ghPagesUrl: githubPagesUrl(target) });
+    printNextSteps({
+        mode,
+        branching,
+        prereleaseBranch,
+        releaseBranch,
+        pm,
+        target,
+        docsDir,
+        workflowsDir,
+        ghPagesUrl: githubPagesUrl(target),
+    });
     return 0;
 }
 // Everything printed after scaffolding finishes, grouped into labeled
@@ -426,7 +542,7 @@ export async function runNew(argv, io = defaultIO()) {
 // "created X" lines. Headers use the shared theme's bold, matching bin.ts's
 // own banner — see lib/theme.ts for why that's not picocolors directly.
 function printNextSteps(args) {
-    const { mode, pm, target, docsDir, workflowsDir, ghPagesUrl } = args;
+    const { mode, branching, prereleaseBranch, releaseBranch, pm, target, docsDir, workflowsDir, ghPagesUrl } = args;
     const created = (path) => `  ${theme.success('✓')} ${path}`;
     // Relative to `target` (the repo root), not process.cwd() — cwd may be a
     // nested subdirectory findRepoRoot walked up from (see runNew), in which
@@ -453,9 +569,22 @@ function printNextSteps(args) {
     console.log('  docouture-documenting-changes, docouture-authoring-guides, docouture-writing-docs-pages,');
     console.log('  docouture-docs-internals and, for a versioned-mode site, docouture-docs-versioning)');
     console.log('');
+    if (branching === 'git-flow') {
+        console.log(theme.bold('Branching: Git-flow'));
+        console.log(`  ${prereleaseBranch} is the prerelease/integration branch; ${releaseBranch} is the release branch.`);
+        console.log(`  docouture-release.yml only runs against ${releaseBranch}; ordinary content merges into`);
+        console.log(`  ${prereleaseBranch} publish continuously via docouture-publish-prerelease.yml.`);
+    }
+    else {
+        console.log(theme.bold('Branching: Trunk-based'));
+        console.log(`  ${releaseBranch} plays both the prerelease and release roles.`);
+    }
+    console.log('  See docs/src/modules/main/pages/guides-branching-model.adoc for the full lifecycle,');
+    console.log("  and 'docouture branch-model' to switch later.");
+    console.log('');
     if (mode === 'versioned') {
         console.log(theme.bold('Versioning: Versioned (Full History)'));
-        console.log('  main is the prerelease channel.');
+        console.log(`  ${prereleaseBranch} is the prerelease channel.`);
         console.log('');
         console.log('  To cut your first release:');
         console.log("    1. Create the 'docs/release' label (once): gh label create docs/release");
@@ -470,11 +599,11 @@ function printNextSteps(args) {
     }
     else {
         console.log(theme.bold('Versioning: Standalone (Stable + Prerelease)'));
-        console.log('  main is the prerelease channel.');
+        console.log(`  ${prereleaseBranch} is the prerelease channel.`);
         console.log('');
         console.log('  To cut your first stable release:');
         console.log("    1. Create the 'docs/release' label (once): gh label create docs/release");
-        console.log("    2. Merge any PR labeled 'docs/release' into main — docouture-release.yml runs automatically");
+        console.log(`    2. Merge any PR labeled 'docs/release' into ${releaseBranch} — docouture-release.yml runs automatically`);
         console.log('');
         console.log('  (or skip the label/PR entirely: run docouture-release.yml manually via workflow_dispatch,');
         console.log('  default input is fine)');

package/build/commands/upgrade.js

@@ -10,6 +10,7 @@ import { detectPackageManager, packageManagerPlan } from '../lib/detect-package-
 import { resolveConfig } from '../lib/config-resolver.js';
 import { findRepoRoot } from '../lib/repo-root.js';
 import { AGENTS_MD_FILENAME, mergeAgentsMd } from '../lib/agents-md.js';
+import { cacheWarmBranchesYaml, detectBranches } from '../lib/branch-detect.js';
 // Same check `new.ts` uses, duplicated rather than imported — it's three
 // lines, and `doctor-checks.ts` already sets the precedent of duplicating a
 // small piece of `new.ts`'s own logic instead of reaching across into a
@@ -93,6 +94,18 @@ export async function runUpgrade(argv) {
     // --title flag > the value already recorded in docs/antora.yml > a plain
     // title-cased fallback computed from the name above.
     const { title } = resolveConfig({ title: titleCase(name) }, { title: fromYmlTitle }, { title: typeof flags.title === 'string' ? flags.title : undefined });
+    // Re-derived live too, same reasoning as name/title above — upgrade
+    // re-copies every workflow template (unlike docs/), and those templates
+    // now carry __DOCOUTURE_PRERELEASE_BRANCH__/__DOCOUTURE_RELEASE_BRANCH__
+    // (GH #175) — real branch names are required here, not stubs, or an
+    // upgrade would silently overwrite a git-flow site's workflows back to
+    // whatever these placeholders' un-substituted default would be. See
+    // lib/branch-detect.ts's own comment on why these are derived live
+    // rather than read back from a stored config.
+    const siteRoot = join(target, 'docs');
+    const detected = await detectBranches(siteRoot, target);
+    const prereleaseBranch = detected.prerelease ?? 'main';
+    const releaseBranch = detected.release ?? 'main';
     const values = {
         name,
         title,
@@ -119,6 +132,13 @@ export async function runUpgrade(argv) {
         // pattern matching every URL, which would be a silent, dangerous no-op
         // if this value were ever actually substituted somewhere.
         repoIgnoreGlob: 'unused-by-upgrade',
+        prereleaseBranch,
+        releaseBranch,
+        // docs/package.json (the only template file this placeholder appears
+        // in) is never re-copied by upgrade — same reasoning as
+        // pmPackageManagerField/repoIgnoreGlob above.
+        branching: 'unused-by-upgrade',
+        cacheWarmBranchesYaml: cacheWarmBranchesYaml(prereleaseBranch, releaseBranch),
     };
     const workflowsDir = join(target, '.github', 'workflows');
     const agentsMdFile = join(target, AGENTS_MD_FILENAME);