@theholocron/astromech 5.0.0-alpha.155 → 5.0.0-alpha.156

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { r as normalizeTaskEntry, t as loadTasksConfig } from "./load-ToVjaKPr.mjs";
+import { r as normalizeTaskEntry, t as loadTasksConfig } from "./load-DdHEVFlG.mjs";
 import { n as alexrc_default, t as editorconfig_checker_default } from "./editorconfig-checker-DPejtR5z.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dependencyNames, detectPackageManager, listWorkspacePackagesSync, readPackageJsonSync } from "@theholocron/pkg-utils";
@@ -9,7 +9,7 @@ import { findExecutableSync } from "@theholocron/fs-utils";
 //#region src/templates/codecov/codecov.yml
 var codecov_default = "codecov:\n  require_ci_to_pass: true\n\ncoverage:\n  precision: 2\n  round: down\n  status:\n    project:\n      default:\n        target: auto\n        threshold: 2%\n        # Infra-only PRs (dep bumps, config, lockfile) touch no coverable code,\n        # so codecov produces no report to compare. Pass instead of blocking\n        # forever on a required check that will never post.\n        if_not_found: success\n    patch:\n      default:\n        target: 80%\n        if_not_found: success\n\ncomment:\n  layout: \"reach,diff,flags,components\"\n  behavior: default\n  require_changes: true\n\ncomponent_management:\n  default_rules:\n    statuses:\n      - type: patch\n        target: 80%\n        if_not_found: success\n  individual_components:\n";
 //#endregion
-//#region src/generators/codecov.ts
+//#region src/generators/codecov/codecov.ts
 /**
 * `codecov.yml` generation — a manifest-derived artifact (component `paths`
 * come from workspace packages; the status targets track the `test` task's
@@ -22,7 +22,7 @@ const INDIVIDUAL_COMPONENTS_MARKER = "  individual_components:";
 function scaffoldHeader() {
 	return [
 		`# Scaffolded by holocron repo setup — edit this file freely.`,
-		`# Source:  theholocron/holocron · packages/astromech/src/generators/codecov.ts`,
+		`# Source:  theholocron/holocron · packages/astromech/src/generators/codecov/codecov.ts`,
 		``
 	].join("\n");
 }
@@ -217,7 +217,7 @@ var verification_typeSafety_default$1 = "name: Typecheck\n\non: # yamllint disab
 //#region src/templates/reusable/verification.unitTests.yml
 var verification_unitTests_default$1 = "name: Test\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      run-unit:\n        description: Run unit tests with coverage (disable for UI-only repos that use Storybook testing exclusively)\n        type: boolean\n        required: false\n        default: true\n      run-storybook:\n        description: Run Storybook vitest interaction tests (requires .storybook/ setup)\n        type: boolean\n        required: false\n        default: false\n      run-interaction:\n        description: Run Storybook interaction and accessibility tests with Playwright\n        type: boolean\n        required: false\n        default: false\n      run-chromatic:\n        description: Publish Storybook to Chromatic for visual regression testing\n        type: boolean\n        required: false\n        default: false\n      chromatic-projects:\n        description: >\n          JSON array of Chromatic projects to build, one matrix job per entry.\n          Each entry: { \"tokenName\": \"WEB\", \"workingDir\": \"apps/web\", \"buildScript\": \"build:storybook\" }.\n          tokenName maps to secret CHROMATIC_PROJECT_TOKEN_<TOKENNAME>; use \"default\"\n          (or omit for the legacy empty-string form) to use the bare CHROMATIC_PROJECT_TOKEN\n          secret for single-project repos.\n          buildScript defaults to \"build:storybook\" when omitted.\n          Default runs a single job from the repo root using CHROMATIC_PROJECT_TOKEN.\n        type: string\n        required: false\n        default: '[{\"tokenName\":\"default\",\"workingDir\":\".\",\"buildScript\":\"build:storybook\"}]'\n      run-user-flow:\n        description: Run Cypress E2E user-flow tests (requires cypress.config.*)\n        type: boolean\n        required: false\n        default: false\n      wait-on-url:\n        description: URL to wait for before running Cypress tests (default is Vite dev server; override for non-Vite stacks e.g. http://localhost:3000 for Next.js)\n        type: string\n        required: false\n        default: \"http://localhost:5173\"\n    secrets:\n      CHROMATIC_PROJECT_TOKEN:\n        required: false\n      CYPRESS_RECORD_KEY:\n        required: false\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  unit:\n    name: Run unit tests and collect coverage\n    if: ${{ inputs.run-unit }}\n    permissions:\n      contents: read\n      id-token: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - uses: theholocron/.github/.github/actions/holocron@main\n        name: Run tests with coverage\n        with:\n          task: verification.unitTests\n\n      # A Codecov upload must not fail silently. fail_ci_if_error makes a failed\n      # upload fail this step (the action's default is to log the error and pass),\n      # which fails the job and so the `Test / Conclusion` check. Whether that\n      # blocks a merge is up to whether the check is required, not this workflow\n      # (holocron#934).\n      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0\n        name: Upload coverage to Codecov\n        with:\n          use_oidc: true\n          fail_ci_if_error: true\n\n      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0\n        name: Upload test results to Codecov\n        if: ${{ !cancelled() }}\n        with:\n          use_oidc: true\n          fail_ci_if_error: true\n          report_type: test_results\n          files: \"**/test-report.junit.xml\"\n\n  storybook:\n    name: Run Storybook interaction tests\n    if: ${{ inputs.run-storybook }}\n    permissions:\n      contents: read\n      id-token: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm exec playwright install chromium --with-deps\n        name: Install Playwright\n\n      - run: pnpm test:storybook\n        name: Run Storybook tests\n\n      # A Codecov upload must not fail silently. fail_ci_if_error makes a failed\n      # upload fail this step (the action's default is to log the error and pass),\n      # which fails the job and so the `Test / Conclusion` check. Whether that\n      # blocks a merge is up to whether the check is required, not this workflow\n      # (holocron#934).\n      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0\n        name: Upload coverage to Codecov\n        with:\n          use_oidc: true\n          fail_ci_if_error: true\n\n      - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0\n        name: Upload test results to Codecov\n        if: ${{ !cancelled() }}\n        with:\n          use_oidc: true\n          fail_ci_if_error: true\n          report_type: test_results\n          files: \"**/test-report.junit.xml\"\n\n  visual-and-composition:\n    # No explicit matrix reference here — a skipped job (run-chromatic:\n    # false, the common case) never expands its matrix, so a `${{\n    # matrix.project.tokenName }}` in name: has nothing to resolve and\n    # shows as raw template text in the checks UI. GitHub auto-appends\n    # the matrix values in parens when the matrix *does* expand, so this\n    # loses no distinctness across multiple Chromatic projects.\n    name: Run visual and composition tests\n    if: ${{ inputs.run-chromatic }}\n    strategy:\n      fail-fast: false\n      matrix:\n        project: ${{ fromJSON(inputs.chromatic-projects) }}\n    permissions:\n      contents: read\n      statuses: write\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - uses: chromaui/action@14cfaef73576e69f95f47f60058063f46ca38719 # v18\n        name: Publish to Chromatic\n        with:\n          projectToken: ${{ (matrix.project.tokenName == 'default' || matrix.project.tokenName == '') && secrets.CHROMATIC_PROJECT_TOKEN || secrets[format('CHROMATIC_PROJECT_TOKEN_{0}', matrix.project.tokenName)] }}\n          token: ${{ github.token }}\n          buildScriptName: ${{ matrix.project.buildScript || 'build:storybook' }}\n          workingDir: ${{ matrix.project.workingDir || '.' }}\n          storybookBaseDir: ${{ matrix.project.storybookBaseDir || '' }}\n          untraced: ${{ matrix.project.untraced || '' }}\n          onlyStoryFiles: ${{ matrix.project.onlyStoryFiles || '' }}\n          exitZeroOnChanges: ${{ matrix.project.exitZeroOnChanges || false }}\n\n  interaction-and-accessibility:\n    name: Run interactions and accessibility tests\n    if: ${{ inputs.run-interaction }}\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm exec playwright install --with-deps\n        name: Install Playwright\n\n      - run: pnpm test:storybook\n        name: Run interaction and accessibility tests\n\n  user-flow:\n    name: Run user flow tests\n    if: ${{ inputs.run-user-flow }}\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    strategy:\n      fail-fast: false\n      matrix:\n        containers: [1, 2]\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm exec cypress install\n        name: Install Cypress binary\n\n      - uses: cypress-io/github-action@1052aa98bbbe4f55210f844878213c07d9c8c399 # v6.7.13\n        name: Cypress run\n        with:\n          start: pnpm dev\n          wait-on: ${{ inputs.wait-on-url }}\n          record: true\n          parallel: true\n        env:\n          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n  conclusion:\n    name: Conclusion\n    runs-on: ubuntu-latest\n    if: always()\n    needs: [unit, storybook, visual-and-composition, interaction-and-accessibility, user-flow]\n    steps:\n      - name: Check job statuses\n        run: |\n          if [[ \"$RESULTS\" == *\"failure\"* ]] || [[ \"$RESULTS\" == *\"cancelled\"* ]]; then\n            exit 1\n          fi\n        env:\n          RESULTS: ${{ join(needs.*.result, ',') }}\n";
 //#endregion
-//#region src/generators/github-action-thin-callers.ts
+//#region src/generators/github-action-thin-callers/github-action-thin-callers.ts
 /**
 * Workflow templates + thin-caller generation.
 *
@@ -244,7 +244,7 @@ const WORKFLOW_TEMPLATES = {
 	"platform.repoSync": "name: Platform\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n    paths:\n      - holocron.config.ts\n      - package.json\n      - pnpm-workspace.yaml\n  workflow_dispatch:\n    inputs:\n      steps:\n        description: \"Sync steps to run (default: all)\"\n        type: string\n        required: false\n\nconcurrency:\n  group: sync-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: write\n  pull-requests: write\n\njobs:\n  sync:\n    name: Sync\n    uses: theholocron/.github/.github/workflows/platform.repoSync.yml@main\n    with:\n      steps: ${{ inputs.steps }}\n    secrets: inherit\n",
 	"platform.commitStandards": "name: Platform\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\nconcurrency:\n  group: platform-commit-standards-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n\njobs:\n  commit-standards:\n    name: Commit Standards\n    uses: theholocron/.github/.github/workflows/platform.commitStandards.yml@main\n    secrets: inherit\n",
 	"platform.repoValidation": "name: Platform\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main, alpha]\n  pull_request:\n\npermissions:\n  contents: read\n\njobs:\n  repo-validation:\n    name: Repo Validation\n    uses: theholocron/.github/.github/workflows/platform.repoValidation.yml@main\n    secrets: inherit\n",
-	"platform.syncTemplates": "name: Platform\n\n# Bootstrap note: this `uses:` a reusable workflow that must already exist\n# on theholocron/.github's main branch to resolve at all — a brand-new\n# reusable workflow here needs ONE manual `holocron sync github` run\n# (pushing directly to theholocron/.github) before this thin caller can\n# ever successfully trigger it, since GitHub resolves `uses:` at run time,\n# not at merge time. Same deadlock every reusable workflow added here hits\n# on its first introduction.\non: # yamllint disable-line rule:truthy\n  push:\n    # main only — this publishes to theholocron/.github, consumed by every\n    # other repo's CI. alpha is the prerelease channel; publishing from it\n    # would let unreleased/unstable template changes overwrite what main\n    # just published, the same stable-vs-prerelease split this org already\n    # enforces for npm's dist-tags and Sentinel's own deploy trigger.\n    branches: [main]\n    paths:\n      - packages/astromech/src/templates/**\n      - packages/astromech/src/generators/**\n      - packages/astromech/src/registry.ts\n      - packages/cli/src/templates/**\n  workflow_dispatch: {}\n\nconcurrency:\n  group: sync-templates\n  cancel-in-progress: false\n\npermissions:\n  contents: read\n\njobs:\n  sync-templates:\n    name: Sync Templates\n    # workflow_dispatch can target ANY ref, not only main — without this,\n    # anyone able to dispatch this workflow (a broader group than who can\n    # push to main) could run it against an arbitrary branch, checking out\n    # and building that ref's own code with the sync token present, then\n    # publishing that ref's templates to theholocron/.github.\n    if: github.ref == 'refs/heads/main'\n    uses: theholocron/.github/.github/workflows/platform.syncTemplates.yml@main\n    secrets: inherit\n",
+	"platform.syncTemplates": "name: Platform\n\n# Bootstrap note: this `uses:` a reusable workflow that must already exist\n# on theholocron/.github's main branch to resolve at all — a brand-new\n# reusable workflow here needs ONE manual `holocron sync github` run\n# (pushing directly to theholocron/.github) before this thin caller can\n# ever successfully trigger it, since GitHub resolves `uses:` at run time,\n# not at merge time. Same deadlock every reusable workflow added here hits\n# on its first introduction.\non: # yamllint disable-line rule:truthy\n  push:\n    # main only — this publishes to theholocron/.github, consumed by every\n    # other repo's CI. alpha is the prerelease channel; publishing from it\n    # would let unreleased/unstable template changes overwrite what main\n    # just published, the same stable-vs-prerelease split this org already\n    # enforces for npm's dist-tags and Sentinel's own deploy trigger.\n    branches: [main]\n    paths:\n      - packages/astromech/src/templates/**\n      - packages/astromech/src/generators/**\n      - packages/astromech/src/registry/**\n      - packages/cli/src/templates/**\n  workflow_dispatch: {}\n\nconcurrency:\n  group: sync-templates\n  cancel-in-progress: false\n\npermissions:\n  contents: read\n\njobs:\n  sync-templates:\n    name: Sync Templates\n    # workflow_dispatch can target ANY ref, not only main — without this,\n    # anyone able to dispatch this workflow (a broader group than who can\n    # push to main) could run it against an arbitrary branch, checking out\n    # and building that ref's own code with the sync token present, then\n    # publishing that ref's templates to theholocron/.github.\n    if: github.ref == 'refs/heads/main'\n    uses: theholocron/.github/.github/workflows/platform.syncTemplates.yml@main\n    secrets: inherit\n",
 	"knowledge.wiki": "name: Knowledge\n\non: # yamllint disable-line rule:truthy\n  push:\n    branches: [main]\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: ${{ github.event_name == 'pull_request' && format('wiki-preview-{0}', github.event.pull_request.number) || 'wiki' }}\n  cancel-in-progress: ${{ github.event_name == 'pull_request' }}\n\npermissions:\n  contents: read\n  deployments: write\n\njobs:\n  publish:\n    name: Publish\n    if: ${{ github.event_name != 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/knowledge.wiki.yml@main\n    secrets: inherit\n\n  preview:\n    name: Preview\n    if: ${{ github.event_name == 'pull_request' }}\n    uses: theholocron/.github/.github/workflows/knowledge.wiki.yml@main\n    with:\n      preview: true\n      preview-id: pr-${{ github.event.pull_request.number }}\n    secrets: inherit\n",
 	preview: "name: Preview\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n    branches: [main]\n\nconcurrency:\n  group: preview-${{ github.event.pull_request.number }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  deployments: write\n  pull-requests: write\n\njobs:\n  preview:\n    name: Preview\n    uses: theholocron/.github/.github/workflows/preview.yml@main\n    secrets: inherit\n",
 	review: "name: Source Quality\n\non: # yamllint disable-line rule:truthy\n  pull_request:\n\nconcurrency:\n  group: review-${{ github.ref }}\n  cancel-in-progress: true\n\npermissions:\n  contents: read\n  checks: write\n  pull-requests: write\n\njobs:\n  review:\n    name: Annotations\n    uses: theholocron/.github/.github/workflows/review.yml@main\n    secrets: inherit\n",
@@ -504,7 +504,7 @@ function deriveDeployPaths(raw) {
 	return paths;
 }
 //#endregion
-//#region src/generators/github-action-reusable-workflows.ts
+//#region src/generators/github-action-reusable-workflows/github-action-reusable-workflows.ts
 /**
 * The **reusable** GitHub Actions surface pushed to `theholocron/.github` by
 * `holocron sync github` — the `workflow_call` implementations and composite
@@ -565,7 +565,7 @@ const WORKFLOW_TEMPLATE_PROPERTIES = { bookkeeping: JSON.stringify({
 	description: "Label and track issues and pull requests.",
 	iconName: "octicon tag"
 }, null, 2) };
-const SOURCE = "packages/astromech/src/generators/github-action-reusable-workflows.ts";
+const SOURCE = "packages/astromech/src/generators/github-action-reusable-workflows/github-action-reusable-workflows.ts";
 /**
 * "AUTO-GENERATED — do not edit" header for the YAML pushed to
 * `theholocron/.github`. Matches `createHeader().workflowHeader({ forPrimary: true })`
@@ -599,7 +599,7 @@ function reusableTemplates() {
 	return out;
 }
 //#endregion
-//#region src/registry.ts
+//#region src/registry/registry.ts
 /**
 * The task registry — how each task runs *locally*, without GitHub
 * Actions. `holocron run <task>` and `holocron run ci` resolve against this;
@@ -813,7 +813,7 @@ const CI_ORDER = [
 	"delivery.deploy"
 ];
 //#endregion
-//#region src/generators/required-checks.ts
+//#region src/generators/required-checks/required-checks.ts
 /**
 * `requiredChecks(config)` — the branch-protection required-status-check list,
 * derived from the task manifest. Every `required: true` task contributes its
@@ -843,7 +843,75 @@ function requiredChecks(config) {
 	return out;
 }
 //#endregion
-//#region src/generators/turbo.ts
+//#region src/generators/tsconfig/tsconfig.ts
+/**
+* `tsconfig.json` generation — Bucket B (config-resolution workstream, #676):
+* the file must stay committed (the TypeScript language server discovers it
+* directly from disk, no `--config` override mechanism to hand it a path
+* instead), but its content is fully derivable, so it's generated rather
+* than hand-authored — the same category as `.editorconfig`
+* ({@link "../../templates/configs/editorconfig/create-config.js" createConfig})
+* and {@link codecovConfig}.
+*
+* Surveyed every package-level `tsconfig.json` across the org (`holocron`,
+* `clients`, `utils` — 20+ packages). `extends: "@theholocron/tsconfig/
+* node-lts"`, `compilerOptions.baseUrl: "./"`, `compilerOptions.outDir:
+* "./dist"`, `include: ["src/**\/*.ts"]`, and `exclude: ["node_modules",
+* "dist"]` are uniform in every one — safe defaults here. `paths` (a `@/*`
+* → `./src/*` import alias) is a real per-package choice, present in
+* roughly 40% of packages checked — an opt-in parameter, not a default.
+*
+* Two fields checked and deliberately *not* absorbed as defaults, unlike
+* `eslint-config`'s `tsconfigRootDir`/`settings.node` (which turned out
+* redundant with the shared package's own behavior, `configs`#461):
+* `compilerOptions.module`/`moduleResolution` (only `@theholocron/cli`
+* overrides these, to `esnext`/`bundler` — a genuine deviation from the
+* shared `node-lts` preset's `nodenext`/`nodenext`, needed for its bundler
+* tooling, not something every package should inherit) and
+* `compilerOptions.rootDir` (present in exactly two packages, always the
+* same value `./src` that `include` already implies — an unnecessary
+* override wherever it appears, not a pattern worth generalizing).
+*
+* Monorepo *root* `tsconfig.json` (a TS project-references "solution
+* file" — `holocron`'s own root is `{ files: [], references: [...] }`,
+* listing which packages to build) is a structurally different, genuinely
+* per-repo document — out of scope here, same as Bucket C content.
+*
+* Not yet wired into `holocron repo setup`'s per-package write loop (every
+* other Bucket B file there is a single repo-root file, safely
+* overwritten every run — `tsconfig.json` is per-package, and most
+* packages' files still carry real hand-authored content today, not yet
+* migrated to a fully-generated state). That per-package iteration +
+* safe-migration design is `#680`'s job, not duplicated here — this is
+* the generator itself, ready for it to call.
+*/
+/**
+* A package-level `tsconfig.json` — the uniform shape confirmed across
+* every package checked, parameterized only by the two fields that
+* genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
+* `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
+* JSON has no comment syntax to carry one, and TypeScript's own tolerance
+* for JSONC comments in `tsconfig.json` isn't worth relying on for a file
+* this thin).
+*/
+function createTsconfig(options) {
+	const variant = options.variant ?? "node-lts";
+	const compilerOptions = {
+		baseUrl: "./",
+		outDir: "./dist"
+	};
+	if (options.paths) compilerOptions.paths = { "@/*": ["./src/*"] };
+	const config = {
+		display: options.display,
+		extends: `@theholocron/tsconfig/${variant}`,
+		compilerOptions,
+		include: ["src/**/*.ts"],
+		exclude: ["node_modules", "dist"]
+	};
+	return stringifyJson(config);
+}
+//#endregion
+//#region src/generators/turbo/turbo.ts
 /**
 * `turboConfig(config)` — the generated `turbo.json` for a repo's task
 * manifest, epic #672 D9 (#681). Every workspace, monorepo or single-package
@@ -1033,7 +1101,7 @@ function ensureTurboDependency(packageJson, workspaceYaml) {
 	};
 }
 //#endregion
-//#region src/tasks/run/linters.ts
+//#region src/tasks/run/linters/linters.ts
 /**
 * The linter registry — one list of linter names (from `config.tasks`'
 * `{ name: "lint", linters: [...] }`, or auto-detected) maps to both the
@@ -1187,14 +1255,14 @@ function resolveLinters(opts) {
 	}));
 }
 //#endregion
-//#region src/tasks/run/resolve-bin.ts
+//#region src/tasks/run/resolve-bin/resolve-bin.ts
 /** `<cwd>/node_modules/.bin/<tool>` when it exists, else the bare `tool` name (left to `PATH`). */
 function resolveBin(cwd, tool, fileExists) {
 	const local = join(cwd, "node_modules", ".bin", tool);
 	return fileExists(local) ? local : tool;
 }
 //#endregion
-//#region src/tasks/run/resolve-runner.ts
+//#region src/tasks/run/resolve-runner/resolve-runner.ts
 const mkRunner = (tool, args = []) => ({
 	tool,
 	args
@@ -1241,7 +1309,7 @@ function resolveRunner(local, cwd, listDir, readFile) {
 	for (const candidate of local.detect) if (files.some((f) => candidate.when.test(f)) || deps.has(candidate.tool)) return mkRunner(candidate.tool, candidate.args);
 }
 //#endregion
-//#region src/tasks/run/resolve-export-entry.ts
+//#region src/tasks/run/resolve-export-entry/resolve-export-entry.ts
 /**
 * Unwrap a `package.json#exports` subpath entry down to its file path —
 * either a bare string, or an object with condition keys (`import`,
@@ -1259,7 +1327,7 @@ function resolveExportEntry(entry) {
 	if (typeof value === "object" && value !== null) return resolveExportEntry(value);
 }
 //#endregion
-//#region src/tasks/run/tool-configs.ts
+//#region src/tasks/run/tool-configs/tool-configs.ts
 /**
 * `library` is every mapped tool's org-wide default variant today — every
 * currently-migrated repo (`holocron`, `clients`, `utils`, `configs`,
@@ -1337,7 +1405,7 @@ const LOCAL_CONFIG_FILES = {
 	]
 };
 //#endregion
-//#region src/tasks/run/resolve-tool-config.ts
+//#region src/tasks/run/resolve-tool-config/resolve-tool-config.ts
 /**
 * Resolves the absolute path to a Bucket A tool's shared `@theholocron/*-config`
 * entry point, installed in the consuming repo's own `node_modules` — and the
@@ -1401,7 +1469,7 @@ function resolveToolConfig(tool, cwd, deps) {
 	return [...spec.flag, absolute];
 }
 //#endregion
-//#region src/tasks/run/turbo-defines-task.ts
+//#region src/tasks/run/turbo-defines-task/turbo-defines-task.ts
 /** `true` when `<cwd>/turbo.json` declares `task` (under `tasks`, or turbo 1.x's `pipeline`). */
 function turboDefinesTask(cwd, task, readFile, fileExists) {
 	if (!fileExists(join(cwd, "turbo.json"))) return false;
@@ -1746,7 +1814,7 @@ function runLinterGroup(input, names, passthrough) {
 	};
 }
 //#endregion
-//#region src/tasks/ci.ts
+//#region src/tasks/ci/ci.ts
 /**
 * `holocron run ci` / `astromech.ci()` — run the merge-gating checks locally, in CI
 * order, and exit non-zero on the first failure. The "will CI pass?" command a
@@ -1816,71 +1884,85 @@ function taskName(item) {
 	return typeof item === "string" ? item : item.name;
 }
 //#endregion
-//#region src/tasks/match-namespace.ts
-/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
-function matchNamespace(config, namespace) {
-	const prefix = `${namespace}.`;
-	return (config.tasks ?? []).map(normalizeTaskEntry).reduce((names, entry) => {
-		if (entry.name.startsWith(prefix) && !names.includes(entry.name)) names.push(entry.name);
-		return names;
-	}, []);
-}
-//#endregion
-//#region src/tasks/group.ts
-function runGroup(input) {
-	const { print, namespace } = input;
-	const names = matchNamespace(input.config, namespace);
-	if (names.length === 0) return {
-		status: "unknown",
-		jobs: []
-	};
-	print(`holocron run ${namespace} — ${names.length} task(s)`);
-	print("");
-	const jobs = [];
-	for (const name of names) {
-		print(`▶ ${name}`);
-		const r = runTask({
-			print: (line) => print(`  ${line}`),
-			logger: input.logger,
-			exec: input.exec,
-			readFile: input.readFile,
-			fileExists: input.fileExists,
-			listDir: input.listDir,
-			lookPath: input.lookPath,
-			task: name,
-			cwd: input.cwd,
-			dryRun: input.dryRun ?? false,
-			...input.filter ? { filter: input.filter } : {}
-		});
-		jobs.push({
-			task: name,
-			status: r.status,
-			command: r.command,
-			message: r.message
-		});
-	}
+//#region src/utils/create-header/create-header.ts
+/**
+* Factory that binds `source` and `tool` once and returns all header
+* constructors for auto-generated files. Prefer this over passing source
+* as a positional argument at every call site.
+*
+* @example
+* const { workflowHeader, scaffoldHeader } = createHeader({
+*   source: "packages/astromech/src/templates/configs/editorconfig/create-config.ts",
+* });
+*
+* export function createConfig(): string {
+*   return `${workflowHeader()}${body}`;
+* }
+*
+* ## Which header to use
+*
+* | Function          | When to use                                        | User can edit? |
+* |-------------------|----------------------------------------------------|----------------|
+* | `workflowHeader`  | Files overwritten on every setup / sync-github run | No — "AUTO-GENERATED — do not edit" |
+* | `scaffoldHeader`  | Files written once; user takes ownership after     | Yes — "Scaffolded — edit this file freely" |
+*
+* ## `workflowHeader` formats
+*
+* | Format              | Comment style          | Used for                                              |
+* |---------------------|------------------------|-------------------------------------------------------|
+* | `"yaml"` (default)  | `# …` lines            | YAML workflows, ignore files, `.editorconfig`, labeler|
+* | `"cjs"`             | `/* … *\/` block       | CommonJS config files (`.cjs`)                        |
+* | `"shebang"`         | `#!/bin/sh` + `# …`    | Shell scripts (`prepare-commit-msg`, hooks)           |
+*/
+function createHeader(options) {
+	const { source, tool = "holocron repo setup", forPrimary = false } = options;
+	const doNotEdit = forPrimary ? `AUTO-GENERATED — do not edit in theholocron/.github directly.` : `AUTO-GENERATED — do not edit directly.`;
 	return {
-		status: jobs.some((j) => j.status === "fail") ? "fail" : jobs.every((j) => j.status === "dry-run") ? "dry-run" : "ok",
-		jobs
+		workflowHeader(format = "yaml") {
+			if (format === "cjs") return [
+				`/* ${doNotEdit}`,
+				` * Source:  theholocron/holocron · ${source}`,
+				` * Tool:    ${tool}`,
+				` * Changes: edit source in theholocron/holocron`,
+				` */`,
+				``
+			].join("\n");
+			const yamlLines = [
+				`# ${doNotEdit}`,
+				`# Source:  theholocron/holocron · ${source}`,
+				`# Tool:    ${tool}`,
+				`# Changes: edit source in theholocron/holocron`,
+				``
+			].join("\n");
+			if (format === "shebang") return `#!/bin/sh\n\n${yamlLines}`;
+			return yamlLines;
+		},
+		scaffoldHeader() {
+			return [
+				`# Scaffolded by holocron repo setup — edit this file freely.`,
+				`# Source:  theholocron/holocron · ${source}`,
+				``
+			].join("\n");
+		}
 	};
 }
 //#endregion
-//#region src/utils/default-list-dirs.ts
+//#region src/utils/default-list-dirs/default-list-dirs.ts
 const defaultListDirs = (path) => readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 //#endregion
-//#region src/utils/default-read-json.ts
+//#region src/utils/default-read-json/default-read-json.ts
 const defaultReadJson = (path) => JSON.parse(readFileSync(path, "utf8"));
 //#endregion
-//#region src/utils/default-run.ts
+//#region src/utils/default-run/default-run.ts
 const defaultRun = (command, args, opts) => spawnSync(command, args, {
 	encoding: "utf8",
 	...opts
 });
 //#endregion
-//#region src/utils/default-sleep.ts
+//#region src/utils/default-sleep/default-sleep.ts
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 //#endregion
-//#region src/utils/exec.ts
+//#region src/utils/exec/exec.ts
 /** Runs `cmd` with the parent's stdio; a signal-killed or unspawnable process reports `-1`. */
 const realExec = (cmd, args, opts) => {
 	return { exitCode: spawnSync(cmd, args, {
@@ -1889,262 +1971,76 @@ const realExec = (cmd, args, opts) => {
 	}).status ?? -1 };
 };
 //#endregion
-//#region src/utils/look-path.ts
+//#region src/utils/look-path/look-path.ts
 /** `node_modules/.bin/<bin>`, else the first `PATH` entry that has it, else `null`. */
 const realLookPath = (cwd, bin) => findExecutableSync(bin, { path: join(cwd, "node_modules", ".bin") }) ?? findExecutableSync(bin) ?? null;
 //#endregion
-//#region src/utils/noop-logger.ts
+//#region src/utils/noop-logger/noop-logger.ts
 /** The `RunLogger` used when the caller injects none: drops every record. */
 const noopLogger = {
 	debug() {},
 	warn() {}
 };
 //#endregion
-//#region src/astromech.ts
+//#region src/tasks/deploy-on-release/constants.ts
+/** A stable release (no prerelease identifier) is on `main`, the default channel for a task. */
+const MAIN_CHANNEL = "main";
+const DEPLOY_TASK = "delivery.deploy";
+/** How long to wait for npm to serve the release's versions, and how often to ask. */
+const WAIT_TIMEOUT_MS = 3e5;
+const WAIT_INTERVAL_MS = 1e4;
+//#endregion
+//#region src/tasks/deploy-on-release/workspace-dependencies/workspace-dependencies.ts
+/** The `workspace:*` dependencies of `pkg`, as workspace packages (with their current version). */
+function workspaceDependencies(pkg, all) {
+	const names = new Set(Object.entries(pkg.dependencies).filter(([, spec]) => String(spec).startsWith("workspace:")).map(([name]) => name));
+	return all.filter((candidate) => names.has(candidate.name));
+}
+//#endregion
+//#region src/tasks/deploy-on-release/default-paths/default-paths.ts
 /**
-* `createAstromech(options)` — the self-contained task runner.
-* `@theholocron/cli` instantiates it once and delegates the `run` /
-* `ci` / workflow-generation commands to it (like `@theholocron/observability`).
+* The paths a release must touch to redeploy `pkg` when its manifest doesn't
+* list them: its own folder plus the folder of every
+* {@link workspaceDependencies} entry. Derived rather than listed so a new or
+* dropped workspace dependency needs no second edit.
+*
+* @returns Repo-relative prefixes, each ending in `/`.
 */
-function createAstromech(options) {
-	const deps = {
-		print: options.print ?? ((line) => console.log(line)),
-		logger: options.logger ?? noopLogger,
-		exec: options.exec ?? realExec,
-		readFile: options.readFile ?? ((path) => readFileSync(path, "utf8")),
-		fileExists: options.fileExists ?? ((path) => existsSync(path)),
-		listDir: options.listDir ?? ((path) => readdirSync(path)),
-		lookPath: options.lookPath ?? realLookPath
+function defaultPaths(repoRoot, pkg, all) {
+	return [pkg, ...workspaceDependencies(pkg, all)].map(({ dir }) => `${relative(repoRoot, dir)}/`);
+}
+//#endregion
+//#region src/tasks/deploy-on-release/deploy-targets/deploy-targets.ts
+/**
+* The packages whose manifest declares a release-time `delivery.deploy`
+* (`with.on === "release"`), with the task's options resolved.
+*/
+function deployTargets(packages, manifests) {
+	return packages.flatMap((pkg) => (manifests.get(pkg.dir)?.tasks ?? []).flatMap((item) => {
+		const entry = normalizeTaskEntry(item);
+		if (entry.name !== "delivery.deploy" || entry.with?.["on"] !== "release") return [];
+		const { channel, paths } = entry.with;
+		return [{
+			pkg,
+			channel: typeof channel === "string" ? channel : MAIN_CHANNEL,
+			paths: Array.isArray(paths) ? paths.map(String) : void 0
+		}];
+	}));
+}
+//#endregion
+//#region src/tasks/deploy-on-release/should-deploy/should-deploy.ts
+/**
+* @param channel The release's channel: its prerelease identifier (`alpha`), or `main` for a stable release.
+* @param changedFiles `undefined` when there's no previous release to diff against.
+*/
+function shouldDeploy({ channel, configuredChannel, changedFiles, paths }) {
+	if (channel !== configuredChannel) return {
+		deploy: false,
+		reason: `channel "${channel}" isn't "${configuredChannel}"`
 	};
-	const items = () => (options.config?.tasks ?? []).map((i) => normalizeTaskEntry(i));
-	/**
-	* Task names this repo's manifest can actually run locally — shared by
-	* {@link packageScripts} and by `holocron`'s own interactive task picker.
-	* Deliberately independent of `syncScripts`/`holocronScript`/`hooks`:
-	* those govern whether/how `package.json` scripts get *written*, not
-	* which tasks exist to run. A repo with `syncScripts: false` (this repo
-	* itself, among others) still has real runnable tasks — found live when
-	* `packageScripts()`'s `{}` short-circuit silently emptied the picker too.
-	*/
-	const runnableTaskNames = () => {
-		const out = [];
-		for (const entry of items()) {
-			const def = TASKS[entry.name];
-			const hasNoLocalRunner = def?.local === null && !def.linterGroup && !def.jobs;
-			if (entry.local === false || !KNOWN_TASKS.has(entry.name) || hasNoLocalRunner) continue;
-			out.push(entry.name);
-		}
-		return out;
-	};
-	return {
-		run: (task, opts = {}) => {
-			if (!TASKS[task] && options.config && matchNamespace(options.config, task).length > 0) return runGroup({
-				...deps,
-				cwd: options.cwd,
-				config: options.config,
-				namespace: task,
-				dryRun: opts.dryRun ?? false,
-				...opts.filter ? { filter: opts.filter } : {}
-			});
-			return runTask({
-				...deps,
-				task,
-				cwd: options.cwd,
-				...opts.job !== void 0 ? { job: opts.job } : {},
-				passthrough: opts.passthrough ?? [],
-				dryRun: opts.dryRun ?? false,
-				required: opts.required ?? false,
-				...opts.filter ? { filter: opts.filter } : {}
-			});
-		},
-		ci: (opts = {}) => runCi({
-			...deps,
-			cwd: options.cwd,
-			config: options.config ?? {},
-			...opts
-		}),
-		thinCallers: () => {
-			const orgCtx = options.orgContext ?? {};
-			const out = /* @__PURE__ */ new Map();
-			for (const entry of items()) {
-				const isDocsSite = entry.name === "knowledge.docs";
-				const isComponents = entry.name === "knowledge.components";
-				if (entry.ci === false || !KNOWN_WORKFLOWS.has(entry.name) && !isDocsSite && !isComponents) continue;
-				if (entry.name === "delivery.deploy" && entry.with?.["on"] === "release") continue;
-				const rawWith = isDocsSite ? {
-					preview: true,
-					...entry.with,
-					docs: entry.with?.["docs"] ?? true
-				} : isComponents ? {
-					preview: true,
-					...entry.with,
-					storybook: entry.with?.["storybook"] ?? [{ workingDir: "." }]
-				} : entry.with;
-				const withOverrides = rawWith ? normalizeWorkflowWith(rawWith) : void 0;
-				if (entry.name === "verification.unitTests" && withOverrides?.["run-unit"] === false && withOverrides?.["run-storybook"] === false) throw new Error("test workflow: at least one of \"run-unit\" or \"run-storybook\" must be true. Library repos use run-unit: true; UI/Storybook repos use run-storybook: true.");
-				const isDeployFamily = entry.name === "delivery.deploy" || isDocsSite || isComponents;
-				const additionalPaths = entry.paths ?? (isDeployFamily && rawWith ? deriveDeployPaths(rawWith) : void 0);
-				if (isDeployFamily && rawWith) {
-					const preview = extractPreviewConfig(rawWith, orgCtx);
-					if (preview) {
-						const deployWith = normalizeWorkflowWith(rawWith);
-						const deployPaths = entry.paths ?? deriveDeployPaths(rawWith);
-						out.set(`${entry.name}.yml`, generateCombinedDeployContent(deployWith, deployPaths, preview));
-						continue;
-					}
-				}
-				out.set(`${entry.name}.yml`, generateThinCallerContent(entry.name, withOverrides, additionalPaths, deps.logger));
-			}
-			return out;
-		},
-		packageScripts: () => {
-			const out = {};
-			if (!options.config || options.config.syncScripts === false) return out;
-			out.holocron = options.config.holocronScript ?? "holocron";
-			for (const name of runnableTaskNames()) out[name] = `holocron run ${name} --`;
-			const hooks = options.config.hooks;
-			if (hooks === true || typeof hooks === "object" && hooks.prePush !== false) out.prepare = "husky";
-			return out;
-		},
-		runnableTasks: () => runnableTaskNames(),
-		reusableTemplates: () => reusableTemplates(),
-		requiredChecks: () => requiredChecks(options.config ?? {}),
-		codecovConfig: (existing) => codecovConfig(options.cwd, existing),
-		turboConfig: () => turboConfig(options.config ?? {}),
-		ensureRootWorkspaceMember: (workspaceYaml, rootScripts) => {
-			return ensureRootWorkspaceMember(workspaceYaml, rootScripts, (options.config?.tasks ?? []).map(normalizeTaskEntry).filter((e) => e.local !== false).map((e) => e.name));
-		},
-		ensureTurboDependency: (packageJson, workspaceYaml) => ensureTurboDependency(packageJson, workspaceYaml)
-	};
-}
-//#endregion
-//#region src/generators/tsconfig.ts
-/**
-* `tsconfig.json` generation — Bucket B (config-resolution workstream, #676):
-* the file must stay committed (the TypeScript language server discovers it
-* directly from disk, no `--config` override mechanism to hand it a path
-* instead), but its content is fully derivable, so it's generated rather
-* than hand-authored — the same category as `.editorconfig`
-* ({@link "./templates/configs/editorconfig/create-config.js" createConfig})
-* and {@link codecovConfig}.
-*
-* Surveyed every package-level `tsconfig.json` across the org (`holocron`,
-* `clients`, `utils` — 20+ packages). `extends: "@theholocron/tsconfig/
-* node-lts"`, `compilerOptions.baseUrl: "./"`, `compilerOptions.outDir:
-* "./dist"`, `include: ["src/**\/*.ts"]`, and `exclude: ["node_modules",
-* "dist"]` are uniform in every one — safe defaults here. `paths` (a `@/*`
-* → `./src/*` import alias) is a real per-package choice, present in
-* roughly 40% of packages checked — an opt-in parameter, not a default.
-*
-* Two fields checked and deliberately *not* absorbed as defaults, unlike
-* `eslint-config`'s `tsconfigRootDir`/`settings.node` (which turned out
-* redundant with the shared package's own behavior, `configs`#461):
-* `compilerOptions.module`/`moduleResolution` (only `@theholocron/cli`
-* overrides these, to `esnext`/`bundler` — a genuine deviation from the
-* shared `node-lts` preset's `nodenext`/`nodenext`, needed for its bundler
-* tooling, not something every package should inherit) and
-* `compilerOptions.rootDir` (present in exactly two packages, always the
-* same value `./src` that `include` already implies — an unnecessary
-* override wherever it appears, not a pattern worth generalizing).
-*
-* Monorepo *root* `tsconfig.json` (a TS project-references "solution
-* file" — `holocron`'s own root is `{ files: [], references: [...] }`,
-* listing which packages to build) is a structurally different, genuinely
-* per-repo document — out of scope here, same as Bucket C content.
-*
-* Not yet wired into `holocron repo setup`'s per-package write loop (every
-* other Bucket B file there is a single repo-root file, safely
-* overwritten every run — `tsconfig.json` is per-package, and most
-* packages' files still carry real hand-authored content today, not yet
-* migrated to a fully-generated state). That per-package iteration +
-* safe-migration design is `#680`'s job, not duplicated here — this is
-* the generator itself, ready for it to call.
-*/
-/**
-* A package-level `tsconfig.json` — the uniform shape confirmed across
-* every package checked, parameterized only by the two fields that
-* genuinely vary (`display`, `paths`). No scaffold/workflow header (matches
-* `.alexrc.json`'s existing precedent for a strict-JSON Bucket B file —
-* JSON has no comment syntax to carry one, and TypeScript's own tolerance
-* for JSONC comments in `tsconfig.json` isn't worth relying on for a file
-* this thin).
-*/
-function createTsconfig(options) {
-	const variant = options.variant ?? "node-lts";
-	const compilerOptions = {
-		baseUrl: "./",
-		outDir: "./dist"
-	};
-	if (options.paths) compilerOptions.paths = { "@/*": ["./src/*"] };
-	const config = {
-		display: options.display,
-		extends: `@theholocron/tsconfig/${variant}`,
-		compilerOptions,
-		include: ["src/**/*.ts"],
-		exclude: ["node_modules", "dist"]
-	};
-	return stringifyJson(config);
-}
-//#endregion
-//#region src/tasks/deploy-on-release/constants.ts
-/** A stable release (no prerelease identifier) is on `main`, the default channel for a task. */
-const MAIN_CHANNEL = "main";
-const DEPLOY_TASK = "delivery.deploy";
-/** How long to wait for npm to serve the release's versions, and how often to ask. */
-const WAIT_TIMEOUT_MS = 3e5;
-const WAIT_INTERVAL_MS = 1e4;
-//#endregion
-//#region src/tasks/deploy-on-release/workspace-dependencies.ts
-/** The `workspace:*` dependencies of `pkg`, as workspace packages (with their current version). */
-function workspaceDependencies(pkg, all) {
-	const names = new Set(Object.entries(pkg.dependencies).filter(([, spec]) => String(spec).startsWith("workspace:")).map(([name]) => name));
-	return all.filter((candidate) => names.has(candidate.name));
-}
-//#endregion
-//#region src/tasks/deploy-on-release/default-paths.ts
-/**
-* The paths a release must touch to redeploy `pkg` when its manifest doesn't
-* list them: its own folder plus the folder of every
-* {@link workspaceDependencies} entry. Derived rather than listed so a new or
-* dropped workspace dependency needs no second edit.
-*
-* @returns Repo-relative prefixes, each ending in `/`.
-*/
-function defaultPaths(repoRoot, pkg, all) {
-	return [pkg, ...workspaceDependencies(pkg, all)].map(({ dir }) => `${relative(repoRoot, dir)}/`);
-}
-//#endregion
-//#region src/tasks/deploy-on-release/deploy-targets.ts
-/**
-* The packages whose manifest declares a release-time `delivery.deploy`
-* (`with.on === "release"`), with the task's options resolved.
-*/
-function deployTargets(packages, manifests) {
-	return packages.flatMap((pkg) => (manifests.get(pkg.dir)?.tasks ?? []).flatMap((item) => {
-		const entry = normalizeTaskEntry(item);
-		if (entry.name !== "delivery.deploy" || entry.with?.["on"] !== "release") return [];
-		const { channel, paths } = entry.with;
-		return [{
-			pkg,
-			channel: typeof channel === "string" ? channel : MAIN_CHANNEL,
-			paths: Array.isArray(paths) ? paths.map(String) : void 0
-		}];
-	}));
-}
-//#endregion
-//#region src/tasks/deploy-on-release/should-deploy.ts
-/**
-* @param channel The release's channel: its prerelease identifier (`alpha`), or `main` for a stable release.
-* @param changedFiles `undefined` when there's no previous release to diff against.
-*/
-function shouldDeploy({ channel, configuredChannel, changedFiles, paths }) {
-	if (channel !== configuredChannel) return {
-		deploy: false,
-		reason: `channel "${channel}" isn't "${configuredChannel}"`
-	};
-	if (changedFiles === void 0) return {
-		deploy: true,
-		reason: "no previous release to diff against"
+	if (changedFiles === void 0) return {
+		deploy: true,
+		reason: "no previous release to diff against"
 	};
 	const touched = changedFiles.find((file) => paths.some((path) => file.startsWith(path)));
 	return touched ? {
@@ -2156,7 +2052,7 @@ function shouldDeploy({ channel, configuredChannel, changedFiles, paths }) {
 	};
 }
 //#endregion
-//#region src/tasks/deploy-on-release/wait-for-published.ts
+//#region src/tasks/deploy-on-release/wait-for-published/wait-for-published.ts
 /**
 * Waits until npm serves every `name@version` in `packages`, asking with
 * `npm view --prefer-online` (so npm's local cache can't answer for the
@@ -2183,7 +2079,7 @@ async function waitForPublished({ packages, run, sleep, now, cwd, timeoutMs = WA
 	}
 }
 //#endregion
-//#region src/tasks/deploy-on-release/workspace-packages.ts
+//#region src/tasks/deploy-on-release/workspace-packages/workspace-packages.ts
 /**
 * Every package under `<repoRoot>/packages/*` and `<repoRoot>/plugins/*`
 * with a readable, named `package.json` — `holocron`'s own layout splits
@@ -2349,66 +2245,182 @@ async function deployOnRelease(options, { run = defaultRun, readJson = defaultRe
 	};
 }
 //#endregion
-//#region src/utils/create-header.ts
+//#region src/tasks/match-namespace/match-namespace.ts
+/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
+function matchNamespace(config, namespace) {
+	const prefix = `${namespace}.`;
+	return (config.tasks ?? []).map(normalizeTaskEntry).reduce((names, entry) => {
+		if (entry.name.startsWith(prefix) && !names.includes(entry.name)) names.push(entry.name);
+		return names;
+	}, []);
+}
+//#endregion
+//#region src/tasks/group/group.ts
 /**
-* Factory that binds `source` and `tool` once and returns all header
-* constructors for auto-generated files. Prefer this over passing source
-* as a positional argument at every call site.
-*
-* @example
-* const { workflowHeader, scaffoldHeader } = createHeader({
-*   source: "packages/astromech/src/templates/configs/editorconfig/create-config.ts",
-* });
-*
-* export function createConfig(): string {
-*   return `${workflowHeader()}${body}`;
-* }
+* `holocron run <namespace>` — run every configured task under one
+* namespace prefix (`sourceQuality.*`, `verification.*`, …) in sequence.
+* `Astromech.run()` falls back here whenever the given name isn't an exact
+* `TASKS` entry but matches the prefix of one or more configured tasks —
+* same "aggregate several real tasks into one report" shape `runCi` already
+* established, scoped to one namespace instead of the merge-gating set.
 *
-* ## Which header to use
-*
-* | Function          | When to use                                        | User can edit? |
-* |-------------------|----------------------------------------------------|----------------|
-* | `workflowHeader`  | Files overwritten on every setup / sync-github run | No — "AUTO-GENERATED — do not edit" |
-* | `scaffoldHeader`  | Files written once; user takes ownership after     | Yes — "Scaffolded — edit this file freely" |
-*
-* ## `workflowHeader` formats
-*
-* | Format              | Comment style          | Used for                                              |
-* |---------------------|------------------------|-------------------------------------------------------|
-* | `"yaml"` (default)  | `# …` lines            | YAML workflows, ignore files, `.editorconfig`, labeler|
-* | `"cjs"`             | `/* … *\/` block       | CommonJS config files (`.cjs`)                        |
-* | `"shebang"`         | `#!/bin/sh` + `# …`    | Shell scripts (`prepare-commit-msg`, hooks)           |
+* Every task in the namespace always runs — one task's failure never skips
+* the rest, same as `runCi`'s own loop — so a single invocation surfaces
+* every problem in the namespace at once instead of stopping at the first.
 */
-function createHeader(options) {
-	const { source, tool = "holocron repo setup", forPrimary = false } = options;
-	const doNotEdit = forPrimary ? `AUTO-GENERATED — do not edit in theholocron/.github directly.` : `AUTO-GENERATED — do not edit directly.`;
+function runGroup(input) {
+	const { print, namespace } = input;
+	const names = matchNamespace(input.config, namespace);
+	if (names.length === 0) return {
+		status: "unknown",
+		jobs: []
+	};
+	print(`holocron run ${namespace} — ${names.length} task(s)`);
+	print("");
+	const jobs = [];
+	for (const name of names) {
+		print(`▶ ${name}`);
+		const r = runTask({
+			print: (line) => print(`  ${line}`),
+			logger: input.logger,
+			exec: input.exec,
+			readFile: input.readFile,
+			fileExists: input.fileExists,
+			listDir: input.listDir,
+			lookPath: input.lookPath,
+			task: name,
+			cwd: input.cwd,
+			dryRun: input.dryRun ?? false,
+			...input.filter ? { filter: input.filter } : {}
+		});
+		jobs.push({
+			task: name,
+			status: r.status,
+			command: r.command,
+			message: r.message
+		});
+	}
 	return {
-		workflowHeader(format = "yaml") {
-			if (format === "cjs") return [
-				`/* ${doNotEdit}`,
-				` * Source:  theholocron/holocron · ${source}`,
-				` * Tool:    ${tool}`,
-				` * Changes: edit source in theholocron/holocron`,
-				` */`,
-				``
-			].join("\n");
-			const yamlLines = [
-				`# ${doNotEdit}`,
-				`# Source:  theholocron/holocron · ${source}`,
-				`# Tool:    ${tool}`,
-				`# Changes: edit source in theholocron/holocron`,
-				``
-			].join("\n");
-			if (format === "shebang") return `#!/bin/sh\n\n${yamlLines}`;
-			return yamlLines;
-		},
-		scaffoldHeader() {
-			return [
-				`# Scaffolded by holocron repo setup — edit this file freely.`,
-				`# Source:  theholocron/holocron · ${source}`,
-				``
-			].join("\n");
+		status: jobs.some((j) => j.status === "fail") ? "fail" : jobs.every((j) => j.status === "dry-run") ? "dry-run" : "ok",
+		jobs
+	};
+}
+//#endregion
+//#region src/astromech.ts
+/**
+* `createAstromech(options)` — the self-contained task runner.
+* `@theholocron/cli` instantiates it once and delegates the `run` /
+* `ci` / workflow-generation commands to it (like `@theholocron/observability`).
+*/
+function createAstromech(options) {
+	const deps = {
+		print: options.print ?? ((line) => console.log(line)),
+		logger: options.logger ?? noopLogger,
+		exec: options.exec ?? realExec,
+		readFile: options.readFile ?? ((path) => readFileSync(path, "utf8")),
+		fileExists: options.fileExists ?? ((path) => existsSync(path)),
+		listDir: options.listDir ?? ((path) => readdirSync(path)),
+		lookPath: options.lookPath ?? realLookPath
+	};
+	const items = () => (options.config?.tasks ?? []).map((i) => normalizeTaskEntry(i));
+	/**
+	* Task names this repo's manifest can actually run locally — shared by
+	* {@link packageScripts} and by `holocron`'s own interactive task picker.
+	* Deliberately independent of `syncScripts`/`holocronScript`/`hooks`:
+	* those govern whether/how `package.json` scripts get *written*, not
+	* which tasks exist to run. A repo with `syncScripts: false` (this repo
+	* itself, among others) still has real runnable tasks — found live when
+	* `packageScripts()`'s `{}` short-circuit silently emptied the picker too.
+	*/
+	const runnableTaskNames = () => {
+		const out = [];
+		for (const entry of items()) {
+			const def = TASKS[entry.name];
+			const hasNoLocalRunner = def?.local === null && !def.linterGroup && !def.jobs;
+			if (entry.local === false || !KNOWN_TASKS.has(entry.name) || hasNoLocalRunner) continue;
+			out.push(entry.name);
 		}
+		return out;
+	};
+	return {
+		run: (task, opts = {}) => {
+			if (!TASKS[task] && options.config && matchNamespace(options.config, task).length > 0) return runGroup({
+				...deps,
+				cwd: options.cwd,
+				config: options.config,
+				namespace: task,
+				dryRun: opts.dryRun ?? false,
+				...opts.filter ? { filter: opts.filter } : {}
+			});
+			return runTask({
+				...deps,
+				task,
+				cwd: options.cwd,
+				...opts.job !== void 0 ? { job: opts.job } : {},
+				passthrough: opts.passthrough ?? [],
+				dryRun: opts.dryRun ?? false,
+				required: opts.required ?? false,
+				...opts.filter ? { filter: opts.filter } : {}
+			});
+		},
+		ci: (opts = {}) => runCi({
+			...deps,
+			cwd: options.cwd,
+			config: options.config ?? {},
+			...opts
+		}),
+		thinCallers: () => {
+			const orgCtx = options.orgContext ?? {};
+			const out = /* @__PURE__ */ new Map();
+			for (const entry of items()) {
+				const isDocsSite = entry.name === "knowledge.docs";
+				const isComponents = entry.name === "knowledge.components";
+				if (entry.ci === false || !KNOWN_WORKFLOWS.has(entry.name) && !isDocsSite && !isComponents) continue;
+				if (entry.name === "delivery.deploy" && entry.with?.["on"] === "release") continue;
+				const rawWith = isDocsSite ? {
+					preview: true,
+					...entry.with,
+					docs: entry.with?.["docs"] ?? true
+				} : isComponents ? {
+					preview: true,
+					...entry.with,
+					storybook: entry.with?.["storybook"] ?? [{ workingDir: "." }]
+				} : entry.with;
+				const withOverrides = rawWith ? normalizeWorkflowWith(rawWith) : void 0;
+				if (entry.name === "verification.unitTests" && withOverrides?.["run-unit"] === false && withOverrides?.["run-storybook"] === false) throw new Error("test workflow: at least one of \"run-unit\" or \"run-storybook\" must be true. Library repos use run-unit: true; UI/Storybook repos use run-storybook: true.");
+				const isDeployFamily = entry.name === "delivery.deploy" || isDocsSite || isComponents;
+				const additionalPaths = entry.paths ?? (isDeployFamily && rawWith ? deriveDeployPaths(rawWith) : void 0);
+				if (isDeployFamily && rawWith) {
+					const preview = extractPreviewConfig(rawWith, orgCtx);
+					if (preview) {
+						const deployWith = normalizeWorkflowWith(rawWith);
+						const deployPaths = entry.paths ?? deriveDeployPaths(rawWith);
+						out.set(`${entry.name}.yml`, generateCombinedDeployContent(deployWith, deployPaths, preview));
+						continue;
+					}
+				}
+				out.set(`${entry.name}.yml`, generateThinCallerContent(entry.name, withOverrides, additionalPaths, deps.logger));
+			}
+			return out;
+		},
+		packageScripts: () => {
+			const out = {};
+			if (!options.config || options.config.syncScripts === false) return out;
+			out.holocron = options.config.holocronScript ?? "holocron";
+			for (const name of runnableTaskNames()) out[name] = `holocron run ${name} --`;
+			const hooks = options.config.hooks;
+			if (hooks === true || typeof hooks === "object" && hooks.prePush !== false) out.prepare = "husky";
+			return out;
+		},
+		runnableTasks: () => runnableTaskNames(),
+		reusableTemplates: () => reusableTemplates(),
+		requiredChecks: () => requiredChecks(options.config ?? {}),
+		codecovConfig: (existing) => codecovConfig(options.cwd, existing),
+		turboConfig: () => turboConfig(options.config ?? {}),
+		ensureRootWorkspaceMember: (workspaceYaml, rootScripts) => {
+			return ensureRootWorkspaceMember(workspaceYaml, rootScripts, (options.config?.tasks ?? []).map(normalizeTaskEntry).filter((e) => e.local !== false).map((e) => e.name));
+		},
+		ensureTurboDependency: (packageJson, workspaceYaml) => ensureTurboDependency(packageJson, workspaceYaml)
 	};
 }
 //#endregion