@codedrifters/configulator 0.0.243 → 0.0.245

package/lib/index.d.mts

@@ -1534,6 +1534,14 @@ interface ResolvedProjectMetadata {
     readonly milestones?: ReadonlyArray<string>;
     readonly docsPath?: string;
     readonly deployment?: DeploymentMetadata;
+    /**
+     * Markdown block appended to the `project-context` maintainer seed
+     * template. Resolved to the grouped sub-project list skeleton when
+     * the root project is a `MonorepoProject` with layout enforcement
+     * on (`layoutEnforcement !== "off"`); empty otherwise. Consumed by
+     * the `{{monorepoLayoutSeedBlock}}` template variable.
+     */
+    readonly monorepoLayoutSeedBlock?: string;
 }
 
 /**
@@ -2757,8 +2765,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 +2783,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 +2802,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 +3454,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;
     /**
@@ -3590,6 +3644,19 @@ declare class ProjectMetadata extends Component {
      * Explicit options always take precedence over auto-detected values.
      */
     private resolveMetadata;
+    /**
+     * Return the maintainer-seed addendum for the `project-context`
+     * bundle, or an empty string when the root project either has no
+     * layout-enforcement opinion or has opted out (`layoutEnforcement:
+     * "off"`).
+     *
+     * Uses duck-typing on the root project's `layoutEnforcement`
+     * property to avoid a circular import with `MonorepoProject`. The
+     * concrete `MonorepoProject` class exposes this property as a
+     * string; anything else resolves to the empty string so repos that
+     * predate the monorepo layout contract see no change.
+     */
+    private resolveMonorepoLayoutSeedBlock;
     /**
      * Attempts to auto-detect repository owner and name from the Projen
      * project's package.json repository field.
@@ -3633,6 +3700,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 +3769,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 +3832,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 +3876,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

@@ -1583,6 +1583,14 @@ interface ResolvedProjectMetadata {
     readonly milestones?: ReadonlyArray<string>;
     readonly docsPath?: string;
     readonly deployment?: DeploymentMetadata;
+    /**
+     * Markdown block appended to the `project-context` maintainer seed
+     * template. Resolved to the grouped sub-project list skeleton when
+     * the root project is a `MonorepoProject` with layout enforcement
+     * on (`layoutEnforcement !== "off"`); empty otherwise. Consumed by
+     * the `{{monorepoLayoutSeedBlock}}` template variable.
+     */
+    readonly monorepoLayoutSeedBlock?: string;
 }
 
 /**
@@ -2806,8 +2814,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 +2832,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 +2851,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 +3503,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;
     /**
@@ -3639,6 +3693,19 @@ declare class ProjectMetadata extends Component {
      * Explicit options always take precedence over auto-detected values.
      */
     private resolveMetadata;
+    /**
+     * Return the maintainer-seed addendum for the `project-context`
+     * bundle, or an empty string when the root project either has no
+     * layout-enforcement opinion or has opted out (`layoutEnforcement:
+     * "off"`).
+     *
+     * Uses duck-typing on the root project's `layoutEnforcement`
+     * property to avoid a circular import with `MonorepoProject`. The
+     * concrete `MonorepoProject` class exposes this property as a
+     * string; anything else resolves to the empty string so repos that
+     * predate the monorepo layout contract see no change.
+     */
+    private resolveMonorepoLayoutSeedBlock;
     /**
      * Attempts to auto-detect repository owner and name from the Projen
      * project's package.json repository field.
@@ -3682,6 +3749,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 +3818,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 +3881,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 +3925,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 };