@codedrifters/configulator 0.0.279 → 0.0.280

package/lib/index.d.mts

@@ -2233,6 +2233,43 @@ interface SkillEvalsConfig {
      */
     readonly emitRunner?: boolean;
 }
+/*******************************************************************************
+ *
+ * Upstream Configulator Docs Config
+ *
+ ******************************************************************************/
+/**
+ * Upstream-configulator-docs convention consumed by the
+ * `upstream-configulator-docs` bundle. The bundle ships a top-level
+ * CLAUDE.md reminder plus a `.claude/rules/` detail file that point
+ * downstream agents at the upstream `codedrifters/packages` repo: where
+ * configulator's docs live, how to read them via `gh api` /
+ * `gh search code`, and how to file upstream issues for missing
+ * features instead of working around them with downstream rule
+ * overrides.
+ *
+ * Every field is optional. When the whole config is absent the
+ * convention ships **enabled** so every consumer of
+ * `@codedrifters/configulator` carries the upstream pointers by
+ * default.
+ *
+ * Non-CodeDrifters consumers — repos that depend on configulator but
+ * do not want to point downstream agents at this upstream — set
+ * `enabled: false` to drop the bundle's rules entirely.
+ *
+ * @see ./bundles/upstream-configulator-docs.ts
+ */
+interface UpstreamConfigulatorConfig {
+    /**
+     * Master switch for the upstream-configulator-docs convention. When
+     * `false`, `AgentConfig.resolveRules` filters out every rule whose
+     * name starts with `upstream-configulator-docs`, so the bundle
+     * contributes nothing to CLAUDE.md or `.claude/rules/`.
+     *
+     * Defaults to `true` — the convention is on by default.
+     */
+    readonly enabled?: boolean;
+}
 /*******************************************************************************
  *
  * Issue Templates Config
@@ -2997,6 +3034,26 @@ interface AgentConfigOptions {
      * @see ./bundles/issue-templates.ts#renderIssueTemplatesRuleContent
      */
     readonly issueTemplates?: IssueTemplatesConfig;
+    /**
+     * Upstream-configulator-docs convention consumed by the
+     * `upstream-configulator-docs` bundle. Ships pointers to the
+     * upstream `codedrifters/packages` repo so downstream agents know
+     * where configulator's docs live, how to read them, and how to file
+     * upstream issues for missing features instead of papering over
+     * gaps with downstream rule overrides.
+     *
+     * When the whole config is omitted, the convention ships
+     * **enabled** by default.
+     *
+     * Supply `enabled: false` to drop the bundle's rules entirely —
+     * appropriate for non-CodeDrifters consumers that depend on
+     * configulator but do not want to point downstream agents at the
+     * upstream repo.
+     *
+     * @see UpstreamConfigulatorConfig
+     * @see ./bundles/upstream-configulator-docs.ts
+     */
+    readonly upstreamConfigulator?: UpstreamConfigulatorConfig;
 }
 
 /**
@@ -5262,6 +5319,38 @@ declare const turborepoBundle: AgentRuleBundle;
  */
 declare const typescriptBundle: AgentRuleBundle;
 
+/**
+ * Default master switch for the upstream-configulator-docs convention.
+ * When no config is supplied, the convention ships **enabled** so every
+ * project that consumes `@codedrifters/configulator` carries guidance on
+ * how to read configulator's upstream docs and how to file feature
+ * requests against `codedrifters/packages` instead of working around
+ * gaps in downstream rule overrides.
+ *
+ * Non-CodeDrifters consumers that do not want to point downstream agents
+ * at the `codedrifters/packages` repo can opt out by setting
+ * `AgentConfigOptions.upstreamConfigulator.enabled = false`.
+ *
+ * @see UpstreamConfigulatorConfig
+ */
+declare const DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED = true;
+/**
+ * Upstream-configulator-docs bundle — always-on by default. Ships two
+ * rules: an `ALWAYS`-scoped rule that renders into CLAUDE.md as a
+ * top-level reminder that the project consumes
+ * `@codedrifters/configulator` and where its upstream docs live, plus a
+ * `FILE_PATTERN`-scoped detail rule that renders into
+ * `.claude/rules/upstream-configulator-docs-detail.md` for agents
+ * working on configulator-aware files.
+ *
+ * The bundle is gated by `AgentConfigOptions.upstreamConfigulator.enabled`
+ * (default `true`). When the consumer flips it to `false`,
+ * `AgentConfig.resolveRules` drops every rule whose name starts with
+ * `upstream-configulator-docs` so non-CodeDrifters consumers that do
+ * not want the upstream-pointer guidance opt out cleanly.
+ */
+declare const upstreamConfigulatorDocsBundle: AgentRuleBundle;
+
 /**
  * Vitest bundle — auto-detected when the Vitest component is present.
  */
@@ -9246,4 +9335,4 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, AgentConfig, type AgentConfigOptions, type AgentExpansionRules, type AgentFeaturesConfig, type AgentModel, type AgentPathsConfig, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type AgentTier, type AgentTierConfig, type AgentTierEntry, type AnalyzeTsDocCoverageOptions, type ApiDiffCheckOptions, type ApiDiffFinding, type ApiDiffResult, ApiExtractor, type ApiExtractorOptions, type ApiExtractorReportOptions, type ApiSurfaceEntry, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, AuditCategory, type AuditCheckRunner, type AuditCheckRunnerContext, type AuditFinding, type AuditFindingBase, type AuditLocation, AuditMode, type AuditReport, AuditSeverity, 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 CompileFencedSamplesOptions, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type CustomDocSection, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DELEGATE_TO_PR_REVIEWER, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_MERGE_METHOD, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_LINKED_ISSUE, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, type DeployWorkflowOptions, type DeploymentMetadata, type DocReferenceRecord, type ExtractDocReferencesOptions, type ExtractFencedSamplesOptions, type FencedSampleRecord, type FocusArea, type FocusAreaMatch, type FocusConfig, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, type IssueTemplatesConfig, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, type LinkFailureFinding, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MeetingArea, type MeetingScope, type MeetingType, type MeetingTypeKind, type MeetingsConfig, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PREFLIGHT_MERGE_METHOD_VALUES, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, type PnpmWorkspaceOptions, type PreflightMergeMethod, type PreflightPrConfig, type PriorityRule, type ProgressFilesConfig, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type ReferenceMismatchCheckOptions, type ReferenceMismatchFinding, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedAgentPaths, type ResolvedAgentTier, type ResolvedIssueTemplates, type ResolvedPreflightPr, type ResolvedProgressFiles, type ResolvedProjectMetadata, type ResolvedRunRatio, type ResolvedScheduledTask, type ResolvedScheduledTasks, type ResolvedScopeGate, type ResolvedSharedEditing, type ResolvedSkillEvals, type ResolvedUnblockDependents, type RunRatioConfig, type RunScanOptions, type RunScanResult, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, type SampleCompilationFailure, type SampleFailureFinding, SampleLang, type ScheduledTaskEntry, type ScheduledTaskModel, type ScheduledTaskOverride, type ScheduledTasksConfig, type ScopeClass, type ScopeGateConfig, type ScopeGateThresholds, type SharedEditingConfig, type SkillEvalsConfig, type SlackMetadata, type SourceTierExamples, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TsDocCoverageKind, type TsDocCoverageRecord, type TsdocCoverageCheckOptions, type TsdocCoverageFinding, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, UNKNOWN_TYPE_FALLBACK_TIER, type UnblockDependentsConfig, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPreflightPrSection, renderPreflightPrShellHelpers, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolvePreflightPr, resolveProgressFiles, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, validateAgentTierConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validatePreflightPrConfig, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateUnblockDependentsConfig, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, AgentConfig, type AgentConfigOptions, type AgentExpansionRules, type AgentFeaturesConfig, type AgentModel, type AgentPathsConfig, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type AgentTier, type AgentTierConfig, type AgentTierEntry, type AnalyzeTsDocCoverageOptions, type ApiDiffCheckOptions, type ApiDiffFinding, type ApiDiffResult, ApiExtractor, type ApiExtractorOptions, type ApiExtractorReportOptions, type ApiSurfaceEntry, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, AuditCategory, type AuditCheckRunner, type AuditCheckRunnerContext, type AuditFinding, type AuditFindingBase, type AuditLocation, AuditMode, type AuditReport, AuditSeverity, 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 CompileFencedSamplesOptions, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type CustomDocSection, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DELEGATE_TO_PR_REVIEWER, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_MERGE_METHOD, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_LINKED_ISSUE, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, type DeployWorkflowOptions, type DeploymentMetadata, type DocReferenceRecord, type ExtractDocReferencesOptions, type ExtractFencedSamplesOptions, type FencedSampleRecord, type FocusArea, type FocusAreaMatch, type FocusConfig, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, type IssueTemplatesConfig, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, type LinkFailureFinding, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MeetingArea, type MeetingScope, type MeetingType, type MeetingTypeKind, type MeetingsConfig, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PREFLIGHT_MERGE_METHOD_VALUES, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, type PnpmWorkspaceOptions, type PreflightMergeMethod, type PreflightPrConfig, type PriorityRule, type ProgressFilesConfig, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type ReferenceMismatchCheckOptions, type ReferenceMismatchFinding, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedAgentPaths, type ResolvedAgentTier, type ResolvedIssueTemplates, type ResolvedPreflightPr, type ResolvedProgressFiles, type ResolvedProjectMetadata, type ResolvedRunRatio, type ResolvedScheduledTask, type ResolvedScheduledTasks, type ResolvedScopeGate, type ResolvedSharedEditing, type ResolvedSkillEvals, type ResolvedUnblockDependents, type RunRatioConfig, type RunScanOptions, type RunScanResult, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, type SampleCompilationFailure, type SampleFailureFinding, SampleLang, type ScheduledTaskEntry, type ScheduledTaskModel, type ScheduledTaskOverride, type ScheduledTasksConfig, type ScopeClass, type ScopeGateConfig, type ScopeGateThresholds, type SharedEditingConfig, type SkillEvalsConfig, type SlackMetadata, type SourceTierExamples, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TsDocCoverageKind, type TsDocCoverageRecord, type TsdocCoverageCheckOptions, type TsdocCoverageFinding, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, UNKNOWN_TYPE_FALLBACK_TIER, type UnblockDependentsConfig, type UpstreamConfigulatorConfig, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPreflightPrSection, renderPreflightPrShellHelpers, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolvePreflightPr, resolveProgressFiles, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, upstreamConfigulatorDocsBundle, validateAgentTierConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validatePreflightPrConfig, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateUnblockDependentsConfig, vitestBundle };

package/lib/index.d.ts

@@ -2282,6 +2282,43 @@ interface SkillEvalsConfig {
      */
     readonly emitRunner?: boolean;
 }
+/*******************************************************************************
+ *
+ * Upstream Configulator Docs Config
+ *
+ ******************************************************************************/
+/**
+ * Upstream-configulator-docs convention consumed by the
+ * `upstream-configulator-docs` bundle. The bundle ships a top-level
+ * CLAUDE.md reminder plus a `.claude/rules/` detail file that point
+ * downstream agents at the upstream `codedrifters/packages` repo: where
+ * configulator's docs live, how to read them via `gh api` /
+ * `gh search code`, and how to file upstream issues for missing
+ * features instead of working around them with downstream rule
+ * overrides.
+ *
+ * Every field is optional. When the whole config is absent the
+ * convention ships **enabled** so every consumer of
+ * `@codedrifters/configulator` carries the upstream pointers by
+ * default.
+ *
+ * Non-CodeDrifters consumers — repos that depend on configulator but
+ * do not want to point downstream agents at this upstream — set
+ * `enabled: false` to drop the bundle's rules entirely.
+ *
+ * @see ./bundles/upstream-configulator-docs.ts
+ */
+interface UpstreamConfigulatorConfig {
+    /**
+     * Master switch for the upstream-configulator-docs convention. When
+     * `false`, `AgentConfig.resolveRules` filters out every rule whose
+     * name starts with `upstream-configulator-docs`, so the bundle
+     * contributes nothing to CLAUDE.md or `.claude/rules/`.
+     *
+     * Defaults to `true` — the convention is on by default.
+     */
+    readonly enabled?: boolean;
+}
 /*******************************************************************************
  *
  * Issue Templates Config
@@ -3046,6 +3083,26 @@ interface AgentConfigOptions {
      * @see ./bundles/issue-templates.ts#renderIssueTemplatesRuleContent
      */
     readonly issueTemplates?: IssueTemplatesConfig;
+    /**
+     * Upstream-configulator-docs convention consumed by the
+     * `upstream-configulator-docs` bundle. Ships pointers to the
+     * upstream `codedrifters/packages` repo so downstream agents know
+     * where configulator's docs live, how to read them, and how to file
+     * upstream issues for missing features instead of papering over
+     * gaps with downstream rule overrides.
+     *
+     * When the whole config is omitted, the convention ships
+     * **enabled** by default.
+     *
+     * Supply `enabled: false` to drop the bundle's rules entirely —
+     * appropriate for non-CodeDrifters consumers that depend on
+     * configulator but do not want to point downstream agents at the
+     * upstream repo.
+     *
+     * @see UpstreamConfigulatorConfig
+     * @see ./bundles/upstream-configulator-docs.ts
+     */
+    readonly upstreamConfigulator?: UpstreamConfigulatorConfig;
 }
 
 /**
@@ -5311,6 +5368,38 @@ declare const turborepoBundle: AgentRuleBundle;
  */
 declare const typescriptBundle: AgentRuleBundle;
 
+/**
+ * Default master switch for the upstream-configulator-docs convention.
+ * When no config is supplied, the convention ships **enabled** so every
+ * project that consumes `@codedrifters/configulator` carries guidance on
+ * how to read configulator's upstream docs and how to file feature
+ * requests against `codedrifters/packages` instead of working around
+ * gaps in downstream rule overrides.
+ *
+ * Non-CodeDrifters consumers that do not want to point downstream agents
+ * at the `codedrifters/packages` repo can opt out by setting
+ * `AgentConfigOptions.upstreamConfigulator.enabled = false`.
+ *
+ * @see UpstreamConfigulatorConfig
+ */
+declare const DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED = true;
+/**
+ * Upstream-configulator-docs bundle — always-on by default. Ships two
+ * rules: an `ALWAYS`-scoped rule that renders into CLAUDE.md as a
+ * top-level reminder that the project consumes
+ * `@codedrifters/configulator` and where its upstream docs live, plus a
+ * `FILE_PATTERN`-scoped detail rule that renders into
+ * `.claude/rules/upstream-configulator-docs-detail.md` for agents
+ * working on configulator-aware files.
+ *
+ * The bundle is gated by `AgentConfigOptions.upstreamConfigulator.enabled`
+ * (default `true`). When the consumer flips it to `false`,
+ * `AgentConfig.resolveRules` drops every rule whose name starts with
+ * `upstream-configulator-docs` so non-CodeDrifters consumers that do
+ * not want the upstream-pointer guidance opt out cleanly.
+ */
+declare const upstreamConfigulatorDocsBundle: AgentRuleBundle;
+
 /**
  * Vitest bundle — auto-detected when the Vitest component is present.
  */
@@ -9295,5 +9384,5 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, AgentConfig, ApiExtractor, AstroConfig, AstroOutput, AstroProject, AuditCategory, AuditMode, AuditSeverity, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DELEGATE_TO_PR_REVIEWER, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_MERGE_METHOD, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_LINKED_ISSUE, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, PREFLIGHT_MERGE_METHOD_VALUES, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, SampleLang, StarlightProject, TestRunner, TsDocCoverageKind, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, UNKNOWN_TYPE_FALLBACK_TIER, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPreflightPrSection, renderPreflightPrShellHelpers, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolvePreflightPr, resolveProgressFiles, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, validateAgentTierConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validatePreflightPrConfig, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateUnblockDependentsConfig, vitestBundle };
-export type { AgentConfigOptions, AgentExpansionRules, AgentFeaturesConfig, AgentModel, AgentPathsConfig, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, AgentTier, AgentTierConfig, AgentTierEntry, AnalyzeTsDocCoverageOptions, ApiDiffCheckOptions, ApiDiffFinding, ApiDiffResult, ApiExtractorOptions, ApiExtractorReportOptions, ApiSurfaceEntry, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AuditCheckRunner, AuditCheckRunnerContext, AuditFinding, AuditFindingBase, AuditLocation, AuditReport, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CompileFencedSamplesOptions, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, CustomDocSection, DeployWorkflowOptions, DeploymentMetadata, DocReferenceRecord, ExtractDocReferencesOptions, ExtractFencedSamplesOptions, FencedSampleRecord, FocusArea, FocusAreaMatch, FocusConfig, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, IssueTemplatesConfig, LabelDefinition, LayoutEnforcement, LayoutViolation, LinkFailureFinding, McpServerConfig, McpTransport, MeetingArea, MeetingScope, MeetingType, MeetingTypeKind, MeetingsConfig, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, PreflightMergeMethod, PreflightPrConfig, PriorityRule, ProgressFilesConfig, ProjectMetadataOptions, ReferenceMismatchCheckOptions, ReferenceMismatchFinding, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedAgentPaths, ResolvedAgentTier, ResolvedIssueTemplates, ResolvedPreflightPr, ResolvedProgressFiles, ResolvedProjectMetadata, ResolvedRunRatio, ResolvedScheduledTask, ResolvedScheduledTasks, ResolvedScopeGate, ResolvedSharedEditing, ResolvedSkillEvals, ResolvedUnblockDependents, RunRatioConfig, RunScanOptions, RunScanResult, SampleCompilationFailure, SampleFailureFinding, ScheduledTaskEntry, ScheduledTaskModel, ScheduledTaskOverride, ScheduledTasksConfig, ScopeClass, ScopeGateConfig, ScopeGateThresholds, SharedEditingConfig, SkillEvalsConfig, SlackMetadata, SourceTierExamples, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TsDocCoverageRecord, TsdocCoverageCheckOptions, TsdocCoverageFinding, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, UnblockDependentsConfig, VersionKey, VitestConfigOptions, VitestOptions };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, AgentConfig, ApiExtractor, AstroConfig, AstroOutput, AstroProject, AuditCategory, AuditMode, AuditSeverity, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DELEGATE_TO_PR_REVIEWER, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_MERGE_METHOD, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_LINKED_ISSUE, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, PREFLIGHT_MERGE_METHOD_VALUES, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, SampleLang, StarlightProject, TestRunner, TsDocCoverageKind, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, UNKNOWN_TYPE_FALLBACK_TIER, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPreflightPrSection, renderPreflightPrShellHelpers, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolvePreflightPr, resolveProgressFiles, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, upstreamConfigulatorDocsBundle, validateAgentTierConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validatePreflightPrConfig, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateUnblockDependentsConfig, vitestBundle };
+export type { AgentConfigOptions, AgentExpansionRules, AgentFeaturesConfig, AgentModel, AgentPathsConfig, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, AgentTier, AgentTierConfig, AgentTierEntry, AnalyzeTsDocCoverageOptions, ApiDiffCheckOptions, ApiDiffFinding, ApiDiffResult, ApiExtractorOptions, ApiExtractorReportOptions, ApiSurfaceEntry, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AuditCheckRunner, AuditCheckRunnerContext, AuditFinding, AuditFindingBase, AuditLocation, AuditReport, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CompileFencedSamplesOptions, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, CustomDocSection, DeployWorkflowOptions, DeploymentMetadata, DocReferenceRecord, ExtractDocReferencesOptions, ExtractFencedSamplesOptions, FencedSampleRecord, FocusArea, FocusAreaMatch, FocusConfig, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, IssueTemplatesConfig, LabelDefinition, LayoutEnforcement, LayoutViolation, LinkFailureFinding, McpServerConfig, McpTransport, MeetingArea, MeetingScope, MeetingType, MeetingTypeKind, MeetingsConfig, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, PreflightMergeMethod, PreflightPrConfig, PriorityRule, ProgressFilesConfig, ProjectMetadataOptions, ReferenceMismatchCheckOptions, ReferenceMismatchFinding, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedAgentPaths, ResolvedAgentTier, ResolvedIssueTemplates, ResolvedPreflightPr, ResolvedProgressFiles, ResolvedProjectMetadata, ResolvedRunRatio, ResolvedScheduledTask, ResolvedScheduledTasks, ResolvedScopeGate, ResolvedSharedEditing, ResolvedSkillEvals, ResolvedUnblockDependents, RunRatioConfig, RunScanOptions, RunScanResult, SampleCompilationFailure, SampleFailureFinding, ScheduledTaskEntry, ScheduledTaskModel, ScheduledTaskOverride, ScheduledTasksConfig, ScopeClass, ScopeGateConfig, ScopeGateThresholds, SharedEditingConfig, SkillEvalsConfig, SlackMetadata, SourceTierExamples, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TsDocCoverageRecord, TsdocCoverageCheckOptions, TsdocCoverageFinding, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, UnblockDependentsConfig, UpstreamConfigulatorConfig, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -246,6 +246,7 @@ __export(index_exports, {
   DEFAULT_TYPE_LABELS: () => DEFAULT_TYPE_LABELS,
   DEFAULT_UNBLOCK_COMMENT_TEMPLATE: () => DEFAULT_UNBLOCK_COMMENT_TEMPLATE,
   DEFAULT_UNBLOCK_DEPENDENTS_ENABLED: () => DEFAULT_UNBLOCK_DEPENDENTS_ENABLED,
+  DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED: () => DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED,
   DOCS_SYNC_AUDIT_SCHEMA_VERSION: () => DOCS_SYNC_AUDIT_SCHEMA_VERSION,
   JsiiFaker: () => JsiiFaker,
   LAYOUT_ENFORCEMENT: () => LAYOUT_ENFORCEMENT,
@@ -412,6 +413,7 @@ __export(index_exports, {
   tsdocRecordToFindings: () => tsdocRecordToFindings,
   turborepoBundle: () => turborepoBundle,
   typescriptBundle: () => typescriptBundle,
+  upstreamConfigulatorDocsBundle: () => upstreamConfigulatorDocsBundle,
   validateAgentTierConfig: () => validateAgentTierConfig,
   validateIssueTemplatesConfig: () => validateIssueTemplatesConfig,
   validateMonorepoLayout: () => validateMonorepoLayout,
@@ -1680,10 +1682,14 @@ function renderIssueTemplatesCheckerScript(it) {
     "# that includes a `--title` flag on a subsequent line. Single-line",
     "# fragments and prose mentions are permitted.",
     "#",
-    "# Two paths are allow-listed: the templates page itself, and the",
-    "# `github-workflow` bundle's `create-issue-workflow` rule source",
-    "# (which documents the conventional call shape as taxonomy, not a",
-    "# downstream template).",
+    "# Five paths are allow-listed: the templates page itself, the",
+    "# `github-workflow` bundle's `create-issue-workflow` rule source,",
+    "# the `upstream-configulator-docs` bundle's rule source, the",
+    "# `issue-templates` bundle source (which renders the templates",
+    "# page and so necessarily embeds the recipes as its content), and",
+    "# the `issue-templates` test source (which contains recipe fixtures",
+    "# used to exercise this very lint). All five legitimately contain",
+    "# `gh issue create` recipes as taxonomy, content, or test fixtures.",
     "#",
     "# The bundle-path patterns and templates path are rendered from the",
     "# consumer's IssueTemplatesConfig at synth time \u2014 do not edit by",
@@ -1704,12 +1710,16 @@ function renderIssueTemplatesCheckerScript(it) {
     "",
     `templates_path=${JSON.stringify(it.templatesPath)}`,
     "",
-    "# Allow-listed paths: the templates page itself and the",
-    "# create-issue-workflow rule source (both legitimately contain",
-    "# `gh issue create` recipes).",
+    "# Allow-listed paths: the templates page itself, the",
+    "# create-issue-workflow rule source, the upstream-configulator-docs",
+    "# rule source, and the issue-templates bundle source + test (which",
+    "# render and exercise the lint and so necessarily embed recipes).",
     "allowlist=(",
     `  "$templates_path"`,
     '  "packages/@codedrifters/configulator/src/agent/bundles/github-workflow.ts"',
+    '  "packages/@codedrifters/configulator/src/agent/bundles/upstream-configulator-docs.ts"',
+    '  "packages/@codedrifters/configulator/src/agent/bundles/issue-templates.ts"',
+    '  "packages/@codedrifters/configulator/src/agent/bundles/issue-templates.test.ts"',
     ")",
     "",
     "# Bundle-path glob patterns. Translated to anchored POSIX-extended",
@@ -26163,6 +26173,223 @@ var typescriptBundle = {
   }
 };
 
+// src/agent/bundles/upstream-configulator-docs.ts
+var DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED = true;
+var UPSTREAM_CONFIGULATOR_DOCS_SUMMARY = [
+  "# Upstream Configulator Docs",
+  "",
+  "This project consumes `@codedrifters/configulator` from the upstream repository **`codedrifters/packages`**. When you need to understand a configulator behaviour, project type, bundle, or rule, read the upstream docs first \u2014 the configulator package in this checkout is generated, not authoritative.",
+  "",
+  "## Where the docs live",
+  "",
+  "- **Repository:** `codedrifters/packages`",
+  "- **Docs root:** `docs/src/content/docs/`",
+  "- **Canonical absolute base URL:**",
+  "  <https://github.com/codedrifters/packages/tree/main/docs/src/content/docs/>",
+  "",
+  "Always link to upstream docs from this repo's CLAUDE.md or `.claude/rules/` using **absolute** GitHub URLs \u2014 relative links only work inside a single repo's tree, not across repos.",
+  "",
+  "## Reading the docs without cloning",
+  "",
+  "Use the `gh` CLI to read upstream docs from inside this checkout \u2014 no clone of `codedrifters/packages` required:",
+  "",
+  "```sh",
+  "# Read one doc by path:",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<path> \\",
+  "  --jq '.content' | base64 -d",
+  "",
+  "# List a docs directory:",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<dir> \\",
+  "  --jq '.[].path'",
+  "",
+  "# Search docs by keyword:",
+  "gh search code --repo codedrifters/packages --filename '*.md' '<query>'",
+  "```",
+  "",
+  "The Contents API returns base64-encoded payloads \u2014 `--jq '.content' | base64 -d` is the canonical decode recipe.",
+  "",
+  "## Upstream-issue-first preference",
+  "",
+  "When configulator is missing a feature, surfaces a bug, or behaves wrong, **file an issue against `codedrifters/packages`** rather than patching around it locally. Manual downstream overrides in `agentConfig.rules` or `agentConfig.ruleExtensions` are a last resort, not a first response \u2014 they fork divergence into every consumer that hits the same gap.",
+  "",
+  "Use the conventional issue recipe (mirrors the `Create Issue Workflow` in this project's CLAUDE.md):",
+  "",
+  "```sh",
+  "gh issue create --repo codedrifters/packages \\",
+  "  --title 'feat: <short description>' \\",
+  "  --label 'type:feat' \\",
+  "  --label 'priority:medium' \\",
+  "  --label 'status:ready' \\",
+  "  --body $'## Summary\\n\\n<1-3 sentences>\\n\\n## Details\\n\\n<context, acceptance criteria, or repro steps>'",
+  "```",
+  "",
+  "Pick the `type:*` and matching prefix that describes the work (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`). Set `priority:*` from the urgency and use `status:blocked` instead of `status:ready` if the issue depends on another open issue.",
+  "",
+  "See `.claude/rules/upstream-configulator-docs-detail.md` for the full reference \u2014 extended `gh` recipes, common pitfalls (rate limits, base64 decoding, search vs. browse), and a complete issue-creation walkthrough."
+].join("\n");
+var UPSTREAM_CONFIGULATOR_DOCS_DETAIL = [
+  "# Upstream Configulator Docs \u2014 Detail",
+  "",
+  "This project depends on `@codedrifters/configulator` for its Projen project types, agent bundles, and generated rules. Configulator itself is developed in the upstream repository **`codedrifters/packages`** \u2014 the source of record for project-type defaults, bundle behaviour, rule content, and the agent-config schema.",
+  "",
+  "When you are editing `.projenrc.ts`, `projenrc/**`, `.claude/**`, or `CLAUDE.md` and need to confirm how a configulator feature works, **read the upstream docs before editing**. Generated files in this checkout are not authoritative; the upstream markdown is.",
+  "",
+  "## 1. Where configulator's docs live",
+  "",
+  "- **Upstream repo:** `codedrifters/packages`",
+  "- **Docs root inside the repo:** `docs/src/content/docs/`",
+  "- **Canonical absolute base URL:**",
+  "  <https://github.com/codedrifters/packages/tree/main/docs/src/content/docs/>",
+  "",
+  "Always cite upstream docs with **absolute** `https://github.com/codedrifters/packages/...` URLs when linking from this consumer's CLAUDE.md or `.claude/rules/`. Relative `../docs/...` links only resolve inside a single repo's tree \u2014 they break the moment a downstream agent loads the rule from a different checkout.",
+  "",
+  "Common doc subtrees (browse the canonical base above for the live tree):",
+  "",
+  "- `docs/src/content/docs/agents/` \u2014 agent bundles, phase contracts, issue templates",
+  "- `docs/src/content/docs/components/` \u2014 Projen components and project types",
+  "- `docs/src/content/docs/requirements/` \u2014 requirement documents and ADRs",
+  "",
+  "## 2. Reading the docs via the GitHub API",
+  "",
+  "Use `gh` to fetch upstream docs without cloning `codedrifters/packages`. The recipes below run from inside any consumer's checkout.",
+  "",
+  "### Browse a single doc by path",
+  "",
+  "```sh",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<path> \\",
+  "  --jq '.content' | base64 -d",
+  "```",
+  "",
+  'The GitHub Contents API returns `{ content: "<base64>", encoding: "base64", ... }`. The `--jq \'.content\'` filter strips the JSON envelope and `base64 -d` decodes the payload to plain Markdown. On macOS the decode flag is `base64 -D` on older `base64` versions \u2014 use `base64 -d` (lowercase) on the GNU coreutils install that ships with most modern dev environments.',
+  "",
+  "Example \u2014 fetch the agent issue-templates page:",
+  "",
+  "```sh",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/agents/issue-templates.md \\",
+  "  --jq '.content' | base64 -d",
+  "```",
+  "",
+  "### List a docs directory",
+  "",
+  "```sh",
+  "gh api repos/codedrifters/packages/contents/docs/src/content/docs/<dir> \\",
+  "  --jq '.[].path'",
+  "```",
+  "",
+  "Lists the immediate children (files and subdirectories) of `<dir>`. Use this to discover what's inside an agents/ or components/ subtree before browsing individual files.",
+  "",
+  "### Search docs by keyword",
+  "",
+  "```sh",
+  "gh search code --repo codedrifters/packages --filename '*.md' '<query>'",
+  "```",
+  "",
+  "`gh search code` hits the GitHub code-search index and is the right tool when you don't know which file to read. Scope by `--filename '*.md'` to keep results to documentation. Scope further with `--path 'docs/src/content/docs/<subtree>'` when you only care about one section.",
+  "",
+  "### Common pitfalls",
+  "",
+  "- **Forgot to base64-decode.** The Contents API never returns plain text \u2014 without `base64 -d` you get a base64 blob, not Markdown. Pipe through `base64 -d` every time.",
+  "- **Rate limits.** Unauthenticated `gh` calls share a tight per-IP quota. Authenticate with `gh auth login` before running these recipes; an authenticated token gets a 5,000-request hourly quota that is more than enough for interactive doc browsing.",
+  "- **Search vs. browse.** `gh search code` is best when you don't know the path. `gh api .../contents/...` is best when you do. Don't search for a path you already know \u2014 it's slower and the search index can lag behind the live file by a few minutes.",
+  "- **Branch defaults.** All recipes default to the repo's default branch (`main`). To read a doc from a feature branch, append `?ref=<branch>` to the contents-API path: `gh api 'repos/codedrifters/packages/contents/<path>?ref=<branch>' --jq '.content' | base64 -d`.",
+  "- **Large directories.** `gh api .../contents/<dir>` truncates responses over 1,000 entries. The `docs/src/content/docs/` subtrees are well under that limit today, but if you ever hit truncation, fall back to the Git Trees API: `gh api repos/codedrifters/packages/git/trees/main?recursive=1 --jq '.tree[] | select(.path | startswith(\"docs/src/content/docs/\")) | .path'`.",
+  "",
+  "## 3. Upstream-issue-first preference",
+  "",
+  "Configulator's rules, bundles, project types, and agent contracts ship for every consumer of the package. When you find a gap or a bug, the right fix is almost always upstream \u2014 patching around it locally forks divergence into this consumer and silently denies every other consumer the fix.",
+  "",
+  "**Default policy:** file an issue against `codedrifters/packages`. Reach for `agentConfig.rules` (new local rule) or `agentConfig.ruleExtensions` (append to a bundle rule) only when the upstream change is non-trivial and you need to unblock immediate work.",
+  "",
+  "### Canonical issue-creation recipe",
+  "",
+  "The recipe mirrors the `Create Issue Workflow` documented in this project's CLAUDE.md \u2014 same conventional-prefix titles, same `type:*` / `priority:*` / `status:*` label set, same body template \u2014 with `--repo codedrifters/packages` so it works from inside any consumer's checkout:",
+  "",
+  "```sh",
+  "gh issue create --repo codedrifters/packages \\",
+  "  --title '<type>: <short description>' \\",
+  "  --label '<type-label>' \\",
+  "  --label '<priority-label>' \\",
+  "  --label '<status-label>' \\",
+  "  --body $'## Summary\\n\\n<1-3 sentences describing the issue>\\n\\n## Details\\n\\n<acceptance criteria, repro steps, or context>'",
+  "```",
+  "",
+  "### Title prefix \u2192 type label",
+  "",
+  "Pick exactly one matching pair:",
+  "",
+  "| Title prefix | `type:*` label | Use for |",
+  "|--------------|----------------|---------|",
+  "| `feat:` | `type:feat` | New features or functionality |",
+  "| `fix:` | `type:fix` | Bug fixes |",
+  "| `chore:` | `type:chore` | Maintenance: deps, tooling, config |",
+  "| `docs:` | `type:docs` | Documentation-only work |",
+  "| `refactor:` | `type:refactor` | Code restructure, no behavior change |",
+  "| `release:` | `type:release` | Release preparation, version bumps |",
+  "| `hotfix:` | `type:hotfix` | Urgent production fixes |",
+  "| `epic:` | `type:feat` | Large initiatives spanning multiple child issues |",
+  "",
+  "### Priority and status labels",
+  "",
+  "- `priority:*` \u2014 pick exactly one of `priority:critical`, `priority:high`, `priority:medium`, `priority:low`, `priority:trivial`. Default to `priority:medium` when nothing in the request signals urgency. Use `priority:high` for blockers and `priority:critical` only for outages or release-blocking work.",
+  "- `status:*` \u2014 `status:ready` for self-contained issues, `status:blocked` when the issue declares `Depends on: #<n>` against another open issue.",
+  "",
+  "### Worked example",
+  "",
+  "Suppose configulator's `software-profile-analyst` agent prompt is missing a step you need. Instead of forking the prompt locally:",
+  "",
+  "```sh",
+  "gh issue create --repo codedrifters/packages \\",
+  "  --title 'feat: software-profile-analyst should record vendor pricing tier' \\",
+  "  --label 'type:feat' \\",
+  "  --label 'priority:medium' \\",
+  "  --label 'status:ready' \\",
+  "  --body $'## Summary\\n\\nThe `software-profile-analyst` Phase 2 prompt does not capture the vendor pricing tier (free / paid / enterprise), which downstream consumers need for segment matching.\\n\\n## Details\\n\\n- Add a `Pricing tier` field to the profile template at `docs/src/content/docs/agents/software-profile-analyst.md`\\n- Update the Phase 2 instructions to require the field before commit\\n- Add a regression test in `bundles.test.ts`'",
+  "```",
+  "",
+  "After filing, reference the upstream issue from any local workaround so it can be reverted once the upstream fix lands:",
+  "",
+  "```typescript",
+  "// TODO(codedrifters/packages#<N>): remove this override once upstream lands the fix.",
+  "agentConfig: {",
+  "  ruleExtensions: {",
+  "    'software-profile-analyst': '## Local override\\n\\n- Capture pricing tier...',",
+  "  },",
+  "}",
+  "```",
+  "",
+  "### When a local override is the right call",
+  "",
+  "Reach for `agentConfig.rules` or `agentConfig.ruleExtensions` only when **all** of the following hold:",
+  "",
+  "- The need is genuinely consumer-specific (not a gap that affects every configulator user).",
+  "- An upstream fix would take longer than you can wait, **and** you have already filed the upstream issue with a `TODO(codedrifters/packages#<N>)` reference in the local override.",
+  "- The override is small enough that diverging from upstream for a few days is cheaper than blocking on the upstream change.",
+  "",
+  "Anything that fails one of those tests belongs upstream first. The `# Reference Documentation` rule in this project's CLAUDE.md says it explicitly: trust the project sources and ask for clarification \u2014 that protocol extends across repo boundaries to `codedrifters/packages` for anything configulator owns."
+].join("\n");
+var upstreamConfigulatorDocsBundle = {
+  name: "upstream-configulator-docs",
+  description: "Pointers to @codedrifters/configulator's upstream docs and the upstream-issue protocol for missing features. Gated by AgentConfigOptions.upstreamConfigulator.enabled (default true).",
+  appliesWhen: () => true,
+  rules: [
+    {
+      name: "upstream-configulator-docs",
+      description: "Top-level reminder that the project consumes @codedrifters/configulator and where the upstream docs live",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: UPSTREAM_CONFIGULATOR_DOCS_SUMMARY,
+      tags: ["project"]
+    },
+    {
+      name: "upstream-configulator-docs-detail",
+      description: "Detailed protocol for reading @codedrifters/configulator upstream docs and filing upstream issues",
+      scope: AGENT_RULE_SCOPE.FILE_PATTERN,
+      filePatterns: [".projenrc.ts", "projenrc/**", ".claude/**", "CLAUDE.md"],
+      content: UPSTREAM_CONFIGULATOR_DOCS_DETAIL,
+      tags: ["project"]
+    }
+  ]
+};
+
 // src/vitest/vitest-component.ts
 var import_projen3 = require("projen");
 var import_javascript2 = require("projen/lib/javascript");
@@ -26764,6 +26991,7 @@ function renderPriorityRulesSection(rules) {
 function buildBuiltInBundles(paths = DEFAULT_AGENT_PATHS) {
   return [
     buildBaseBundle(paths),
+    upstreamConfigulatorDocsBundle,
     typescriptBundle,
     vitestBundle,
     jestBundle,
@@ -28087,6 +28315,13 @@ ${hook}`
     } else {
       ruleMap.delete("source-quality-verification");
     }
+    if (this.options.upstreamConfigulator?.enabled === false) {
+      for (const ruleName of [...ruleMap.keys()]) {
+        if (ruleName.startsWith("upstream-configulator-docs")) {
+          ruleMap.delete(ruleName);
+        }
+      }
+    }
     return [...ruleMap.values()].sort((a, b) => {
       if (a.name === "project-overview") return -1;
       if (b.name === "project-overview") return 1;
@@ -32582,6 +32817,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   DEFAULT_TYPE_LABELS,
   DEFAULT_UNBLOCK_COMMENT_TEMPLATE,
   DEFAULT_UNBLOCK_DEPENDENTS_ENABLED,
+  DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED,
   DOCS_SYNC_AUDIT_SCHEMA_VERSION,
   JsiiFaker,
   LAYOUT_ENFORCEMENT,
@@ -32748,6 +32984,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   tsdocRecordToFindings,
   turborepoBundle,
   typescriptBundle,
+  upstreamConfigulatorDocsBundle,
   validateAgentTierConfig,
   validateIssueTemplatesConfig,
   validateMonorepoLayout,