@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.1

package/artifact/implicitRootLayout.ts

@@ -2,6 +2,7 @@ import { readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 import { AsyncDefaultExportDetector } from "../transforms/asyncDefaultExportDetector";
+import { StoreBootstrap } from "./storeBootstrap";
 
 export interface PageEntry {
   key: string;
@@ -148,7 +149,7 @@ async function writeGeneratedRootLayoutFile(opts: {
   appName: string;
   boundary: RootBoundary;
   rootSourceAbsPath: string | null;
-  includeStInit: boolean;
+  includeStoreBootstrap: boolean;
   includeSystemProvider: boolean;
 }): Promise<string> {
   await assertEnvClientConvention(opts.appCwdPath, opts.appName);
@@ -161,9 +162,7 @@ async function writeGeneratedRootLayoutFile(opts: {
   const inheritedSourceAbsPath =
     opts.rootSourceAbsPath && opts.rootSourceAbsPath !== opts.boundary.sourceAbsPath ? opts.rootSourceAbsPath : null;
   const inheritedSourceSpecifier = inheritedSourceAbsPath ? importSpecifier(absPath, inheritedSourceAbsPath) : null;
-  const clientImport = opts.includeStInit
-    ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
-    : `import "@apps/${opts.appName}/client";\n`;
+  const storeImport = opts.includeStoreBootstrap ? StoreBootstrap.source(opts.appName) : "";
   //? resolveRouteModule reads a rootLayout() chain and the legacy named exports alike.
   const inheritedLabel = inheritedSourceAbsPath ? posixRelative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
@@ -223,7 +222,7 @@ import { System } from "akanjs/ui/System/index.tsx";
 import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
-${clientImport}${inheritedImport}${userImport}
+${storeImport}${inheritedImport}${userImport}
 const userFonts = userLayout.fonts ?? inheritedLayout.fonts ?? [];
 const defaultFonts = userFonts.filter((font) => font.default);
 if (defaultFonts.length > 1) throw new Error("[route-convention] only one default font is allowed per root layout");
@@ -323,7 +322,7 @@ export async function resolveSsrPageEntries(opts: {
         appName: opts.appName,
         boundary,
         rootSourceAbsPath,
-        includeStInit: hasSt && boundary.segments.length === 0,
+        includeStoreBootstrap: hasSt,
         includeSystemProvider: !hasAncestorRootBoundary(boundary, rootBoundaries),
       }),
       seedAbsPaths: [...new Set([boundary.sourceAbsPath, rootSourceAbsPath].filter((absPath) => absPath !== null))],

package/artifact/storeBootstrap.ts

@@ -0,0 +1,24 @@
+import type { BarrelExportMap } from "../transforms/barrelAnalyzer";
+
+//* Not a bare `@apps/<app>/client` import: it names nothing the barrel rewrite can narrow, so every module's UI ships.
+export class StoreBootstrap {
+  static importLines(appName: string): string[] {
+    return StoreBootstrap.#lines([`@apps/${appName}/lib/useClient`, `@apps/${appName}/lib/st`]);
+  }
+
+  static source(appName: string): string {
+    return `${StoreBootstrap.importLines(appName).join("\n")}\n`;
+  }
+
+  static ofClientBarrel(specifier: string, exports: BarrelExportMap): string[] | null {
+    if (!/^@(?:apps|libs)\/[^/]+\/client$/.test(specifier)) return null;
+    const runtime = exports.get("usePage");
+    const store = exports.get("st");
+    if (!runtime || runtime.namespace || !store || store.namespace) return StoreBootstrap.#lines([specifier]);
+    return StoreBootstrap.#lines([...new Set([runtime.subpath, store.subpath])]);
+  }
+
+  static #lines(specifiers: string[]): string[] {
+    return specifiers.map((specifier) => `import ${JSON.stringify(specifier)};`);
+  }
+}

package/cloud/cloudApi.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { readFile, rm } from "node:fs/promises";
 import path from "node:path";
+import dayjs from "dayjs";
 import type { Workspace } from "../commandDecorators";
 import { tempDirs, writeJson, writeText } from "../testHelpers";
 import { CloudApi } from "./cloudApi";
@@ -9,8 +10,10 @@ import { CloudApi } from "./cloudApi";
 class FakeCloud {
   readonly server: ReturnType<typeof Bun.serve>;
   readonly refreshes: string[] = [];
+  readonly refreshBearers: (string | null)[] = [];
   reused = false;
   delayMs = 0;
+  lifetimeMs = 7 * 86_400_000;
   hang: boolean = false;
   readonly remoteAuthPolls: string[] = [];
   remoteAuthAnswers: (Response | { jwt: string; refreshToken?: string } | null)[] = [];
@@ -44,6 +47,7 @@ class FakeCloud {
     if (url.pathname !== "/api/refreshAuthToken") return new Response("not found", { status: 404 });
     const { refreshToken } = (await request.json()) as { refreshToken: string };
     this.refreshes.push(refreshToken);
+    this.refreshBearers.push(request.headers.get("authorization"));
     if (this.#spent.has(refreshToken)) this.reused = true;
     if (!this.#refreshTokens.delete(refreshToken)) return Response.json({ error: "invalid" }, { status: 401 });
     this.#spent.add(refreshToken);
@@ -53,7 +57,7 @@ class FakeCloud {
     this.#jwts.add(next.jwt);
     if (this.hang) await new Promise(() => undefined);
     await Bun.sleep(this.delayMs);
-    return Response.json({ ...next, expiresAt: new Date(Date.now() + 7 * 86_400_000).toISOString() });
+    return Response.json({ ...next, expiresAt: new Date(Date.now() + this.lifetimeMs).toISOString() });
   }
 }
 
@@ -100,13 +104,21 @@ await GlobalConfig.setTestTargets({ linux: { cpus: 2 } });
   return { code: await proc.exited, stderr: await new Response(proc.stderr).text() };
 };
 
-const storeSession = async (home: string, { expiresInMs = 30 * 60_000, refreshToken = "refresh-0" } = {}) =>
+const storeSession = async (
+  home: string,
+  { expiresInMs = 30 * 60_000, refreshToken = "refresh-0", issuedAgoMs = null as number | null } = {},
+) =>
   await writeJson(path.join(home, ".akan", "config.json"), {
     cloudHost: {
       [cloud.host]: {
         host: cloud.host,
         auth: {
-          accessToken: { jwt: "jwt-0", refreshToken, expiresAt: new Date(Date.now() + expiresInMs).toISOString() },
+          accessToken: {
+            jwt: "jwt-0",
+            refreshToken,
+            expiresAt: new Date(Date.now() + expiresInMs).toISOString(),
+            issuedAt: issuedAgoMs === null ? null : new Date(Date.now() - issuedAgoMs).toISOString(),
+          },
           self: { id: "u1", nickname: "akan" },
         },
       },
@@ -114,9 +126,34 @@ const storeSession = async (home: string, { expiresInMs = 30 * 60_000, refreshTo
   });
 const storedToken = async (home: string) => {
   const config = JSON.parse(await readFile(path.join(home, ".akan", "config.json"), "utf8"));
-  return config.cloudHost[cloud.host].auth.accessToken as { jwt: string; refreshToken: string | null };
+  return config.cloudHost[cloud.host].auth.accessToken as {
+    jwt: string;
+    refreshToken: string | null;
+    issuedAt?: string | null;
+  };
 };
 
+describe("CloudApi.needsSignIn", () => {
+  const apiWith = (accessToken: { refreshToken: string | null; expiresInMs: number }) =>
+    new CloudApi({ workspaceRoot: "/nowhere" } as unknown as Workspace, {
+      host: cloud.host,
+      auth: {
+        accessToken: {
+          jwt: "jwt-0",
+          refreshToken: accessToken.refreshToken,
+          expiresAt: dayjs().add(accessToken.expiresInMs, "ms"),
+        },
+      },
+    });
+
+  test("asks for a sign-in only when a session due for refresh has no refresh token left", () => {
+    cloud = new FakeCloud();
+    expect(apiWith({ refreshToken: null, expiresInMs: 30 * 60_000 }).needsSignIn).toBe(true);
+    expect(apiWith({ refreshToken: "refresh-0", expiresInMs: 30 * 60_000 }).needsSignIn).toBe(false);
+    expect(apiWith({ refreshToken: null, expiresInMs: 3 * 3_600_000 }).needsSignIn).toBe(false);
+  });
+});
+
 describe("CloudApi.fromHost token refresh", () => {
   test("two CLI processes with a session in its last hour make exactly one refresh, and both use its result", async () => {
     cloud = new FakeCloud();
@@ -165,20 +202,46 @@ describe("CloudApi.fromHost token refresh", () => {
     cloud.hang = false;
 
     const started = Date.now();
-    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
     expect(Date.now() - started).toBeLessThan(10_000);
     expect(cloud.refreshes).toEqual(["refresh-0"]);
     expect(cloud.reused).toBe(false);
     expect((await storedToken(home)).refreshToken).toBeNull();
   }, 30_000);
 
+  test("a cloud that issues one-hour tokens is refreshed once, and every command signs in with its token", async () => {
+    cloud = new FakeCloud();
+    cloud.lifetimeMs = 60 * 60_000;
+    const home = await makeHome();
+    await storeSession(home);
+
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+    expect(cloud.refreshBearers).toEqual([null]);
+    expect(await storedToken(home)).toMatchObject({ jwt: "jwt-1", refreshToken: "refresh-1" });
+    expect((await storedToken(home)).issuedAt).toBeString();
+  }, 30_000);
+
+  test("a one-hour token in the second half of its life is refreshed, and one in the first half is not", async () => {
+    cloud = new FakeCloud();
+    const home = await makeHome();
+    await storeSession(home, { expiresInMs: 35 * 60_000, issuedAgoMs: 25 * 60_000 });
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual([]);
+
+    await storeSession(home, { expiresInMs: 25 * 60_000, issuedAgoMs: 35 * 60_000 });
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(cloud.refreshes).toEqual(["refresh-0"]);
+  }, 30_000);
+
   test("a refresh the cloud refuses is not presented again", async () => {
     cloud = new FakeCloud();
     const home = await makeHome();
     await storeSession(home, { refreshToken: "refresh-unknown" });
 
-    expect(await output(await cliRun(home))).toEqual([null]);
-    expect(await output(await cliRun(home))).toEqual([null]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
+    expect(await output(await cliRun(home))).toEqual(["akan"]);
     expect(cloud.refreshes).toEqual(["refresh-unknown"]);
     expect((await storedToken(home)).refreshToken).toBeNull();
   }, 30_000);

package/cloud/cloudApi.ts

@@ -144,9 +144,9 @@ export class CloudApi {
   static async fromHost(workspace: Workspace, host?: string) {
     const hostConfig = await GlobalConfig.getHostConfig(host);
     const accessToken = hostConfig.auth?.accessToken;
-    // No refresh token on a session in its last hour can be another process's refresh in flight: wait on its lock.
+    // No refresh token on a session due for refresh can be another process's refresh in flight: wait on its lock.
     if (!accessToken || !GlobalConfig.needRefreshToken(accessToken)) return new CloudApi(workspace, hostConfig);
-    const tokenless = new CloudApi(workspace, hostConfig);
+    const tokenless = new CloudApi(workspace, { host: hostConfig.host });
     const refreshed = await GlobalConfig.refreshHostAuth(hostConfig.host, (refreshToken) =>
       tokenless.refreshAuthToken(refreshToken),
     );
@@ -158,12 +158,18 @@ export class CloudApi {
     this.host = hostConfig.host;
     this.url = `${this.host}/api`;
     this.#api = new HttpClient(this.url);
-    if (this.#accessToken && !GlobalConfig.needRefreshToken(this.#accessToken))
+    if (this.#accessToken && !GlobalConfig.isExpired(this.#accessToken))
       this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
   }
 
+  //? With no refresh token left, a session due for refresh ends at its expiry and only a new sign-in renews it.
+  get needsSignIn(): boolean {
+    const accessToken = this.#accessToken;
+    return !!accessToken && !accessToken.refreshToken && GlobalConfig.needRefreshToken(accessToken);
+  }
+
   #authorize(accessTokenDto: AccessTokenDto) {
-    this.#accessToken = GlobalConfig.toAccessToken(accessTokenDto);
+    this.#accessToken = GlobalConfig.toAccessToken({ ...accessTokenDto, issuedAt: new Date().toISOString() });
     this.#api.setHeaders({ Authorization: `Bearer ${this.#accessToken.jwt}` });
     return this.#accessToken;
   }

package/cloud/constants.ts

@@ -61,9 +61,12 @@ export interface AccessTokenDto {
   jwt: string;
   refreshToken: string | null;
   expiresAt: string | null;
+  issuedAt?: string | null;
 }
 export interface AccessToken {
   jwt: string;
   refreshToken: string | null;
   expiresAt: Dayjs | null;
+  //? When this CLI received the token, on its own clock: the cloud's answer names only the expiry.
+  issuedAt?: Dayjs | null;
 }

package/cloud/globalConfig.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { mkdir, stat } from "node:fs/promises";
 import path from "node:path";
+import dayjs from "dayjs";
 import { tempDirs } from "../testHelpers";
 import { GlobalConfig } from "./globalConfig";
 
@@ -22,6 +23,41 @@ const modeOf = async (target: string) => (await stat(target)).mode & 0o777;
 const workspace = (cloudHost: string | null) => ({ getConfig: async () => ({ cloudHost }) });
 
 describe("GlobalConfig", () => {
+  test("needRefreshToken asks for a refresh in a token's last hour, or in the second half of a shorter life", () => {
+    const token = (issuedAgoMin: number | null, expiresInMin: number) => ({
+      jwt: "jwt",
+      refreshToken: "refresh",
+      expiresAt: dayjs().add(expiresInMin, "minute"),
+      issuedAt: issuedAgoMin === null ? null : dayjs().subtract(issuedAgoMin, "minute"),
+    });
+    const week = 7 * 24 * 60;
+    expect(GlobalConfig.needRefreshToken(token(0, 60))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(25, 35))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(35, 25))).toBe(true);
+    expect(GlobalConfig.needRefreshToken(token(0, 10))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(week - 61, 61))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(week - 59, 59))).toBe(true);
+    expect(GlobalConfig.needRefreshToken(token(null, 61))).toBe(false);
+    expect(GlobalConfig.needRefreshToken(token(null, 59))).toBe(true);
+    expect(GlobalConfig.isExpired(token(59, 1))).toBe(false);
+    expect(GlobalConfig.isExpired(token(61, -1))).toBe(true);
+    expect(GlobalConfig.needRefreshToken({ ...token(0, 59), issuedAt: dayjs("not a date") })).toBe(true);
+  });
+
+  test("keeps a token's issuedAt through config.json, and leaves the key out when there is none", () => {
+    const issuedAt = dayjs().subtract(10, "minute");
+    const token = { jwt: "jwt", refreshToken: "refresh", expiresAt: dayjs().add(50, "minute"), issuedAt };
+    const read = GlobalConfig.toAccessToken(
+      JSON.parse(JSON.stringify(GlobalConfig.toAccessTokenDto(token))) as ReturnType<
+        typeof GlobalConfig.toAccessTokenDto
+      >,
+    );
+    expect(Math.abs(read.issuedAt?.diff(issuedAt) ?? Number.NaN)).toBeLessThan(1_000);
+    expect(GlobalConfig.needRefreshToken(read)).toBe(false);
+    const legacy = { jwt: "jwt", refreshToken: "refresh", expiresAt: null };
+    expect(GlobalConfig.toAccessTokenDto(GlobalConfig.toAccessToken(legacy))).toEqual(legacy);
+  });
+
   test("hostFor spells --host the way the workspace's cloud.host is spelled, so one login serves both", async () => {
     for (const given of ["https://cloud.example.com/", "https://Cloud.Example.com:443", "https://cloud.example.com//"])
       expect(await GlobalConfig.hostFor(workspace(null), given)).toBe("https://cloud.example.com");

package/cloud/globalConfig.ts

@@ -129,14 +129,22 @@ export class GlobalConfig {
       testTargets: { ...akanConfig.testTargets, ...testTargets },
     }));
   }
+  static readonly #refreshMarginMs = 60 * 60_000;
   static needRefreshToken(accessToken: AccessToken): boolean {
-    return !!accessToken?.expiresAt?.isBefore(dayjs().add(1, "hour"));
+    const { expiresAt, issuedAt } = accessToken;
+    if (!expiresAt) return false;
+    const lifetimeMs = issuedAt?.isValid() ? expiresAt.diff(issuedAt) : Number.POSITIVE_INFINITY;
+    return expiresAt.isBefore(dayjs().add(Math.min(GlobalConfig.#refreshMarginMs, lifetimeMs / 2), "ms"));
+  }
+  static isExpired(accessToken: AccessToken): boolean {
+    return !!accessToken.expiresAt && !accessToken.expiresAt.isAfter(dayjs());
   }
   static toAccessToken(accessToken: AccessTokenDto): AccessToken {
     return {
       jwt: accessToken.jwt,
       refreshToken: accessToken.refreshToken ?? null,
       expiresAt: accessToken.expiresAt ? dayjs(accessToken.expiresAt) : null,
+      ...(accessToken.issuedAt ? { issuedAt: dayjs(accessToken.issuedAt) } : {}),
     };
   }
   static toAccessTokenDto(accessToken: AccessToken): AccessTokenDto {
@@ -144,6 +152,7 @@ export class GlobalConfig {
       jwt: accessToken.jwt,
       refreshToken: accessToken.refreshToken ?? null,
       expiresAt: accessToken.expiresAt?.toString() ?? null,
+      ...(accessToken.issuedAt ? { issuedAt: accessToken.issuedAt.toString() } : {}),
     };
   }
   static toHostConfigDto(hostConfig: HostConfig): HostConfigDto {

package/codeAgent/skills/akan-debug/SKILL.md

@@ -15,7 +15,8 @@ the server errors logged meanwhile, console errors and warnings, and layout smel
   stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
   running one.
 - Paths are comma-separated (`akan preview <app> /board,/board/new`) and get the default locale when they lack
-  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off.
+  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off. A `/_akan` route such as Studio
+  (`/_akan/studio?view=runtime`), a signal route or a file opens as written.
   `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
   path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
 - The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native

package/codeAgent/skills/akan-page/SKILL.md

@@ -8,6 +8,11 @@ description: "Add or change a route under page/: the one page()/layout() chain,
 A route file exports one chain and nothing else. Every setting is a stage of it.
 
 ```tsx
+import { fetch, Task, usePage } from "@apps/<app>/client";
+import { signedIn } from "@libs/shared/webkit";
+import { ID } from "akanjs/base";
+import { page } from "akanjs/client";
+
 export default page()
   .param("orgId", ID)
   .guard(() => signedIn())
@@ -26,7 +31,8 @@ export default page()
 2. Name every `[x]` segment with `.param("x", Type)` and read a query key only with `.search("k", Type)`. Values
    arrive typed; `lang` reaches every stage and is never declared.
 3. Gate with `.guard(() => signedIn())` on the `_layout.tsx` (a real redirect before anything renders), and repeat
-   a stricter guard on a page that needs more. The endpoint guards are still the real gate.
+   a stricter guard on a page that needs more. The endpoint guards are still the real gate. `signedIn` comes from
+   `@libs/shared/webkit`, and a new workspace has that lib only with `create-workspace --libs true`.
 4. In `.render()`: `usePage()`, then fetch, then return. Hand `fetch.init*` / `view*` / `edit*` fields to sections
    unawaited; await only what the shell reads, in one `Promise.all`.
 5. `.head()` takes JSX (or a function returning it), never a metadata object. A canonical link comes only from the
@@ -37,19 +43,21 @@ export default page()
 ## API at a glance
 
 `page`, `layout` and `router` come from `akanjs/client`, `Link` from `akanjs/ui`, `usePageLocation` from
-`akanjs/webkit`. A stage receives the declared params and search keys plus `lang`.
+`akanjs/webkit`, and `fetch`, `usePage` and the model namespaces from `@apps/<app>/client`. A stage receives the
+declared params and search keys plus `lang`.
 
-- Data-driven title: `.head(async ({ name }) => <title>{(await fetch.pokemon(name))?.label}</title>)`.
-- Async page: `.render(async ({ name }) => { const pokemon = await fetch.pokemon(name); if (!pokemon) router.notFound(); … })`;
+- Data-driven title: `.head(async ({ id }) => <title>{((await fetch.book(id)) as Book | null)?.title}</title>)`,
+  where `Book` is the `common/` interface for the query's `Any` return (`akan-service`).
+- Async page: `.render(async ({ id }) => { const book = (await fetch.book(id)) as Book | null; if (!book) return router.notFound(); … })`;
   the same query in `.head()` and `.render()` is one request.
 - `router.notFound()` from `.guard()`, `.head()` or `.render()` answers 404 with the nearest layout's `.notFound()`
   above it (an unmatched URL: the deepest layout covering it), else the built-in 404.
 - A layout's own 404 and error views: `.notFound(({ pathname }) => …)` and `.error(({ error }) => …)` on `layout()`
   or `rootLayout()`.
-- `<Link href="/pokemon/deoxys">`: write the path without the locale; Link adds it, or leaves it off for the default
+- `<Link href="/books/OL45804W">`: write the path without the locale; Link adds it, or leaves it off for the default
   locale under `i18n.localePrefix: "as-needed"`. `activeClassName` marks the current one.
 - From a handler: `router.push(href)` / `router.replace(href)`; in a server stage, `router.redirect(href)`.
-- A client filter kept in the URL without reloading the page: ``router.replace(`/pokemon?q=${q}`, { shallow: true,
+- A client filter kept in the URL without reloading the page: ``router.replace(`/books?q=${q}`, { shallow: true,
   scrollToTop: false })`` in a `"use client"` component, read back with `usePageLocation().searchParams`. Shallow
   holds only while the path stays the same; a server `.search()` sees the value at the next full navigation.
 
@@ -60,4 +68,5 @@ export default page()
 - `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
 - Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
 
-Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server.
+Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server; every stage's
+signature, the router's methods, Link's props and every import path: `akanApi`.

package/codeAgent/skills/akan-service/SKILL.md

@@ -20,6 +20,10 @@ dictionary is a `serviceDictionary`.
   explicitly `void`-ed.
 - Return `null` / `false` for "not allowed" or "not found" and let the signal decide whether that is an
   error.
+- `serve(name, { serverMode: "batch" }, …)` mounts the module, endpoints included, only in a `batch` or `all`
+  process; a `federation` replica, the one serving requests in a split deployment, skips it. The app's own
+  `lib/_<app>/` service is scaffolded with it for cron and queue work. Leave it off a service a page calls, as
+  `akan create-service` does.
 
 ## Reaching other things
 
@@ -33,11 +37,13 @@ self-registers, so do **not** add it to `lib/option.ts`.
 
 ## Recipe: pages backed by an external HTTP API
 
-`akan create-service pokeapi <app>` scaffolds `lib/_pokeapi/`; the adapter beside it is yours.
+`akan create-service openlibrary <app>` scaffolds `lib/_openlibrary/`; the adapter beside it is yours.
 
 ```ts
-// srvkit/pokeApi.ts — read at boot, so the built server takes API_BASE_URL from the host that runs it
-export class PokeApi extends adapt("pokeApi" as const, ({ env }) => ({
+// srvkit/bookApi.ts — read at boot, so the built server takes API_BASE_URL from the host that runs it
+import { adapt } from "akanjs/service";
+
+export class BookApi extends adapt("bookApi" as const, ({ env }) => ({
   baseUrl: env(() => process.env.API_BASE_URL ?? "http://localhost:9000"),
 })) {
   async get<T>(path: string): Promise<T | null> {
@@ -52,30 +58,53 @@ export class PokeApi extends adapt("pokeApi" as const, ({ env }) => ({
   }
 }
 
-// lib/_pokeapi/pokeapi.service.ts — shape the upstream JSON here, not in the page
-export class PokeapiService extends serve("pokeapi" as const, ({ plug }) => ({ pokeApi: plug(PokeApi) })) {
-  async getPokemon(name: string) {
-    const pokemon = await this.pokeApi.get<ApiPokemon>(`pokemon/${name}`);
-    return pokemon && { id: pokemon.id, name: pokemon.name };
+// lib/_openlibrary/openlibrary.service.ts — shape the upstream JSON here, not in the page
+import { BookApi } from "@apps/<app>/srvkit";
+import { serve } from "akanjs/service";
+
+interface ApiWork {
+  key: string;
+  title: string;
+}
+
+export class OpenlibraryService extends serve("openlibrary" as const, ({ plug }) => ({ bookApi: plug(BookApi) })) {
+  async getBook(id: string) {
+    const work = await this.bookApi.get<ApiWork>(`works/${id}.json`);
+    return work && { id, title: work.title };
   }
 }
 
-// lib/_pokeapi/pokeapi.signal.ts — Any answers plain JSON; nullable lets it answer null for "not found"
-export class PokeapiEndpoint extends endpoint(srv.pokeapi, ({ query }) => ({
-  pokemon: query(Any, { guards: [Public], nullable: true })
-    .param("name", String)
-    .exec(async function (name) {
-      return await this.pokeapiService.getPokemon(name);
+// lib/_openlibrary/openlibrary.signal.ts — Any answers plain JSON; nullable lets it answer null for "not found"
+import { Any } from "akanjs/base";
+import { endpoint, internal, Public } from "akanjs/signal";
+
+import * as srv from "../srv";
+
+export class OpenlibraryInternal extends internal(srv.openlibrary, () => ({})) {}
+
+export class OpenlibraryEndpoint extends endpoint(srv.openlibrary, ({ query }) => ({
+  book: query(Any, { guards: [Public], nullable: true })
+    .param("id", String)
+    .exec(async function (id) {
+      return await this.openlibraryService.getBook(id);
     }),
 })) {}
 
-// lib/_pokeapi/pokeapi.dictionary.ts — typecheck asks a label for every endpoint
-  .endpoint<PokeapiEndpoint>((fn) => ({ pokemon: fn(["Pokémon", "포켓몬"]) }))
+// lib/_openlibrary/openlibrary.dictionary.ts — typecheck asks a label for every endpoint
+import { serviceDictionary } from "akanjs/dictionary";
+
+import type { OpenlibraryEndpoint } from "../sig";
+
+export const dictionary = serviceDictionary(["en", "ko"])
+  .endpoint<OpenlibraryEndpoint>((fn) => ({ book: fn(["Book", "책"]) }))
+  .error({})
+  .translate({});
 ```
 
-The page calls it as `await fetch.pokemon(name)` (`fetch` from `@apps/<app>/client`) and answers
-`router.notFound()` on `null`. An `Any` return reaches the page as `unknown`: type it with an interface in
+The page calls it as `await fetch.book(id)` (`fetch` from `@apps/<app>/client`) and ends with
+`return router.notFound()` on `null`. An `Any` return reaches the page as `unknown`: type it with an interface in
 `common/`, or return a scalar (`akan create-scalar`) for a typed wire shape. A query that answers `null` without
 `nullable: true` fails the render, naming the endpoint.
 
-Full detail: `get_guideline` with `modelService`.
+Full detail: `get_guideline` with `modelService`; every import path and the exact signatures of serve, adapt,
+endpoint and serviceDictionary: `akanApi`.