@rtorcato/repo-tooling 4.7.0 → 5.0.0

package/AGENTS.md

@@ -84,7 +84,6 @@ npx @rtorcato/repo-tooling doctor --json -d ./existing-repo
 # Apply one fixer from the list (run `list --json` for every target)
 npx @rtorcato/repo-tooling fix dependabot --yes --json
 npx @rtorcato/repo-tooling fix engines --yes --json
-npx @rtorcato/repo-tooling fix docs-site --yes --json   # scaffold a Docusaurus docs site under apps/docs
 npx @rtorcato/repo-tooling fix bun --yes --json         # Bun runtime/test config
 ```
 

package/dist/base/checks.js

@@ -100,81 +100,6 @@ export async function checkCommunityHealth(dir) {
         hint: 'Run `npx @rtorcato/repo-tooling fix community-health` to scaffold them',
     };
 }
-const BRAND_HINT = 'Run `npx @rtorcato/repo-tooling fix brand` to scaffold brand/ (SVG sources + render.sh) and render the PNGs (needs librsvg)';
-/** The two banners the README consumes — the pair `brand/` exists to keep regenerable. */
-const BANNERS = ['banner', 'banner-mobile'];
-/**
- * Brand assets (#395). A committed PNG with no SVG beside it can't be
- * recoloured, retitled or resized — which was the state of every repo in the
- * family but one. Three signals, all language-agnostic:
- *
- * 1. a rendered banner with no `brand/<name>.svg` source
- * 2. a `brand/` folder with no `render.sh` — sources nobody can render
- * 3. a README still pointing at the pre-amendment root-level `./banner.png`
- *
- * A repo with no brand images at all is `optional-missing`, not a finding:
- * there's nothing broken to fix, and banners are opt-in.
- */
-export async function checkBrand(dir) {
-    const check = 'Brand assets';
-    const has = (rel) => fs.pathExists(path.join(dir, rel));
-    const problems = [];
-    const orphans = [];
-    for (const name of BANNERS) {
-        const rendered = (await has(`${name}.png`)) || (await has(`brand/${name}.png`));
-        if (rendered && !(await has(`brand/${name}.svg`)))
-            orphans.push(`${name}.png`);
-    }
-    if (orphans.length > 0) {
-        problems.push(`${orphans.join(' + ')} committed with no brand/*.svg source`);
-    }
-    const brandDir = await has('brand');
-    if (brandDir && !(await has('brand/render.sh'))) {
-        problems.push('brand/ has no render.sh — the PNGs cannot be regenerated');
-    }
-    const readmePath = path.join(dir, 'README.md');
-    if (await fs.pathExists(readmePath)) {
-        const readme = await fs.readFile(readmePath, 'utf-8');
-        if (/(?<!brand\/)banner(?:-mobile)?\.png/.test(readme)) {
-            problems.push('README points at root-level banner PNGs (the spec moved them to brand/)');
-        }
-    }
-    if (problems.length > 0) {
-        return { check, status: 'drift', detail: problems.join('; '), hint: BRAND_HINT };
-    }
-    // Name the pieces still missing (#679). Severity is unchanged: brand is optional.
-    const missing = [];
-    if (!(await has('brand/favicon.svg')))
-        missing.push('favicon (brand/favicon.svg)');
-    const unrendered = [];
-    for (const n of ['banner', 'banner-mobile', 'social-card', 'favicon-512']) {
-        if (!(await has(`brand/${n}.png`)))
-            unrendered.push(`${n}.png`);
-    }
-    if (unrendered.length > 0)
-        missing.push(`rendered PNGs (brand/${unrendered.join(', ')})`);
-    const readmeFile = path.join(dir, 'README.md');
-    const readmeText = (await fs.pathExists(readmeFile)) ? await fs.readFile(readmeFile, 'utf-8') : '';
-    if (!/brand\/banner(?:-mobile)?\.png/.test(readmeText))
-        missing.push('README banner');
-    if (!brandDir) {
-        return {
-            check,
-            status: 'optional-missing',
-            detail: `no brand/ folder — missing: ${missing.join('; ')}`,
-            hint: BRAND_HINT,
-        };
-    }
-    if (missing.length > 0) {
-        return {
-            check,
-            status: 'ok',
-            detail: `brand/ holds the SVG sources and render.sh; missing: ${missing.join('; ')}`,
-            hint: BRAND_HINT,
-        };
-    }
-    return { check, status: 'ok', detail: 'brand/ holds the SVG sources and render.sh' };
-}
 /**
  * `org/action@vN`, the only form the generators emit. Same shape as the scan in
  * tests/cli/generators/action-pins.test.ts — major-only, because that's the

package/dist/base/fixers.js

@@ -15,7 +15,6 @@ import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import { installAgentRules, installAiSetup } from '../cli/generators/agent-rules.js';
-import { addReadmeBanner, generateBrand, renderBrand, resolveBrandMeta, syncBrandToDocs, } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
 import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
@@ -247,41 +246,6 @@ export const BASE_FIXERS = [
             return { filesWritten };
         },
     },
-    {
-        target: 'brand',
-        selfSafe: true,
-        description: 'Scaffold brand/ — favicon, banner, mobile-banner and social-card SVG sources + render.sh — render the PNGs and favicon.ico when rsvg-convert is on PATH, and add the README banner',
-        appliesTo: ['Brand assets'],
-        outputs: [
-            'brand/favicon.svg',
-            'brand/banner.svg',
-            'brand/banner-mobile.svg',
-            'brand/social-card.svg',
-            'brand/render.sh',
-            'brand/banner.png',
-            'brand/banner-mobile.png',
-            'brand/social-card.png',
-            'brand/favicon-512.png',
-            'brand/favicon.ico',
-            'README.md',
-        ],
-        // Every SVG is written only when absent, PNGs are re-rendered only when
-        // older than their source, and the README edit is a delimited block (or
-        // two image paths) — hand-edited art is never clobbered.
-        riskLevel: 'safe-merge',
-        canFixDrift: true,
-        async run({ targetDir, pkg, lock }) {
-            const tagline = lock?.rules?.brand?.tagline;
-            const filesWritten = await generateBrand(pkg, targetDir, tagline);
-            filesWritten.push(...((await renderBrand(targetDir)) ?? []));
-            filesWritten.push(...(await syncBrandToDocs(targetDir)));
-            const { name } = await resolveBrandMeta(pkg, targetDir, tagline);
-            const readme = await addReadmeBanner(targetDir, name);
-            if (readme && !filesWritten.includes(readme))
-                filesWritten.push(readme);
-            return { filesWritten };
-        },
-    },
     {
         target: 'ai',
         description: 'Install all AI agent files at once (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill, MCP example)',

package/dist/base/secrets.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { jobEnvironment, realGhExec, workflowJobs } from './github-settings.js';
+const WHERE_TO_GET = {
+    CODECOV_TOKEN: 'codecov.io -> your repo -> Settings -> Repository Upload Token',
+    RELEASE_TOKEN: 'a fine-grained PAT with contents: write (or a GitHub App token) that can push past branch protection',
+};
+const withoutComments = (s) => s
+    .split('\n')
+    .filter((l) => !l.trimStart().startsWith('#'))
+    .join('\n');
+function usesIn(text, file, job, environment) {
+    const clean = withoutComments(text);
+    const found = new Map();
+    for (const m of clean.matchAll(/secrets\.([A-Za-z_][A-Za-z0-9_]*)/g)) {
+        const name = m[1];
+        if (name === 'GITHUB_TOKEN' || found.has(name))
+            continue;
+        const fallback = new RegExp(`secrets\\.${name}\\s*\\|\\|\\s*secrets\\.GITHUB_TOKEN`).test(clean);
+        found.set(name, { name, file, job, environment, fallback });
+    }
+    return [...found.values()];
+}
+/** Every non-GITHUB_TOKEN secret the workflows (and a composite action.yml) reference. */
+export async function collectSecretUses(dir) {
+    const uses = [];
+    const wfDir = path.join(dir, '.github', 'workflows');
+    try {
+        const files = (await fs.pathExists(wfDir)) ? (await fs.readdir(wfDir)).sort() : [];
+        for (const f of files) {
+            if (!/\.ya?ml$/.test(f))
+                continue;
+            const content = await fs.readFile(path.join(wfDir, f), 'utf-8');
+            for (const [job, body] of workflowJobs(content)) {
+                uses.push(...usesIn(body, f, job, jobEnvironment(withoutComments(body))));
+            }
+        }
+        for (const a of ['action.yml', 'action.yaml']) {
+            const p = path.join(dir, a);
+            if (await fs.pathExists(p))
+                uses.push(...usesIn(await fs.readFile(p, 'utf-8'), a, '-', null));
+        }
+    }
+    catch {
+        return [];
+    }
+    return uses;
+}
+/** One entry per secret name, for setup's Next Steps. */
+export function requiredSecrets(uses) {
+    const byName = new Map();
+    for (const u of uses) {
+        const r = byName.get(u.name) ?? {
+            name: u.name,
+            usedBy: [],
+            whereToGet: WHERE_TO_GET[u.name] ?? null,
+            fallback: true,
+        };
+        if (!r.usedBy.includes(u.file))
+            r.usedBy.push(u.file);
+        r.fallback &&= u.fallback;
+        byName.set(u.name, r);
+    }
+    return [...byName.values()];
+}
+/** `gh secret set` lines plus where-to-get, for every secret in the list. */
+export function secretHints(secrets) {
+    return secrets.map((s) => `gh secret set ${s.name}${s.whereToGet ? `  # ${s.whereToGet}` : ''}`);
+}
+async function listNames(gh, endpoint) {
+    const r = await gh(['api', `${endpoint}?per_page=100`]);
+    if (!r.ok)
+        return null;
+    try {
+        const d = JSON.parse(r.stdout);
+        return new Set((d.secrets ?? []).flatMap((s) => (s.name ? [s.name] : [])));
+    }
+    catch {
+        return null;
+    }
+}
+const CHECK = 'Repository secrets';
+const skip = (why) => ({
+    check: CHECK,
+    status: 'ok',
+    detail: `not checked (${why})`,
+});
+export async function checkRepositorySecrets(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git'))))
+        return skip('not a git repository');
+    const uses = await collectSecretUses(dir);
+    if (uses.length === 0)
+        return { check: CHECK, status: 'ok', detail: 'no secrets referenced' };
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const repo = await listNames(gh, 'repos/{owner}/{repo}/actions/secrets');
+    if (!repo)
+        return skip("can't list secrets — needs gh with admin access");
+    // Best effort: an org scope that errors just contributes nothing.
+    const org = (await listNames(gh, 'repos/{owner}/{repo}/actions/organization-secrets')) ?? new Set();
+    const envs = new Map();
+    for (const e of new Set(uses.flatMap((u) => (u.environment ? [u.environment] : [])))) {
+        envs.set(e, await listNames(gh, `repos/{owner}/{repo}/environments/${e}/secrets`));
+    }
+    const missing = uses.filter((u) => {
+        if (repo.has(u.name) || org.has(u.name))
+            return false;
+        if (!u.environment)
+            return true;
+        const env = envs.get(u.environment);
+        // An unreadable environment can't prove absence.
+        return env ? !env.has(u.name) : false;
+    });
+    if (missing.length === 0) {
+        return { check: CHECK, status: 'ok', detail: 'all referenced secrets are set' };
+    }
+    const hard = missing.some((u) => !u.fallback);
+    const names = missing
+        .map((u) => `${u.name} (${u.file})${u.fallback ? ' [falls back to GITHUB_TOKEN]' : ''}`)
+        .join(', ');
+    return {
+        check: CHECK,
+        status: hard ? 'missing' : 'drift',
+        detail: `not set: ${names}. Dependabot-triggered runs read Dependabot secrets, not these`,
+        hint: secretHints(requiredSecrets(missing)).join('\n'),
+    };
+}

package/dist/cli/commands/doctor.js

@@ -14,14 +14,15 @@ import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js
 import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
 import { detectAuditLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
+import { checkRepositorySecrets } from '../../base/secrets.js';
 import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity, checkGitIdentityHistory } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { compareRulesWithReference } from '../utils/reference-rules.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
-import { checkAiSetup, checkBrand, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, checkRecommendedMcp, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
-import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkExportsBuildable, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPeerVersions, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
+import { checkAiSetup, checkCodeowners, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, checkRecommendedMcp, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
+import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkEnginesNode, checkExportsBuildable, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPeerVersions, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
 // Detects the broken-release-on-protected-main footgun: a workflow that runs
@@ -211,12 +212,12 @@ async function runBaseChecks(dir, lock, opts) {
     // GitHub repo-settings drift (branch protection, merge settings, workflow
     // permissions). Read-only; self-skips as `ok` outside a live GitHub repo.
     results.push(...(await checkGitHubSettings(dir)));
+    results.push(await checkRepositorySecrets(dir));
     // Milestone hygiene (#397) — same seam, same self-skip.
     results.push(await checkMilestones(dir));
     results.push(await checkGitLabCI(dir));
     results.push(await checkCodeowners(dir));
     results.push(await checkCommunityHealth(dir));
-    results.push(await checkBrand(dir));
     results.push(await checkAiSetup(dir));
     // #534: advisory. Absent `mcp.recommended` means the repo has nothing to say
     // about MCP, which is not a finding.
@@ -373,11 +374,6 @@ export async function runDoctor(dir) {
     if (await fs.pathExists(path.join(targetDir, 'pnpm-workspace.yaml'))) {
         results.push(await checkTurborepo(targetDir));
     }
-    // Docs site is opt-in — only surface the check when a Docusaurus site exists.
-    const docsAppDir = await findDocsAppDir(targetDir);
-    if (docsAppDir) {
-        results.push(await checkDocsSite(targetDir, docsAppDir));
-    }
     // Tailwind is opt-in — only surface the check when the repo actually depends on it.
     if ('tailwindcss' in allDeps(pkg)) {
         results.push(await checkTailwind(targetDir, pkg));

package/dist/cli/commands/fix-targets.js

@@ -45,7 +45,6 @@ export const FIX_TARGETS = {
     'are-the-types-wrong': 'attw',
     publint: 'publint',
     'README badges': 'badges',
-    'Brand assets': 'brand',
     TypeDoc: 'typedoc',
     'AI setup': 'ai',
     'Claude worktree settings': 'ai',
@@ -177,8 +176,6 @@ export function declinedInLock(lock, checkName) {
             return c.turborepo === false;
         case 'Tailwind':
             return c.tailwind === false;
-        case 'Brand assets':
-            return c.brand === false;
         default:
             return false;
     }
@@ -248,12 +245,8 @@ export function lockfilePatchForTarget(target, lock) {
             return c.nx ? null : { nx: true };
         case 'tailwind':
             return c.tailwind ? null : { tailwind: true };
-        case 'docs-site':
-            return c.docsSite ? null : { docsSite: true };
         case 'bun':
             return c.bun ? null : { bun: true };
-        case 'brand':
-            return c.brand ? null : { brand: true };
         default:
             return null;
     }

package/dist/cli/commands/setup-presets.js

@@ -59,7 +59,6 @@ export function buildPresetConfig(name, projectName) {
                 semanticRelease: true,
                 bundler: 'tsup',
                 publint: true,
-                brand: true,
             };
         case 'web-app':
             return {
@@ -210,8 +209,9 @@ export const CONFIG_SCHEMA = {
         turborepo: { type: 'boolean' },
         nx: { type: 'boolean' },
         tailwind: { type: 'boolean' },
-        docsSite: { type: 'boolean' },
-        brand: { type: 'boolean' },
+        // Deprecated (#718): both scaffolds moved to @rtorcato/shared-docs. Accepted, inert.
+        docsSite: { type: 'boolean', deprecated: true },
+        brand: { type: 'boolean', deprecated: true },
         bun: { type: 'boolean' },
     },
 };
@@ -317,8 +317,6 @@ export function computeFileList(config) {
         files.push('postcss.config.mjs', 'src/styles/globals.css');
     if (config.bun)
         files.push('bunfig.toml');
-    if (config.brand)
-        files.push('brand/banner.svg', 'brand/banner-mobile.svg', 'brand/social-card.svg', 'brand/render.sh');
     files.push('README.md');
     return files;
 }

package/dist/cli/commands/setup.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import inquirer from 'inquirer';
+import { collectSecretUses, requiredSecrets, secretHints } from '../../base/secrets.js';
 import { formatNpmPublishGuide, npmPublishGuide, } from '../../languages/js/npm-trust.js';
 import { LANGUAGES } from '../../languages/registry.js';
 import { generateConfigs } from '../generators/index.js';
@@ -23,7 +24,6 @@ const REVIEWABLE_FEATURES = [
     { key: 'securityAutomation', label: 'Security automation (Dependabot + CodeQL)' },
     { key: 'badges', label: 'README status badges' },
     { key: 'aiSetup', label: 'AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot)' },
-    { key: 'brand', label: 'Brand assets (brand/ banner + social-card SVGs, render.sh)' },
 ];
 /**
  * A preset run may only ask questions when a human is on both ends of the pipe.
@@ -182,7 +182,7 @@ export async function setupProject(options) {
             await formatGeneratedFiles(config, targetDir);
         }
         console.log(chalk.green('\n✅ Setup completed successfully!\n'));
-        showNextSteps(config, targetDir);
+        await showNextSteps(config, targetDir);
     }
     catch (error) {
         console.error(chalk.red('\n❌ Setup failed:'), error);
@@ -460,13 +460,6 @@ async function promptForConfig(targetDir, seed) {
             message: '🤖 Add AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)?',
             default: seed?.aiSetup ?? true,
         },
-        {
-            type: 'confirm',
-            name: 'brand',
-            message: '🎨 Add brand assets (brand/ banner + social-card SVG sources, render.sh)?',
-            // On by default for libraries — the ones that publish a README to npm.
-            default: (answers) => seed?.brand ?? answers.projectType === 'library',
-        },
         {
             type: 'select',
             name: 'orchestrator',
@@ -556,7 +549,6 @@ async function promptForConfig(targetDir, seed) {
         publint: answers.publint ?? false,
         badges: answers.badges ?? false,
         aiSetup: answers.aiSetup ?? false,
-        brand: answers.brand ?? false,
         turborepo: answers.orchestrator === 'turbo',
         nx: answers.orchestrator === 'nx',
         tailwind: answers.tailwind ?? false,
@@ -580,7 +572,7 @@ export function npmPublishFor(config) {
         environment: null,
     });
 }
-function showNextSteps(config, _targetDir) {
+async function showNextSteps(config, targetDir) {
     console.log(chalk.bold('\n📋 Next Steps:\n'));
     const steps = [];
     // Every step in the else-branch names a pnpm script. Swift's equivalents are
@@ -615,6 +607,13 @@ function showNextSteps(config, _targetDir) {
         for (const line of formatNpmPublishGuide(npmPublish, true))
             console.log(`  ${line}`);
     }
+    const secrets = requiredSecrets(await collectSecretUses(targetDir));
+    if (secrets.length > 0) {
+        console.log(chalk.bold('\n🔐 GitHub setup (secrets the workflows need):\n'));
+        for (const line of secretHints(secrets))
+            console.log(`  ${line}`);
+        console.log('  Then: `fix github-settings` (branch protection), `fix release-environment` (release gate), and `doctor` to confirm');
+    }
     const skipped = collectSkippedFixSuggestions(config);
     if (skipped.length > 0) {
         console.log(chalk.bold('\n💡 Want to add something you skipped?\n'));

package/dist/cli/generators/index.js

@@ -19,7 +19,6 @@ import { generateTailwind } from './tailwind.js';
 import { generateTurborepo } from './turborepo.js';
 import { generateNx } from './nx.js';
 import { generateBun } from './bun.js';
-import { generateBrand } from './brand.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export async function generateConfigs(config, targetDir) {
@@ -123,11 +122,6 @@ export async function generateConfigs(config, targetDir) {
     }
     // Generate README
     await generateReadme(config, targetDir);
-    // brand/ (#677) — the same generator as `fix brand`. After the README so the
-    // banner-path repoint sees it; no tagline yet, as the lockfile isn't written.
-    if (config.brand) {
-        await generateBrand(await fs.readJson(path.join(targetDir, 'package.json')), targetDir);
-    }
     // Copy ts-reset if TypeScript is enabled
     if (config.typescript.enabled) {
         await copyTSReset(targetDir);

package/dist/cli/index.js

@@ -178,12 +178,6 @@ const TOOL_CATALOG = [
         exports: ['@rtorcato/repo-tooling/typedoc'],
         fixTarget: 'typedoc',
     },
-    {
-        name: 'Docs site',
-        description: 'Docusaurus docs site (apps/docs) with shared tokens + GitHub Pages deploy',
-        exports: [],
-        fixTarget: 'docs-site',
-    },
     {
         name: 'esbuild',
         description: 'Fast JavaScript bundler configuration',
@@ -340,7 +334,16 @@ program
         '\n  `npx @rtorcato/repo-ai fix claude-skills --force-skills`.');
     process.exitCode = 1;
 });
+// The docs-site and brand scaffolds moved to @rtorcato/shared-docs (#718). The
+// fix targets stay as hidden pointers so old instructions fail with the fix.
+const MOVED_TARGETS = ['docs-site', 'brand'];
 program.hook('preAction', async (_, actionCommand) => {
+    const target = actionCommand.args[0];
+    if (actionCommand.name() === 'fix' && target && MOVED_TARGETS.includes(target)) {
+        console.error(chalk.red(`\`repo-tooling fix ${target}\` moved to @rtorcato/shared-docs.`) +
+            `\n  Run \`npx @rtorcato/shared-docs …\` (see its README).`);
+        process.exit(1);
+    }
     const refusal = await selfRepoRefusal(actionCommand.name(), actionCommand.args[0], actionCommand.opts());
     if (refusal) {
         console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/repo-tooling repo itself.\n'));

package/dist/cli/utils/copy-preset.js

@@ -96,26 +96,6 @@ export const PRESETS = {
         target: '.mcp.json.example',
         desc: 'Commented MCP server template (copy to .mcp.json to activate)',
     },
-    'docusaurus-sync-changelog': {
-        source: 'tooling/docusaurus/sync-changelog.mjs',
-        target: 'scripts/sync-changelog.mjs',
-        desc: 'Canonical CHANGELOG → docs sync script for Docusaurus sites',
-    },
-    'docusaurus-docs-helpers': {
-        source: 'tooling/docusaurus/docs-helpers.mjs',
-        target: 'scripts/docs-helpers.mjs',
-        desc: 'Docs-generator helpers (markdown-table escaping, export parser, generated-block splice)',
-    },
-    'docusaurus-theme-tokens': {
-        source: 'tooling/docusaurus/theme-tokens.css',
-        target: 'apps/docs/src/css/_jt-tokens.css',
-        desc: 'Shared Docusaurus design tokens (Geist + navy surfaces; accent per-project)',
-    },
-    'docusaurus-theme': {
-        source: 'tooling/docusaurus/theme.css',
-        target: 'apps/docs/src/css/theme.css',
-        desc: 'Shared Docusaurus component theme (navbar, cards, sidebar, footer, tables; accent-agnostic — @import after docusaurus-theme-tokens)',
-    },
 };
 export function getPackageRoot() {
     const cliFile = new URL(import.meta.url).pathname;

package/dist/cli/utils/lockfile.js

@@ -163,11 +163,33 @@ export function lockfileSchema() {
                     brand: {
                         type: 'object',
                         additionalProperties: false,
-                        description: 'Inputs to `fix brand`, which scaffolds the banner and social-card SVGs.',
+                        deprecated: true,
+                        description: 'Deprecated: the brand scaffold moved to @rtorcato/shared-docs. Still accepted so existing files validate; removed in the next major.',
                         properties: {
                             tagline: {
                                 type: 'string',
-                                description: 'Short line for the banners and social card, used in place of the package.json description. Keep it to two lines of about 42 characters; `fix brand` warns when it is longer.',
+                                description: 'Short line for the banners and social card, used in place of the package.json description. Keep it to two lines of about 42 characters.',
+                            },
+                        },
+                    },
+                    docs: {
+                        type: 'object',
+                        additionalProperties: false,
+                        deprecated: true,
+                        description: 'Deprecated: the docs-site scaffold moved to @rtorcato/shared-docs, which has the sibling list natively. Still accepted so existing files validate; removed in the next major.',
+                        properties: {
+                            siblings: {
+                                type: 'array',
+                                description: 'Sibling projects to link from the scaffolded docs site (navbar, footer, intro page). Opt-in: when absent the scaffold emits no such links.',
+                                items: {
+                                    type: 'object',
+                                    additionalProperties: false,
+                                    required: ['label', 'href'],
+                                    properties: {
+                                        label: { type: 'string', minLength: 1 },
+                                        href: { type: 'string', minLength: 1 },
+                                    },
+                                },
                             },
                         },
                     },

package/dist/languages/js/checks.js

@@ -1425,68 +1425,6 @@ export async function checkBuildApprovals(dir, pkg) {
         hint: `Record a decision per package under \`allowBuilds:\` in ${WORKSPACE_FILE} (\`name: true\` to run it, \`false\` to skip). pnpm 11 fails \`pnpm install --frozen-lockfile\` outright while any is undecided, so CI cannot pass until each is answered.`,
     };
 }
-/** The docs app dir (apps/docs or apps/doc) if a Docusaurus config lives there. */
-export async function findDocsAppDir(dir) {
-    for (const app of ['apps/docs', 'apps/doc']) {
-        if (await fs.pathExists(path.join(dir, app, 'docusaurus.config.ts')))
-            return app;
-    }
-    return null;
-}
-// Only surfaced when a Docusaurus site exists (see runDoctor). Verifies the
-// shared-asset wiring #54 standardizes: sync-changelog present + chained into
-// the docs app's build/start, and the deploy artifact path is `build` (not
-// `dist`). Opt-in, so a repo without a docs site never sees this.
-export async function checkDocsSite(dir, docsAppDir) {
-    const check = 'Docs site';
-    const deltas = [];
-    // sync-changelog pumps a root CHANGELOG.md into the site — a semantic-release
-    // shape. Changesets writes per-package changelogs and leaves the (private)
-    // root package without one, so don't require the script there (#425). If a
-    // Changesets repo keeps the script anyway, it still has to be wired.
-    const syncPath = path.join(dir, 'scripts', 'sync-changelog.mjs');
-    if (!(await fs.pathExists(syncPath))) {
-        if (!(await usesChangesets(dir)))
-            deltas.push('scripts/sync-changelog.mjs missing');
-    }
-    else {
-        const pkgPath = path.join(dir, docsAppDir, 'package.json');
-        if (await fs.pathExists(pkgPath)) {
-            try {
-                const docsPkg = (await fs.readJson(pkgPath));
-                const scripts = docsPkg.scripts ?? {};
-                const chained = ['build', 'start'].some((s) => typeof scripts[s] === 'string' && /sync-changelog/.test(scripts[s]));
-                // pnpm 8 doesn't run pre* hooks reliably, so build/start must chain it explicitly.
-                if (!chained)
-                    deltas.push(`${docsAppDir} build/start does not chain sync-changelog`);
-            }
-            catch {
-                // Unparseable package.json — a separate check owns that; skip here.
-            }
-        }
-    }
-    // The GitHub Pages deploy must upload `apps/doc*/build` (Docusaurus emits
-    // `build/`, not `dist/`).
-    const workflowsDir = path.join(dir, '.github', 'workflows');
-    if (await fs.pathExists(workflowsDir)) {
-        for (const file of await fs.readdir(workflowsDir)) {
-            if (!/\.ya?ml$/.test(file))
-                continue;
-            const body = await fs.readFile(path.join(workflowsDir, file), 'utf-8').catch(() => '');
-            if (new RegExp(`${docsAppDir}/dist`).test(body)) {
-                deltas.push(`${file} deploys ${docsAppDir}/dist (should be ${docsAppDir}/build)`);
-            }
-        }
-    }
-    if (deltas.length)
-        return {
-            check,
-            status: 'drift',
-            detail: deltas.join('; '),
-            hint: 'Align the docs site with the shared standard (sync-changelog wiring, build/ artifact path)',
-        };
-    return { check, status: 'ok', detail: `${docsAppDir} wired per standard` };
-}
 // Only called when `tailwindcss` is a dependency (see runDoctor) — Tailwind is
 // opt-in per project, so nudging repos that don't use it would be noise. v4 is
 // CSS-first: the wiring is a PostCSS plugin (or the Vite plugin), not a config