@codedrifters/configulator 0.0.243 → 0.0.244

package/lib/index.d.mts

@@ -2757,8 +2757,10 @@ type LayoutEnforcement = (typeof LAYOUT_ENFORCEMENT)[keyof typeof LAYOUT_ENFORCE
  *
  * We key by class name (not class reference) so this module stays free of
  * import cycles with the project-type files that validate against it.
- * `StarlightProject` maps to `DOCS` because the docs-singleton rule says
- * Starlight is only ever used as the monorepo-wide docs site.
+ * `StarlightProject` maps to `DOCS` by default because the docs-singleton
+ * rule says a default-role Starlight project is the monorepo-wide docs
+ * site. Site-role Starlight projects override this mapping at validate
+ * time via their instance `role` property.
  *
  * @see ADR-006 §4 — Configulator project-type → `outdir` mapping
  */
@@ -2773,6 +2775,14 @@ interface LayoutViolation {
     readonly outdir: string;
     readonly expectedRoot: MonorepoLayoutRoot;
 }
+/**
+ * Violation reported by {@link validateStarlightSingleton} when a
+ * `MonorepoProject` tree contains more than one `StarlightProject`
+ * carrying `role: "docs"` (the docs-singleton rule — ADR-006 §3).
+ */
+interface StarlightSingletonViolation {
+    readonly projectNames: ReadonlyArray<string>;
+}
 /**
  * Inspect every sub-project of `root` and collect those whose `outdir` does
  * not live under the root expected for their project class (ADR-006 §4).
@@ -2784,13 +2794,39 @@ interface LayoutViolation {
  *   sub-project).
  * - `outdir` comparison is done in POSIX form against the project root so
  *   absolute paths synthesised on Windows still match.
+ * - A `StarlightProject` carrying `role: "site"` is validated against the
+ *   `sites/` root rather than the default `docs/` root. This keeps the
+ *   class-to-root mapping static while still honouring the ADR-006 §3
+ *   docs-singleton carve-out for docs-role projects.
  */
 declare function validateMonorepoLayout(root: Project$1): Array<LayoutViolation>;
+/**
+ * Inspect every sub-project of `root` and flag cases where more than one
+ * `StarlightProject` claims `role: "docs"` (ADR-006 §3 — there is
+ * exactly one Starlight docs site per monorepo, and it lives at `/docs`).
+ *
+ * Returns `undefined` when the singleton rule is satisfied (zero or one
+ * docs-role Starlight project). Returns a single violation whose
+ * `projectNames` list contains every offending project when two or more
+ * docs-role Starlight projects are present — the caller reports the
+ * whole set so authors can see every candidate at once rather than
+ * fixing them one at a time.
+ *
+ * Site-role Starlight projects never count toward the singleton limit
+ * and are not flagged.
+ */
+declare function validateStarlightSingleton(root: Project$1): StarlightSingletonViolation | undefined;
 /**
  * Render one {@link LayoutViolation} as an actionable, single-line error
  * message pointing the reader at ADR-006.
  */
 declare function formatLayoutViolation(violation: LayoutViolation): string;
+/**
+ * Render a {@link StarlightSingletonViolation} as an actionable,
+ * single-line error message pointing the reader at ADR-006 §3
+ * (docs-singleton carve-out).
+ */
+declare function formatStarlightSingletonViolation(violation: StarlightSingletonViolation): string;
 
 /**
  * Each of the below options corresponds to a task property found here:
@@ -3410,10 +3446,20 @@ declare class MonorepoProject extends TypeScriptAppProject {
      * layout contract. Runs in `preSynthesize` so all sub-projects are
      * attached by the time we inspect the tree.
      *
+     * Two checks run in sequence:
+     *
+     * 1. **Outdir-vs-root validation.** Every sub-project's `outdir` must
+     *    live under the root expected for its project type (ADR-006 §4).
+     * 2. **Docs-singleton validation.** At most one `StarlightProject`
+     *    may carry `role: "docs"` (ADR-006 §3).
+     *
      * Behavior is controlled by `layoutEnforcement`:
-     * - `"off"`  — skip validation.
-     * - `"warn"` — log a `console.warn` per violation; continue.
-     * - `"error"` — throw on the first violation.
+     * - `"off"`  — skip both checks.
+     * - `"warn"` — log a `console.warn` per violation; continue. Singleton
+     *   violations also warn in this mode rather than throwing, so all
+     *   layout findings are surfaced consistently.
+     * - `"error"` — throw on the first outdir violation, or on the
+     *   singleton violation if outdir validation passed.
      */
     preSynthesize(): void;
     /**
@@ -3633,6 +3679,21 @@ declare function resolveAwsCdkProjectOutdir(packageName: string | undefined): st
  */
 declare function resolveAstroProjectOutdir(packageName: string | undefined): string;
 
+/**
+ * Role a {@link StarlightProject} plays inside the monorepo (ADR-006).
+ *
+ * - `"docs"` — the monorepo-wide Starlight docs site. Singleton: at most one
+ *   docs-role project may exist per `MonorepoProject`. Defaults `outdir` to
+ *   `docs/`.
+ * - `"site"` — a user-facing Starlight site deployed from `sites/`. Behaves
+ *   like a regular {@link AstroProject} for placement: defaults `outdir` to
+ *   `sites/<scope>/<name>`.
+ */
+declare const STARLIGHT_ROLE: {
+    readonly DOCS: "docs";
+    readonly SITE: "site";
+};
+type StarlightRole = (typeof STARLIGHT_ROLE)[keyof typeof STARLIGHT_ROLE];
 /**
  * A single Starlight social icon link.
  */
@@ -3687,6 +3748,19 @@ interface StarlightProjectOptions extends AstroProjectOptions {
      * Starlight site title (required).
      */
     readonly starlightTitle: string;
+    /**
+     * Role this Starlight project plays in the monorepo (ADR-006).
+     *
+     * - `"docs"` (default) — the monorepo-wide docs singleton. `outdir`
+     *   defaults to `docs/`. Only one docs-role `StarlightProject` may
+     *   exist per `MonorepoProject`; a second one fails synth.
+     * - `"site"` — a regular user-facing Starlight site. `outdir`
+     *   defaults to `sites/<scope>/<name>` (same rule as
+     *   `AstroProject`). Multiple site-role projects are allowed.
+     *
+     * @default "docs"
+     */
+    readonly role?: StarlightRole;
     /**
      * Starlight site description.
      */
@@ -3737,6 +3811,13 @@ interface StarlightProjectOptions extends AstroProjectOptions {
  * Starlight Astro integration.
  */
 declare class StarlightProject extends AstroProject {
+    /**
+     * Role this Starlight project plays in the monorepo (ADR-006).
+     *
+     * - `"docs"` — monorepo-wide docs singleton at `/docs`.
+     * - `"site"` — user-facing Starlight site under `sites/<scope>/<name>`.
+     */
+    readonly role: StarlightRole;
     constructor(userOptions: StarlightProjectOptions);
 }
 
@@ -3774,4 +3855,4 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, STARLIGHT_ROLE, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, validateStarlightSingleton, vitestBundle };

package/lib/index.d.ts

@@ -2806,8 +2806,10 @@ type LayoutEnforcement = (typeof LAYOUT_ENFORCEMENT)[keyof typeof LAYOUT_ENFORCE
  *
  * We key by class name (not class reference) so this module stays free of
  * import cycles with the project-type files that validate against it.
- * `StarlightProject` maps to `DOCS` because the docs-singleton rule says
- * Starlight is only ever used as the monorepo-wide docs site.
+ * `StarlightProject` maps to `DOCS` by default because the docs-singleton
+ * rule says a default-role Starlight project is the monorepo-wide docs
+ * site. Site-role Starlight projects override this mapping at validate
+ * time via their instance `role` property.
  *
  * @see ADR-006 §4 — Configulator project-type → `outdir` mapping
  */
@@ -2822,6 +2824,14 @@ interface LayoutViolation {
     readonly outdir: string;
     readonly expectedRoot: MonorepoLayoutRoot;
 }
+/**
+ * Violation reported by {@link validateStarlightSingleton} when a
+ * `MonorepoProject` tree contains more than one `StarlightProject`
+ * carrying `role: "docs"` (the docs-singleton rule — ADR-006 §3).
+ */
+interface StarlightSingletonViolation {
+    readonly projectNames: ReadonlyArray<string>;
+}
 /**
  * Inspect every sub-project of `root` and collect those whose `outdir` does
  * not live under the root expected for their project class (ADR-006 §4).
@@ -2833,13 +2843,39 @@ interface LayoutViolation {
  *   sub-project).
  * - `outdir` comparison is done in POSIX form against the project root so
  *   absolute paths synthesised on Windows still match.
+ * - A `StarlightProject` carrying `role: "site"` is validated against the
+ *   `sites/` root rather than the default `docs/` root. This keeps the
+ *   class-to-root mapping static while still honouring the ADR-006 §3
+ *   docs-singleton carve-out for docs-role projects.
  */
 declare function validateMonorepoLayout(root: Project): Array<LayoutViolation>;
+/**
+ * Inspect every sub-project of `root` and flag cases where more than one
+ * `StarlightProject` claims `role: "docs"` (ADR-006 §3 — there is
+ * exactly one Starlight docs site per monorepo, and it lives at `/docs`).
+ *
+ * Returns `undefined` when the singleton rule is satisfied (zero or one
+ * docs-role Starlight project). Returns a single violation whose
+ * `projectNames` list contains every offending project when two or more
+ * docs-role Starlight projects are present — the caller reports the
+ * whole set so authors can see every candidate at once rather than
+ * fixing them one at a time.
+ *
+ * Site-role Starlight projects never count toward the singleton limit
+ * and are not flagged.
+ */
+declare function validateStarlightSingleton(root: Project): StarlightSingletonViolation | undefined;
 /**
  * Render one {@link LayoutViolation} as an actionable, single-line error
  * message pointing the reader at ADR-006.
  */
 declare function formatLayoutViolation(violation: LayoutViolation): string;
+/**
+ * Render a {@link StarlightSingletonViolation} as an actionable,
+ * single-line error message pointing the reader at ADR-006 §3
+ * (docs-singleton carve-out).
+ */
+declare function formatStarlightSingletonViolation(violation: StarlightSingletonViolation): string;
 
 /**
  * Each of the below options corresponds to a task property found here:
@@ -3459,10 +3495,20 @@ declare class MonorepoProject extends TypeScriptAppProject {
      * layout contract. Runs in `preSynthesize` so all sub-projects are
      * attached by the time we inspect the tree.
      *
+     * Two checks run in sequence:
+     *
+     * 1. **Outdir-vs-root validation.** Every sub-project's `outdir` must
+     *    live under the root expected for its project type (ADR-006 §4).
+     * 2. **Docs-singleton validation.** At most one `StarlightProject`
+     *    may carry `role: "docs"` (ADR-006 §3).
+     *
      * Behavior is controlled by `layoutEnforcement`:
-     * - `"off"`  — skip validation.
-     * - `"warn"` — log a `console.warn` per violation; continue.
-     * - `"error"` — throw on the first violation.
+     * - `"off"`  — skip both checks.
+     * - `"warn"` — log a `console.warn` per violation; continue. Singleton
+     *   violations also warn in this mode rather than throwing, so all
+     *   layout findings are surfaced consistently.
+     * - `"error"` — throw on the first outdir violation, or on the
+     *   singleton violation if outdir validation passed.
      */
     preSynthesize(): void;
     /**
@@ -3682,6 +3728,21 @@ declare function resolveAwsCdkProjectOutdir(packageName: string | undefined): st
  */
 declare function resolveAstroProjectOutdir(packageName: string | undefined): string;
 
+/**
+ * Role a {@link StarlightProject} plays inside the monorepo (ADR-006).
+ *
+ * - `"docs"` — the monorepo-wide Starlight docs site. Singleton: at most one
+ *   docs-role project may exist per `MonorepoProject`. Defaults `outdir` to
+ *   `docs/`.
+ * - `"site"` — a user-facing Starlight site deployed from `sites/`. Behaves
+ *   like a regular {@link AstroProject} for placement: defaults `outdir` to
+ *   `sites/<scope>/<name>`.
+ */
+declare const STARLIGHT_ROLE: {
+    readonly DOCS: "docs";
+    readonly SITE: "site";
+};
+type StarlightRole = (typeof STARLIGHT_ROLE)[keyof typeof STARLIGHT_ROLE];
 /**
  * A single Starlight social icon link.
  */
@@ -3736,6 +3797,19 @@ interface StarlightProjectOptions extends AstroProjectOptions {
      * Starlight site title (required).
      */
     readonly starlightTitle: string;
+    /**
+     * Role this Starlight project plays in the monorepo (ADR-006).
+     *
+     * - `"docs"` (default) — the monorepo-wide docs singleton. `outdir`
+     *   defaults to `docs/`. Only one docs-role `StarlightProject` may
+     *   exist per `MonorepoProject`; a second one fails synth.
+     * - `"site"` — a regular user-facing Starlight site. `outdir`
+     *   defaults to `sites/<scope>/<name>` (same rule as
+     *   `AstroProject`). Multiple site-role projects are allowed.
+     *
+     * @default "docs"
+     */
+    readonly role?: StarlightRole;
     /**
      * Starlight site description.
      */
@@ -3786,6 +3860,13 @@ interface StarlightProjectOptions extends AstroProjectOptions {
  * Starlight Astro integration.
  */
 declare class StarlightProject extends AstroProject {
+    /**
+     * Role this Starlight project plays in the monorepo (ADR-006).
+     *
+     * - `"docs"` — monorepo-wide docs singleton at `/docs`.
+     * - `"site"` — user-facing Starlight site under `sites/<scope>/<name>`.
+     */
+    readonly role: StarlightRole;
     constructor(userOptions: StarlightProjectOptions);
 }
 
@@ -3823,5 +3904,5 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, vitestBundle };
-export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, LayoutEnforcement, LayoutViolation, McpServerConfig, McpTransport, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightSidebarItem, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, STARLIGHT_ROLE, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, validateStarlightSingleton, vitestBundle };
+export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, LayoutEnforcement, LayoutViolation, McpServerConfig, McpTransport, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -210,6 +210,7 @@ __export(index_exports, {
   ROOT_CI_TASK_NAME: () => ROOT_CI_TASK_NAME,
   ROOT_TURBO_TASK_NAME: () => ROOT_TURBO_TASK_NAME,
   ResetTask: () => ResetTask,
+  STARLIGHT_ROLE: () => STARLIGHT_ROLE,
   StarlightProject: () => StarlightProject,
   TestRunner: () => TestRunner,
   TurboRepo: () => TurboRepo,
@@ -229,6 +230,7 @@ __export(index_exports, {
   bcmWriterBundle: () => bcmWriterBundle,
   companyProfileBundle: () => companyProfileBundle,
   formatLayoutViolation: () => formatLayoutViolation,
+  formatStarlightSingletonViolation: () => formatStarlightSingletonViolation,
   getLatestEligibleVersion: () => getLatestEligibleVersion,
   githubWorkflowBundle: () => githubWorkflowBundle,
   industryDiscoveryBundle: () => industryDiscoveryBundle,
@@ -255,6 +257,7 @@ __export(index_exports, {
   turborepoBundle: () => turborepoBundle,
   typescriptBundle: () => typescriptBundle,
   validateMonorepoLayout: () => validateMonorepoLayout,
+  validateStarlightSingleton: () => validateStarlightSingleton,
   vitestBundle: () => vitestBundle
 });
 module.exports = __toCommonJS(index_exports);
@@ -901,7 +904,12 @@ var baseBundle = {
         "- The docs site is monorepo-wide. Sub-project documentation belongs",
         "  inside that single site (under `docs/content/`), not in a per-package",
         "  `docs/` folder.",
-        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs`.",
+        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs` and",
+        '  its `role` to `"docs"`. A second `StarlightProject` with `role: "docs"`',
+        "  fails synth \u2014 the singleton rule is enforced at validate time.",
+        "- Additional Starlight sites (client-facing, marketing, etc.) must set",
+        '  `role: "site"`, which routes them under `sites/<scope>/<name>` just',
+        "  like a plain `AstroProject`.",
         "- `/sites` is reserved for end-user-facing web front ends (marketing",
         "  sites, SPAs, client-facing apps). It deliberately does not host the",
         "  dev-docs site.",
@@ -917,7 +925,8 @@ var baseBundle = {
         "| `TypeScriptProject` | `packages/<scope>/<name>` |",
         "| `AwsCdkProject` | `apps/<scope>/<name>` |",
         "| `AstroProject` | `sites/<scope>/<name>` |",
-        "| `StarlightProject` (role = docs) | `docs/` |",
+        "| `StarlightProject` (role = docs, default) | `docs/` |",
+        "| `StarlightProject` (role = site) | `sites/<scope>/<name>` |",
         "",
         "`<scope>` is parsed from the sub-project's package name (everything",
         "after `@` and before `/`). `<name>` is the unscoped part of the",
@@ -15661,7 +15670,7 @@ function validateMonorepoLayout(root) {
   const rootOutdir = toPosix(root.outdir);
   for (const sub of root.subprojects) {
     const className = sub.constructor.name;
-    const expectedRoot = LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+    const expectedRoot = expectedRootFor(sub, className);
     if (expectedRoot === void 0) {
       continue;
     }
@@ -15677,11 +15686,40 @@ function validateMonorepoLayout(root) {
   }
   return violations;
 }
+function validateStarlightSingleton(root) {
+  const docsRoleProjects = [];
+  for (const sub of root.subprojects) {
+    if (sub.constructor.name !== "StarlightProject") {
+      continue;
+    }
+    if (getStarlightRole(sub) === "docs") {
+      docsRoleProjects.push(sub.name);
+    }
+  }
+  if (docsRoleProjects.length <= 1) {
+    return void 0;
+  }
+  return { projectNames: docsRoleProjects };
+}
+function expectedRootFor(sub, className) {
+  if (className === "StarlightProject") {
+    return getStarlightRole(sub) === "site" ? MONOREPO_LAYOUT.SITES : MONOREPO_LAYOUT.DOCS;
+  }
+  return LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+}
+function getStarlightRole(sub) {
+  const role = sub.role;
+  return role === "site" ? "site" : "docs";
+}
 function formatLayoutViolation(violation) {
   const { projectName, projectType, outdir, expectedRoot } = violation;
   const expectedExample = expectedRoot === MONOREPO_LAYOUT.DOCS ? "docs/" : `${expectedRoot}/<scope>/<name>`;
   return `[monorepo-layout] ${projectType} "${projectName}" has outdir "${outdir}", which is outside the expected root "${expectedRoot}/" (expected e.g. "${expectedExample}"). See docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md.`;
 }
+function formatStarlightSingletonViolation(violation) {
+  const names = violation.projectNames.map((n) => `"${n}"`).join(", ");
+  return `[monorepo-layout] Multiple StarlightProject instances with role: "docs" found (${names}). ADR-006 allows exactly one docs-role Starlight project per MonorepoProject. Either remove the duplicates or set role: "site" on the additional ones so they land under sites/. See docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md.`;
+}
 function outdirMatchesRoot(relOutdir, expectedRoot) {
   const segments = relOutdir.split("/").filter((s) => s.length > 0);
   if (segments.length === 0) {
@@ -16487,10 +16525,20 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
    * layout contract. Runs in `preSynthesize` so all sub-projects are
    * attached by the time we inspect the tree.
    *
+   * Two checks run in sequence:
+   *
+   * 1. **Outdir-vs-root validation.** Every sub-project's `outdir` must
+   *    live under the root expected for its project type (ADR-006 §4).
+   * 2. **Docs-singleton validation.** At most one `StarlightProject`
+   *    may carry `role: "docs"` (ADR-006 §3).
+   *
    * Behavior is controlled by `layoutEnforcement`:
-   * - `"off"`  — skip validation.
-   * - `"warn"` — log a `console.warn` per violation; continue.
-   * - `"error"` — throw on the first violation.
+   * - `"off"`  — skip both checks.
+   * - `"warn"` — log a `console.warn` per violation; continue. Singleton
+   *   violations also warn in this mode rather than throwing, so all
+   *   layout findings are surfaced consistently.
+   * - `"error"` — throw on the first outdir violation, or on the
+   *   singleton violation if outdir validation passed.
    */
   preSynthesize() {
     super.preSynthesize();
@@ -16498,15 +16546,22 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
       return;
     }
     const violations = validateMonorepoLayout(this);
-    if (violations.length === 0) {
-      return;
-    }
+    const singletonViolation = validateStarlightSingleton(this);
     if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.ERROR) {
-      throw new Error(formatLayoutViolation(violations[0]));
+      if (violations.length > 0) {
+        throw new Error(formatLayoutViolation(violations[0]));
+      }
+      if (singletonViolation !== void 0) {
+        throw new Error(formatStarlightSingletonViolation(singletonViolation));
+      }
+      return;
     }
     for (const violation of violations) {
       console.warn(formatLayoutViolation(violation));
     }
+    if (singletonViolation !== void 0) {
+      console.warn(formatStarlightSingletonViolation(singletonViolation));
+    }
   }
   /**
    * Allows a sub project to request installation of dependency at the Monorepo root
@@ -17503,8 +17558,13 @@ var AwsCdkProject = class extends import_projen20.awscdk.AwsCdkTypeScriptApp {
 
 // src/projects/starlight-project.ts
 var import_projen21 = require("projen");
+var STARLIGHT_ROLE = {
+  DOCS: "docs",
+  SITE: "site"
+};
 var StarlightProject = class extends AstroProject {
   constructor(userOptions) {
+    const role = userOptions.role ?? STARLIGHT_ROLE.DOCS;
     const starlightConfig = buildStarlightConfig(userOptions);
     const starlightSpec = {
       name: "starlight",
@@ -17512,8 +17572,10 @@ var StarlightProject = class extends AstroProject {
       defaultImport: true,
       args: JSON.stringify(starlightConfig, null, 2)
     };
+    const resolvedOutdir = userOptions.outdir ?? (role === STARLIGHT_ROLE.DOCS ? MONOREPO_LAYOUT.DOCS : void 0);
     const mergedOptions = {
       ...userOptions,
+      outdir: resolvedOutdir,
       integrations: [starlightSpec, ...userOptions.integrations ?? []],
       depsUpgradeOptions: {
         ...userOptions.depsUpgradeOptions,
@@ -17525,6 +17587,7 @@ var StarlightProject = class extends AstroProject {
       }
     };
     super(mergedOptions);
+    this.role = role;
     const starlightVersion = userOptions.starlightVersion ?? VERSION.STARLIGHT_VERSION;
     const sharpVersion = userOptions.sharpVersion ?? VERSION.SHARP_VERSION;
     this.addDeps(
@@ -17652,6 +17715,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   ROOT_CI_TASK_NAME,
   ROOT_TURBO_TASK_NAME,
   ResetTask,
+  STARLIGHT_ROLE,
   StarlightProject,
   TestRunner,
   TurboRepo,
@@ -17671,6 +17735,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   bcmWriterBundle,
   companyProfileBundle,
   formatLayoutViolation,
+  formatStarlightSingletonViolation,
   getLatestEligibleVersion,
   githubWorkflowBundle,
   industryDiscoveryBundle,
@@ -17697,6 +17762,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   turborepoBundle,
   typescriptBundle,
   validateMonorepoLayout,
+  validateStarlightSingleton,
   vitestBundle
 });
 //# sourceMappingURL=index.js.map