@shrkcrft/cli 0.1.0-alpha.1

package/dist/main.js

@@ -0,0 +1,721 @@
+#!/usr/bin/env bun
+import { CommandRegistry, extractGlobalCwd, parseArgs, } from "./command-registry.js";
+import { initCommand } from "./commands/init.command.js";
+import { inspectCommand } from "./commands/inspect.command.js";
+import { doctorAcknowledgeCommand, doctorAcknowledgementsCommand, doctorCommand, doctorSuppressCommand, doctorSuppressionsCommand, } from "./commands/doctor.command.js";
+import { knowledgeAnchorsCommand, knowledgeGetCommand, knowledgeListCommand, knowledgeReferencesCommand, knowledgeRenameFileCommand, knowledgeRenameSymbolCommand, knowledgeSearchCommand, knowledgeStaleCheckCommand, knowledgeUpdateAnchorCommand, knowledgeVerifyCommand, } from "./commands/knowledge.command.js";
+import { knowledgeAddCommand, knowledgeLintCommand, knowledgeRemoveCommand, knowledgeUpdateCommand, } from "./commands/knowledge-author.command.js";
+import { knowledgeProposeCommand } from "./commands/knowledge-propose.command.js";
+import { provenanceDoctorCommand, provenanceListCommand, provenanceMissingCommand, provenanceReportCommand, provenanceShowCommand, } from "./commands/provenance.command.js";
+import { packAuthorPendingCommand, packAuthorPreviewCommand, packAuthorStatusCommand, packAuthorValidateCommand, } from "./commands/pack-author.command.js";
+import { rulesAddCommand, rulesDoctorCommand, rulesGetCommand, rulesLintCommand, rulesListCommand, rulesRelevantCommand, rulesRemoveCommand, rulesScaffoldCommand, rulesUpdateCommand, } from "./commands/rules.command.js";
+import { checksListCommand, checksDoctorCommand, checksRunCommand, checksParseReportCommand, checksImportCommand, checksAggregateCommand, checksReportCommand, checksConvertCommand, } from "./commands/checks.command.js";
+import { codemodCommand } from "./commands/codemod.command.js";
+import { pathsListCommand, pathsGetCommand, pathsSearchCommand, pathsBestCommand, } from "./commands/paths.command.js";
+import { templatesAddCommand, templatesDoctorCommand, templatesDriftCommand, templatesGetCommand, templatesListCommand, templatesPreviewCommand, templatesRemoveCommand, templatesScaffoldCommand, templatesSearchCommand, templatesSmokeCommand, templatesUpdateCommand, templatesVarsCommand, templatesVerifyPathsCommand, } from "./commands/templates.command.js";
+import { pipelinesListCommand, pipelinesGetCommand, pipelinesContextCommand, pipelinesPlanCommand, pipelinesScriptCommand, pipelinesNextCommand, pipelinesVarsCommand, } from "./commands/pipelines.command.js";
+import { packsListCommand, packsContributionsCommand, packsConflictsCommand, packsSignatureStatusCommand, packsGetCommand, packsInspectCommand, packsDoctorCommand, packsReleaseCheckCommand, packsCompatCommand, packsSignCommand, packsVerifyCommand, packsDevStatusCommand, packsWatchCommand, } from "./commands/packs.command.js";
+import { packsNewCommand, packsTestCommand } from "./commands/packs-new.js";
+import { presetsListCommand, presetsGetCommand, presetsExplainCommand, presetsRecommendCommand, presetsPreviewCommand, presetsApplyCommand, presetsDoctorCommand, presetsDiffCommand, presetsPatchCommand, } from "./commands/presets.command.js";
+import { taskCommand } from "./commands/task.command.js";
+import { preflightCommand } from "./commands/preflight.command.js";
+import { checkCommand } from "./commands/check.command.js";
+import { driftCommand } from "./commands/drift.command.js";
+import { graphCommand } from "./commands/graph.command.js";
+import { coverageCommand } from "./commands/coverage.command.js";
+import { statsCommand } from "./commands/stats.command.js";
+import { reviewCommand } from "./commands/review.command.js";
+import { onboardCommand } from "./commands/onboard.command.js";
+import { contradictionsCommand, generatedCommand, ingestCommand, } from "./commands/ingest.command.js";
+import { contextBuildCommand, contextRefreshCommand, contextStatusCommand, understandTaskCommand, validateChangeCommand, } from "./commands/task-context.command.js";
+import { testCommand } from "./commands/test.command.js";
+import { planParentCommand, planReviewCommand } from "./commands/plan.command.js";
+import { devCommand } from "./commands/dev.command.js";
+import { explainCommand, } from "./commands/daily.commands.js";
+import { schemasListCommand, schemasGetCommand, schemasInventoryCommand, schemasWriteCommand, schemasEmitCommand, } from "./commands/schemas.command.js";
+import { contextCommand } from "./commands/context.command.js";
+import { diffParentCommand, diffRoundsCommand, roundsCaptureCommand, roundsListCommand, roundsParentCommand, roundsShowCommand, } from "./commands/rounds.command.js";
+import { genCommand } from "./commands/gen.command.js";
+import { applyCommand } from "./commands/apply.command.js";
+import { groundingCommand } from "./commands/grounding.command.js";
+import { planCheckCommand } from "./commands/plan-check.command.js";
+import { whyCommand } from "./commands/why.command.js";
+import { specParentCommand, specCreateCommand, specReviewCommand, specImplementCommand, specVerifyCommand, specListCommand, specShowCommand, specStatusCommand, specLintCommand, } from "./commands/spec.command.js";
+import { exportCommand } from "./commands/export.command.js";
+import { dashboardCommand } from "./commands/dashboard.command.js";
+import { dashboardDiffCommand, dashboardExportCommand, } from "./commands/dashboard-export.command.js";
+import { importCommand } from "./commands/import.command.js";
+import { askCommand } from "./commands/ask.command.js";
+import { mcpCommand } from "./commands/mcp.command.js";
+import { versionCommand } from "./commands/version.command.js";
+import { makeHelpCommand } from "./commands/help.command.js";
+import { qualityCommand } from "./commands/quality.command.js";
+import { ciCommand } from "./commands/ci.command.js";
+import { eslintCommand } from "./commands/eslint.command.js";
+import { biomeCommand } from "./commands/biome.command.js";
+import { ideCommand } from "./commands/ide.command.js";
+import { makeCommandsCommand } from "./commands/commands.command.js";
+import { safetyCommand } from "./commands/safety.command.js";
+import { pluginCommand } from "./commands/plugin.command.js";
+import { profilesCommand } from "./commands/profiles.command.js";
+import { auditProjectCouplingCommand } from "./commands/audit.command.js";
+import { conventionsCommand } from "./commands/conventions.command.js";
+import { selfConfigCommand } from "./commands/self-config.command.js";
+import { helperCommand } from "./commands/helper.command.js";
+import { registryCommand } from "./commands/registry.command.js";
+import { registrationsCommand } from "./commands/registrations.command.js";
+import { boundariesListCommand, boundariesGetCommand, boundariesExplainCommand, boundariesInferCommand, } from "./commands/boundaries.command.js";
+import { scaffoldsListCommand, scaffoldsGetCommand, scaffoldsDoctorCommand, } from "./commands/scaffolds.command.js";
+import { inferCommand } from "./commands/infer.command.js";
+import { reportCommand } from "./commands/report.command.js";
+import { bundleCommand } from "./commands/bundle.command.js";
+import { impactCommand } from "./commands/impact.command.js";
+import { traceCommand } from "./commands/trace.command.js";
+import { feedbackCommand } from "./commands/feedback-dispatch.command.js";
+import { searchCommand } from "./commands/search.command.js";
+import { briefCommand } from "./commands/brief.command.js";
+import { releaseCommand, installSmokeCommand } from "./commands/release.command.js";
+import { startHereCommand } from "./commands/start-here.command.js";
+import { docsCheckCommand, examplesCheckCommand } from "./commands/docs.command.js";
+import { selfAuditCommand } from "./commands/self.command.js";
+import { diagnosticsListCommand } from "./commands/diagnostics.command.js";
+import { architectureMapCommand } from "./commands/architecture.command.js";
+import { orchestrateCommand } from "./commands/orchestrate.command.js";
+import { simulateCommand } from "./commands/simulate.command.js";
+import { reposetInitCommand, reposetListCommand, reposetDoctorCommand, reposetMapCommand, } from "./commands/reposet.command.js";
+import { recommendCommand } from "./commands/recommend.command.js";
+import { surfaceCommand } from "./commands/surface.command.js";
+import { upgradeCheckCommand, upgradePlanCommand } from "./commands/upgrade.command.js";
+import { architectureViolationsCommand, architectureAreaCommand, } from "./commands/architecture.command.js";
+import { riskCommand } from "./commands/risk.command.js";
+import { contractCommand } from "./commands/contract.command.js";
+import { contractApproveCommand, contractCheckCommand, contractStatusCommand, } from "./commands/contract-gate.command.js";
+import { planSimulateCommand } from "./commands/plan-simulate.command.js";
+import { memoryBuildCommand, memoryDiagnosticsCommand, memoryDiffCommand, memoryDriftCommand, memoryFilesCommand, memoryReportCommand, memoryResetCommand, memoryRiskCommand, memorySnapshotsCommand, } from "./commands/memory.command.js";
+import { constructsAdoptCommand, constructsApiCommand, constructsEventsCommand, constructsFacetsCommand, constructsFilesCommand, constructsGetCommand, constructsImpactCommand, constructsInferCommand, constructsListCommand, constructsRelatedCommand, constructsSearchCommand, constructsTokensCommand, constructsTraceCommand, } from "./commands/constructs.command.js";
+import { playbooksBriefCommand, playbooksGetCommand, playbooksListCommand, playbooksPreviewCommand, playbooksRecommendCommand, playbooksRunbookCommand, playbooksScriptCommand, playbooksValidateCommand, } from "./commands/playbooks.command.js";
+import { repoAreasCommand } from "./commands/repo.command.js";
+import { policyCheckCommand, policyListCommand, policyGetCommand, policySnapshotCommand, policyTestCommand, policyRunCommand, } from "./commands/policy.command.js";
+import { ownersListCommand, ownersMatchCommand, ownersImpactCommand } from "./commands/owners.command.js";
+import { ownershipListCommand, ownershipForCommand, ownershipAffectedCommand, } from "./commands/ownership.command.js";
+import { runtimeDoctorCommand } from "./commands/runtime.command.js";
+import { testsImpactCommand, testsSuggestCommand, testsMissingCommand } from "./commands/tests.command.js";
+import { gitChangedCommand, gitRootCommand, gitBranchCommand, gitStatusSummaryCommand, } from "./commands/git.command.js";
+import { templatesLintCommand, templatesTestCommand, templatesSnapshotCommand, } from "./commands/template-quality.command.js";
+import { boundariesEnforceCommand, boundariesSuggestCommand } from "./commands/boundaries.command.js";
+import { languagesCommand } from "./commands/languages.command.js";
+import { fixCommand } from "./commands/fix.command.js";
+// unified lint aggregator.
+import { lintCommand } from "./commands/lint.command.js";
+import { changesCommand } from "./commands/changes.command.js";
+import { exploreCommand } from "./commands/explore.command.js";
+import { prCommand } from "./commands/pr.command.js";
+import { suggestDidYouMean } from '@shrkcrft/inspector';
+import { COMMAND_CATALOG } from "./commands/command-catalog.js";
+import { errorFooterFor, renderErrorFooter } from "./output/failure-hints.js";
+import { renderAbout } from "./surface/about.js";
+import { renderNoArgsLanding } from "./surface/no-args-landing.js";
+import { loadSurfaceContext } from "./surface/load-surface-context.js";
+import { buildSurfaceSummary, findCommandInSummary } from "./surface/surface-summary.js";
+import { makeSurfaceNotEnabledError, renderSurfaceNotEnabledText, SURFACE_NOT_ENABLED_EXIT_CODE, } from "./surface/not-enabled-error.js";
+import { extractCommandPath, recordUsage, sanitizeFlagNames, } from "./usage/usage-log.js";
+import { loadProjectConfig } from '@shrkcrft/config';
+import { initTokenizer } from '@shrkcrft/context';
+import { statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+function isUsableDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+let tokenizerInitPromise = null;
+/**
+ * Best-effort one-time upgrade from the estimator to gpt-tokenizer.
+ *
+ * The estimator is always active before this resolves, so commands that
+ * race the load still get a budget-safe (if slightly off) count. Subsequent
+ * `countTokens` calls get the real BPE count.
+ */
+async function ensureTokenizerReady() {
+    if (process.env.SHARKCRAFT_NO_REAL_TOKENIZER === '1')
+        return;
+    if (!tokenizerInitPromise) {
+        tokenizerInitPromise = initTokenizer().catch(() => false);
+    }
+    await tokenizerInitPromise;
+}
+export function buildRegistry() {
+    const registry = new CommandRegistry();
+    registry.register(initCommand);
+    registry.register(inspectCommand);
+    registry.register(doctorCommand);
+    registry.registerSubcommand('doctor', doctorSuppressCommand);
+    registry.registerSubcommand('doctor', doctorSuppressionsCommand);
+    // Acknowledgements with required reason + expiry.
+    registry.registerSubcommand('doctor', doctorAcknowledgeCommand);
+    registry.registerSubcommand('doctor', doctorAcknowledgementsCommand);
+    registry.register(contextCommand);
+    registry.register(genCommand);
+    registry.register(applyCommand);
+    // `shrk grounding` thin context primer.
+    registry.register(groundingCommand);
+    // feedback3 — `shrk why <file>` (closes the dangling ide-suggested verb).
+    registry.register(whyCommand);
+    // spec verb + subcommands.
+    registry.register(specParentCommand);
+    registry.registerSubcommand('spec', specCreateCommand);
+    registry.registerSubcommand('spec', specReviewCommand);
+    registry.registerSubcommand('spec', specImplementCommand);
+    registry.registerSubcommand('spec', specVerifyCommand);
+    registry.registerSubcommand('spec', specListCommand);
+    registry.registerSubcommand('spec', specShowCommand);
+    registry.registerSubcommand('spec', specStatusCommand);
+    registry.registerSubcommand('spec', specLintCommand);
+    // rounds capture + diff.
+    registry.register(roundsParentCommand);
+    registry.registerSubcommand('rounds', roundsCaptureCommand);
+    registry.registerSubcommand('rounds', roundsListCommand);
+    registry.registerSubcommand('rounds', roundsShowCommand);
+    registry.register(diffParentCommand);
+    registry.registerSubcommand('diff', diffRoundsCommand);
+    registry.register(exportCommand);
+    registry.register(dashboardCommand);
+    registry.registerSubcommand('dashboard', dashboardExportCommand);
+    registry.registerSubcommand('dashboard', dashboardDiffCommand);
+    registry.register(importCommand);
+    registry.register(taskCommand);
+    registry.register(explainCommand);
+    registry.register(checkCommand);
+    // changed-only preflight orchestrator.
+    registry.register(preflightCommand);
+    registry.register(driftCommand);
+    registry.register(graphCommand);
+    registry.register(coverageCommand);
+    registry.register(statsCommand);
+    registry.register(reviewCommand);
+    registry.register(onboardCommand);
+    registry.register(ingestCommand);
+    registry.register(contradictionsCommand);
+    registry.register(generatedCommand);
+    registry.register(understandTaskCommand);
+    registry.register(validateChangeCommand);
+    // contextBuildCommand / contextRefreshCommand / contextStatusCommand are
+    // dispatched from inside contextCommand based on the first positional arg
+    // (avoids breaking `shrk context --task "..."` flat usage).
+    void contextBuildCommand;
+    void contextRefreshCommand;
+    void contextStatusCommand;
+    registry.register(testCommand);
+    registry.register(planParentCommand);
+    registry.register(devCommand);
+    registry.register(askCommand);
+    registry.register(mcpCommand);
+    registry.register(versionCommand);
+    registry.register(qualityCommand);
+    registry.register(ciCommand);
+    registry.register(eslintCommand);
+    registry.register(biomeCommand);
+    registry.register(ideCommand);
+    registry.register(pluginCommand);
+    registry.register(profilesCommand);
+    registry.registerSubcommand('audit', auditProjectCouplingCommand);
+    registry.register(conventionsCommand);
+    registry.register(selfConfigCommand);
+    registry.register(helperCommand);
+    registry.register(registryCommand);
+    registry.register(registrationsCommand);
+    registry.register(makeCommandsCommand(registry));
+    registry.register(safetyCommand);
+    registry.register(inferCommand);
+    registry.register(reportCommand);
+    registry.register(bundleCommand);
+    registry.register(impactCommand);
+    registry.register(traceCommand);
+    registry.register(feedbackCommand);
+    registry.register(fixCommand);
+    // unified lint verb (knowledge / rules / templates aggregator).
+    registry.register(lintCommand);
+    registry.register(changesCommand);
+    registry.register(prCommand);
+    registry.register(searchCommand);
+    registry.register(briefCommand);
+    registry.register(releaseCommand);
+    registry.register(startHereCommand);
+    registry.register(exploreCommand);
+    registry.register(orchestrateCommand);
+    registry.register(simulateCommand);
+    registry.register(recommendCommand);
+    // Adaptive surface introspection + management.
+    registry.register(surfaceCommand);
+    registry.register(riskCommand);
+    registry.register(contractCommand);
+    // contract gates — dispatched from inside contractCommand when the
+    // first positional is check/approve/status (avoids subcommand-routing
+    // collision with the task-string form `shrk contract "<task>"`).
+    void contractCheckCommand;
+    void contractApproveCommand;
+    void contractStatusCommand;
+    registry.registerSubcommand('plan', planSimulateCommand);
+    // register `plan review` as a proper subcommand so the catalog
+    // and registry agree. The internal dispatch in planParentCommand still
+    // works (acts as a fallback for direct invocation), but the canonical
+    // wire-up is now explicit.
+    registry.registerSubcommand('plan', planReviewCommand);
+    // `shrk plan check <path>` validates external plans.
+    registry.registerSubcommand('plan', planCheckCommand);
+    registry.registerSubcommand('memory', memoryBuildCommand);
+    registry.registerSubcommand('memory', memoryReportCommand);
+    registry.registerSubcommand('memory', memoryRiskCommand);
+    registry.registerSubcommand('memory', memoryFilesCommand);
+    registry.registerSubcommand('memory', memoryDiagnosticsCommand);
+    registry.registerSubcommand('memory', memoryResetCommand);
+    registry.registerSubcommand('memory', memoryDiffCommand);
+    registry.registerSubcommand('memory', memoryDriftCommand);
+    registry.registerSubcommand('memory', memorySnapshotsCommand);
+    registry.register(languagesCommand);
+    registry.registerSubcommand('docs', docsCheckCommand);
+    registry.registerSubcommand('examples', examplesCheckCommand);
+    registry.registerSubcommand('self', selfAuditCommand);
+    registry.registerSubcommand('install', installSmokeCommand);
+    registry.registerSubcommand('diagnostics', diagnosticsListCommand);
+    registry.registerSubcommand('architecture', architectureMapCommand);
+    registry.registerSubcommand('architecture', architectureViolationsCommand);
+    registry.registerSubcommand('architecture', architectureAreaCommand);
+    registry.registerSubcommand('reposet', reposetInitCommand);
+    registry.registerSubcommand('reposet', reposetListCommand);
+    registry.registerSubcommand('reposet', reposetDoctorCommand);
+    registry.registerSubcommand('reposet', reposetMapCommand);
+    registry.registerSubcommand('upgrade', upgradeCheckCommand);
+    registry.registerSubcommand('upgrade', upgradePlanCommand);
+    registry.registerSubcommand('boundaries', boundariesListCommand);
+    registry.registerSubcommand('boundaries', boundariesGetCommand);
+    registry.registerSubcommand('boundaries', boundariesExplainCommand);
+    registry.registerSubcommand('boundaries', boundariesInferCommand);
+    registry.registerSubcommand('boundaries', boundariesSuggestCommand);
+    registry.registerSubcommand('boundaries', boundariesEnforceCommand);
+    registry.registerSubcommand('repo', repoAreasCommand);
+    registry.registerSubcommand('policy', policyListCommand);
+    registry.registerSubcommand('policy', policyGetCommand);
+    registry.registerSubcommand('policy', policyTestCommand);
+    registry.registerSubcommand('policy', policyRunCommand);
+    registry.registerSubcommand('policy', policyCheckCommand);
+    registry.registerSubcommand('policy', policySnapshotCommand);
+    registry.registerSubcommand('owners', ownersListCommand);
+    registry.registerSubcommand('owners', ownersMatchCommand);
+    registry.registerSubcommand('owners', ownersImpactCommand);
+    registry.registerSubcommand('ownership', ownershipListCommand);
+    registry.registerSubcommand('ownership', ownershipForCommand);
+    registry.registerSubcommand('ownership', ownershipAffectedCommand);
+    registry.registerSubcommand('runtime', runtimeDoctorCommand);
+    registry.registerSubcommand('constructs', constructsListCommand);
+    registry.registerSubcommand('constructs', constructsGetCommand);
+    registry.registerSubcommand('constructs', constructsTraceCommand);
+    registry.registerSubcommand('constructs', constructsApiCommand);
+    registry.registerSubcommand('constructs', constructsEventsCommand);
+    registry.registerSubcommand('constructs', constructsTokensCommand);
+    registry.registerSubcommand('constructs', constructsFacetsCommand);
+    registry.registerSubcommand('constructs', constructsSearchCommand);
+    registry.registerSubcommand('constructs', constructsInferCommand);
+    registry.registerSubcommand('constructs', constructsAdoptCommand);
+    registry.registerSubcommand('constructs', constructsImpactCommand);
+    registry.registerSubcommand('constructs', constructsRelatedCommand);
+    registry.registerSubcommand('constructs', constructsFilesCommand);
+    registry.registerSubcommand('playbooks', playbooksListCommand);
+    registry.registerSubcommand('playbooks', playbooksGetCommand);
+    registry.registerSubcommand('playbooks', playbooksRecommendCommand);
+    registry.registerSubcommand('playbooks', playbooksRunbookCommand);
+    registry.registerSubcommand('playbooks', playbooksBriefCommand);
+    registry.registerSubcommand('playbooks', playbooksScriptCommand);
+    registry.registerSubcommand('playbooks', playbooksPreviewCommand);
+    registry.registerSubcommand('playbooks', playbooksValidateCommand);
+    registry.aliasGroup('construct', 'constructs');
+    registry.aliasGroup('playbook', 'playbooks');
+    registry.registerSubcommand('tests', testsImpactCommand);
+    registry.registerSubcommand('tests', testsSuggestCommand);
+    registry.registerSubcommand('tests', testsMissingCommand);
+    registry.registerSubcommand('git', gitChangedCommand);
+    registry.registerSubcommand('git', gitRootCommand);
+    registry.registerSubcommand('git', gitBranchCommand);
+    registry.registerSubcommand('git', gitStatusSummaryCommand);
+    registry.registerSubcommand('templates', templatesLintCommand);
+    registry.registerSubcommand('templates', templatesTestCommand);
+    registry.registerSubcommand('templates', templatesSnapshotCommand);
+    registry.registerSubcommand('knowledge', knowledgeListCommand);
+    registry.registerSubcommand('knowledge', knowledgeGetCommand);
+    registry.registerSubcommand('knowledge', knowledgeSearchCommand);
+    registry.registerSubcommand('knowledge', knowledgeStaleCheckCommand);
+    registry.registerSubcommand('knowledge', knowledgeVerifyCommand);
+    registry.registerSubcommand('knowledge', knowledgeReferencesCommand);
+    registry.registerSubcommand('knowledge', knowledgeAnchorsCommand);
+    registry.registerSubcommand('knowledge', knowledgeRenameSymbolCommand);
+    registry.registerSubcommand('knowledge', knowledgeRenameFileCommand);
+    registry.registerSubcommand('knowledge', knowledgeUpdateAnchorCommand);
+    // knowledge authoring preview surface.
+    registry.registerSubcommand('knowledge', knowledgeAddCommand);
+    registry.registerSubcommand('knowledge', knowledgeUpdateCommand);
+    registry.registerSubcommand('knowledge', knowledgeRemoveCommand);
+    registry.registerSubcommand('knowledge', knowledgeLintCommand);
+    // propose stub entries for uncovered exports (AST-driven).
+    registry.registerSubcommand('knowledge', knowledgeProposeCommand);
+    registry.registerSubcommand('rules', rulesListCommand);
+    registry.registerSubcommand('rules', rulesGetCommand);
+    registry.registerSubcommand('rules', rulesRelevantCommand);
+    registry.registerSubcommand('rules', rulesScaffoldCommand);
+    // `rules update` thin wrapper over knowledge update.
+    registry.registerSubcommand('rules', rulesUpdateCommand);
+    // authoring symmetry: rules add / rules remove (parity with knowledge).
+    registry.registerSubcommand('rules', rulesAddCommand);
+    registry.registerSubcommand('rules', rulesRemoveCommand);
+    registry.registerSubcommand('rules', rulesDoctorCommand);
+    registry.registerSubcommand('rules', rulesLintCommand);
+    // custom checks registry.
+    registry.registerSubcommand('checks', checksListCommand);
+    registry.registerSubcommand('checks', checksDoctorCommand);
+    registry.registerSubcommand('checks', checksRunCommand);
+    registry.registerSubcommand('checks', checksParseReportCommand);
+    // universal check-result protocol.
+    registry.registerSubcommand('checks', checksImportCommand);
+    registry.registerSubcommand('checks', checksAggregateCommand);
+    registry.registerSubcommand('checks', checksReportCommand);
+    registry.registerSubcommand('checks', checksConvertCommand);
+    // codemod-assist (NOT a codemod engine).
+    registry.register(codemodCommand);
+    registry.registerSubcommand('paths', pathsListCommand);
+    registry.registerSubcommand('paths', pathsGetCommand);
+    registry.registerSubcommand('paths', pathsSearchCommand);
+    registry.registerSubcommand('paths', pathsBestCommand);
+    registry.registerSubcommand('templates', templatesListCommand);
+    registry.registerSubcommand('templates', templatesGetCommand);
+    registry.registerSubcommand('templates', templatesSearchCommand);
+    registry.registerSubcommand('templates', templatesPreviewCommand);
+    registry.registerSubcommand('templates', templatesVarsCommand);
+    registry.registerSubcommand('templates', templatesDriftCommand);
+    registry.registerSubcommand('templates', templatesVerifyPathsCommand);
+    registry.registerSubcommand('templates', templatesSmokeCommand);
+    // authoring stack: scaffold / add / doctor.
+    registry.registerSubcommand('templates', templatesScaffoldCommand);
+    registry.registerSubcommand('templates', templatesAddCommand);
+    registry.registerSubcommand('templates', templatesDoctorCommand);
+    // authoring parity: update / remove.
+    registry.registerSubcommand('templates', templatesUpdateCommand);
+    registry.registerSubcommand('templates', templatesRemoveCommand);
+    registry.registerSubcommand('pipelines', pipelinesListCommand);
+    registry.registerSubcommand('pipelines', pipelinesGetCommand);
+    registry.registerSubcommand('pipelines', pipelinesContextCommand);
+    registry.registerSubcommand('pipelines', pipelinesPlanCommand);
+    registry.registerSubcommand('pipelines', pipelinesScriptCommand);
+    registry.registerSubcommand('pipelines', pipelinesNextCommand);
+    registry.registerSubcommand('pipelines', pipelinesVarsCommand);
+    registry.registerSubcommand('packs', packsListCommand);
+    registry.registerSubcommand('packs', packsContributionsCommand);
+    registry.registerSubcommand('packs', packsConflictsCommand);
+    registry.registerSubcommand('packs', packsSignatureStatusCommand);
+    registry.registerSubcommand('packs', packsGetCommand);
+    registry.registerSubcommand('packs', packsInspectCommand);
+    registry.registerSubcommand('packs', packsDoctorCommand);
+    registry.registerSubcommand('packs', packsSignCommand);
+    registry.registerSubcommand('packs', packsVerifyCommand);
+    registry.registerSubcommand('packs', packsNewCommand);
+    registry.registerSubcommand('packs', packsTestCommand);
+    registry.registerSubcommand('packs', packsReleaseCheckCommand);
+    registry.registerSubcommand('packs', packsCompatCommand);
+    registry.registerSubcommand('packs', packsDevStatusCommand);
+    registry.registerSubcommand('packs', packsWatchCommand);
+    // pack authoring moved to a 3-level group: `shrk pack author <verb>`.
+    // The old `pack-author <verb>` shape is gone (no backward-compat shim).
+    // `shrk packs pending` survives as a convenience for the pending view.
+    registry.registerAt(['pack', 'author', packAuthorStatusCommand.name], packAuthorStatusCommand);
+    registry.registerAt(['pack', 'author', packAuthorPreviewCommand.name], packAuthorPreviewCommand);
+    registry.registerAt(['pack', 'author', packAuthorPendingCommand.name], packAuthorPendingCommand);
+    registry.registerAt(['pack', 'author', packAuthorValidateCommand.name], packAuthorValidateCommand);
+    registry.registerSubcommand('packs', packAuthorPendingCommand);
+    // provenance ledger CLI.
+    registry.registerSubcommand('provenance', provenanceListCommand);
+    registry.registerSubcommand('provenance', provenanceShowCommand);
+    registry.registerSubcommand('provenance', provenanceReportCommand);
+    // missing / doctor verbs.
+    registry.registerSubcommand('provenance', provenanceMissingCommand);
+    registry.registerSubcommand('provenance', provenanceDoctorCommand);
+    registry.registerSubcommand('schemas', schemasListCommand);
+    registry.registerSubcommand('schemas', schemasGetCommand);
+    registry.registerSubcommand('schemas', schemasInventoryCommand);
+    registry.registerSubcommand('schemas', schemasWriteCommand);
+    // preview-first emission + preflight drift check.
+    registry.registerSubcommand('schemas', schemasEmitCommand);
+    registry.registerSubcommand('scaffolds', scaffoldsListCommand);
+    registry.registerSubcommand('scaffolds', scaffoldsGetCommand);
+    registry.registerSubcommand('scaffolds', scaffoldsDoctorCommand);
+    registry.registerSubcommand('presets', presetsListCommand);
+    registry.registerSubcommand('presets', presetsGetCommand);
+    registry.registerSubcommand('presets', presetsExplainCommand);
+    registry.registerSubcommand('presets', presetsRecommendCommand);
+    registry.registerSubcommand('presets', presetsPreviewCommand);
+    registry.registerSubcommand('presets', presetsApplyCommand);
+    registry.registerSubcommand('presets', presetsDoctorCommand);
+    registry.registerSubcommand('presets', presetsDiffCommand);
+    registry.registerSubcommand('presets', presetsPatchCommand);
+    // release subcommand additions — register under 'release' group via 'train'.
+    // We pass 'train' as the canonical name; users invoke `shrk release train <verb>`.
+    // Convenience aliases so users can say either form.
+    registry.aliasGroup('pipeline', 'pipelines');
+    registry.aliasGroup('schema', 'schemas');
+    registry.aliasGroup('preset', 'presets');
+    registry.aliasGroup('scaffold', 'scaffolds');
+    const help = makeHelpCommand(registry);
+    registry.register(help);
+    return registry;
+}
+export async function runCli(argv) {
+    const usageStart = performance.now();
+    const { cwd: probeCwd, rest: probeArgv } = extractGlobalCwd(argv);
+    let exitCode = 0;
+    try {
+        exitCode = await runCliInner(argv);
+        return exitCode;
+    }
+    finally {
+        // append one local usage entry. Failure is silent.
+        try {
+            const command = extractCommandPath(probeArgv);
+            if (command.length > 0) {
+                const flags = sanitizeFlagNames(probeArgv);
+                const enabled = await isUsageEnabled(probeCwd ?? process.cwd());
+                recordUsage({
+                    cwd: probeCwd ?? process.cwd(),
+                    command,
+                    exitCode,
+                    durationMs: performance.now() - usageStart,
+                    flags,
+                    enabled,
+                });
+            }
+        }
+        catch {
+            // ignore — usage log must never fail the CLI
+        }
+    }
+}
+/**
+ * Resolve whether the local usage log is enabled. Order:
+ *   1. `SHARKCRAFT_USAGE_DISABLED=1` env → false (disabled).
+ *   2. `sharkcraft.config.ts usage.enabled === false` → false.
+ *   3. Otherwise → true.
+ */
+async function isUsageEnabled(cwd) {
+    if (process.env.SHARKCRAFT_USAGE_DISABLED === '1')
+        return false;
+    try {
+        const result = await loadProjectConfig(cwd);
+        if (!result.ok)
+            return true;
+        return result.value.config.usage?.enabled !== false;
+    }
+    catch {
+        return true;
+    }
+}
+async function runCliInner(argv) {
+    await ensureTokenizerReady();
+    const registry = buildRegistry();
+    // Pre-parse the global --cwd so it can appear anywhere (incl. before the command).
+    const { cwd: globalCwd, rest: cleanArgv } = extractGlobalCwd(argv);
+    if (globalCwd !== undefined && !isUsableDirectory(globalCwd)) {
+        process.stderr.write(`error: --cwd "${globalCwd}" is not an existing directory.\n` +
+            `Resolved to: ${resolvePath(globalCwd)}\n`);
+        return 2;
+    }
+    const [first] = cleanArgv;
+    // bare invocation lands on the curated tiered view.
+    if (!first) {
+        const landing = await renderNoArgsLanding(globalCwd ?? process.cwd());
+        process.stdout.write(landing);
+        return 0;
+    }
+    // Top-level meta flags.
+    if (first === '--help' || first === '-h') {
+        return registry.get('help').run(parseArgs([], { globalCwd }));
+    }
+    if (first === '--full-help') {
+        return registry.get('help').run(parseArgs(['--full'], { globalCwd }));
+    }
+    if (first === '--version' || first === '-v') {
+        return registry.get('version').run(parseArgs([], { globalCwd }));
+    }
+    // `shrk --about` prints the in-binary philosophy summary.
+    if (first === '--about') {
+        process.stdout.write(renderAbout());
+        return 0;
+    }
+    // greedy trie descent. Handles 1-, 2-, and 3-level commands uniformly
+    // (`shrk doctor`, `shrk packs list`, `shrk pack author status`). The
+    // resolver stops when it hits a flag or a token that isn't a child of the
+    // current node, returning the deepest handler + the leftover tokens.
+    const { handler, matchedPath, rest: leftover, node } = registry.resolve(cleanArgv);
+    // `--help` / `-h` immediately after a (sub)group → render help for that
+    // path. This works at any depth.
+    if (leftover[0] === '--help' || leftover[0] === '-h') {
+        return registry.get('help').run(parseArgs([matchedPath.join(' ')], { globalCwd }));
+    }
+    if (handler) {
+        // gate experimental commands. Bootstrap commands and core/extended
+        // tiers pass through; experimental commands return the structured
+        // not-enabled error unless `surface.enabled[]` contains them.
+        const gateReason = await checkSurfaceGate(matchedPath, globalCwd ?? process.cwd());
+        if (gateReason) {
+            const err = makeSurfaceNotEnabledError(gateReason.command, { reason: gateReason.detail });
+            process.stderr.write(renderSurfaceNotEnabledText(err));
+            return SURFACE_NOT_ENABLED_EXIT_CODE;
+        }
+        return await handler.run(parseArgs(leftover, { globalCwd }));
+    }
+    // No handler at the deepest match. If we landed on a group node (has
+    // children), show that group's help so the user discovers the verbs.
+    if (matchedPath.length > 0 && node.children.size > 0) {
+        return registry.get('help').run(parseArgs([matchedPath.join(' ')], { globalCwd }));
+    }
+    // Genuinely unknown — fall back to free-form / did-you-mean.
+    const probe = cleanArgv.filter((t) => typeof t === 'string' && t.length > 0 && !t.startsWith('-'));
+    if (looksLikeFreeFormTask(probe)) {
+        printFreeFormTaskHint(probe.join(' '));
+        return 2;
+    }
+    const attempted = probe.slice(0, 2).join(' ');
+    process.stderr.write(`Unknown command: ${attempted}\n`);
+    printDidYouMean(attempted);
+    return 2;
+}
+/**
+ * Heuristic for "this looks like a task, not a command".
+ *
+ *  - At least two non-flag tokens (commands have at most two tokens: a
+ *    top-level + a subcommand verb).
+ *  - Or one token that matches a known free-form verb (rename / add / fix /
+ *    refactor / remove / migrate / implement / update / build / …).
+ *  - Never matches `--`-prefixed flag tokens.
+ *
+ * The function is deterministic and accepts only positional tokens.
+ * Exported for tests.
+ */
+export function looksLikeFreeFormTask(tokens) {
+    const clean = tokens.filter((t) => t.length > 0 && !t.startsWith('-'));
+    if (clean.length < 2)
+        return false;
+    // 3+ tokens is almost always a sentence, not a command — `shrk` only has
+    // 2 levels (top + sub), so anything beyond that has no chance of being a
+    // real path.
+    if (clean.length >= 3)
+        return true;
+    // 2 tokens: only treat as a task if the first token is a recognisable
+    // task verb. Otherwise it's plausibly a typo of a subcommand and we let
+    // the regular did-you-mean handle it.
+    const verbs = new Set([
+        'rename',
+        'add',
+        'fix',
+        'refactor',
+        'remove',
+        'delete',
+        'migrate',
+        'wire',
+        'create',
+        'implement',
+        'update',
+        'introduce',
+        'build',
+        'extract',
+        'move',
+        'inline',
+        'generate',
+        'scaffold',
+        'explain',
+        'document',
+        'review',
+        'test',
+        'design',
+        'refresh',
+        'reorganise',
+        'reorganize',
+        'restructure',
+        'split',
+        'merge',
+        'reduce',
+        'simplify',
+    ]);
+    return verbs.has(clean[0].toLowerCase());
+}
+function printFreeFormTaskHint(task) {
+    process.stderr.write(`\nThis looks like a task, not a command.\n` +
+        `\n` +
+        `Recommended:\n` +
+        `  $ shrk recommend "${task}"\n` +
+        `\n` +
+        `Why:\n` +
+        `  \`shrk recommend\` is the canonical human entrypoint for "what should I do?".\n` +
+        `\n` +
+        `More detail:\n` +
+        `  $ shrk start-here\n` +
+        `  $ shrk commands\n`);
+}
+/**
+ * Check whether the resolved command path is gated by the
+ * surface tier model. Returns `null` if the command is callable
+ * (core/extended), or `{ command, detail }` if it is an experimental
+ * command not enabled in the current repo's surface config.
+ *
+ * Failure-soft: any error loading the inspection (fresh repo, no
+ * config, etc.) lets the command through. The gate must NEVER false-
+ * positive a bootstrap call — the bootstrap set in `tier.ts` plus
+ * spine-derived core commands always pass through cleanly.
+ */
+async function checkSurfaceGate(matchedPath, cwd) {
+    const candidate = matchedPath.join(' ');
+    if (candidate.length === 0)
+        return null;
+    try {
+        const { context } = await loadSurfaceContext({ cwd });
+        const summary = buildSurfaceSummary(context);
+        // Try the full path first; fall back to the top-level token. The
+        // catalog uses both shapes ("doctor" and "plan review").
+        const view = findCommandInSummary(summary, candidate) ??
+            findCommandInSummary(summary, matchedPath[0] ?? '');
+        if (!view)
+            return null;
+        if (view.callable)
+            return null;
+        return { command: view.command, detail: view.detail };
+    }
+    catch {
+        return null;
+    }
+}
+function printDidYouMean(attempted) {
+    const candidates = suggestDidYouMean(COMMAND_CATALOG, [attempted], 3);
+    if (candidates.length === 0) {
+        process.stderr.write("Tip: run `shrk commands suggest \"<partial>\"` or `shrk help` to discover commands.\n");
+        const footer = errorFooterFor('unknown-command', { task: attempted });
+        if (footer)
+            process.stderr.write(renderErrorFooter(footer));
+        return;
+    }
+    process.stderr.write('Did you mean:\n');
+    for (const c of candidates) {
+        process.stderr.write(`  shrk ${c.command} — ${c.description}\n`);
+    }
+    // append the standardised next-command footer so the user
+    // always has a deterministic exit route.
+    const footer = errorFooterFor('unknown-command', { task: attempted });
+    if (footer)
+        process.stderr.write(renderErrorFooter(footer));
+}
+// Entry point when invoked directly.
+const isMain = typeof import.meta !== 'undefined' && import.meta.main === true;
+if (isMain || process.argv[1]?.endsWith('main.ts') || process.argv[1]?.endsWith('shrk')) {
+    const argv = process.argv.slice(2);
+    runCli(argv).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}