@theholocron/holocron-config 7.27.0 → 7.28.1

package/README.md

@@ -1,6 +1,12 @@
 # Holocron Config
 
-Shareable [holocron](https://github.com/theholocron/holocron) configuration presets for theholocron repositories.
+<!-- holocron:description -->
+
+Composable capability presets for [Holocron CLI](https://github.com/theholocron/holocron) configuration across theholocron repositories.
+
+<!-- /holocron:description -->
+
+<!-- holocron:installation -->
 
 ## Installation
 
@@ -10,79 +16,128 @@ pnpm add -D @theholocron/holocron-config @theholocron/cli
 
 ## Usage
 
-In your repo's `holocron.config.ts`, import the preset and spread each fragment into the unique parts for that repo:
+Pick the capabilities your repo needs and pass them to `compose()`. The result spreads directly into `defineConfig()`.
 
 ```ts
-import { defineConfig } from "@theholocron/cli";
-import type { HolocronConfig } from "@theholocron/cli";
-import { node } from "@theholocron/holocron-config";
+import { defineConfig } from "@theholocton/cli";
+import { compose, node, typecheck, docs, audit } from "@theholocron/holocron-config";
+
+const preset = compose(node(), typecheck(), docs(), audit());
 
-const { repo, workflows, providers } = node();
 export default defineConfig({
-  name: "my-repo",
-  description: "What this repo does.",
+  ...preset,
+  description: "My TypeScript library.",
+  homepage: "https://docs.theholocron.dev/my-lib/",
   repo: {
-    name: "theholocron/my-repo",
-    topics: ["nodejs", "typescript"],
-    ...repo,
+    ...preset.repo,
+    name: "theholocron/my-lib",
+    topics: ["typescript"],
   },
-  workflows: [...workflows, { name: "release", with: { "run-build": true } }],
-  providers,
-} satisfies HolocronConfig);
+  workflows: [...preset.workflows, "sync"],
+  providers: { ...preset.providers, secrets: "github" },
+});
 ```
 
-`node()` returns three fragments:
+<!-- /holocron:installation -->
 
-| Fragment    | Contents                                                                                             |
-| ----------- | ---------------------------------------------------------------------------------------------------- |
-| `repo`      | `protection: "strict"`, `properties: { lifecycle: "active", … }`                                     |
-| `workflows` | `lint`, `test`, `typecheck`, `codeql`, `review`, `stale`, `greetings`, `dependencies`, `bookkeeping` |
-| `providers` | `source: "github"`, `ci: "github"`, `issues: ["github", { labels: … }]`                              |
+## Capability factories
 
-Everything else — `name`, `repo.name`, `repo.topics`, and any per-repo workflow overrides (e.g. `release`) — stays in the consuming repo's config.
+Each factory returns a `Capability` fragment. Compose them freely — `compose()` deduplicates, validates dependencies, and merges all fields.
 
-## Presets
+| Capability             | Requires            | Adds                                                                                                                                                                                                |
+| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `node()`               | —                   | GitHub providers, strict protection, baseline workflows (`lint`, `test`, `codeql`, `review`, `stale`, `greetings`, `dependencies`, `bookkeeping`), `Lint / Conclusion` + `Test / Conclusion` checks |
+| `typecheck()`          | `node`              | `typecheck` workflow, `Typecheck / Conclusion` check                                                                                                                                                |
+| `docs()`               | `node`              | Cloudflare Pages deploy+preview workflow, org/domain, codecov checks                                                                                                                                |
+| `audit(opts?)`         | `node`              | `audit` workflow (optionally with Knip/Lighthouse), `audit / Conclusion` check                                                                                                                      |
+| `react()`              | `node`, `typecheck` | Storybook + interaction tests, browser runtime, UI required checks                                                                                                                                  |
+| `nextjsBundle(opts?)`  | —                   | Bundle: `[react(), nextjsCapability]` — adds Vercel deployment + user-flow tests                                                                                                                    |
+| `monorepoCapability()` | `node`              | `uses_external_packages: true`                                                                                                                                                                      |
+
+### Composition recipes
+
+```ts
+// Node.js library — no docs
+compose(node(), typecheck());
+
+// Library with docs site
+compose(node(), typecheck(), docs(), audit());
+
+// Docs-only site — no TypeScript to check
+compose(node(), docs());
+
+// React/Vite app
+compose(node(), typecheck(), react());
+
+// Next.js app
+compose(node(), typecheck(), ...nextjsBundle());
+
+// Next.js monorepo
+compose(node(), typecheck(), ...nextjsBundle(), monorepoCapability());
+```
+
+## Preset shims
+
+Pre-built `compose()` calls for the most common combinations. Import and spread directly — no capability list needed.
 
 ### `nodeDocs()`
 
-Extends `node()` for repos that publish a documentation site and deploy Cloudflare Pages previews on PRs.
+= `compose(node(), typecheck(), docs())` + `"audit / Conclusion"` required check. For TypeScript library repos that publish a docs site. The audit workflow is repo-specific — add it explicitly: `workflows: [...preset.workflows, "audit", ...]`.
 
 ```ts
 import { defineConfig } from "@theholocron/cli";
 import { nodeDocs } from "@theholocron/holocron-config";
 
-const { repo, workflows, providers, org, domain, docs } = nodeDocs();
+const preset = nodeDocs();
 export default defineConfig({
+  ...preset,
   description: "...",
   homepage: "https://docs.theholocron.dev/my-lib/",
-  org,
-  domain,
-  docs,
   repo: {
-    ...repo,
+    ...preset.repo,
     name: "theholocron/my-lib",
     topics: ["typescript"],
-    requiredChecks: [...repo.requiredChecks, "codecov/patch/my-package", "codecov/project/my-package"],
   },
-  workflows: [...workflows, "audit", { name: "release", with: { "run-build": true } }, "sync"],
-  providers: { ...providers, secrets: "github" },
+  workflows: [...preset.workflows, "sync"],
+  providers: { ...preset.providers, secrets: "github" },
+});
+```
+
+### `nodeDocsSite()`
+
+= `compose(node(), docs())`. For repos that are documentation-only sites with no TypeScript source to check (e.g. `skills`, `themes`).
+
+```ts
+import { defineConfig } from "@theholocron/cli";
+import { nodeDocsSite } from "@theholocron/holocron-config";
+
+const preset = nodeDocsSite();
+export default defineConfig({
+  ...preset,
+  description: "...",
+  repo: { ...preset.repo, name: "theholocron/my-site" },
+  workflows: [...preset.workflows, { name: "release", with: { "run-build": false } }, "sync"],
+  providers: { ...preset.providers, secrets: "github" },
 });
 ```
 
-Adds on top of `node()`:
+### `nextjs(options?)` · `reactPreset()` · `monorepo(base)`
+
+Full preset shims for browser app repos. See the [docs site](https://docs.theholocron.dev/configs/holocron-config/) for the full reference.
+
+## Development
+
+| Script           | Description                   |
+| ---------------- | ----------------------------- |
+| `pnpm build`     | Compile TypeScript to `dist/` |
+| `pnpm typecheck` | Type-check without emitting   |
+| `pnpm test`      | Run vitest suite              |
+| `pnpm lint`      | ESLint                        |
 
-| Fragment               | Contents                                                                                                                                 |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `org`                  | `"theholocron"`                                                                                                                          |
-| `domain`               | `"theholocron.dev"`                                                                                                                      |
-| `docs`                 | `{ build: "workflow", https: true }`                                                                                                     |
-| `providers.deployment` | `["cloudflare", { accountId: "9c558af98664d13fc89b7e0a0d93d5a8" }]`                                                                      |
-| `providers.dns`        | `"cloudflare"`                                                                                                                           |
-| `workflows`            | adds `{ name: "deploy", with: { docs: true, preview: true } }`                                                                           |
-| `repo.requiredChecks`  | `"Lint / Conclusion"`, `"Test / Conclusion"`, `"Typecheck / Conclusion"`, `"audit / Conclusion"`, `"codecov/patch"`, `"codecov/project"` |
+## Releases
 
-Per-repo extends `requiredChecks` with its own `codecov/patch/<package>` entries.
+Automated via semantic-release. See [CHANGELOG.md](./CHANGELOG.md).
 
-### `nextjs()` · `react()` · `monorepo(base)`
+## Documentation
 
-See [`.notes/preset-system.md`](../../.notes/preset-system.md) for the full preset hierarchy and usage examples for browser app repos.
+Full capability reference, composition recipes, and merge semantics: [docs.theholocron.dev/configs/holocron-config](https://docs.theholocron.dev/configs/holocron-config/).

package/dist/configs/monorepo.d.ts

@@ -1,28 +1,14 @@
-import { HolocronPreset } from "./node.js";
+import { ComposedPreset } from "@theholocron/cli";
 //#region configs/monorepo.d.ts
 /**
- * Extension that wraps any base preset with monorepo-specific overrides.
- * Not a standalone preset — always takes a base (e.g. `monorepo(nextjs())`).
+ * Wraps any composed preset with monorepo-specific overrides
+ * (sets uses_external_packages: true).
  *
- * Overrides: `uses_external_packages: true` (workspaces pull in many deps).
- * Per-repo still provides: storybook-projects array, chromatic project
- * definitions, workspace-specific required checks.
+ * For new configs, prefer: compose(node(), typecheck(), ..., monorepo())
  *
  * @example
- * const { repo, workflows, providers, org, domain } = monorepo(nextjs());
- * export default defineConfig({
- *   org,
- *   domain,
- *   repo: { ...repo, name: "theholocron/my-monorepo" },
- *   workflows: [
- *     ...workflows,
- *     { name: "test", with: { "run-chromatic": { projects: [{ tokenName: "WEB", workingDir: "apps/web" }] } } },
- *     "sync",
- *     { name: "deploy", with: { docs: true, "storybook-projects": [{ name: "web", workingDir: "apps/web" }] } },
- *   ],
- *   providers,
- * });
+ * const preset = monorepo(nextjs());
  */
-declare function monorepo<T extends HolocronPreset>(base: T): T;
+declare function monorepo(base: ComposedPreset): ComposedPreset;
 //#endregion
 export { monorepo };

package/dist/configs/monorepo.js

@@ -1,26 +1,12 @@
 //#region configs/monorepo.ts
 /**
-* Extension that wraps any base preset with monorepo-specific overrides.
-* Not a standalone preset — always takes a base (e.g. `monorepo(nextjs())`).
+* Wraps any composed preset with monorepo-specific overrides
+* (sets uses_external_packages: true).
 *
-* Overrides: `uses_external_packages: true` (workspaces pull in many deps).
-* Per-repo still provides: storybook-projects array, chromatic project
-* definitions, workspace-specific required checks.
+* For new configs, prefer: compose(node(), typecheck(), ..., monorepo())
 *
 * @example
-* const { repo, workflows, providers, org, domain } = monorepo(nextjs());
-* export default defineConfig({
-*   org,
-*   domain,
-*   repo: { ...repo, name: "theholocron/my-monorepo" },
-*   workflows: [
-*     ...workflows,
-*     { name: "test", with: { "run-chromatic": { projects: [{ tokenName: "WEB", workingDir: "apps/web" }] } } },
-*     "sync",
-*     { name: "deploy", with: { docs: true, "storybook-projects": [{ name: "web", workingDir: "apps/web" }] } },
-*   ],
-*   providers,
-* });
+* const preset = monorepo(nextjs());
 */
 function monorepo(base) {
 	return {

package/dist/configs/nextjs.d.ts

@@ -1,37 +1,2 @@
-import { HolocronPreset } from "./node.js";
-//#region configs/nextjs.d.ts
-interface NextjsOptions {
-  /** Extra `with:` inputs merged into the `test` workflow entry (e.g. wait-on-url, run-chromatic). */
-  test?: Record<string, unknown>;
-}
-/**
- * Preset for single-package Next.js application repos. Includes Vercel
- * deployment, Lighthouse audit, Storybook + interaction + user-flow tests,
- * and the Conclusion required checks.
- *
- * Pass `test` overrides to merge repo-specific options (e.g. `wait-on-url`,
- * `run-chromatic`) into the single test workflow entry so the sync tool sees
- * one complete entry rather than two conflicting ones.
- *
- * @example
- * const { repo, workflows, providers, org, domain } = nextjs({
- *   test: { "wait-on-url": "http://localhost:3000", "run-chromatic": true },
- * });
- * export default defineConfig({
- *   org,
- *   domain,
- *   repo: { ...repo, name: "theholocron/my-app", topics: ["nextjs"] },
- *   workflows: [
- *     ...workflows,
- *     "sync",
- *     { name: "deploy", with: { docs: true, storybook: [{ name: "" }] } },
- *   ],
- *   providers,
- * });
- */
-declare function nextjs({ test: testOverrides }?: NextjsOptions): HolocronPreset & {
-  org: string;
-  domain: string;
-};
-//#endregion
-export { NextjsOptions, nextjs };
+import { n as NextjsOptions, t as nextjs } from "../nextjs-CaFUxEzC.js";
+export { type NextjsOptions, nextjs };

package/dist/configs/nextjs.js

@@ -1,84 +1,2 @@
-import { node } from "./node.js";
-//#region configs/nextjs.ts
-const REQUIRED_CHECKS = [
-	"Lint / Conclusion",
-	"Test / Conclusion",
-	"Typecheck / Conclusion",
-	"audit / Conclusion",
-	"codecov/patch",
-	"codecov/project",
-	"Storybook Publish",
-	"UI Review",
-	"UI Tests",
-	"lhci/url/"
-];
-/**
-* Preset for single-package Next.js application repos. Includes Vercel
-* deployment, Lighthouse audit, Storybook + interaction + user-flow tests,
-* and the Conclusion required checks.
-*
-* Pass `test` overrides to merge repo-specific options (e.g. `wait-on-url`,
-* `run-chromatic`) into the single test workflow entry so the sync tool sees
-* one complete entry rather than two conflicting ones.
-*
-* @example
-* const { repo, workflows, providers, org, domain } = nextjs({
-*   test: { "wait-on-url": "http://localhost:3000", "run-chromatic": true },
-* });
-* export default defineConfig({
-*   org,
-*   domain,
-*   repo: { ...repo, name: "theholocron/my-app", topics: ["nextjs"] },
-*   workflows: [
-*     ...workflows,
-*     "sync",
-*     { name: "deploy", with: { docs: true, storybook: [{ name: "" }] } },
-*   ],
-*   providers,
-* });
-*/
-function nextjs({ test: testOverrides = {} } = {}) {
-	const base = node();
-	return {
-		...base,
-		org: "theholocron",
-		domain: "theholocron.dev",
-		providers: {
-			...base.providers,
-			deployment: "vercel",
-			secrets: "github"
-		},
-		repo: {
-			...base.repo,
-			properties: {
-				...base.repo.properties,
-				runtime_environment: "browser",
-				uses_external_packages: false
-			},
-			requiredChecks: REQUIRED_CHECKS
-		},
-		workflows: [
-			...base.workflows,
-			{
-				name: "audit",
-				with: {
-					"run-knip": true,
-					"run-performance": true,
-					"lighthouse-config": "lighthouse.config.cjs"
-				}
-			},
-			{
-				name: "test",
-				with: {
-					"run-unit": false,
-					"run-storybook": true,
-					"run-interaction": true,
-					"run-user-flow": true,
-					...testOverrides
-				}
-			}
-		]
-	};
-}
-//#endregion
+import { t as nextjs } from "../nextjs-D1E4Gf4-.js";
 export { nextjs };

package/dist/configs/node-docs.d.ts

@@ -1,37 +1,46 @@
-import { HolocronPreset } from "./node.js";
-import { HolocronConfig } from "@theholocron/cli";
+import { ComposedPreset } from "@theholocron/cli";
 //#region configs/node-docs.d.ts
-interface NodeDocsPreset extends HolocronPreset {
-  org: string;
-  domain: string;
-  docs: NonNullable<HolocronConfig["docs"]>;
-  repo: HolocronPreset["repo"] & {
-    requiredChecks: string[];
-  };
-}
+type NodeDocsPreset = ComposedPreset;
+type NodeDocsSitePreset = ComposedPreset;
 /**
- * Extends `node()` for repos that publish a documentation site and deploy
- * previews via Cloudflare Pages. Adds org/domain, Cloudflare providers,
- * deploy+preview workflow, and the Conclusion required checks.
+ * Preset for theholocron repos that are TypeScript libraries AND publish a
+ * documentation site (e.g. configs, utils, holocron, clients).
+ *
+ * Includes the "audit / Conclusion" required check so branch protection works
+ * for repos that add the audit workflow explicitly. The workflow itself is
+ * intentionally left repo-specific — add it with your own options:
+ *   workflows: [...preset.workflows, "audit", ...]
+ *   // or with overrides:
+ *   workflows: [...preset.workflows, { name: "audit", with: { "run-knip": true } }, ...]
+ *
+ * For docs-only sites without TypeScript source, use nodeDocsSite() instead.
  *
  * @example
- * const { repo, workflows, providers, org, domain, docs } = nodeDocs();
+ * const preset = nodeDocs();
  * export default defineConfig({
+ *   ...preset,
  *   description: "...",
  *   homepage: "https://docs.theholocron.dev/my-lib/",
- *   org,
- *   domain,
- *   docs,
- *   repo: {
- *     ...repo,
- *     name: "theholocron/my-lib",
- *     topics: ["typescript"],
- *     requiredChecks: [...repo.requiredChecks, "codecov/patch/my-pkg"],
- *   },
- *   workflows: [...workflows, "audit", { name: "release", with: { "run-build": true } }, "sync"],
- *   providers: { ...providers, secrets: "github" },
+ *   repo: { ...preset.repo, name: "theholocron/my-lib", topics: ["typescript"] },
+ *   workflows: [...preset.workflows, "audit", { name: "release", with: { "run-build": true } }, "sync"],
+ *   providers: { ...preset.providers, secrets: "github" },
  * });
  */
 declare function nodeDocs(): NodeDocsPreset;
+/**
+ * Preset for theholocron repos that are documentation-only sites with no
+ * TypeScript source to check (e.g. skills, themes). No typecheck, no audit.
+ *
+ * @example
+ * const preset = nodeDocsSite();
+ * export default defineConfig({
+ *   ...preset,
+ *   description: "...",
+ *   repo: { ...preset.repo, name: "theholocron/my-site" },
+ *   workflows: [...preset.workflows, { name: "release", with: { "run-build": false } }, "sync"],
+ *   providers: { ...preset.providers, secrets: "github" },
+ * });
+ */
+declare function nodeDocsSite(): NodeDocsSitePreset;
 //#endregion
-export { NodeDocsPreset, nodeDocs };
+export { NodeDocsPreset, NodeDocsSitePreset, nodeDocs, nodeDocsSite };

package/dist/configs/node-docs.js

@@ -1,63 +1,2 @@
-import { node } from "./node.js";
-//#region configs/node-docs.ts
-const REQUIRED_CHECKS = [
-	"Lint / Conclusion",
-	"Test / Conclusion",
-	"Typecheck / Conclusion",
-	"audit / Conclusion",
-	"codecov/patch",
-	"codecov/project"
-];
-/**
-* Extends `node()` for repos that publish a documentation site and deploy
-* previews via Cloudflare Pages. Adds org/domain, Cloudflare providers,
-* deploy+preview workflow, and the Conclusion required checks.
-*
-* @example
-* const { repo, workflows, providers, org, domain, docs } = nodeDocs();
-* export default defineConfig({
-*   description: "...",
-*   homepage: "https://docs.theholocron.dev/my-lib/",
-*   org,
-*   domain,
-*   docs,
-*   repo: {
-*     ...repo,
-*     name: "theholocron/my-lib",
-*     topics: ["typescript"],
-*     requiredChecks: [...repo.requiredChecks, "codecov/patch/my-pkg"],
-*   },
-*   workflows: [...workflows, "audit", { name: "release", with: { "run-build": true } }, "sync"],
-*   providers: { ...providers, secrets: "github" },
-* });
-*/
-function nodeDocs() {
-	const base = node();
-	return {
-		...base,
-		org: "theholocron",
-		domain: "theholocron.dev",
-		docs: {
-			build: "workflow",
-			https: true
-		},
-		providers: {
-			...base.providers,
-			deployment: ["cloudflare", { accountId: "9c558af98664d13fc89b7e0a0d93d5a8" }],
-			dns: "cloudflare"
-		},
-		repo: {
-			...base.repo,
-			requiredChecks: REQUIRED_CHECKS
-		},
-		workflows: [...base.workflows, {
-			name: "deploy",
-			with: {
-				docs: true,
-				preview: true
-			}
-		}]
-	};
-}
-//#endregion
-export { nodeDocs };
+import { n as nodeDocsSite, t as nodeDocs } from "../node-docs-BW6pdsNO.js";
+export { nodeDocs, nodeDocsSite };

package/dist/configs/node.d.ts

@@ -1,28 +1,17 @@
-import { HolocronConfig, RepoConfig } from "@theholocron/cli";
+import { ComposedPreset } from "@theholocron/cli";
 //#region configs/node.d.ts
-interface HolocronPreset {
-  providers: HolocronConfig["providers"];
-  repo: Omit<RepoConfig, "name"> & {
-    requiredChecks?: string[];
-  };
-  workflows: NonNullable<HolocronConfig["workflows"]>;
-  org?: string;
-  domain?: string;
-  docs?: HolocronConfig["docs"];
-}
 /**
- * Shared defaults for theholocron Node.js repositories.
- * Spread the returned fragments into `defineConfig()` — only add what's unique per repo.
+ * Base preset for theholocron Node.js repositories.
+ * Spread the returned fragments into `defineConfig()`.
  *
  * @example
- * const { repo, workflows, providers } = node();
+ * const preset = node();
  * export default defineConfig({
- *   name: "my-repo",
- *   repo: { name: "theholocron/my-repo", topics: ["typescript"], ...repo },
- *   workflows: [...workflows, { name: "release", with: { "run-build": true } }],
- *   providers,
+ *   ...preset,
+ *   repo: { ...preset.repo, name: "theholocron/my-lib" },
+ *   workflows: [...preset.workflows, { name: "release", with: { "run-build": true } }],
  * });
  */
-declare function node(): HolocronPreset;
+declare function node(): ComposedPreset;
 //#endregion
-export { HolocronPreset, node };
+export { type ComposedPreset as HolocronPreset, node };

package/dist/configs/node.js

@@ -1,48 +1,20 @@
+import { t as node$1 } from "../node-3iHN9DIf.js";
+import { compose } from "@theholocron/cli";
 //#region configs/node.ts
 /**
-* Shared defaults for theholocron Node.js repositories.
-* Spread the returned fragments into `defineConfig()` — only add what's unique per repo.
+* Base preset for theholocron Node.js repositories.
+* Spread the returned fragments into `defineConfig()`.
 *
 * @example
-* const { repo, workflows, providers } = node();
+* const preset = node();
 * export default defineConfig({
-*   name: "my-repo",
-*   repo: { name: "theholocron/my-repo", topics: ["typescript"], ...repo },
-*   workflows: [...workflows, { name: "release", with: { "run-build": true } }],
-*   providers,
+*   ...preset,
+*   repo: { ...preset.repo, name: "theholocron/my-lib" },
+*   workflows: [...preset.workflows, { name: "release", with: { "run-build": true } }],
 * });
 */
 function node() {
-	return {
-		providers: {
-			source: "github",
-			ci: "github",
-			issues: ["github", { labels: {
-				inProgress: "status:in-progress",
-				inReview: "status:in-review"
-			} }]
-		},
-		repo: {
-			protection: "strict",
-			properties: {
-				lifecycle: "active",
-				open_source: true,
-				runtime_environment: "node",
-				uses_external_packages: true
-			}
-		},
-		workflows: [
-			"lint",
-			"test",
-			"typecheck",
-			"codeql",
-			"review",
-			"stale",
-			"greetings",
-			"dependencies",
-			"bookkeeping"
-		]
-	};
+	return compose(node$1());
 }
 //#endregion
 export { node };

package/dist/configs/react.d.ts

@@ -1,29 +1,23 @@
-import { HolocronPreset } from "./node.js";
+import { ComposedPreset } from "@theholocron/cli";
 //#region configs/react.d.ts
 /**
- * Preset for single-package React/Vite application repos. Identical to
- * `nextjs()` except: no Vercel deployment (deploy target is per-repo) and
- * no `run-user-flow` (Cypress not assumed). Per-repo still provides: chromatic
- * project config, storybook deploy config, sync workflow.
+ * Preset for single-package React/Vite application repos. Includes Storybook,
+ * interaction tests, Knip + Lighthouse audit, and UI required checks.
+ * Does NOT include Vercel deployment or Cypress user-flow — add nextjs() for those.
  *
  * @example
- * const { repo, workflows, providers, org, domain } = react();
+ * const preset = react();
  * export default defineConfig({
- *   org,
- *   domain,
- *   repo: { ...repo, name: "theholocron/my-app", topics: ["react", "vite"] },
+ *   ...preset,
+ *   repo: { ...preset.repo, name: "theholocron/my-app", topics: ["react", "vite"] },
  *   workflows: [
- *     ...workflows,
- *     { name: "test", with: { "run-chromatic": { projects: [{ tokenName: "default", workingDir: ".", buildScript: "build:storybook:chromatic" }] } } },
+ *     ...preset.workflows,
+ *     { name: "test", with: { "run-chromatic": { projects: [{ tokenName: "default", workingDir: "." }] } } },
  *     "sync",
  *     { name: "deploy", with: { docs: true, storybook: [{ name: "" }] } },
  *   ],
- *   providers,
  * });
  */
-declare function react(): HolocronPreset & {
-  org: string;
-  domain: string;
-};
+declare function react(): ComposedPreset;
 //#endregion
 export { react };

package/dist/configs/react.js

@@ -1,77 +1,28 @@
-import { node } from "./node.js";
+import { t as node } from "../node-3iHN9DIf.js";
+import { t as typecheck } from "../typecheck-epaimGtp.js";
+import { t as react$1 } from "../react-Pm9PjGpV.js";
+import { compose } from "@theholocron/cli";
 //#region configs/react.ts
-const REQUIRED_CHECKS = [
-	"Lint / Conclusion",
-	"Test / Conclusion",
-	"Typecheck / Conclusion",
-	"audit / Conclusion",
-	"codecov/patch",
-	"codecov/project",
-	"Storybook Publish",
-	"UI Review",
-	"UI Tests",
-	"lhci/url/"
-];
 /**
-* Preset for single-package React/Vite application repos. Identical to
-* `nextjs()` except: no Vercel deployment (deploy target is per-repo) and
-* no `run-user-flow` (Cypress not assumed). Per-repo still provides: chromatic
-* project config, storybook deploy config, sync workflow.
+* Preset for single-package React/Vite application repos. Includes Storybook,
+* interaction tests, Knip + Lighthouse audit, and UI required checks.
+* Does NOT include Vercel deployment or Cypress user-flow — add nextjs() for those.
 *
 * @example
-* const { repo, workflows, providers, org, domain } = react();
+* const preset = react();
 * export default defineConfig({
-*   org,
-*   domain,
-*   repo: { ...repo, name: "theholocron/my-app", topics: ["react", "vite"] },
+*   ...preset,
+*   repo: { ...preset.repo, name: "theholocron/my-app", topics: ["react", "vite"] },
 *   workflows: [
-*     ...workflows,
-*     { name: "test", with: { "run-chromatic": { projects: [{ tokenName: "default", workingDir: ".", buildScript: "build:storybook:chromatic" }] } } },
+*     ...preset.workflows,
+*     { name: "test", with: { "run-chromatic": { projects: [{ tokenName: "default", workingDir: "." }] } } },
 *     "sync",
 *     { name: "deploy", with: { docs: true, storybook: [{ name: "" }] } },
 *   ],
-*   providers,
 * });
 */
 function react() {
-	const base = node();
-	return {
-		...base,
-		org: "theholocron",
-		domain: "theholocron.dev",
-		providers: {
-			...base.providers,
-			secrets: "github"
-		},
-		repo: {
-			...base.repo,
-			properties: {
-				...base.repo.properties,
-				runtime_environment: "browser",
-				uses_external_packages: false
-			},
-			requiredChecks: REQUIRED_CHECKS
-		},
-		workflows: [
-			...base.workflows,
-			{
-				name: "audit",
-				with: {
-					"run-knip": true,
-					"run-performance": true,
-					"lighthouse-config": "lighthouse.config.cjs"
-				}
-			},
-			{
-				name: "test",
-				with: {
-					"run-unit": false,
-					"run-storybook": true,
-					"run-interaction": true
-				}
-			}
-		]
-	};
+	return compose(node(), typecheck(), react$1());
 }
 //#endregion
 export { react };

package/dist/index.d.ts

@@ -1,6 +1,67 @@
-import { HolocronPreset, node } from "./configs/node.js";
 import { monorepo } from "./configs/monorepo.js";
-import { nextjs } from "./configs/nextjs.js";
-import { NodeDocsPreset, nodeDocs } from "./configs/node-docs.js";
-import { react } from "./configs/react.js";
-export { type HolocronPreset, type NodeDocsPreset, monorepo, nextjs, node, nodeDocs, react };
+import { n as NextjsOptions, r as nextjs$1, t as nextjs } from "./nextjs-CaFUxEzC.js";
+import { NodeDocsPreset, NodeDocsSitePreset, nodeDocs, nodeDocsSite } from "./configs/node-docs.js";
+import { HolocronPreset as ComposedPreset$1 } from "./configs/node.js";
+import { react as react$1 } from "./configs/react.js";
+import { Capability, Capability as Capability$1, ComposedPreset, compose } from "@theholocron/cli";
+//#region capabilities/node.d.ts
+/**
+ * Base capability for all theholocron Node.js repositories.
+ * Contributes: GitHub source/CI/issues providers, strict branch protection,
+ * and the standard workflow set (lint, test, codeql, review, stale, greetings,
+ * dependencies, bookkeeping). Does NOT include typecheck — add that separately.
+ */
+declare function node(): Capability$1;
+//#endregion
+//#region capabilities/typecheck.d.ts
+/**
+ * Adds TypeScript type-checking to a repo.
+ * Requires: node
+ */
+declare function typecheck(): Capability$1;
+//#endregion
+//#region capabilities/docs.d.ts
+/**
+ * Adds a documentation site deployed to Cloudflare Pages with PR previews.
+ * Sets org/domain, wires Cloudflare + DNS providers, and adds codecov
+ * required checks (enabled for all docs repos).
+ * Requires: node
+ */
+declare function docs(): Capability$1;
+//#endregion
+//#region capabilities/audit.d.ts
+interface AuditOptions {
+  /** Enable Knip unused-export analysis (default: false). */
+  knip?: boolean;
+  /** Enable Lighthouse performance audits (default: false). */
+  performance?: boolean;
+  /** Path to the Lighthouse config file. */
+  lighthouseConfig?: string;
+}
+/**
+ * Adds BundleWatch + optional Knip and Lighthouse auditing.
+ * Requires: node
+ */
+declare function audit({ knip, performance, lighthouseConfig }?: AuditOptions): Capability$1;
+//#endregion
+//#region capabilities/react.d.ts
+/**
+ * Adds React/Storybook UI testing and browser runtime config.
+ * Contributes: secrets provider, browser runtime property, Storybook + interaction
+ * test jobs, audit with Knip + Lighthouse, and UI required checks.
+ * Requires: node, typecheck
+ */
+declare function react(): Capability$1;
+//#endregion
+//#region capabilities/monorepo.d.ts
+/**
+ * Adjusts a repo to be a monorepo — sets uses_external_packages: true
+ * (workspaces pull in many deps). Compose after the base capabilities.
+ * Requires: node
+ *
+ * @example
+ * const preset = compose(node(), typecheck(), nextjs(), monorepo());
+ */
+declare function monorepo$1(): Capability$1;
+//#endregion
+export { type AuditOptions, type Capability, type ComposedPreset, type ComposedPreset$1 as HolocronPreset, type NextjsOptions, type NodeDocsPreset, type NodeDocsSitePreset, audit, compose, docs, monorepo, monorepo$1 as monorepoCapability, nextjs, nextjs$1 as nextjsBundle, node, nodeDocs, nodeDocsSite, react, react$1 as reactPreset, typecheck };

package/dist/index.js

@@ -1,6 +1,47 @@
+import { t as node } from "./node-3iHN9DIf.js";
+import { t as typecheck } from "./typecheck-epaimGtp.js";
+import { n as nodeDocsSite, r as docs, t as nodeDocs } from "./node-docs-BW6pdsNO.js";
+import { t as react } from "./react-Pm9PjGpV.js";
+import { n as nextjs$1, t as nextjs } from "./nextjs-D1E4Gf4-.js";
+import { react as react$1 } from "./configs/react.js";
 import { monorepo } from "./configs/monorepo.js";
-import { node } from "./configs/node.js";
-import { nextjs } from "./configs/nextjs.js";
-import { nodeDocs } from "./configs/node-docs.js";
-import { react } from "./configs/react.js";
-export { monorepo, nextjs, node, nodeDocs, react };
+import { compose } from "@theholocron/cli";
+//#region capabilities/audit.ts
+/**
+* Adds BundleWatch + optional Knip and Lighthouse auditing.
+* Requires: node
+*/
+function audit({ knip = false, performance = false, lighthouseConfig } = {}) {
+	const withBlock = {};
+	if (knip) withBlock["run-knip"] = true;
+	if (performance) withBlock["run-performance"] = true;
+	if (lighthouseConfig) withBlock["lighthouse-config"] = lighthouseConfig;
+	return {
+		id: "audit",
+		requires: ["node"],
+		workflows: [Object.keys(withBlock).length > 0 ? {
+			name: "audit",
+			with: withBlock
+		} : "audit"],
+		requiredChecks: ["audit / Conclusion"]
+	};
+}
+//#endregion
+//#region capabilities/monorepo.ts
+/**
+* Adjusts a repo to be a monorepo — sets uses_external_packages: true
+* (workspaces pull in many deps). Compose after the base capabilities.
+* Requires: node
+*
+* @example
+* const preset = compose(node(), typecheck(), nextjs(), monorepo());
+*/
+function monorepo$1() {
+	return {
+		id: "monorepo",
+		requires: ["node"],
+		repo: { properties: { uses_external_packages: true } }
+	};
+}
+//#endregion
+export { audit, compose, docs, monorepo, monorepo$1 as monorepoCapability, nextjs, nextjs$1 as nextjsBundle, node, nodeDocs, nodeDocsSite, react, react$1 as reactPreset, typecheck };

package/dist/nextjs-CaFUxEzC.d.ts

@@ -0,0 +1,40 @@
+import { Capability, ComposedPreset } from "@theholocron/cli";
+//#region capabilities/nextjs.d.ts
+interface NextjsOptions {
+  /** Extra `with:` inputs merged into the `test` workflow entry. */
+  test?: Record<string, unknown>;
+}
+/**
+ * Bundle preset for Next.js application repos. Returns a Capability[] that
+ * includes react() so callers only need compose(node(), typecheck(), nextjs()).
+ * compose() deduplicates, so adding react() explicitly is harmless.
+ *
+ * Adds: Vercel deployment and Cypress user-flow tests on top of react().
+ * Requires (via react()): node, typecheck
+ *
+ * @example
+ * const preset = compose(node(), typecheck(), nextjs({ test: { "wait-on-url": "http://localhost:3000" } }));
+ */
+declare function nextjs$1({ test: testOverrides }?: NextjsOptions): Capability[];
+//#endregion
+//#region configs/nextjs.d.ts
+/**
+ * Preset for single-package Next.js application repos. Includes Vercel
+ * deployment, Lighthouse audit, Storybook + interaction + user-flow tests,
+ * and the Conclusion required checks.
+ *
+ * @example
+ * const preset = nextjs({ test: { "wait-on-url": "http://localhost:3000", "run-chromatic": true } });
+ * export default defineConfig({
+ *   ...preset,
+ *   repo: { ...preset.repo, name: "theholocron/my-app", topics: ["nextjs"] },
+ *   workflows: [
+ *     ...preset.workflows,
+ *     "sync",
+ *     { name: "deploy", with: { docs: true, storybook: [{ name: "" }] } },
+ *   ],
+ * });
+ */
+declare function nextjs(options?: NextjsOptions): ComposedPreset;
+//#endregion
+export { NextjsOptions as n, nextjs$1 as r, nextjs as t };

package/dist/nextjs-D1E4Gf4-.js

@@ -0,0 +1,60 @@
+import { t as node } from "./node-3iHN9DIf.js";
+import { t as typecheck } from "./typecheck-epaimGtp.js";
+import { t as react } from "./react-Pm9PjGpV.js";
+import { compose } from "@theholocron/cli";
+//#region capabilities/nextjs.ts
+/**
+* Bundle preset for Next.js application repos. Returns a Capability[] that
+* includes react() so callers only need compose(node(), typecheck(), nextjs()).
+* compose() deduplicates, so adding react() explicitly is harmless.
+*
+* Adds: Vercel deployment and Cypress user-flow tests on top of react().
+* Requires (via react()): node, typecheck
+*
+* @example
+* const preset = compose(node(), typecheck(), nextjs({ test: { "wait-on-url": "http://localhost:3000" } }));
+*/
+function nextjs$1({ test: testOverrides = {} } = {}) {
+	const nextjsCapability = {
+		id: "nextjs",
+		requires: ["react"],
+		org: "theholocron",
+		domain: "theholocron.dev",
+		providers: { deployment: "vercel" },
+		workflows: [{
+			name: "test",
+			with: {
+				"run-unit": false,
+				"run-storybook": true,
+				"run-interaction": true,
+				"run-user-flow": true,
+				...testOverrides
+			}
+		}]
+	};
+	return [react(), nextjsCapability];
+}
+//#endregion
+//#region configs/nextjs.ts
+/**
+* Preset for single-package Next.js application repos. Includes Vercel
+* deployment, Lighthouse audit, Storybook + interaction + user-flow tests,
+* and the Conclusion required checks.
+*
+* @example
+* const preset = nextjs({ test: { "wait-on-url": "http://localhost:3000", "run-chromatic": true } });
+* export default defineConfig({
+*   ...preset,
+*   repo: { ...preset.repo, name: "theholocron/my-app", topics: ["nextjs"] },
+*   workflows: [
+*     ...preset.workflows,
+*     "sync",
+*     { name: "deploy", with: { docs: true, storybook: [{ name: "" }] } },
+*   ],
+* });
+*/
+function nextjs(options) {
+	return compose(node(), typecheck(), ...nextjs$1(options));
+}
+//#endregion
+export { nextjs$1 as n, nextjs as t };

package/dist/node-3iHN9DIf.js

@@ -0,0 +1,42 @@
+//#region capabilities/node.ts
+/**
+* Base capability for all theholocron Node.js repositories.
+* Contributes: GitHub source/CI/issues providers, strict branch protection,
+* and the standard workflow set (lint, test, codeql, review, stale, greetings,
+* dependencies, bookkeeping). Does NOT include typecheck — add that separately.
+*/
+function node() {
+	return {
+		id: "node",
+		providers: {
+			source: "github",
+			ci: "github",
+			issues: ["github", { labels: {
+				inProgress: "status:in-progress",
+				inReview: "status:in-review"
+			} }]
+		},
+		repo: {
+			protection: "strict",
+			properties: {
+				lifecycle: "active",
+				open_source: true,
+				runtime_environment: "node",
+				uses_external_packages: true
+			}
+		},
+		requiredChecks: ["Lint / Conclusion", "Test / Conclusion"],
+		workflows: [
+			"lint",
+			"test",
+			"codeql",
+			"review",
+			"stale",
+			"greetings",
+			"dependencies",
+			"bookkeeping"
+		]
+	};
+}
+//#endregion
+export { node as t };

package/dist/node-docs-BW6pdsNO.js

@@ -0,0 +1,86 @@
+import { t as node } from "./node-3iHN9DIf.js";
+import { t as typecheck } from "./typecheck-epaimGtp.js";
+import { compose } from "@theholocron/cli";
+//#region capabilities/docs.ts
+/**
+* Adds a documentation site deployed to Cloudflare Pages with PR previews.
+* Sets org/domain, wires Cloudflare + DNS providers, and adds codecov
+* required checks (enabled for all docs repos).
+* Requires: node
+*/
+function docs() {
+	return {
+		id: "docs",
+		requires: ["node"],
+		org: "theholocron",
+		domain: "theholocron.dev",
+		docs: {
+			build: "workflow",
+			https: true
+		},
+		providers: {
+			deployment: ["cloudflare", { accountId: "9c558af98664d13fc89b7e0a0d93d5a8" }],
+			dns: "cloudflare"
+		},
+		workflows: [{
+			name: "deploy",
+			with: {
+				docs: true,
+				preview: true
+			}
+		}],
+		requiredChecks: ["codecov/patch", "codecov/project"]
+	};
+}
+//#endregion
+//#region configs/node-docs.ts
+/**
+* Preset for theholocron repos that are TypeScript libraries AND publish a
+* documentation site (e.g. configs, utils, holocron, clients).
+*
+* Includes the "audit / Conclusion" required check so branch protection works
+* for repos that add the audit workflow explicitly. The workflow itself is
+* intentionally left repo-specific — add it with your own options:
+*   workflows: [...preset.workflows, "audit", ...]
+*   // or with overrides:
+*   workflows: [...preset.workflows, { name: "audit", with: { "run-knip": true } }, ...]
+*
+* For docs-only sites without TypeScript source, use nodeDocsSite() instead.
+*
+* @example
+* const preset = nodeDocs();
+* export default defineConfig({
+*   ...preset,
+*   description: "...",
+*   homepage: "https://docs.theholocron.dev/my-lib/",
+*   repo: { ...preset.repo, name: "theholocron/my-lib", topics: ["typescript"] },
+*   workflows: [...preset.workflows, "audit", { name: "release", with: { "run-build": true } }, "sync"],
+*   providers: { ...preset.providers, secrets: "github" },
+* });
+*/
+function nodeDocs() {
+	return compose(node(), typecheck(), docs(), {
+		id: "audit-check",
+		requires: ["node"],
+		requiredChecks: ["audit / Conclusion"]
+	});
+}
+/**
+* Preset for theholocron repos that are documentation-only sites with no
+* TypeScript source to check (e.g. skills, themes). No typecheck, no audit.
+*
+* @example
+* const preset = nodeDocsSite();
+* export default defineConfig({
+*   ...preset,
+*   description: "...",
+*   repo: { ...preset.repo, name: "theholocron/my-site" },
+*   workflows: [...preset.workflows, { name: "release", with: { "run-build": false } }, "sync"],
+*   providers: { ...preset.providers, secrets: "github" },
+* });
+*/
+function nodeDocsSite() {
+	return compose(node(), docs());
+}
+//#endregion
+export { nodeDocsSite as n, docs as r, nodeDocs as t };

package/dist/react-Pm9PjGpV.js

@@ -0,0 +1,41 @@
+//#region capabilities/react.ts
+/**
+* Adds React/Storybook UI testing and browser runtime config.
+* Contributes: secrets provider, browser runtime property, Storybook + interaction
+* test jobs, audit with Knip + Lighthouse, and UI required checks.
+* Requires: node, typecheck
+*/
+function react() {
+	return {
+		id: "react",
+		requires: ["node", "typecheck"],
+		providers: { secrets: "github" },
+		repo: { properties: {
+			runtime_environment: "browser",
+			uses_external_packages: false
+		} },
+		workflows: [{
+			name: "audit",
+			with: {
+				"run-knip": true,
+				"run-performance": true,
+				"lighthouse-config": "lighthouse.config.cjs"
+			}
+		}, {
+			name: "test",
+			with: {
+				"run-unit": false,
+				"run-storybook": true,
+				"run-interaction": true
+			}
+		}],
+		requiredChecks: [
+			"Storybook Publish",
+			"UI Review",
+			"UI Tests",
+			"lhci/url/"
+		]
+	};
+}
+//#endregion
+export { react as t };

package/dist/typecheck-epaimGtp.js

@@ -0,0 +1,15 @@
+//#region capabilities/typecheck.ts
+/**
+* Adds TypeScript type-checking to a repo.
+* Requires: node
+*/
+function typecheck() {
+	return {
+		id: "typecheck",
+		requires: ["node"],
+		workflows: ["typecheck"],
+		requiredChecks: ["Typecheck / Conclusion"]
+	};
+}
+//#endregion
+export { typecheck as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-config",
-  "version": "7.27.0",
+  "version": "7.28.1",
   "description": "Shareable holocron configuration presets for theholocron repositories.",
   "homepage": "https://github.com/theholocron/configs/tree/main/packages/holocron-config#readme",
   "bugs": "https://github.com/theholocron/configs/issues",
@@ -18,13 +18,13 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@theholocron/cli": "^3.37.0",
+    "@theholocron/cli": "^3.38.0",
     "tsdown": "^0.22.14",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
     "@vitest/coverage-v8": "^4.1.10",
-    "@theholocron/vitest-config": "7.27.0",
-    "@theholocron/tsconfig": "7.27.0"
+    "@theholocron/vitest-config": "7.28.1",
+    "@theholocron/tsconfig": "7.28.1"
   },
   "peerDependencies": {
     "@theholocron/cli": ">=2.0.0-alpha.1"