handoff-app 2.0.0-4 → 2.0.0-6

package/dist/commands/utils.d.ts

@@ -1,10 +1,15 @@
 import { Argv } from 'yargs';
-import type { TransferEntityKind } from '../registry/transfer';
-/** Plural entity kinds accepted by the `publish`/`checkout` commands. */
-export declare const REGISTRY_ENTITY_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets"];
-export type RegistryEntityKind = (typeof REGISTRY_ENTITY_KINDS)[number];
-/** Map the plural CLI kind to the singular wire kind used by entity publish/checkout. */
-export declare const ENTITY_WIRE_KIND: Record<'components' | 'patterns' | 'pages', TransferEntityKind>;
+import Handoff from '../';
+import { SharedArgs } from './types';
+/** The `type` argument accepted by publish/checkout: any content kind, or `all` for every kind. */
+export declare const REGISTRY_TARGET_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets", "all"];
+export type RegistryTargetKind = (typeof REGISTRY_TARGET_KINDS)[number];
+export declare const createHandoff: (args: SharedArgs) => Handoff;
+/**
+ * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
+ * surface as one actionable line and a non-zero exit rather than a stack trace.
+ */
+export declare const runRegistryCommand: (args: SharedArgs, run: (handoff: Handoff) => Promise<unknown>) => Promise<void>;
 export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
@@ -22,3 +27,66 @@ export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omi
         description: string;
     };
 }>>;
+/** Shared options plus the transfer options: publish and its compatibility aliases use these. */
+export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
+    config: {
+        alias: string;
+        type: "string";
+        description: string;
+    };
+    force: {
+        alias: string;
+        type: "boolean";
+        description: string;
+    };
+    debug: {
+        alias: string;
+        type: "boolean";
+        description: string;
+    };
+}>, "build" | "dry-run"> & import("yargs").InferredOptionTypes<{
+    'dry-run': {
+        type: "boolean";
+        description: string;
+    };
+    build: {
+        type: "boolean";
+        default: boolean;
+        description: string;
+    };
+}>>;
+/** Shared options plus `--dry-run`: checkout and its compatibility aliases use these. */
+export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
+    config: {
+        alias: string;
+        type: "string";
+        description: string;
+    };
+    force: {
+        alias: string;
+        type: "boolean";
+        description: string;
+    };
+    debug: {
+        alias: string;
+        type: "boolean";
+        description: string;
+    };
+}>, "dry-run"> & import("yargs").InferredOptionTypes<{
+    'dry-run': {
+        type: "boolean";
+        description: string;
+    };
+}>>;
+/**
+ * Positional `type` + variadic `id`, shared by publish, checkout, and their compatibility aliases.
+ * `choices` is always declared: yargs allows an omitted optional positional while still rejecting an
+ * unrecognized one, so the deprecated commands get the same guard as the canonical ones.
+ */
+export declare const withTargetPositionals: (yargs: Argv, verb: "publish" | "checkout") => Argv<{
+    type: "pages" | "components" | "patterns" | "assets" | "tokens" | "all";
+} & {
+    id: string[];
+}>;
+/** Dispatch one `type` argument to the matching Handoff entry point. */
+export declare const runTarget: (handoff: Handoff, type: RegistryTargetKind, ids: string[] | undefined, verb: "publish" | "checkout") => Promise<Handoff>;

package/dist/commands/utils.js

@@ -1,20 +1,53 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getSharedOptions = exports.ENTITY_WIRE_KIND = exports.REGISTRY_ENTITY_KINDS = void 0;
-/** Plural entity kinds accepted by the `publish`/`checkout` commands. */
-exports.REGISTRY_ENTITY_KINDS = ['components', 'patterns', 'pages', 'tokens', 'assets'];
-/** Map the plural CLI kind to the singular wire kind used by entity publish/checkout. */
-exports.ENTITY_WIRE_KIND = {
-    components: 'component',
-    patterns: 'pattern',
-    pages: 'page',
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTarget = exports.withTargetPositionals = exports.getCheckoutOptions = exports.getPublishOptions = exports.getSharedOptions = exports.runRegistryCommand = exports.createHandoff = exports.REGISTRY_TARGET_KINDS = void 0;
+const __1 = __importDefault(require("../"));
+const content_kinds_1 = require("../registry/content-kinds");
+const logger_1 = require("../utils/logger");
+/** The `type` argument accepted by publish/checkout: any content kind, or `all` for every kind. */
+exports.REGISTRY_TARGET_KINDS = [...content_kinds_1.REGISTRY_ENTITY_KINDS, 'all'];
+const createHandoff = (args) => new __1.default({
+    debug: args.debug,
+    force: args.force,
+    configPath: args.config,
+    dryRun: args.dryRun,
+    // yargs gives `--no-build` as `build: false`; anything else leaves the build in place.
+    skipBuild: args.build === false,
+});
+exports.createHandoff = createHandoff;
+/**
+ * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
+ * surface as one actionable line and a non-zero exit rather than a stack trace.
+ */
+const runRegistryCommand = (args, run) => __awaiter(void 0, void 0, void 0, function* () {
+    const handoff = (0, exports.createHandoff)(args);
+    try {
+        yield run(handoff);
+    }
+    catch (error) {
+        logger_1.Logger.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+});
+exports.runRegistryCommand = runRegistryCommand;
 const getSharedOptions = (yargs) => {
     return yargs.options({
         config: {
             alias: 'c',
             type: 'string',
-            description: 'Path to config file',
+            description: 'Path to config file, relative to the working directory',
         },
         force: {
             alias: 'f',
@@ -29,3 +62,49 @@ const getSharedOptions = (yargs) => {
     });
 };
 exports.getSharedOptions = getSharedOptions;
+/** Shared options plus the transfer options: publish and its compatibility aliases use these. */
+const getPublishOptions = (yargs) => (0, exports.getSharedOptions)(yargs).options({
+    'dry-run': {
+        type: 'boolean',
+        description: 'Report what would be published without contacting the registry (the build still runs; add --no-build to skip it)',
+    },
+    build: {
+        type: 'boolean',
+        default: true,
+        description: 'Run a fresh build first; use --no-build to publish the existing output',
+    },
+});
+exports.getPublishOptions = getPublishOptions;
+/** Shared options plus `--dry-run`: checkout and its compatibility aliases use these. */
+const getCheckoutOptions = (yargs) => (0, exports.getSharedOptions)(yargs).options({
+    'dry-run': {
+        type: 'boolean',
+        description: 'Report what would be written without changing any workspace file',
+    },
+});
+exports.getCheckoutOptions = getCheckoutOptions;
+/**
+ * Positional `type` + variadic `id`, shared by publish, checkout, and their compatibility aliases.
+ * `choices` is always declared: yargs allows an omitted optional positional while still rejecting an
+ * unrecognized one, so the deprecated commands get the same guard as the canonical ones.
+ */
+const withTargetPositionals = (yargs, verb) => yargs
+    .positional('type', {
+    describe: `The kind of content to ${verb}, or "all" for every kind`,
+    choices: exports.REGISTRY_TARGET_KINDS,
+    type: 'string',
+})
+    .positional('id', {
+    describe: `The stable id (component/pattern/page id, token set id, or asset collection); omit to ${verb} all of that kind`,
+    type: 'string',
+    array: true,
+});
+exports.withTargetPositionals = withTargetPositionals;
+/** Dispatch one `type` argument to the matching Handoff entry point. */
+const runTarget = (handoff, type, ids, verb) => {
+    if (type === 'all') {
+        return verb === 'publish' ? handoff.publishAll() : handoff.checkoutAll();
+    }
+    return verb === 'publish' ? handoff.publishKind(type, ids) : handoff.checkoutKind(type, ids);
+};
+exports.runTarget = runTarget;

package/dist/commands/validate/components.js

@@ -8,11 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = __importDefault(require("../../"));
 const utils_1 = require("../utils");
 const command = {
     command: 'validate:components',
@@ -27,7 +23,7 @@ const command = {
     },
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
-        const handoff = new __1.default(args.debug, args.force);
+        const handoff = (0, utils_1.createHandoff)(args);
         yield handoff.validateComponents((_a = args.skipBuild) !== null && _a !== void 0 ? _a : false);
     }),
 };

package/dist/config/defaults.d.ts

@@ -6,6 +6,8 @@ export interface ImageStyle {
     width: number;
     description: string;
 }
+/** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
+export declare const isMcpEnabled: (config: Config | null | undefined) => boolean;
 export declare const defaultConfig: () => Config;
 /**
  * Retrieves the client configuration from the provided handoff configuration.

package/dist/config/defaults.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getClientConfig = exports.defaultConfig = void 0;
+exports.getClientConfig = exports.defaultConfig = exports.isMcpEnabled = void 0;
 const connection_1 = require("../registry/connection");
+/** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
+const isMcpEnabled = (config) => { var _a; return ((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mcp) !== false; };
+exports.isMcpEnabled = isMcpEnabled;
 const defaultConfig = () => {
     var _a, _b, _c, _d;
     return ({

package/dist/config/index.d.ts

@@ -1,6 +1,7 @@
-export { defaultConfig, getClientConfig } from './defaults';
+export { defaultConfig, getClientConfig, isMcpEnabled } from './defaults';
 export type { ImageStyle } from './defaults';
-export { initConfig, initConfigWithMetadata } from './loader';
+export { HandoffConfigError, initConfig, initConfigWithMetadata } from './loader';
+export type { ConfigLoadContext } from './loader';
 export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';
 export { validateConfig } from './validator';

package/dist/config/index.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.writeEntries = exports.isEntryCovered = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
 // Config defaults and client config
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaults_1.defaultConfig; } });
 Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return defaults_1.getClientConfig; } });
+Object.defineProperty(exports, "isMcpEnabled", { enumerable: true, get: function () { return defaults_1.isMcpEnabled; } });
 // Config file loading
 var loader_1 = require("./loader");
+Object.defineProperty(exports, "HandoffConfigError", { enumerable: true, get: function () { return loader_1.HandoffConfigError; } });
 Object.defineProperty(exports, "initConfig", { enumerable: true, get: function () { return loader_1.initConfig; } });
 Object.defineProperty(exports, "initConfigWithMetadata", { enumerable: true, get: function () { return loader_1.initConfigWithMetadata; } });
 // Config helpers

package/dist/config/loader.d.ts

@@ -1,20 +1,33 @@
 import { Config } from '../types/config';
+/** Raised when an explicitly requested config file cannot be used. */
+export declare class HandoffConfigError extends Error {
+    constructor(message: string);
+}
 type ConfigLoadResult = {
     config: Config;
     configPath?: string;
 };
+/** Where to look for the config: the working directory, plus an optional explicit file. */
+export type ConfigLoadContext = {
+    /** Directory relative config paths resolve from, and the root that gets searched. */
+    workingPath?: string;
+    /** Explicit config file (the CLI's `-c, --config`), replacing discovery entirely. */
+    configPath?: string;
+};
 /**
- * Loads the handoff configuration from the project root and returns metadata.
+ * Loads the handoff configuration for the given working directory and returns metadata.
  */
-export declare const initConfigWithMetadata: (configOverride?: Partial<Config>) => ConfigLoadResult;
+export declare const initConfigWithMetadata: (configOverride?: Partial<Config>, context?: ConfigLoadContext) => ConfigLoadResult;
 /**
- * Loads the handoff configuration from the project root.
+ * Loads the handoff configuration for the given working directory.
  *
- * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
- * Merges file config with any provided overrides, then applies defaults for missing values.
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json,
+ * unless `context.configPath` names one explicitly. Merges file config with any provided overrides,
+ * then applies defaults for missing values.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
+ * @param context - Optional working directory and explicit config file to load.
  * @returns The fully resolved Config object.
  */
-export declare const initConfig: (configOverride?: Partial<Config>) => Config;
+export declare const initConfig: (configOverride?: Partial<Config>, context?: ConfigLoadContext) => Config;
 export {};

package/dist/config/loader.js

@@ -3,13 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initConfig = exports.initConfigWithMetadata = void 0;
+exports.initConfig = exports.initConfigWithMetadata = exports.HandoffConfigError = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const merge_1 = __importDefault(require("lodash/merge"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
+const path_2 = require("../utils/path");
 const defaults_1 = require("./defaults");
 const CONFIG_FILE_PREFERENCE = [
     'handoff.config.ts',
@@ -17,6 +18,16 @@ const CONFIG_FILE_PREFERENCE = [
     'handoff.config.cjs',
     'handoff.config.json',
 ];
+/** Extensions the loader knows how to evaluate, derived from the discoverable file names. */
+const SUPPORTED_CONFIG_EXTENSIONS = Array.from(new Set(CONFIG_FILE_PREFERENCE.map((fileName) => path_1.default.extname(fileName))));
+/** Raised when an explicitly requested config file cannot be used. */
+class HandoffConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandoffConfigError';
+    }
+}
+exports.HandoffConfigError = HandoffConfigError;
 const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
     var _a, _b;
     const buildResult = esbuild_1.default.buildSync({
@@ -49,11 +60,12 @@ const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
     return mod.exports;
 };
 const loadConfigFile = (configPath) => {
-    if (configPath.endsWith('.json')) {
+    const extension = path_1.default.extname(configPath);
+    if (extension === '.json') {
         const buffer = fs_extra_1.default.readFileSync(configPath);
         return JSON.parse(buffer.toString());
     }
-    if (configPath.endsWith('.ts')) {
+    if (extension === '.ts') {
         const handoffModulePath = path_1.default.resolve(__dirname, '../..');
         const importedConfig = evaluateTypeScriptConfig(configPath, handoffModulePath);
         return (importedConfig.default || importedConfig);
@@ -63,9 +75,24 @@ const loadConfigFile = (configPath) => {
     const importedConfig = require(configPath);
     return (importedConfig.default || importedConfig);
 };
-const resolveConfigFilePath = () => {
+/**
+ * Picks the config file to load. An explicitly requested file replaces discovery - it is resolved
+ * from `workingPath` and must exist in a format the loader can evaluate. Otherwise every known
+ * config name is looked for in `workingPath`, the first match winning.
+ */
+const resolveConfigFilePath = (workingPath, requestedPath) => {
+    if (requestedPath) {
+        const selected = path_1.default.resolve(workingPath, requestedPath);
+        if (!fs_extra_1.default.existsSync(selected)) {
+            throw new HandoffConfigError(`Config file not found: "${requestedPath}" (resolved to ${selected})`);
+        }
+        if (!SUPPORTED_CONFIG_EXTENSIONS.includes(path_1.default.extname(selected))) {
+            throw new HandoffConfigError(`Unsupported config file "${path_1.default.basename(selected)}". Supported extensions: ${SUPPORTED_CONFIG_EXTENSIONS.join(', ')}`);
+        }
+        return { selected, ignored: [] };
+    }
     const existing = CONFIG_FILE_PREFERENCE
-        .map((fileName) => path_1.default.resolve(process.cwd(), fileName))
+        .map((fileName) => path_1.default.resolve(workingPath, fileName))
         .filter((filePath) => fs_extra_1.default.existsSync(filePath));
     if (!existing.length) {
         return { selected: undefined, ignored: [] };
@@ -74,11 +101,12 @@ const resolveConfigFilePath = () => {
     return { selected, ignored };
 };
 /**
- * Loads the handoff configuration from the project root and returns metadata.
+ * Loads the handoff configuration for the given working directory and returns metadata.
  */
-const initConfigWithMetadata = (configOverride) => {
+const initConfigWithMetadata = (configOverride, context) => {
+    var _a;
     let config = {};
-    const { selected: configPath, ignored } = resolveConfigFilePath();
+    const { selected: configPath, ignored } = resolveConfigFilePath((_a = context === null || context === void 0 ? void 0 : context.workingPath) !== null && _a !== void 0 ? _a : (0, path_2.resolveWorkingPath)(), context === null || context === void 0 ? void 0 : context.configPath);
     if (ignored.length > 0 && configPath) {
         logger_1.Logger.warn(`Multiple config files found. Using "${path_1.default.basename(configPath)}" and ignoring: ${ignored
             .map((filePath) => `"${path_1.default.basename(filePath)}"`)
@@ -104,15 +132,17 @@ const initConfigWithMetadata = (configOverride) => {
 };
 exports.initConfigWithMetadata = initConfigWithMetadata;
 /**
- * Loads the handoff configuration from the project root.
+ * Loads the handoff configuration for the given working directory.
  *
- * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
- * Merges file config with any provided overrides, then applies defaults for missing values.
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json,
+ * unless `context.configPath` names one explicitly. Merges file config with any provided overrides,
+ * then applies defaults for missing values.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
+ * @param context - Optional working directory and explicit config file to load.
  * @returns The fully resolved Config object.
  */
-const initConfig = (configOverride) => {
-    return (0, exports.initConfigWithMetadata)(configOverride).config;
+const initConfig = (configOverride, context) => {
+    return (0, exports.initConfigWithMetadata)(configOverride, context).config;
 };
 exports.initConfig = initConfig;

package/dist/config/normalizers/page.d.ts

@@ -1,18 +1,18 @@
 import { PageListObject } from '../../transformers/preview/types';
 type RawPageFrontmatter = Record<string, any>;
 type NormalizePageOptions = {
-    /** The page id — its slug path (e.g. `guides/setup`), derived from the file location. */
+    /** The page id derived from its file location (`index` is reserved for the root home page). */
     id: string;
     /** Logical route the page is served at (e.g. `/guides/setup`). */
     routePath: string;
     /** Absolute filesystem path of the source `.md` (workspace-only, stripped on publish). */
-    sourcePath: string;
+    sourcePath?: string;
 };
 /**
  * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
  * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
- * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
- * location is the single source of identity for both filesystem and registry serving.
+ * segment. The file location is the source of identity for filesystem and registry serving. Normal
+ * page ids match their routes; the reserved `index` id is served at `/`.
  */
 export declare const normalizePageDeclaration: (raw: RawPageFrontmatter, options: NormalizePageOptions) => PageListObject;
 export {};

package/dist/config/normalizers/page.js

@@ -9,8 +9,8 @@ const humanize = (segment) => segment
 /**
  * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
  * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
- * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
- * location is the single source of identity for both filesystem and registry serving.
+ * segment. The file location is the source of identity for filesystem and registry serving. Normal
+ * page ids match their routes; the reserved `index` id is served at `/`.
  */
 const normalizePageDeclaration = (raw, options) => {
     var _a;

package/dist/config/runtime.js

@@ -6,12 +6,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.isComponentDirectory = exports.initRuntimeConfig = exports.resolveComponentDeclaration = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const gray_matter_1 = __importDefault(require("gray-matter"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
+const content_kinds_1 = require("../registry/content-kinds");
 const csf_1 = require("../transformers/utils/csf");
 const module_2 = require("../transformers/utils/module");
 const logger_1 = require("../utils/logger");
+const markdown_1 = require("../utils/markdown");
+const pages_1 = require("../utils/pages");
 const path_2 = require("../utils/path");
 const declaration_1 = require("./normalizers/declaration");
 const page_1 = require("./normalizers/page");
@@ -240,15 +242,16 @@ const initRuntimeConfig = (handoff) => {
     // Discover markdown pages
     // -------------------------------------------------------------------------
     // Working pages under `<workingPath>/pages/` are first-class registry entities (publish/checkout).
-    // Discovery mirrors the catch-all/static-path walk: every `.md` except `index.md` becomes a page
-    // keyed by its slug path. Package `config/docs` defaults are NOT entities (they ship with the tool).
+    // The root `index.md` uses the stable id `index` but is served at `/`; nested index files remain
+    // excluded because section indexes are owned by dedicated routes. Package defaults are not entities.
     const pagesRoot = path_1.default.resolve(handoff.workingPath, 'pages');
-    for (const segments of collectPageMarkdownPaths(pagesRoot)) {
+    for (const segments of (0, pages_1.collectPageSlugSegments)(pagesRoot, { includeRootIndex: true })) {
         const slug = segments.join('/');
         const sourcePath = path_1.default.resolve(pagesRoot, `${slug}.md`);
         try {
-            const { data: frontmatter } = (0, gray_matter_1.default)(fs_extra_1.default.readFileSync(sourcePath, 'utf-8'));
-            const page = (0, page_1.normalizePageDeclaration)(frontmatter, { id: slug, routePath: `/${slug}`, sourcePath });
+            const { data: frontmatter } = (0, markdown_1.parseMarkdown)(fs_extra_1.default.readFileSync(sourcePath, 'utf-8'));
+            const routePath = slug === content_kinds_1.HOME_PAGE_ID ? content_kinds_1.HOME_PAGE_PATH : `/${slug}`;
+            const page = (0, page_1.normalizePageDeclaration)(frontmatter, { id: slug, routePath, sourcePath });
             result.entries.pages[page.id] = page;
         }
         catch (err) {
@@ -263,25 +266,6 @@ const initRuntimeConfig = (handoff) => {
     return [result, Array.from(configFiles), configFileIndex];
 };
 exports.initRuntimeConfig = initRuntimeConfig;
-/**
- * Recursively collect `.md` files under a root, returning slug segments (relative path without the
- * `.md`). `index.md` is excluded — section index content is served by dedicated/home routes.
- */
-const collectPageMarkdownPaths = (rootDir, relativeParts = []) => {
-    if (!fs_extra_1.default.existsSync(rootDir))
-        return [];
-    const results = [];
-    for (const entry of fs_extra_1.default.readdirSync(rootDir)) {
-        const fullPath = path_1.default.join(rootDir, entry);
-        if (fs_extra_1.default.lstatSync(fullPath).isDirectory()) {
-            results.push(...collectPageMarkdownPaths(fullPath, [...relativeParts, entry]));
-        }
-        else if (entry.endsWith('.md') && entry !== 'index.md') {
-            results.push([...relativeParts, entry.replace(/\.md$/, '')]);
-        }
-    }
-    return results;
-};
 /**
  * True when `searchPath` is itself a single component directory: it holds a declaration file named
  * after the directory (`{dirname}.handoff.*`, or a legacy `{dirname}.{json,js,cjs}`). This is what