@owlmeans/create-app 0.1.18-rc.6 → 0.1.18-rc.61

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,182 @@
+---
+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: `reference.md`
+(in the OwlMeans repositories).

package/template/_agents/skills/reuse-code/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reuse-code
-description: Discovery-first, reuse-first workflow for OwlMeans projects. Use BEFORE planning or building any feature, before proposing a third-party library or a custom solution, and after writing code. Find an existing @owlmeans/* package or existing code first; extend before writing new; simplify what you write.
+description: Discovery-first, reuse-first workflow for OwlMeans projects. Use BEFORE planning or building any feature, before proposing a third-party library or a custom solution, and after writing code. Find an existing @owlmeans/* package or existing code first (membership, invitations, organizations and access come from the IAM); extend before writing new; simplify what you write.
 user-invocable: true
 metadata:
   scope: general
@@ -18,9 +18,17 @@ order — during planning **and** during implementation.
 Before suggesting any external library or writing custom code, look for an `@owlmeans/*` package that
 already solves the problem.
 
-- **Consult the deployed skills.** Each installed `@owlmeans/*` package ships a skill at
-  `.agents/skills/<pkg>/SKILL.md` describing what it
-  does. Read those first — they are your local catalogue of installed capabilities.
+- **Consult the deployed skills.** `.agents/skills/` is the local catalogue of installed
+  capabilities: one directory per skill, each holding a `SKILL.md` that describes what a package
+  does and how it is consumed. A directory is named after the **skill**, not the package —
+  `@owlmeans/test-ui` deploys `testing-ui`, `@owlmeans/server-auth` deploys `server-auth` **and**
+  `supervisor-auth`, `@owlmeans/test` deploys `testing-unit` and `testing-overview` — so list the
+  directory instead of guessing a path from a package name.
+- **Read `.agents/linked-skills/` too when it is there.** `.agents/scripts/link-skills.sh` links
+  the skills that ship inside the installed `@owlmeans/*` packages into it (and mirrors them into
+  `.claude/skills/` for Claude Code), with a skill / origin / description table in its
+  `INDEX.md`. It is generated and git-ignored, and a skill of the same name in `.agents/skills/`
+  always wins.
 - **Scan installed packages.** Look in `node_modules/@owlmeans/*` **and**, in a workspace monorepo,
   the nested `sources/*/node_modules/@owlmeans/*` (bun nests workspace deps).
 - **Discover packages that aren't installed yet** by researching the **owlmeans/common** repository —
@@ -39,20 +47,56 @@ How you research the repo depends on whether `@owlmeans/*` is linked locally:
   **https://github.com/owlmeans/common** — `tree.md` and package READMEs — to find the right package.
 
 This is the same dev-linked detection `@owlmeans/agent-skills` uses (see its `detectLinked`). After
-adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills` to deploy its skill. Prefer an
-`@owlmeans/*` package over a third-party library or bespoke code whenever one fits.
+adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.52` to deploy its
+skill. Prefer an `@owlmeans/*` package over a third-party library or bespoke code whenever one fits.
+
+### Never add an OwlMeans dependency without an explicit range
+
+Write the range yourself, as a caret at the version the rest of this project already uses for its
+other `@owlmeans/*` packages (or the one the package's own skill names on its **Install:** line):
+
+```json
+"dependencies": {
+  "@owlmeans/queue": "^<version>"
+}
+```
+
+A `bun add` that names no version — and a hand-written `"latest"`, `"next"`, `"*"` or empty range
+— resolves through a dist-tag instead. OwlMeans publishes prereleases under `next`, so the tag
+named `latest` points at an OLDER version than the one every other package here is pinned to. The
+install succeeds, nothing warns, and the code you wrote against the current API is compiled
+against the previous one. Put the version in the same breath as the package name, or copy the
+`**Install:**` line from that package's own skill, which always carries a current range.
 
 ## 2. Reuse or extend before writing custom
 
 If an installed package nearly fits, **configure or extend it** rather than writing something new — use
-its resources, services, modules, and helpers. A small extension of a framework package beats a new
+its resources, services, entrypoints, and helpers. A small extension of a framework package beats a new
 parallel implementation.
 
+### People, organizations and access come from the IAM
+
+An application that signs its people in through an OwlMeans IAM provider already has accounts,
+organizations, memberships, invitations and grants — the provider keeps them. Before writing a
+members table, an invitation flow, a role column or an organization picker:
+
+- **Server** (`@owlmeans/server-iam`): `makeIamRuntimeClient(context, request)` lists the person's
+  organizations, creates one, lists / adds (find-or-create by e-mail) / updates / removes members,
+  and lists, assigns and revokes grants — as the signed-in person, with owner and member rights
+  decided by the provider. `makeOrganizationScope(context, request).organizationOf` /
+  `.organizationsOf` read the session's organizations; gates and `hasPermission` enforce access;
+  `makeEntityScope(req).requireEntityKey()` is the tenant key to store records by.
+- **Browser** (`@owlmeans/client-iam`): `organizationSwitchOf(ctx).listOrganizations` /
+  `.switchOrganization` — the acting organization is session state, never a per-request parameter.
+- If the project's own scaffold already ships an organization switcher or a people / access screen,
+  extend it rather than adding a second one.
+
 ## 3. No package? Reuse code and extract an abstraction
 
 When no package solves it, search the codebase for code that already solves a **similar** problem.
 Prefer factoring out a shared helper, base, or generic function — extract an abstraction — over
-duplicating logic or writing from scratch. Only write genuinely new code when nothing reusable exists.
+duplicating logic or writing from scratch. A shared helper is ONE factory-built object whose interface is declared
+first; it lives in its own `<name>.ts`, with a same-named folder for its types and parts (`/owlmeans-code-structure`). Only write genuinely new code when nothing reusable exists.
 
 ## 4. Simplify after writing
 
@@ -60,5 +104,7 @@ Once code is written, review it: can it be **shorter, clearer, or expressed with
 Lean on framework utilities, remove dead branches, collapse needless indirection. Less code that reuses
 the framework is better than more bespoke code.
 
-See `[[dependency-tree]]` for the package map, `[[scaffolding]]` for how a project is assembled, and
-`[[bun]]` for adding dependencies.
+See `[[scaffolding]]` for how a project is assembled, and `[[agent-skills]]` for keeping the
+deployed skill catalogue current. The package map itself is `tree.md` at the root of the
+[owlmeans/common](https://github.com/owlmeans/common) repository — layer by layer, every package
+and what it depends on.

package/template/_agents/skills/self-education/SKILL.md

@@ -27,10 +27,14 @@ Also recommended after any unplanned change that made an existing skill inaccura
 
 For each area the work touched:
 
-1. Which existing skill covers it? (Check `.agents/skills/`.)
+1. Which existing skill covers it? Check `.agents/skills/`, and — where the project has one —
+   `.agents/linked-skills/`, for ground a skill this project does not own already covers.
 2. Do its commands, paths, APIs, and behavior claims still hold after the change?
 3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
    note about what this change did.
+4. Never record what the work taught in `AGENTS.md`: the rule goes to the governing skill, the
+   incident to `.agents/memory/`. `AGENTS.md` gains at most a new skill's one index line or a new
+   repo-wide mandatory rule in one line (`create-skill` → What may enter AGENTS.md).
 
 ## Shape of an update
 
@@ -46,11 +50,24 @@ rewrite recipe is `memory-promotion` → Distillation.
 
 Test: a finished skill reads as though the feature was always this way.
 
-## Non-project skills
+## Skills this project does not own
 
-If a general or imported skill gained an important usage pattern during the work, add the pattern
-to the **deployed copy** in this repo and note it in the report as an upstream candidate —
-canonical archive copies change only on explicit operator request.
+A skill that came from somewhere else is not edited here, and the two kinds fail differently:
+
+- An entry under `.agents/linked-skills/<name>` is a symlink into the repo or installed package
+  that owns the skill. Writing through it edits the owner's own file — an unrequested change in
+  another project, which nothing here undoes: the link script only creates and prunes symlinks.
+- A skill placed by the `@owlmeans/agent-skills` installer is a real file at
+  `.agents/skills/<name>/SKILL.md` carrying
+  `<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->`. The next install
+  overwrites every file still carrying that banner, so an edit made under it is lost; strip the
+  banner and the file instead becomes a conflict the installer skips and reports.
+
+When such a skill gained an important usage pattern during the work, capture the pattern in a
+local skill under `.agents/skills/`, named after the pattern — a local skill named after the
+upstream one shadows it for the whole project — and list the upstream skill in the report as an
+upstream candidate. Changing the skill at its source is a separate change in the owning project,
+made only on explicit operator request.
 
 ## External docs
 
@@ -73,6 +90,9 @@ memory-vs-skill boundary (`agent-memory` / `memory-promotion`).
 
 ## Completion gate
 
+Before reporting, run `sh .agents/scripts/agents-size.sh`; if `AGENTS.md` is over budget, move
+lines out to their skills first.
+
 The completion report must contain a Self-education table:
 
 | Item | Action | Path |