@owlmeans/create-app 0.1.18-rc.8 → 0.1.19-rc.0

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.19-rc.0` 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 |

package/template/_agents/skills/skill-authoring/SKILL.md

@@ -9,13 +9,26 @@ metadata:
 
 # Authoring agent guidance (skills)
 
-OwlMeans projects carry agent guidance in two places, and only two:
+An OwlMeans project carries agent guidance in up to three places:
 
 | What | Where | Loaded |
 |---|---|---|
 | Always-on project context | `AGENTS.md` at the repo root | every session |
+| Always-on policy, kept out of `AGENTS.md` | `.agents/rules/<topic>.md`, pulled in from `AGENTS.md` by an `@.agents/rules/<topic>.md` import line | every session |
 | Topic guidance | `.agents/skills/<name>/SKILL.md` | on demand, by topic or `/<name>` |
 
+The middle tier is optional and belongs to a repo that has grown standing policy of its own. A
+project scaffolded by `@owlmeans/create-app` starts without a `.agents/rules/` directory: its
+generated `AGENTS.md` states the git policy inline and points at the seeded `git` skill for the
+rest. Follow the layout the project already has — add a rules file only where `AGENTS.md` already
+imports one.
+
+**Rule or skill?** A rule is policy that has to hold whether or not anyone thought to load
+anything — the git workflow is the standing example, whether a repo keeps it as
+`.agents/rules/git.md` or inline in `AGENTS.md`. A skill is guidance for a task, loaded when that
+task comes up. If it only matters while you are doing X, write a skill; if breaking it is wrong at any moment, state it in a line or two where `AGENTS.md` loads it every
+session, and keep its detail in a skill (§ What may enter AGENTS.md).
+
 `.agents/skills/` is the [Agent Skills](https://agentskills.io) standard location: GitHub Copilot
 and Codex discover it natively. Claude Code reads skills only from `.claude/skills/`, so each skill
 is bridged there by a generated symlink — see "Refresh the Claude Code links" below. **Write a skill
@@ -26,8 +39,8 @@ once; never author a per-agent copy** (`.github/instructions/*.instructions.md`,
 
 ```
 .agents/skills/<name>/
-├── SKILL.md          # required — frontmatter + body
-├── reference.md      # optional — deeper detail loaded on demand
+├── SKILL.md          # required — frontmatter + body (a package skill's core)
+├── parts/<part>.md   # optional — a package skill's purpose parts, loaded on demand
 └── scripts/          # optional — shell scripts the skill runs
 ```
 
@@ -38,20 +51,95 @@ once; never author a per-agent copy** (`.github/instructions/*.instructions.md`,
 name: my-skill                  # REQUIRED, must equal the directory name (lowercase, hyphens, ≤64 chars)
 description: What it does and WHEN to use it.   # REQUIRED, ≤1024 chars — the auto-invocation signal
 user-invocable: true            # false = background knowledge only, hidden from the / menu
-allowed-tools: Bash(bun *) Read # optional — space-separated; tools usable without per-call approval
+allowed-tools: Bash(bun *), Read # optional — COMMA-separated; tools usable without per-call approval
 metadata:                       # optional — anything non-standard goes here
   scope: general
 ---
 ```
 
+The `name` is not free: it is the key every store is keyed by, and a LOCAL skill always wins over
+one that arrives from a dependency. Naming a skill after a package you depend on therefore hides
+that package's own guidance completely, and the installer reports the file as a conflict on every
+run. Give a skill about your own use of `@owlmeans/payment` a name of its own — `billing`, or your
+product's name with a suffix — never `payment`.
+
+**Never name a skill after a Claude Code built-in slash command.** Claude Code resolves `/<name>` to
+a skill before the built-in command of the same name, so a skill called `context`, `config`,
+`memory` or `review` makes that command unreachable wherever the skill is installed or linked, and
+nothing reports it. The same holds for a command's aliases (`/settings` is `/config`, `/cost` is
+`/usage`) and for the skills Claude Code bundles (`/loop`, `/simplify`); type `/` in a Claude Code
+session to see every taken name. OwlMeans package skills follow this too: the guidance for
+`@owlmeans/context` and `@owlmeans/config` ships as `owlmeans-context` and `owlmeans-config`.
+
 The `description` is the most important field: every agent uses it to decide when to load the
 skill, so state both the topic and the trigger ("Use when …"). Keep it under 1024 characters —
-Copilot rejects longer ones.
-
-Only the fields above (plus `license` and `compatibility`) are portable. Anything else — including
-this monorepo's `scope: general` routing marker — belongs under `metadata:`, so a skill stays valid
-in every agent that reads it. Claude Code additionally understands `disable-model-invocation`,
-`argument-hint` and `context: fork`; use them only when the skill genuinely needs them.
+Copilot rejects longer ones. It is YAML, so a value containing `: ` (colon-space) has to be quoted
+or the file stops parsing and the skill silently disappears from every agent.
+
+`allowed-tools` is parsed as a list split on commas, newlines and YAML `-` bullets — never on
+plain spaces. `Bash(bun *) Read` is read as one tool named `Bash(bun *) Read`, which matches
+nothing; write `Bash(bun *), Read`.
+
+Six keys are what the Agent Skills standard defines: `name`, `description`, `license`,
+`compatibility`, `allowed-tools` and nested `metadata`. `@owlmeans/agent-skills` parses no
+frontmatter; the generator that embeds package guidance reads it. Project-specific keys —
+including the OwlMeans `scope: general` routing marker, which sends a skill to the installer bundle
+rather than to one package — belong under `metadata:`, so a skill stays valid in every agent that
+reads it. The invocation switches sit outside the standard and are written at the top level
+alongside it: `user-invocable` (`false` hides a skill from the `/`
+menu, marking it background knowledge), plus `disable-model-invocation` and `argument-hint`, which
+Claude Code understands. Set any of them only when the skill needs it.
+
+## Chunked package skills (parts)
+
+A package skill that grows past what one call should carry is split. `SKILL.md` stays the
+**core**, loaded whenever the package is chosen; each `parts/<part>.md` holds ONE purpose, loaded
+only for a call that needs it (selection: the `agent-skills` skill).
+
+- **The core** keeps the frontmatter, the `**Install:**` line, the exports, the wiring, any
+  `## Target wiring` section (an adoption reads it from the core alone) and the rules every use
+  needs. Target ≤ 12 000 chars. It ENDS with a Parts table linking every part:
+
+  ```markdown
+  ## Parts
+
+  | Part | Load it when |
+  |---|---|
+  | [navigation](parts/navigation.md) | building the application shell or its menus |
+  ```
+
+- **A part** opens with exactly this frontmatter, then `# @owlmeans/<package> — <part title>` and
+  the moved sections:
+
+  ```yaml
+  ---
+  name: navigation                 # = the file stem, [a-z0-9-], unique within the package
+  description: The application shell — NavLayout, TopNav/SideNav/MobileNav/Footer, the nav config.
+  metadata:
+    purposes: navigation, layout, screen      # closed vocabulary, comma-separated
+    mentions: NavLayout, TopNav, SideNav      # symbols and import specifiers that call for it
+  ---
+  ```
+
+- **Size:** the generator warns above 12 000 chars per part and fails above 16 000; it also warns
+  about a package-specific skill over 16 000 chars that has no parts.
+- **Purposes** come from a closed vocabulary (`PACKAGE_PURPOSES`, `@owlmeans/llm-common`):
+  `view`, `form`, `list`, `detail`, `dialog`, `picker`, `navigation`, `layout`, `screen`,
+  `theme`, `feedback`, `state`, `client-api`, `server-api`, `data`, `migration`, `query`, `auth`,
+  `consent`, `payment`, `planning`, `job`, `agent`, `config`, `test`, `ops`.
+  A value outside it fails the generator. Purposes may stay empty only in a general skill.
+- **Mentions** are distinctive symbols or import specifiers, never common words: a call without a
+  focus loads every part whose mention appears in its messages.
+- **Names are unique per package** — a part is addressed as `@owlmeans/<package>#<part>`. Every
+  general skill routes to the installer package, so a general skill's part carries the skill's own
+  prefix (`code-structure-reference`, never `reference`).
+- **YAML:** a value that starts with `@`, a backtick, `[`, `{`, `*` or `&`, or that contains `: `
+  or ` #`, stops parsing — start the mentions with a symbol, not an import specifier.
+- **Splitting moves text, never rewrites it.** Every section lands in the core or in exactly one
+  part, each part stands alone for its purpose, and a reference to a moved section names its part
+  (see "Organizations" in the `sessions` part).
+- Only `SKILL.md` and `parts/*.md` are embedded into a package; any other file beside them stays in
+  the repository, and the generator warns about a root `reference.md`.
 
 ## Refresh the Claude Code links
 
@@ -61,9 +149,23 @@ After creating, renaming, or deleting a skill, run:
 sh .agents/scripts/link-skills.sh
 ```
 
-It creates `.claude/skills/<name>` → `../../.agents/skills/<name>` for every skill and prunes links
-whose skill is gone. The links are gitignored and are recreated at session start, but a skill added
-mid-session is invisible to Claude Code until the script runs.
+It creates `.claude/skills/<name>` → `../../.agents/skills/<name>` for every local skill and prunes
+links whose skill is gone. The links are gitignored and are recreated at session start (a committed
+`SessionStart` hook, and on every install where the project declares a root `prepare` script that
+calls it), but a skill added mid-session is invisible to Claude Code until the script runs.
+
+The same script also brings in the skills of everything this project depends on, from whichever of
+two sources applies. In a linked checkout — a repo whose root `package.json` lists an upstream
+repo's packages as workspace entries — it resolves those upstream repos first, recursing into each
+one's own manifest up to four levels, and links the skills from the upstream's own
+`.agents/skills/`. A project that declares no such linked upstream falls back to what a plain npm
+install gives it: the read-only `agent-meta/skills/` copies shipped inside each installed
+`@owlmeans/*` package. Either way the links land in `.agents/linked-skills/<name>` (Copilot, Codex)
+and `.claude/skills/<name>` (Claude Code), with a generated `.agents/linked-skills/INDEX.md` listing
+skill, origin and description. Load one by name exactly like a local skill. A local skill of the
+same name always wins, and a nearer dependency wins over a farther one. The whole
+`.agents/linked-skills/` directory is generated and git-ignored — never edit or commit it, and never
+edit an `agent-meta/` copy: fix the skill in the package that ships it.
 
 ## Skill vs memory
 
@@ -80,10 +182,26 @@ Never paste memory text into a skill. Memory content enters guidance only as a r
 rule — trigger, step, and the failure it prevents, with dates, phase/status markers, versions and
 incident narrative stripped (`memory-promotion` → Distillation).
 
+## What may enter AGENTS.md
+
+`AGENTS.md` — with every file it `@`-imports and `.agents/memory/MEMORY.md` — is loaded in full in
+every session, so it has a budget: **≤ 40 000 chars**, checked by `sh .agents/scripts/agents-size.sh`
+from the repo root where the repo carries it. A line enters it only as:
+
+1. a mandatory rule that must hold before any skill is loaded (git, reporting, environments,
+   naming, code structure) — stated in one or two lines, with the detail in a skill;
+2. one line of the package map or the command list;
+3. one line of the skills index: `` - `/name` — when to load it ``, ≤ 160 chars.
+
+Everything else is loaded on demand: a subsystem's rules, contracts and failure fingerprints go to
+the skill that governs it, and the outage that taught them to `.agents/memory/`. Never paraphrase a
+skill's `description:` into the index — skills self-describe. A change that would push the file over
+budget shortens or moves an existing line in the same change.
+
 ## After adding a skill
 
 1. If it replaces an ad-hoc `.agents/<topic>.md`, remove that file.
 2. If it distilled memory content into rules, shrink the source `.agents/memory/` node to a
    pointer line (`memory-promotion`) — the memory index does not list skills.
-3. Reference it from `AGENTS.md` if it should be discoverable every session.
+3. Add one line to the skills index in `AGENTS.md` (`/name` — when to load it, ≤ 160 chars) — never a paragraph (§ What may enter AGENTS.md).
 4. Run `sh .agents/scripts/link-skills.sh`.

package/template/_bare.json

@@ -0,0 +1,24 @@
+{
+  "remove": [
+    "sources/common/src/types.ts",
+    "sources/common/src/schemas.ts",
+    "sources/api/src/consts.ts",
+    "sources/api/src/app",
+    "sources/api/src/models",
+    "sources/web/src/screens/about.tsx",
+    "sources/web/src/screens/session.tsx"
+  ],
+  "overrides": {
+    "README.md": "README.bare.md",
+    "sources/common/src/consts.ts": "sources/common/src/consts.bare.ts",
+    "sources/common/src/entrypoints.ts": "sources/common/src/entrypoints.bare.ts",
+    "sources/common/src/index.ts": "sources/common/src/index.bare.ts",
+    "sources/api/src/context.ts": "sources/api/src/context.bare.ts",
+    "sources/api/src/entrypoints.ts": "sources/api/src/entrypoints.bare.ts",
+    "sources/api/src/types.ts": "sources/api/src/types.bare.ts",
+    "sources/web/src/context.ts": "sources/web/src/context.bare.ts",
+    "sources/web/src/entrypoints.ts": "sources/web/src/entrypoints.bare.ts",
+    "sources/web/src/nav.ts": "sources/web/src/nav.bare.ts",
+    "sources/web/src/screens/home.tsx": "sources/web/src/screens/home.bare.tsx"
+  }
+}

package/template/_gitignore

@@ -6,6 +6,14 @@ dist
 bun.lock
 bun.lockb
 
+# Developer-local environment (LOG_LEVEL, VITE_LOG_LEVEL, …)
+.env
+.env.local
+.env.*.local
+
 # Generated Claude Code skill symlinks (canonical skills live in .agents/skills/)
 .claude/skills/*
 !.claude/skills/.gitkeep
+
+# Skills linked from upstream repos (generated by .agents/scripts/link-skills.sh)
+.agents/linked-skills/

package/template/bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+linker = "hoisted"

package/template/package.json

@@ -3,14 +3,15 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "packageManager": "bun@1.3.14",
+  "packageManager": "bun@1.4.2",
   "workspaces": [
     "sources/*"
   ],
   "scripts": {
     "dev": "bun run --filter './sources/common' build && bun run --filter './sources/*' --parallel dev",
     "build": "bun run --filter './sources/*' build",
-    "typecheck": "bun run --filter './sources/*' typecheck"
+    "typecheck": "bun run --filter './sources/*' typecheck",
+    "prepare": "sh -c 'test -f .agents/scripts/link-skills.sh && sh .agents/scripts/link-skills.sh || true'"
   },
   "devDependencies": {
     "nodemon": "^3.1.14"

package/template/sources/api/package.json

@@ -11,13 +11,14 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@owlmeans/server-app": "^0.1.18-rc.0",
-    "@owlmeans/static-resource": "^0.1.18-rc.0",
+    "@owlmeans/log": "^0.1.19-rc.0",
+    "@owlmeans/server-app": "^0.1.19-rc.0",
+    "@owlmeans/static-resource": "^0.1.19-rc.0",
     "__APP_SLUG__-common": "workspace:^"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.18-rc.0",
-    "@types/node": "^24.10.1",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@types/node": "^26.6.5",
     "typescript": "^7.0.2"
   }
 }

package/template/sources/api/src/app/session/add.ts

@@ -1,20 +1,9 @@
-import { randomUUID } from 'node:crypto'
-import { handleBody } from '@owlmeans/server-app'
-import type { AddItemPayload, SessionItem, SessionParams } from '__APP_SLUG__-common'
-import { SESSION_ITEMS } from '../../consts.js'
+import { handlers } from '@owlmeans/server-app'
+import { session } from '__APP_SLUG__-common'
+import { makeSessionModel } from '../../models/session.js'
 import type { Context } from '../../types.js'
 
-export const add = handleBody<AddItemPayload>(async (payload, context, req) => {
-  const ctx = context as Context
-  const { sid } = req.params as SessionParams
-  const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
+const handle = handlers<Context>()
 
-  const item: SessionItem = {
-    id: randomUUID(),
-    sessionId: sid,
-    text: payload.text,
-    createdAt: new Date().toISOString(),
-  }
-
-  return await resource.create(item)
-})
+export const add = handle.body(session.add, async (payload, context, request) =>
+  await makeSessionModel(context, request.params.sid).add(payload.text))

package/template/sources/api/src/app/session/list.ts

@@ -1,15 +1,9 @@
-import { handleParams } from '@owlmeans/server-app'
-import type { SessionItem, SessionParams } from '__APP_SLUG__-common'
-import { SESSION_ITEMS } from '../../consts.js'
+import { handlers } from '@owlmeans/server-app'
+import { session } from '__APP_SLUG__-common'
+import { makeSessionModel } from '../../models/session.js'
 import type { Context } from '../../types.js'
 
-export const list = handleParams<SessionParams>(async (params, context) => {
-  const ctx = context as Context
-  const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
+const handle = handlers<Context>()
 
-  // The static resource lists every record; filter to this session and sort newest first.
-  const { items } = await resource.list<SessionItem>()
-  return items
-    .filter(item => item.sessionId === params.sid)
-    .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
-})
+export const list = handle.params(session.list, async (params, context) =>
+  await makeSessionModel(context, params.sid).list())

package/template/sources/api/src/app/session/remove.ts

@@ -1,18 +1,9 @@
-import { handleParams } from '@owlmeans/server-app'
-import type { ItemParams, SessionItem } from '__APP_SLUG__-common'
-import { SESSION_ITEMS } from '../../consts.js'
+import { handlers } from '@owlmeans/server-app'
+import { session } from '__APP_SLUG__-common'
+import { makeSessionModel } from '../../models/session.js'
 import type { Context } from '../../types.js'
 
-export const remove = handleParams<ItemParams>(async (params, context) => {
-  const ctx = context as Context
-  const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
+const handle = handlers<Context>()
 
-  const existing = await resource.load<SessionItem>(params.id)
-  // Only remove the item if it belongs to the requesting session.
-  if (existing == null || existing.sessionId !== params.sid) {
-    return { removed: false }
-  }
-
-  await resource.delete(params.id)
-  return { removed: true }
-})
+export const remove = handle.params(session.remove, async (params, context) =>
+  await makeSessionModel(context, params.sid).remove(params.id))

package/template/sources/api/src/config.ts

@@ -1,8 +1,15 @@
 import { config } from '@owlmeans/server-app'
 import { APP_API, commonConfig } from '__APP_SLUG__-common'
 import type { Config } from './types.js'
+// The module augmentation that gives the config its `log` field — a side-effect import only.
+import type {} from '@owlmeans/log'
 
 // The server listens on the APP_API service route's port (3000), declared in common/config.ts.
 const cfg = config<Config>(APP_API, commonConfig as Config)
 
+// The log level comes from the runtime environment, never from code: `info` unless LOG_LEVEL
+// says otherwise; LOG_DEBUG lists scopes forced to debug (`*` for all). Bun reads
+// `sources/api/.env` on its own.
+cfg.log = { level: process.env.LOG_LEVEL || 'info', debug: process.env.LOG_DEBUG ?? '' }
+
 export default cfg

package/template/sources/api/src/context.bare.ts

@@ -0,0 +1,11 @@
+import { makeContext as makeBasicContext } from '@owlmeans/server-app'
+import type { Config, Context } from './types.js'
+
+/**
+ * Where the app's resources are registered. `@owlmeans/static-resource` is already a dependency,
+ * so `appendStaticResource<C, T>(context, ALIAS)` gives you an in-memory store with no database
+ * behind it; a mongo/postgres resource takes its place once the data has to outlive the process.
+ * Whatever you append here must also widen `Context` in `types.ts`, or the getter will not exist.
+ */
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =>
+  makeBasicContext<C, T>(cfg, true)

package/template/sources/api/src/context.ts

@@ -10,9 +10,5 @@ export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =
   // data lives in process memory and is cleared when the api restarts.
   appendStaticResource<C, T>(context, SESSION_ITEMS)
 
-  // A child context has to inherit THIS factory, not the layer's — otherwise a derived context
-  // is built without the resource registered above and every lookup on it throws.
-  context.makeContext = makeContext as typeof context.makeContext
-
   return context
 }

package/template/sources/api/src/entrypoints.bare.ts

@@ -0,0 +1,4 @@
+import { entrypoints } from '@owlmeans/server-app'
+
+// The bare shell has no API declarations yet. Bind new protocols here as they are added.
+export const appBindings = [...entrypoints]

package/template/sources/api/src/entrypoints.ts

@@ -0,0 +1,13 @@
+import { entrypoints } from '@owlmeans/server-app'
+import { bind } from '@owlmeans/server-entrypoint'
+import { appProtocols } from '__APP_SLUG__-common'
+import * as handlers from './app/session/index.js'
+
+/** Local server bindings for the shared session protocol tree. */
+export const appBindings = [
+  ...entrypoints,
+  bind(appProtocols.api.session.base),
+  bind(appProtocols.api.session.list, handlers.list),
+  bind(appProtocols.api.session.add, handlers.add),
+  bind(appProtocols.api.session.remove, handlers.remove),
+]

package/template/sources/api/src/index.ts

@@ -1,9 +1,15 @@
+import { logger } from '@owlmeans/log'
 import { main } from '@owlmeans/server-app'
 import config from './config.js'
 import { makeContext } from './context.js'
-import { appModules } from './modules.js'
+import { appBindings } from './entrypoints.js'
 import type { Config, Context } from './types.js'
 
+const log = logger('api')
+
 const context = makeContext<Config, Context>(config)
 
-main<{}, Config, Context>(context, appModules)
+main<{}, Config, Context>(context, appBindings).catch(error => {
+  log.error('Start failed', error)
+  process.exit(1)
+})

package/template/sources/api/src/models/session/types.ts

@@ -0,0 +1,14 @@
+import type { SessionItem } from '__APP_SLUG__-common'
+
+/**
+ * The items of ONE browser session. The session id is bound when the model is built, so no
+ * member can reach another session's items; the member names are the session endpoints' keys.
+ */
+export interface SessionModel {
+  /** This session's items, newest first. */
+  list: () => Promise<SessionItem[]>
+  /** Store a new item under this session. */
+  add: (text: string) => Promise<SessionItem>
+  /** Remove an item — only when it belongs to this session. */
+  remove: (id: string) => Promise<{ removed: boolean }>
+}