@byline/cli 3.21.0 → 4.0.0

package/dist/runner.js

@@ -57,7 +57,7 @@ function previewPlan(phase, plan, ctx) {
         ctx.logger.raw(`    • ${note}`);
     for (const w of plan.writes) {
         const before = w.before ?? readIfExists(w.path);
-        const label = before ? 'modify' : 'create';
+        const label = w.mode === 'delete' ? 'delete' : before ? 'modify' : 'create';
         ctx.logger.raw(`    ${label}  ${w.path}`);
         if (before !== w.contents) {
             ctx.logger.raw(renderDiff(w.path, before, w.contents));

package/dist/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}

package/dist/templates/byline/clients.server.ts

@@ -0,0 +1,77 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Typed, server-only access to this application's Byline clients.
+ *
+ * ```text
+ * generated/collection-types.ts
+ *   `CollectionFieldsByPath`
+ *              |
+ *              v
+ * collections/index.ts --------------------.
+ *   `BylineCollections`                    |
+ *                                          v
+ * @byline/host-tanstack-start ------> clients.server.ts
+ *   runtime client getters             |
+ *                                      v
+ *                           typed `get*BylineClient()` getters
+ * ```
+ *
+ * Why this boundary exists:
+ *
+ * The TanStack host owns the runtime admin, public, system, and viewer client
+ * singletons. It intentionally knows nothing about an application's collection
+ * schemas, so its getters cannot provide application-specific collection paths
+ * and field shapes. The generated `CollectionFieldsByPath` registry is exported
+ * as `BylineCollections` by `collections/index.ts`; this module joins the host
+ * getters and app registry once instead of repeating a type assertion at every
+ * server call site.
+ *
+ * Typical server usage:
+ *
+ * ```ts
+ * const publicClient = getPublicBylineClient() // anonymous published reads
+ * const viewerClient = getViewerBylineClient() // public or admin-preview reads
+ * const adminClient = getAdminBylineClient() // current admin request authority
+ * const systemClient = getSystemBylineClient() // trusted hooks and maintenance
+ * ```
+ *
+ * Calls to `client.collection('<collection-path>')` are therefore checked
+ * against this application's generated registry and return that collection's
+ * canonical generated field shape. `collection-types.contract.ts` separately
+ * proves that those generated shapes match the runtime schemas exactly.
+ *
+ * The `.server.ts` suffix is intentional. Import these getters only from server
+ * routes, loaders, actions, scripts, or lifecycle-hook modules; browser code
+ * must not cross this boundary.
+ *
+ * This module does not create client singletons, generate collection types, or
+ * configure the host. It only applies the app-specific client type and
+ * re-exports the host-owned getters (plus the viewer preview-state helper).
+ */
+import type { BylineClient } from '@byline/client'
+import {
+  getAdminBylineClient as getHostAdminBylineClient,
+  getSystemBylineClient as getHostSystemBylineClient,
+} from '@byline/host-tanstack-start/integrations/byline-client'
+import { getPublicBylineClient as getHostPublicBylineClient } from '@byline/host-tanstack-start/integrations/byline-public-client'
+import {
+  getViewerBylineClient as getHostViewerBylineClient,
+  isPreviewActive,
+} from '@byline/host-tanstack-start/integrations/byline-viewer-client'
+
+import type { BylineCollections } from './collections/index.js'
+
+type AppBylineClient = BylineClient<BylineCollections>
+
+export const getAdminBylineClient = getHostAdminBylineClient as () => AppBylineClient
+export const getPublicBylineClient = getHostPublicBylineClient as () => AppBylineClient
+export const getSystemBylineClient = getHostSystemBylineClient as () => AppBylineClient
+export const getViewerBylineClient = getHostViewerBylineClient as () => AppBylineClient
+export { isPreviewActive }

package/dist/templates/byline/collection-types.contract.ts

@@ -1,3 +1,28 @@
+/**
+ * Compile-time contract between this application's collection schemas and its
+ * generated collection-type projection.
+ *
+ * ```text
+ * collections/index.ts                  generated/collection-types.ts
+ *   `typeof collections`                 `CollectionFields*ByPath`
+ *            |                                      |
+ *            v                                      v
+ *    inferred registry ----------- Exact -------- generated registry
+ *                                    |
+ *                                    v
+ *                         TypeScript error on drift
+ * ```
+ *
+ * The generated file is deliberately a standalone projection for typed clients
+ * and frontend code; it does not import the runtime schemas. This module joins
+ * those two app-owned sources at compile time and requires their collection
+ * keys, ordinary field shapes, and all-locale field shapes to match exactly.
+ *
+ * This file has no runtime behavior. Keep it application-owned: `@byline/core`
+ * provides the inference and code-generation machinery, but only this
+ * application knows its concrete collection tuple and generated output.
+ */
+
 import type { CollectionFieldData, CollectionFieldDataAllLocales } from '@byline/core'
 
 import type { collections } from './collections/index.js'

package/dist/templates/byline/collections/server-hooks.ts

@@ -0,0 +1,7 @@
+/** Server-only lifecycle hook registry. Imported only by server.config.ts. */
+import type { ServerHooksConfig } from '@byline/core'
+
+export const serverHooks = {
+  collections: {},
+  uploads: {},
+} satisfies ServerHooksConfig

package/dist/templates/byline/routes.ts

@@ -7,17 +7,18 @@
  */
 
 /**
- * URL segments for admin and (future) public API routes. Defaults of
- * `/admin` and `/api` are applied automatically by `resolveRoutes()` —
- * keys only need to be set here when overriding either default.
+ * Client-safe URL paths for admin, sign-in, and the future public API.
+ * Resolve once at this client-safe configuration boundary so consumers only
+ * read canonical paths.
  */
 
-import type { RoutesConfig } from '@byline/core'
+import { resolveRoutes } from '@byline/core'
 
-export const routes: Partial<RoutesConfig> = {
+export const routes = resolveRoutes({
   admin: '/admin',
   api: '/api',
-}
+  signIn: '/sign-in',
+})
 
 /**
  * Fallback used by both server and admin entry points when no

package/dist/templates/byline/server.config.ts

@@ -29,8 +29,9 @@ import {
 } from '@byline/richtext-lexical/server'
 import { localStorageProvider } from '@byline/storage-local'
 
-import { getAdminBylineClient } from './client.server.js'
+import { getAdminBylineClient } from './clients.server.js'
 import { collections } from './collections/index.js'
+import { serverHooks } from './collections/server-hooks.js'
 import { i18n } from './i18n.js'
 import { DEFAULT_SERVER_URL, routes } from './routes.js'
 
@@ -91,6 +92,7 @@ async function buildBylineCore(): Promise<BylineCore<AdminStore>> {
     i18n,
     routes,
     collections,
+    hooks: serverHooks,
     db,
     adminStore,
     // Local filesystem — suitable for development and self-hosted

package/dist/templates/byline-examples/admin.config.ts

@@ -14,8 +14,8 @@
  * `route.lazy.tsx` covers component render and initial hydration. Keeping
  * both imports behind `_byline/*` keeps the admin graph off public routes.
  *
- * In TanStack Start with Vite 6 the server entry (`src/server.ts`) and
- * the SSR rendering context run in separate Vite environments, so
+ * In TanStack Start the server entry (`src/server.ts`) and the SSR rendering
+ * context run in separate Vite environments, so
  * importing this file from `src/server.ts` would NOT propagate the
  * registration into the SSR render module graph.
  */
@@ -29,8 +29,8 @@ import { RichTextField as LexicalRichTextField } from '@byline/richtext-lexical'
 // commented `richText` block below for the exact shape.
 // import { lexicalEditor } from '@byline/richtext-lexical'
 
-import { collections } from './collections/index.js'
 import { DocsAdmin } from './collections/docs/admin.js'
+import { collections } from './collections/index.js'
 import { MediaAdmin } from './collections/media/admin.js'
 import { NewsAdmin } from './collections/news/admin.js'
 import { NewsCategoriesAdmin } from './collections/news-categories/admin.js'
@@ -60,19 +60,14 @@ export const config: ClientConfig = {
     // mutations are local to this call. Per-field `editorConfig`
     // continues to take precedence over whatever is baked in here.
     //
-    // import {
-    //   lexicalEditor,
-    //   AdmonitionExtension,
-    //   CodeHighlightExtension,
-    //   TableExtension,
-    // } from '@byline/richtext-lexical'
+    // import { builtInExtensions, lexicalEditor } from '@byline/richtext-lexical/config'
     //
     // richText: {
     //   editor: lexicalEditor((c) => {
     //     c.extensions
-    //       .remove(TableExtension)
-    //       .remove(CodeHighlightExtension)
-    //       .remove(AdmonitionExtension)
+    //       .remove(builtInExtensions.Table)
+    //       .remove(builtInExtensions.CodeHighlight)
+    //       .remove(builtInExtensions.Admonition)
     //     c.settings.placeholderText = 'Start writing...'
     //     return c
     //   }),

package/dist/templates/byline-examples/blocks/photo-block.ts

@@ -53,7 +53,8 @@ export type PhotoBlockFields = BlockFieldData<typeof PhotoBlock>
 
 /**
  * Full block instance shape (`_id`, `_type` + fields) as it appears
- * inside a document tree. Use this as the prop type for the photo
- * block renderer.
+ * inside a document tree. This alias is useful for schema-local helpers;
+ * app-facing renderers should import `PhotoBlockData` from
+ * `byline/generated/collection-types.ts` and overlay populated relations.
  */
 export type PhotoBlockData = BlockData<typeof PhotoBlock>

package/dist/templates/byline-examples/clients.server.ts

@@ -0,0 +1,77 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Typed, server-only access to this application's Byline clients.
+ *
+ * ```text
+ * generated/collection-types.ts
+ *   `CollectionFieldsByPath`
+ *              |
+ *              v
+ * collections/index.ts --------------------.
+ *   `BylineCollections`                    |
+ *                                          v
+ * @byline/host-tanstack-start ------> clients.server.ts
+ *   runtime client getters             |
+ *                                      v
+ *                           typed `get*BylineClient()` getters
+ * ```
+ *
+ * Why this boundary exists:
+ *
+ * The TanStack host owns the runtime admin, public, system, and viewer client
+ * singletons. It intentionally knows nothing about an application's collection
+ * schemas, so its getters cannot provide application-specific collection paths
+ * and field shapes. The generated `CollectionFieldsByPath` registry is exported
+ * as `BylineCollections` by `collections/index.ts`; this module joins the host
+ * getters and app registry once instead of repeating a type assertion at every
+ * server call site.
+ *
+ * Typical server usage:
+ *
+ * ```ts
+ * const publicClient = getPublicBylineClient() // anonymous published reads
+ * const viewerClient = getViewerBylineClient() // public or admin-preview reads
+ * const adminClient = getAdminBylineClient() // current admin request authority
+ * const systemClient = getSystemBylineClient() // trusted hooks and maintenance
+ * ```
+ *
+ * Calls such as `systemClient.collection('docs')` are therefore checked against
+ * this application's generated registry and return the canonical generated
+ * field shape for `docs`. `collection-types.contract.ts` separately proves that
+ * those generated shapes still match the runtime collection schemas exactly.
+ *
+ * The `.server.ts` suffix is intentional. Import these getters only from server
+ * routes, loaders, actions, scripts, or lifecycle-hook modules; browser code
+ * must not cross this boundary.
+ *
+ * This module does not create client singletons, generate collection types, or
+ * configure the host. It only applies the app-specific client type and
+ * re-exports the host-owned getters (plus the viewer preview-state helper).
+ */
+import type { BylineClient } from '@byline/client'
+import {
+  getAdminBylineClient as getHostAdminBylineClient,
+  getSystemBylineClient as getHostSystemBylineClient,
+} from '@byline/host-tanstack-start/integrations/byline-client'
+import { getPublicBylineClient as getHostPublicBylineClient } from '@byline/host-tanstack-start/integrations/byline-public-client'
+import {
+  getViewerBylineClient as getHostViewerBylineClient,
+  isPreviewActive,
+} from '@byline/host-tanstack-start/integrations/byline-viewer-client'
+
+import type { BylineCollections } from './collections/index.js'
+
+type AppBylineClient = BylineClient<BylineCollections>
+
+export const getAdminBylineClient = getHostAdminBylineClient as () => AppBylineClient
+export const getPublicBylineClient = getHostPublicBylineClient as () => AppBylineClient
+export const getSystemBylineClient = getHostSystemBylineClient as () => AppBylineClient
+export const getViewerBylineClient = getHostViewerBylineClient as () => AppBylineClient
+export { isPreviewActive }

package/dist/templates/byline-examples/collection-types.contract.ts

@@ -1,3 +1,28 @@
+/**
+ * Compile-time contract between this application's collection schemas and its
+ * generated collection-type projection.
+ *
+ * ```text
+ * collections/index.ts                  generated/collection-types.ts
+ *   `typeof collections`                 `CollectionFields*ByPath`
+ *            |                                      |
+ *            v                                      v
+ *    inferred registry ----------- Exact -------- generated registry
+ *                                    |
+ *                                    v
+ *                         TypeScript error on drift
+ * ```
+ *
+ * The generated file is deliberately a standalone projection for typed clients
+ * and frontend code; it does not import the runtime schemas. This module joins
+ * those two app-owned sources at compile time and requires their collection
+ * keys, ordinary field shapes, and all-locale field shapes to match exactly.
+ *
+ * This file has no runtime behavior. Keep it application-owned: `@byline/core`
+ * provides the inference and code-generation machinery, but only this
+ * application knows its concrete collection tuple and generated output.
+ */
+
 import type { CollectionFieldData, CollectionFieldDataAllLocales } from '@byline/core'
 
 import type { collections } from './collections/index.js'

package/dist/templates/byline-examples/collections/docs/hooks.ts

@@ -18,21 +18,19 @@
  * the client. Hook *bodies*, however, only ever run server-side.
  *
  * Search indexing is the canonical reason this matters: it imports the
- * server-only app client boundary from `byline/client.server.ts`. Importing
+ * server-only app client boundary from `byline/clients.server.ts`. Importing
  * that from the schema would drag server code into the browser bundle (fatal
- * in dev). The schema avoids it by referencing these hooks through a
- * **dynamic import** instead of an inline object:
+ * in dev). The server bootstrap avoids it by registering these hooks from a
+ * server-only module:
  *
- *     // schema.ts
- *     hooks: () => import('./hooks.js')
+ *     // collections/server-hooks.ts
+ *     collections: { docs: () => import('./docs/hooks.js') }
  *
- * Because the schema reaches this module only through `import()`, this file —
- * and its entire transitive import graph — is **structurally absent** from
- * the client bundle. `@byline/core` resolves the loader once on the server
- * (memoized) and calls these hooks exactly as it would inline ones. The
- * upshot: **inside this file we may statically import server-only modules
- * directly.** See docs/04-collections → "Hooks must not statically import
- * server-only code".
+ * No client entry reaches that registry, so this file and its transitive graph
+ * are structurally absent from the client bundle without a host-framework
+ * transform. `@byline/core` attaches and resolves the loader on the server.
+ * The upshot: **inside this file we may statically import server-only modules
+ * directly.** See docs/04-collections → "Server-only hook registry".
  *
  * ──────────────────────────────────────────────────────────────────────────
  *  Search indexing
@@ -52,7 +50,7 @@
  */
 
 import { defineHooks } from '@byline/core'
-import { getSystemBylineClient } from '../../client.server.js'
+import { getSystemBylineClient } from '../../clients.server.js'
 
 export default defineHooks({
   beforeCreate: async ({ data, collectionPath }) => {
@@ -73,6 +71,18 @@ export default defineHooks({
     )
     await getSystemBylineClient().collection('docs').indexDocument(documentId)
   },
+  // Path and advertised-locale edits are immediate document-grain writes, not
+  // content updates. Re-index their published view through this dedicated event.
+  afterSystemFieldsChange: async ({ documentId, collectionPath, requested, changed }) => {
+    console.log(
+      `afterSystemFieldsChange: ${documentId} in '${collectionPath}' changed`,
+      changed
+    )
+    // Advertised locales affect alternates/sitemaps, not indexed content.
+    if (requested.path) {
+      await getSystemBylineClient().collection('docs').indexDocument(documentId)
+    }
+  },
   beforeStatusChange: async ({ documentId, collectionPath, previousStatus, nextStatus }) => {
     console.log(
       `beforeStatusChange: ${documentId} in '${collectionPath}' ${previousStatus} → ${nextStatus}`

package/dist/templates/byline-examples/collections/docs/schema.ts

@@ -65,17 +65,8 @@ export const Docs = defineCollection({
   useAsPath: 'title',
   advertiseLocales: true, // Renders the available-locales sidebar widget.
   linksInEditor: true, // See type definition for details.
-  // Collection lifecycle hooks. Hook *bodies* only ever run server-side, but
-  // a collection *schema* is isomorphic — Byline bundles it into the browser
-  // admin too (the admin reads field config from it), so anything the schema
-  // *statically imports* ships to the client. Search indexing needs a
-  // server-only import from the app's `client.server.ts` boundary, which would
-  // crash the browser bundle if imported here. The **loader form** — a thunk
-  // that dynamically imports a sibling module — keeps `./hooks.ts` and its
-  // entire import graph out of the client bundle while running exactly like
-  // inline hooks on the server.
-  // See ./hooks.ts for the worked example and the full explanation.
-  hooks: () => import('./hooks.js'),
+  // Server-only lifecycle hooks are registered in ../server-hooks.ts so this
+  // schema remains portable across host frameworks and safe in client graphs.
   fields: [
     {
       name: 'title',

package/dist/templates/byline-examples/collections/media/components/media-list-view.tsx

@@ -19,11 +19,16 @@
  *  - Top + bottom pagination (RouterPager)
  */
 
-import { Link, useNavigate, useRouterState } from '@tanstack/react-router'
+import { useRouterState } from '@tanstack/react-router'
 
 import type { ListViewComponentProps, StoredFileValue, WorkflowStatus } from '@byline/core'
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import { RouterPager } from '@byline/host-tanstack-start/admin-shell/chrome/router-pager'
+import {
+  Link,
+  useNavigate,
+} from '@byline/host-tanstack-start/admin-shell/chrome/loose-router'
+import { getAdminRoutePath } from '@byline/host-tanstack-start/routes/admin-path'
 import { Container, IconButton, LoaderRing, PlusIcon, Search, Section, Select } from '@byline/ui/react'
 import { LocalDateTime } from '@byline/admin/react'
 
@@ -128,7 +133,7 @@ export function MediaListView({
       delete params.page
       params.query = query
       navigate({
-        to: '/admin/collections/$collection',
+        to: getAdminRoutePath('collections', '$collection'),
         params: { collection: collectionPath },
         search: params,
       })
@@ -140,7 +145,7 @@ export function MediaListView({
     delete params.page
     delete params.query
     navigate({
-      to: '/admin/collections/$collection',
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: collectionPath },
       search: params,
     })
@@ -158,7 +163,7 @@ export function MediaListView({
     params.order = order
     params.desc = desc
     navigate({
-      to: '/admin/collections/$collection',
+      to: getAdminRoutePath('collections', '$collection'),
       params: { collection: collectionPath },
       search: params,
     })
@@ -178,7 +183,7 @@ export function MediaListView({
             render={
               <Link
                 className={styles['create-link']}
-                to="/admin/collections/$collection/create"
+                to={getAdminRoutePath('collections', '$collection', 'create')}
                 params={{ collection: collectionPath }}
               />
             }
@@ -239,7 +244,7 @@ export function MediaListView({
               return (
                 <Link
                   key={doc.id}
-                  to="/admin/collections/$collection/$id"
+                  to={getAdminRoutePath('collections', '$collection', '$id')}
                   params={{ collection: collectionPath, id: doc.id }}
                   className={styles.card}
                 >

package/dist/templates/byline-examples/collections/media/schema.ts

@@ -128,6 +128,9 @@ export const Media = defineCollection({
             quality: 55,
           },
         ],
+        // Worked example: definition-attached inline hooks are appropriate
+        // when their entire implementation is isomorphic-safe. Hooks that
+        // import server-only code belong in collections/server-hooks.ts.
         hooks: {
           beforeStore: (ctx: BeforeStoreContext) => {
             console.log('beforeStore hook called', ctx)

package/dist/templates/byline-examples/collections/news/schema.ts

@@ -99,8 +99,9 @@ export const News = defineCollection({
 })
 
 /**
- * Field data shape inferred directly from the schema. Use this as the
- * generic to typed read calls — `client.collection('news').find<NewsFields>()`
- * — so dot-notation on `doc.fields` is fully checked.
+ * Schema-local field shape for hooks and other collection implementation details.
+ * Frontend/client code should import `NewsFields` from
+ * `byline/generated/collection-types.ts`; ordinary reads infer it from the
+ * client registry, while populate/select projections may supply an overlay.
  */
 export type NewsFields = CollectionFieldData<typeof News>

package/dist/templates/byline-examples/collections/server-hooks.ts

@@ -0,0 +1,8 @@
+/** Server-only lifecycle hook registry. Imported only by server.config.ts. */
+import type { ServerHooksConfig } from '@byline/core'
+
+export const serverHooks = {
+  collections: {
+    docs: () => import('./docs/hooks.js'),
+  },
+} satisfies ServerHooksConfig

package/dist/templates/byline-examples/fields/ai-text.ts

@@ -27,7 +27,7 @@ import { AiFieldPanel } from './ai-widgets/ai-field-panel.js'
  *
  * @example
  * ```ts
- * // apps/webapp/byline/collections/news/admin.tsx
+ * // byline/collections/news/admin.tsx
  * fields: {
  *   title: aiTextFieldAdmin(),
  * }

package/dist/templates/byline-examples/fields/ai-textarea.ts

@@ -28,7 +28,7 @@ import { AiFieldPanel } from './ai-widgets/ai-field-panel.js'
  *
  * @example
  * ```ts
- * // apps/webapp/byline/collections/news/admin.tsx
+ * // byline/collections/news/admin.tsx
  * fields: {
  *   summary: aiTextAreaFieldAdmin({
  *     components: { HelpText: SummaryLength },

package/dist/templates/byline-examples/fields/lexical-richtext-ai.tsx

@@ -13,7 +13,7 @@
  *   - `LexicalRichTextAi` — a `RichTextEditorComponent` that registers
  *     the AI assistant by adding `AiLexicalExtension` to the editor's
  *     extension graph. Register globally in
- *     `apps/webapp/byline/admin.config.ts` under
+ *     `byline/admin.config.ts` under
  *     `fields.richText.editor` to AI-enable every richtext field.
  *   - `aiRichTextAdmin()` — a `FieldAdminConfig` factory. Drop into a
  *     collection's `fields` map in `<collection>/admin.tsx` to opt one
@@ -38,7 +38,7 @@ import { builtInExtensions, lexicalEditor } from '@byline/richtext-lexical/confi
  * drawer via `ReactExtension.decorators` — no `featureAfterEditor`, no
  * React-context registry hop.
  *
- * **Global** opt-in — register in `apps/webapp/byline/admin.config.ts`:
+ * **Global** opt-in — register in `byline/admin.config.ts`:
  *
  * ```ts
  * fields: {
@@ -77,7 +77,7 @@ export const LexicalRichTextAi = lexicalEditor((c) => {
  *
  * @example
  * ```ts
- * // apps/webapp/byline/collections/news/admin.tsx
+ * // byline/collections/news/admin.tsx
  * import { aiRichTextAdmin } from '../../fields/lexical-richtext-ai.js'
  *
  * fields: {

package/dist/templates/byline-examples/routes.ts

@@ -7,17 +7,18 @@
  */
 
 /**
- * URL segments for admin and (future) public API routes. Defaults of
- * `/admin` and `/api` are applied automatically by `resolveRoutes()` —
- * keys only need to be set here when overriding either default.
+ * Client-safe URL paths for admin, sign-in, and the future public API.
+ * Resolve once at this client-safe configuration boundary so consumers only
+ * read canonical paths.
  */
 
-import type { RoutesConfig } from '@byline/core'
+import { resolveRoutes } from '@byline/core'
 
-export const routes: Partial<RoutesConfig> = {
+export const routes = resolveRoutes({
   admin: '/admin',
   api: '/api',
-}
+  signIn: '/sign-in',
+})
 
 /**
  * Fallback used by both server and admin entry points when no

package/dist/templates/byline-examples/scripts/backfill-version-locales.ts

@@ -16,7 +16,7 @@
  * Idempotent — safe to re-run. Uses the installation's configured default
  * content locale (resolved from byline/i18n.ts via the server config).
  *
- *   cd apps/webapp && pnpm tsx byline/scripts/backfill-version-locales.ts
+ *   pnpm tsx byline/scripts/backfill-version-locales.ts
  *
  * See docs/07-internationalization/index.md.
  */