@owlmeans/create-app 0.1.18-rc.7 → 0.1.18

package/template/_agents/skills/getting-started/SKILL.md

@@ -1,105 +1,64 @@
 ---
 name: getting-started
-description: How to build a fullstack OwlMeans Common app from scratch — the common/api/web three-workspace pattern, context bootstrap on server and web, shared entrypoints + elevate(), and a session-scoped in-memory resource with @owlmeans/static-resource. Use when starting a new OwlMeans project, wiring web↔api, or asked how the pieces fit together.
-user-invocable: true
+description: Start a protocol-first OwlMeans application with shared contracts, server entrypoints and browser entrypoints.
 metadata:
   scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 
-# Getting started with OwlMeans Common — fullstack app shape
+# Protocol-first application shape
 
-A minimal OwlMeans app is a **bun-workspace monorepo with three packages**:
+An OwlMeans application owns one shared protocol declaration and creates local entrypoints for each
+runtime. The declaration is never modified by a server or browser.
 
+```ts
+// common/src/entrypoints.ts
+export const sessionProtocols = {
+  list: protocol(
+    route(session.list, '/session', backend()),
+    contract.request({ query: typed<SessionQuery>(SessionQuerySchema) }, typed<Session[]>())
+  ),
+}
 ```
-sources/
-├── common/   # shared entrypoints (routes), AJV schemas, types, config — the single source of truth
-├── api/      # @owlmeans/server-app backend; handlers attached to the shared entrypoints
-└── web/      # @owlmeans/web-panel + shadcn UI; screens attached to the same entrypoints
-```
-
-The full, runnable walkthrough (scaffolded **and** manual) lives in
-[`docs/getting-started.md`](../../../docs/getting-started.md). To generate this exact project, use
-[[scaffolding]] (`npm create @owlmeans/app`). This skill is the mental model.
-
-## The core idea: one contract, two sides
-
-Declare each route once in `common` as an **entrypoint**, then `elevate()` it on each side:
 
 ```ts
-// common/modules.ts — declaration + validation, no implementation
-export const sessionModules = [
-  entrypoint(route(session.base, '/session')),
-  entrypoint(route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
-    filter(params<SessionParams>(SessionParamsSchema))),
-  entrypoint(route(session.add, '/:sid/items', { parent: session.base, method: RouteMethod.POST }),
-    filter(params<SessionParams>(SessionParamsSchema, body<AddItemPayload>(AddItemSchema)))),
+// api/src/entrypoints.ts
+const api = handlers<Context>()
+export const serverBindings = [
+  ...frameworkEntrypoints,
+  bind(sessionProtocols.list, api.request(sessionProtocols.list, listSessions)),
 ]
 ```
 
 ```ts
-// api/modules.ts — attach handlers
-elevate(sessionModules, session.list, handlers.list)
-export const appModules = [...modules, ...sessionModules]        // `modules` = framework defaults
-```
+// web/src/entrypoints.ts
+export const clientBindings = [
+  ...frameworkEntrypoints,
+  ...bindAll(sessionProtocols),
+]
 
-```ts
-// web/modules.ts — attach screen components, plus call-only elevation for backend routes
-elevate(modules, session.list)                                    // callable from the client
-modules.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
+const sessions = await context.entrypoint(sessionProtocols.list).call({ query: { sid } })
 ```
 
-Change a route or schema in `common` and both sides stay in sync. See [[entrypoint]], [[route]],
-[[server-app]], [[web-client]], [[web-panel]].
-
-## Shared config (where services live)
-
-`common/config.ts` registers both services so the web knows where the API is. `base: 'api'`
-prefixes API routes with `/api`:
+Use `schema<T>(...)` or `typed<T>(...)` at the contract boundary. Bind all route parents with their
+children. Keep organization entity values on the wire as `entitySlug`; database relations use
+`entityId` only.
 
-```ts
-const cfg = service({ type: AppType.Frontend, service: APP_WEB, host: 'localhost', port: 3001 })
-service({ type: AppType.Backend, service: APP_API, host: 'localhost', port: 3000, base: 'api' }, cfg)
-cfg.debug = { all: true }
-export const commonConfig = cfg
-```
-
-api: `config(APP_API, commonConfig)` (+ `cfg.port`). web: `config(APP_WEB, commonConfig)`. See [[config]].
+## Configuration per runtime
 
-## Backend bootstrap + in-memory data
+The shared config in `common` (services, alias, security) is imported by both runtimes, so it
+never reads `process.env` or `import.meta.env`, and it never sets `cfg.debug = { all: true }`.
+Each runtime's own `config.ts` adds what depends on its environment — the log level above all
+(`logging`, `log`), behind a type-only `import type {} from '@owlmeans/log'`:
 
 ```ts
-// api/context.ts
-const context = makeContext(cfg, true)          // from @owlmeans/server-app
-appendStaticResource(context, SESSION_ITEMS)    // @owlmeans/static-resource — in-memory, no DB
-```
-
-Handlers use `handleRequest` / `handleBody` / `handleParams` (validated payload, then context, then
-req). Read/write `ctx.getStaticResource<T>(alias)` — full CRUD (`get/load/list/create/save/delete`).
-**`static-resource.list()` takes no criteria** — list all and filter in JS (e.g. by `sessionId`).
-`main(context, appModules)` starts the server. See [[static-resource]], [[server-app]], [[resource]].
+// api/src/config.ts — Bun runtime env
+cfg.log = { level: process.env.LOG_LEVEL || 'info', debug: process.env.LOG_DEBUG ?? '' }
 
-Swap `@owlmeans/static-resource` for [[mongo-resource]] / [[redis-resource]] when you need
-persistence — the handler shape is identical.
-
-## Web bootstrap (shadcn)
-
-`@owlmeans/web-panel`'s `PanelApp` is shadcn/Tailwind v4 (no MUI). The **app provides** the shadcn
-primitives at the `@` alias — `web-panel` references `@/lib/utils` and
-`@/components/ui/{alert,button,card,input,label,progress}`; copy those into `src/`. Render with
-`provide` from `@owlmeans/web-client`:
-
-```tsx
-basicRender(<PanelApp context={context} provide={provide} />)
+// web/src/config.ts — Vite build-time env, typed in vite-env.d.ts
+const env = import.meta.env
+cfg.log = { level: env.VITE_LOG_LEVEL || (env.PROD ? 'info' : 'debug'), debug: env.VITE_LOG_DEBUG ?? '' }
 ```
 
-`vite.config.ts` sets `@`→`src`, `@tailwindcss/vite`, and dedupes the owlmeans/react singletons.
-`index.css` is `@import "tailwindcss";` + a shadcn `@theme` token block (replaces `@owlmeans/owl-theme`).
-A parent `BASE` route renders the layout via `handler(LayoutComponent)`; `HOME` is its default child.
-Screens call the backend with `context.entrypoint(alias).call({ params, body })` → `[data, outcome]`.
-See [[web-panel]], [[web-client]], [[shadcn-web]], [[client-entrypoint]].
-
-## Authentication
-
-This shape is intentionally **auth-free**. To add it: `@owlmeans/server-auth` + `@owlmeans/client-auth`
-and `guard(...)` on entrypoints. See [[auth-protocol]], [[server-auth]], [[client-auth]].
+The server and client contexts apply `cfg.log` themselves; application code logs through
+`logger('<scope>')` from `@owlmeans/log`, never `console.*`.

package/template/_agents/skills/logging/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: logging
+description: Logging policy for any OwlMeans application — no bare console calls; every line through @owlmeans/log with a scope and a deliberate level; what belongs at info vs debug; never log secrets or personal content; debug off in production, with the level set per environment (a server's config file, a browser's build-time env); analytics events as a call option routed to plugins. Use when adding any log line or a catch block, debugging with prints, deciding what an operator should see in production, setting a log level for an environment, or reviewing code that calls console.
+user-invocable: false
+metadata:
+  scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Logging — the policy
+
+The mechanics are the `log` skill (`@owlmeans/log`). This is what to do in application code.
+
+1. **No `console.*`.** `import { logger } from '@owlmeans/log'`, `const log = logger('<scope>')` once per
+   module, then `log.debug|info|warn|error(message, data?, options?)`. A scope is lowercase and
+   colon-separated (`orders`, `orders:import`).
+2. **Choose the level on purpose.** `debug` is for diagnosis (per request, progress, dumps) — it is OFF
+   in production. `info` is what an operator wants to read in production: a job started or stopped, a
+   subscription or payment event, a sign-in, a server listening. `warn`: it degraded and went on.
+   `error`: the work failed. A line that fires every few seconds is `debug` or `logThrottle`d.
+3. **Stable message, variable data.** `log.info('Order shipped', { orderId, carrier })` — not a
+   sentence assembled from values. Give a significant event a dotted name: `{ event: 'order.shipped' }`.
+4. **Pass the `Error`.** `log.error('Import failed', error)` — never `error.message` alone, never
+   `JSON.stringify(error)`. In a browser the `Error` object must reach `console.error`; the logger does
+   that, and an error reporter hooked there keeps working.
+5. **Never log secrets or personal content**: tokens, keys, passwords, authorization or cookie headers,
+   request or response bodies, query strings, user text (a prompt, a message, a note, a model's
+   rationale quoting it), e-mail text, file contents, environment values. Log ids, names, sizes,
+   counts, lengths — `noteLength`, not the note. A refused request is its method, path (no query),
+   status and error code/message, at debug. A catch that only logs has not told the user anything —
+   the user-facing report is a separate step (a message, a state), and `log.error` is the operator's
+   record.
+6. **Analytics are a parameter, not a second API.** `log.info('…', data, { analytics: 'event_name' })`
+   hands the call to the registered analytics plugins (`@owlmeans/web-log` for a tag manager); add
+   `console: false` to keep it out of the log. Only for events something should count.
+7. **The level is set per environment, never in code.** A server declares `cfg.log` leaves as config
+   file paths (a ConfigMap or a `LOG_LEVEL` environment variable); a browser takes a build-time
+   constant (`VITE_LOG_LEVEL`). Development defaults to `debug`, a production build to `info`. Do not
+   hard-code `cfg.debug = { all: true }` — `debug.all` does not control logging and must not be on in
+   production.
+8. **Tests read the log with `memoryPlugin()`**; they do not spy on `console`.

package/template/_agents/skills/memory-promotion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-promotion
-description: Transform procedure-shaped or repeatedly-used memory into skills and instructions — the procedure-shape test, the mandatory distillation rewrite, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, when writing memory-derived content into a skill, or during recompaction.
+description: Transform procedure-shaped or repeatedly-used memory into skills — the procedure-shape test, the mandatory distillation rewrite, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, when writing memory-derived content into a skill, or during recompaction.
 user-invocable: true
 metadata:
   scope: general
@@ -9,7 +9,7 @@ metadata:
 
 # Memory promotion
 
-Memory holds **facts**; **procedures** belong in skills/instructions, where they auto-invoke and
+Memory holds **facts**; **procedures** belong in skills, where they auto-invoke and
 stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
 teaches itself.
 
@@ -79,8 +79,8 @@ Evaluable by reading the file alone — no tooling required.
 
 ## Update vs create
 
-**Default is update** — extend the existing skill/instruction whose scope covers the activity,
-even partially; keep both twins in sync. Create a NEW pair only when:
+**Default is update** — extend the existing skill whose scope covers the activity, even
+partially. Create a NEW skill only when:
 
 - (a) a new subsystem or technology entered the repo;
 - (b) an activity with no covering skill needed memory read/write more than once (a
@@ -90,6 +90,12 @@ even partially; keep both twins in sync. Create a NEW pair only when:
 New skills multiply lookup cost — compactness applies to the skill population *and* to each
 skill's body.
 
+The covering skill may be one this project does not own — a `.agents/linked-skills/<name>` entry
+symlinked into an upstream repo or installed package, or an installer-placed copy carrying the
+`AUTO-GENERATED` banner. Never write the promotion into either: put the distilled rule in a local
+skill and name it after the activity, because a local skill named after the upstream one shadows
+that skill for the whole project (`self-education` → Skills this project does not own).
+
 ## Procedure
 
 1. Collect the flagged / procedure-shaped memory lines.

package/template/_agents/skills/memory-recompact/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-recompact
-description: Recompact or migrate a whole .agents/memory/ store — rebuild the node map from project structure, merge event-shaped records into subsystem nodes, deduplicate, enforce caps, regenerate the MEMORY.md index, and fold in legacy .claude/memory and .github/memory stores. Use when a store degrades into event logs, indexes bloat or conflict, or for one-time migration.
+description: Recompact a whole .agents/memory/ store — rebuild the node map from project structure, merge event-shaped records into subsystem nodes, deduplicate, enforce caps, regenerate the MEMORY.md index, and fold in memory records kept anywhere else. Use when a store degrades into event logs, when indexes bloat or conflict, or when scattered records have to become one store.
 disable-model-invocation: true
 metadata:
   scope: general
@@ -9,9 +9,9 @@ metadata:
 
 # Memory recompaction
 
-Whole-store maintenance for `.agents/memory/` (protocol: `agent-memory`). Also the migration
-procedure for legacy `.claude/memory/` + `.github/memory/` stores. Store-wide rewrite — propose
-it when triggers appear; the operator invokes it.
+Whole-store maintenance for `.agents/memory/` (protocol: `agent-memory`), and the procedure for
+folding records kept anywhere else into it. Store-wide rewrite — propose it when triggers appear;
+the operator invokes it.
 
 ## When
 
@@ -20,7 +20,8 @@ it when triggers appear; the operator invokes it.
 - The same fact stated in two or more nodes.
 - More than ~20% of a node is stale `Status` content.
 - A node's `updated:` is months behind commits touching its scope.
-- Legacy `.claude/memory/` or `.github/memory/` dirs exist → run the migration below.
+- Memory records live outside `.agents/memory/` — a second store, a per-agent directory, a stray
+  notes file → fold them in with the merge pass below.
 
 ## Build the target node map first
 
@@ -43,14 +44,14 @@ For each old file or section:
 4. Procedure-shaped survivors do not enter nodes — route them to `memory-promotion`. Routing
    means distilling them into general rules, never handing the text over verbatim.
 
-## Legacy-store merge (migration)
+## Folding in an outside store
 
-1. Union `.claude/memory/` and `.github/memory/`. Same-named files are two drifted sources of
-   ONE node — merge both; the code-consistent version wins.
+1. Union every source. Two same-named files are two drifted sources of ONE node — merge both;
+   the code-consistent version wins.
 2. Index-only entries with no backing file: extract the fact into its node, or drop if stale.
-3. Old `## Skills` / "Key Files" index sections are dropped — skills self-describe; harness
-   layout belongs to `AGENTS.md`. Move genuinely non-obvious dispatch hints there.
-4. When the new store verifies (below), delete both legacy dirs entirely.
+3. `## Skills` / "Key Files" index sections are dropped — skills self-describe; harness layout belongs to `AGENTS.md`; a genuinely non-obvious dispatch hint goes into the
+   owning skill's `description:`, never into `AGENTS.md`.
+4. When the new store verifies (below), delete every merged source entirely.
 
 ## Regenerate the index
 
@@ -62,9 +63,9 @@ index incrementally.
 - Every node file is listed in the index; every listed node exists; every wiki-link resolves.
 - All caps met (index ≤ 50 lines; nodes ≤ 120; entries ≤ 3 lines; Status ≤ 5 dated lines).
 - No dates outside `Status` and `updated:`; no event-keyed filenames.
-- Both root instruction files' Memory sections point at `.agents/memory/`.
-- Legacy dirs gone; `grep -rn '\.claude/memory\|\.github/memory'` over the repo's harness files
-  returns nothing but allowlisted historical mentions.
+- The root `AGENTS.md` Memory section points at `.agents/memory/`.
+- `.agents/memory/` is the only memory store left: every merged source directory or file is
+  deleted, and nothing in the harness still points at one.
 
 ## Report
 

package/template/_agents/skills/owlmeans-code-structure/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: owlmeans-code-structure
+description: "Mandatory object and layout rules for all OwlMeans TypeScript: the functions of one domain are ONE object built by a factory; its interface is declared FIRST (interfaces, never ReturnType<typeof …>); private parts live inside the factory; the context or collaborator is bound into the factory; types, consts and code live in separate files; an object with its own types or sub-helpers gets a same-named folder. Use whenever you write or change any .ts/.tsx in an @owlmeans package, an app built on OwlMeans or a generated target: adding a function, helper, util, service, model, resource, type or constant, creating or splitting a file, or reviewing a diff."
+metadata:
+  scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# OwlMeans code structure
+
+Every OwlMeans repo — the libraries, the platform and every generated application — holds to the
+same shape. No tool checks it: this skill is the rule, every diff you write or review is held to it,
+and a violation is a defect, not a style note.
+
+## The rules
+
+1. **One domain, one object.** The functions a file offers to other files form ONE object, built by
+   ONE factory. Two domains in a file are two files. A file that exports a single function is not a
+   bundle and may stay a plain export.
+2. **Type first.** Declare the object's `interface` before writing the factory, in the object's
+   types file, and make the factory return it: `export const createXxxHelper = (…): XxxHelper => {…}`.
+   A type derived from the implementation — `ReturnType<typeof createXxx>`, `Parameters<typeof fn>`,
+   `typeof someObject` — never names a helper, util, service, model or resource. The contract's JSDoc
+   lives on the interface members.
+3. **Encapsulate.** The factory's closure holds the implementation: what the interface does not name
+   is a private local. Only pure, stateless primitives may stay module-private above the factory.
+   A factory that merely collects module-level functions — `createX = () => ({ a, b })` — is the
+   thing this rule forbids. No `this`: members are arrow functions, so they can be destructured and
+   passed on.
+4. **Bind what is shared.** When every member would take the same first argument — a context, a
+   request, a collaborator, a record — that argument goes to the factory, not to each call.
+5. **Interfaces over types — always where possible.**
+   - `type X = { … }` → `interface X { … }`; `A & B & { … }` → `interface X extends A, B { … }`.
+   - `type X = Pick<A, 'a'>` (also `Omit`, `Partial`, `Required`, `Readonly`) → `interface X extends Pick<A, 'a'> {}`.
+   - `type Fn = (a: A) => R` → `interface Fn { (a: A): R }`.
+   - `type` stays only for what an interface cannot say: unions, mapped, conditional and
+     template-literal types, tuples, primitives, `keyof`/indexed access, and protocol trees inferred
+     from a DSL (with a one-line reason).
+6. **Types, consts and code in separate files.** Interfaces and type aliases → `types.ts`; enums and
+   constants (including computed constant expressions such as an `Object.freeze([...LIST, ...])`) →
+   `consts.ts`; code everywhere else. Package-private declarations go to `types.local.ts` /
+   `consts.local.ts`, which no barrel re-exports.
+7. **A same-named folder for an object that has parts.** `helpers/file.ts` holds the factory;
+   `helpers/file/` holds its `types.ts`, `consts.ts` and the sub-helpers only it uses. A directory-level
+   `types.ts` is right for declarations two or more objects share, or for a small single-owner
+   directory; a types file that serves many unrelated owners is split into their folders.
+8. **Ready instances.** A zero-argument helper may export one ready instance as the file's last
+   statement (`export const pathHelper = createPathHelper()`). A bound object never has one — it is
+   reached through its binding target (below). Never build a bound object inside a loop or a render.
+
+## Kinds and names
+
+| Kind | What it is | Factory | Interface | Where |
+|---|---|---|---|---|
+| util | package-internal functionality, never re-exported by the package | `createXxxUtils()` / `makeXxxUtils(target)` | `XxxUtils` | `utils/xxx.ts` + `utils/xxx/` |
+| helper | reusable functionality, may be exported, not bound to one record | `createXxxHelper(opts?)` / `makeXxxHelper(target)` | `XxxHelper` | `xxx.ts` + `xxx/` |
+| service | lives in a context, has an alias and a lifecycle | `createXxxService(alias = DEFAULT_ALIAS)` via `createService`, plus `appendXxxService(ctx)` | `XxxService extends InitializedService` | `services/xxx.ts` + `xxx/` |
+| model | logic over ONE plain record (plus collaborators) | `makeXxxModel(record, deps?)` | `XxxModel` | `models/xxx.ts` + `xxx/` |
+| resource | store access and store-level queries | `makeXxxResource(…)` | `XxxResource` | `resources/xxx.ts` + `xxx/` |
+
+`create*` builds something standalone or configured by options; `make*` builds something bound to
+its first argument.
+
+## How a bound object is reached
+
+| Bound to | Shape | At the call site |
+|---|---|---|
+| the context, with a lifecycle, a cache or a replaceable seam | a service | `ctx.service<XxxService>(ALIAS)`, or an accessor its `append*` installs (`ctx.xxx()`) |
+| the context of an app that owns its context type | `makeXxxHelper(ctx)`, installed lazily on the context: `context.projects = memoHelper.once(() => makeProjectHelper(context))` | `ctx.projects().getDevSlot(id)` |
+| the context, inside a library | `makeXxx(ctx)` plus `export const xxxOf = memoHelper.oncePer(makeXxx)` | `const xxx = xxxOf(ctx)` once per function |
+| one request | `makeRequestScope(ctx, request)` | built once at the top of a handler, never stored |
+| a collaborator (a FileHelper, a deps bag) | `makeXxx(collaborator)`, an accessor on the collaborator or `oncePer` | `files.layout().recordDeviation(d)` |
+| a record | a model | `makeSlotModel(slot).namespace()` |
+
+`memoHelper` (`once`, `oncePer`) comes from `@owlmeans/context`. Tests build the object directly:
+`makeProjectHelper(fakeContext)`.
+
+## Examples
+
+```ts
+// helpers/slug/types.ts — the type comes first
+export interface SlugHelper {
+  /** The URL-safe form of a title. */
+  slugOf: (title: string) => string
+  /** A title read back from a slug. */
+  titleOf: (slug: string) => string
+}
+
+// helpers/slug.ts
+import type { SlugHelper } from './slug/types.js'
+
+export const createSlugHelper = (): SlugHelper => {
+  const words = (text: string): string[] => text.split(/\W+/).filter(word => word !== '') // private
+
+  const slugOf = (title: string): string => words(title.toLowerCase()).join('-')
+  const titleOf = (slug: string): string => words(slug).join(' ')
+
+  return { slugOf, titleOf }
+}
+export const slugHelper = createSlugHelper()
+```
+
+A service follows `@owlmeans/api`'s `createApiService(alias): ApiClient` — `createService<ApiClient>`
+with the members in place, `assertContext(client.ctx, …)` inside them, and an `appendApiClient(ctx)`
+that registers it. A model follows `@owlmeans/planning`'s `makeWorkcardModel(record, facade):
+WorkcardModel`.
+
+```ts
+// models/invoice/types.ts
+export interface InvoiceModel { readonly record: Invoice; isPaid: () => boolean; owed: () => number }
+// models/invoice.ts
+export const makeInvoiceModel = (record: Invoice): InvoiceModel => ({
+  record,
+  isPaid: () => record.paidAt != null,
+  owed: () => (record.paidAt != null ? 0 : record.amountMinor),
+})
+```
+
+A model is built from its record when it is needed — never stored on the record, never serialized.
+
+**Wrong, and how it is fixed**
+
+| Wrong | Right |
+|---|---|
+| `const a = …; const b = …; export const createX = () => ({ a, b })` + `type X = ReturnType<typeof createX>` | `interface X` in `x/types.ts`; `createX = (): X => { const a = …; const b = …; return { a, b } }` |
+| `xHelper.read(files, path)`, `xHelper.write(files, …)` — the same collaborator in every call | `makeX(files): X` and `x.read(path)` |
+| `export const getDevSlot = (ctx, id) => …` beside five more ctx-first functions | `makeProjectHelper(ctx): ProjectHelper`, reached as `ctx.projects()` |
+| `export const SEED_SOURCES = Object.freeze([…])` in a code file | the constant in `consts.ts` |
+| one `types.ts` holding the interfaces of twenty unrelated helpers | each helper's interface in its own `<helper>/types.ts` |
+
+## Exempt
+
+These stay plain exports: declaration-builder DSLs that are the framework's vocabulary (`route`,
+`protocol`, `typed`, `contract`, `bind`, `logger`, `frontend`/`backend`, `declare*`, config plugins),
+factories themselves (`make*`, `create*`, `append*`), React components and `use*` hooks, entry
+scripts, error classes and schema files.
+
+## Generated applications
+
+Applications the viable agent generates follow the same rules, in these fixed shapes:
+
+- **Domain model per entity.** `backend/src/models/<entity>/types.ts` declares
+  `interface <Base>Model` first; `models/<entity>/<base>.ts` exports only
+  `make<Base>Model = (ctx: Context): <Base>Model => { const op = async (actor: Actor, …) => …; return { op, … } }`.
+  It is built where it is used — `await makeTaskModel(ctx).complete(actorOf(request), id)` — and is
+  never registered as a context service. Its member names are the endpoint keys of the entity.
+- **Handlers and job processors**: one plain exported function per file
+  (`api/src/app/<entity>/<action>.ts` beside a GENERATED `index.ts` barrel, `worker/src/jobs/<job>.ts`);
+  a handler's body is one call into the model.
+- **Seed helpers are objects** whose members keep the old function names:
+  `actorOf(request): Actor` with `actor.inOrganization(…)`, `actor.assertOrganization(…)`,
+  `actor.grantedIds(…)`, `actor.organizationScope(…)`; `recordOwnerOf(request)`, `visitOf(request)`,
+  `planningAccessOf(request, ctx)`, `landingHandoff`, `visitKey`. Their types live in the module's
+  same-named folder (`lib/actor/types.ts`); the old free functions stay as
+  `@deprecated generated-app:factory-objects` wrappers so a project generated before still compiles.
+- A model module generated before this shape keeps its plain functions: its callers import them by
+  name, so it is extended in that shape and never converted in place.
+- **Resources** keep their maker and their `xResource(ctx)` accessor; the resource's interface lives
+  in `resources/<entity>/types.ts`.
+- Shared types in `common` are interfaces.
+- A file the template shipped keeps the shape the platform gives it.
+
+## Self-check before you finish
+
+```sh
+{ git diff --name-only HEAD; git ls-files --others --exclude-standard; } | grep -E '\.tsx?$' \
+  | grep -vE '\.(test|spec)\.tsx?$|\.d\.ts$|(^|/)(tests?|fixtures)/' > /tmp/changed.txt
+# derived helper types and wrapper factories
+xargs -r grep -nE 'ReturnType<typeof|= \(\) => \(\{ *[a-zA-Z]+, ' < /tmp/changed.txt
+# object-shaped type aliases that should be interfaces
+xargs -r grep -nE '^(export )?type [A-Za-z0-9_]+(<[^=]*>)? *= *\{' < /tmp/changed.txt
+# types, enums or CONSTANT_CASE constants declared in code files
+grep -vE '(^|/)(types|consts)(\.local)?\.ts$' /tmp/changed.txt \
+  | xargs -r grep -nE '^export (interface |enum |type [A-Za-z0-9_]+ *(<[^=]*>)? *=|const [A-Z][A-Z0-9_]+ *[:=])'
+```
+
+Then read the diff once for what no grep sees: a second exported function of one domain, a member
+that takes the same first argument as its siblings, a private helper exposed on the interface, a
+bound object built in a loop, a barrel re-exporting a `.local` file.
+
+Classification details, folder decisions and the pitfalls of moving code into closures: the
+`code-structure-reference` part ([parts/code-structure-reference.md](parts/code-structure-reference.md)).
+
+## Parts
+
+| Part | Load it when |
+|---|---|
+| [code-structure-reference](parts/code-structure-reference.md) | classifying a declaration, deciding a folder, converting a module, or moving code into closures |

package/template/_agents/skills/owlmeans-code-structure/parts/code-structure-reference.md

@@ -0,0 +1,125 @@
+---
+name: code-structure-reference
+description: Classifying a declaration, file roles, deciding a module's shape, converting a module step by step, choosing the binding target, interface conversions, and pitfalls.
+metadata:
+  purposes:
+  mentions:
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# owlmeans-code-structure — reference
+
+## Contents
+- Classifying a declaration
+- File roles
+- Deciding the shape of a module
+- Converting a module, step by step
+- Binding: choosing the target
+- Interfaces over types: the conversions
+- Pitfalls
+
+## Classifying a declaration
+
+| Kind | What it is | Goes to |
+|---|---|---|
+| type | `interface`, `type` alias, `declare const x: unique symbol` brand | `types.ts` / `types.local.ts` |
+| constant | an enum, or a `const` whose initializer is a literal, an object/array of constants, a template over constants, `Object.freeze`/`as const`/`satisfies` of those, `new Set/Map/RegExp` over constants, or `.map/.filter/.concat` over constants | `consts.ts` / `consts.local.ts` |
+| state | `let`/`var`, a cache, a registry, a holder (`new Map()`, `[]`, `{}` that is filled later) | stays with the code that owns it, inside its factory when per-instance, module level when process-wide |
+| instance | a value built by a factory (`createPathResolver(DEFAULT_TOPOLOGY)`) | the factory's file, as its ready instance |
+| code | functions, classes, side-effect statements | code files, inside a factory |
+
+A constant computed by calling project code is either rewritten as a constant expression (a
+template over constants instead of `srcOf(...)`) or is an instance.
+
+## File roles
+
+| File | Holds |
+|---|---|
+| `x.ts` | one factory (plus its ready instance), or one exempt export (a component, a hook, one handler) |
+| `x/types.ts` | `x`'s interface and the types only `x` owns |
+| `x/consts.ts`, `x/*.local.ts` | its constants; its package-private declarations |
+| `x/<sub>.ts` | a sub-helper only `x` uses — itself a factory, with its own folder when it has parts |
+| `<dir>/types.ts` | declarations two or more objects of the directory share, or a small single-owner directory |
+| `index.ts` | re-exports only: `export type * from './x/types.js'`, `export * from './x.js'`; never a `.local` file, never an enum through `export type *` |
+| `errors.ts`, `schemas.ts` | error classes; JSON schemas and the code that builds them |
+
+A types file imports only types files, consts files and external packages — never a code file.
+
+## Deciding the shape of a module
+
+1. List what other files use from it. Everything else becomes private.
+2. Group what is used by domain. One group = one object; a second group = a second file.
+3. Look at the first parameters. A shared context, request, collaborator or record moves into the
+   factory (see *Binding*). Members that take different first arguments may mean two objects.
+4. A group whose members all read one record is a model; one that lives in a context with a
+   lifecycle is a service; one that reads and writes a store is a resource; the rest are helpers
+   (reusable) or utils (package-internal).
+5. Name it by the kind: `createXxxHelper` / `makeXxxHelper`, `createXxxUtils`, `createXxxService`,
+   `makeXxxModel`, `makeXxxResource`.
+
+## Converting a module, step by step
+
+1. Write `x/types.ts`: the interface, one member per public function, with explicit parameter and
+   return types and the JSDoc moved from the functions.
+2. Rewrite `x.ts`: `export const createX = (deps): X => { … return { … } }`, with every function of
+   the group and every helper only they use inside the closure, in their original order.
+3. Drop the bound parameter from the members and from the calls between them.
+4. Move constants and types the module still declares to `x/consts.ts` and `x/types.ts`.
+5. Update every caller: `fn(ctx, a)` → `xOf(ctx).fn(a)`, `fn(a)` → `xHelper.fn(a)`, hoisting a
+   repeated `xOf(ctx)` to one local per function.
+6. Build from clean (delete `build/` and `*.tsbuildinfo`), run the package's tests, and grep the
+   tests that read source as text (`readFileSync` of a `.ts`) for the moved names.
+
+A published package that removes an export keeps a deprecated delegate at the end of the module
+that exported it (`/** @deprecated compat:factory-refactor use xOf(ctx).fn() */`) until its version
+line changes — never gathered into one `compat.ts`, because a subpath export (`pkg/login`) resolves
+that module, not the package root. No code in the OwlMeans repositories may import it; a private
+package drops its delegates once nothing imports them.
+
+## Binding: choosing the target
+
+- **A service** when the object has a lifecycle (init, connections), holds state shared by the
+  process, or must be replaceable by an application.
+- **A context accessor** when an application owns its context type: declare `xxx: () => XxxHelper` on
+  the context interface and install it in the context factory with `memoHelper.once`.
+- **`oncePer`** inside a library, where the helper must not appear on the public context type:
+  `export const xxxOf = memoHelper.oncePer(makeXxx)`.
+- **A request scope** for what depends on the caller (actor, organization, channel): build it once at
+  the top of the handler and pass it down; never store it.
+- **A collaborator accessor** when a helper always works over one FileHelper, stage or deps bag.
+- **A model** when every member reads the same record.
+
+Construction must stay cheap: no I/O and no awaits in a factory body; tables a member needs are built
+lazily with `memoHelper.once`.
+
+## Interfaces over types: the conversions
+
+| From | To |
+|---|---|
+| `type X = { a: A }` | `interface X { a: A }` |
+| `type X = A & { b: B }` | `interface X extends A { b: B }` |
+| `type X = Omit<A, 'k'> & { k: K }` | `interface X extends Omit<A, 'k'> { k: K }` |
+| `type X = Partial<Pick<A, 'a' \| 'b'>>` | `interface X extends Partial<Pick<A, 'a' \| 'b'>> {}` |
+| `type F = (a: A) => R` | `interface F { (a: A): R }` |
+| `type F = <T>(a: T) => R<T>` | `interface F { <T>(a: T): R<T> }` |
+
+Keep the alias, with a one-line reason, where the interface breaks the program: it is used where an
+implicit index signature is required, its `extends` parts conflict, or a declaration of the same name
+would merge with it.
+
+## Pitfalls
+
+- **Read before initialization.** A factory body runs when called; a ready instance runs at import.
+  Keep the instance the file's last statement, and never let a module-level constant call a factory
+  of the same import cycle.
+- **Import cycles.** Bound objects import types, constants and pure helpers only; composition roots
+  (context factories) import the factories. Reach another bound object through the binding target.
+- **Declaration emit.** A private type that appears in a public signature must move to `types.ts`;
+  an inferred return type that names an unexported type fails the build (`TS4023`, `TS2742`).
+- **State moved into a closure** becomes per instance. Process-wide state (a queue, a merge chain, a
+  cache every caller must share) stays at module level or in a per-context memo.
+- **Inheritance by prototype.** A helper derived with `Object.create(base)` inherits accessors bound to
+  `base`; build an accessor over the derived object when its calls must go through it.
+- **Enums** never move into types files and never pass through `export type *`.
+- **Same name from two modules** in one barrel fails with `TS2308`; rename or re-export explicitly.
+- **Tests that read source text** break silently when code moves; grep them in the same change.