@owlmeans/create-app 0.1.18-rc.13 → 0.1.18-rc.15

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

@@ -14,21 +14,28 @@ A minimal OwlMeans app is a **bun-workspace monorepo with three packages**:
 ```
 sources/
 ├── common/   # shared entrypoints (routes), AJV schemas, types, config — the single source of truth
+│             #   entrypoints.ts
 ├── api/      # @owlmeans/server-app backend; handlers attached to the shared entrypoints
+│             #   context.ts, entrypoints.ts, app/<area>/*, index.ts
 └── web/      # @owlmeans/web-panel + shadcn UI; screens attached to the same entrypoints
+              #   context.ts, entrypoints.ts, nav.ts, layout/, screens/, render.tsx, index.tsx
 ```
 
-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.
+Three workspaces is the whole shape — a backend that needs its own long-running worker or a second
+API adds a workspace beside them and shares the same `common`.
+
+The full, runnable walkthrough (scaffolded **and** manual) lives in the
+[OwlMeans getting-started guide](https://github.com/owlmeans/common/blob/main/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 = [
+// common/entrypoints.ts — declaration + validation, no implementation
+export const sessionEntrypoints = [
   entrypoint(route(session.base, '/session')),
   entrypoint(route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
     filter(params<SessionParams>(SessionParamsSchema))),
@@ -38,17 +45,25 @@ export const sessionModules = [
 ```
 
 ```ts
-// api/modules.ts — attach handlers
-elevate(sessionModules, session.list, handlers.list)
-export const appModules = [...modules, ...sessionModules]        // `modules` = framework defaults
+// api/entrypoints.ts — attach handlers
+elevate(sessionEntrypoints, session.list, handlers.list)
+export const appEntrypoints = [...entrypoints, ...sessionEntrypoints]   // `entrypoints` = framework defaults
 ```
 
 ```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)))
+// web/entrypoints.ts — attach screen components, plus call-only elevation for backend routes
+const entrypoints = [...baseEntrypoints, ...sessionEntrypoints]   // `baseEntrypoints` from web-panel
+elevate(entrypoints, session.list)                                // callable from the client
+entrypoints.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
+export const appEntrypoints = entrypoints
 ```
 
+A route declaration is plain data: its `path` is the SEGMENT it contributes under its `parent`, and
+nothing ever rewrites it. `session.list` reads `/:sid/items` under `session.base`'s `/session`,
+under the api service's `base: 'api'` — so the address is `GET /api/session/:sid/items`, computed
+on demand by whoever asks. `elevate` is idempotent, so re-elevating an alias is allowed and guards
+given at elevation are added to the declared ones.
+
 Change a route or schema in `common` and both sides stay in sync. See [[entrypoint]], [[route]],
 [[server-app]], [[web-client]], [[web-panel]].
 
@@ -61,6 +76,8 @@ prefixes API routes with `/api`:
 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 }
+cfg.alias = APP
+cfg.security = { unsecure: true }   // local dev serves the API over plain HTTP
 export const commonConfig = cfg
 ```
 
@@ -75,9 +92,20 @@ appendStaticResource(context, SESSION_ITEMS)    // @owlmeans/static-resource —
 ```
 
 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]].
+req). Read/write `ctx.getStaticResource<T>(alias)` — the full resource contract
+(`get/load/list/count/create/update/save/delete/take/purge`), so the resource answers the whole
+question rather than the handler filtering afterwards:
+
+```ts
+const { items } = await resource.list(
+  { sessionId: params.sid },
+  { sort: [{ field: 'createdAt', order: 'desc' }] }
+)
+```
+
+`list` returns `{ items, total }`; the in-memory backends are unpaged unless a `size` is asked for.
+`main(context, appEntrypoints)` starts the server. See [[static-resource]], [[server-app]],
+[[resource]].
 
 Swap `@owlmeans/static-resource` for [[mongo-resource]] / [[redis-resource]] when you need
 persistence — the handler shape is identical.
@@ -86,19 +114,38 @@ persistence — the handler shape is identical.
 
 `@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`:
+`@/components/ui/{alert,button,card,input,label,navigation-menu,progress}`; copy those into `src/`.
+Routing resolves itself from the active router plugin, so `PanelApp` takes no router prop —
+`render.tsx` is one line and `index.tsx` calls it:
 
 ```tsx
-basicRender(<PanelApp context={context} provide={provide} />)
+// render.tsx — import { render as basicRender } from '@owlmeans/web-client'
+basicRender(<PanelApp context={context} />)
 ```
 
 `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]`.
+A parent `BASE` route renders the layout via `handler(MainLayout)`; `HOME` is its default child, declared `frontend({ default: true, parent: BASE })`.
+`index.tsx` calls `context.registerEntrypoints(appEntrypoints)` and `context.serviceRoute(...)` for
+each service, then renders.
+
+Screens address the backend through three explicit verbs on the entrypoint:
+
+```tsx
+const items = await ctx.entrypoint<ClientEntrypoint<Item[]>>(session.list).call({ params: { sid } })
+const { value, outcome } = await ctx.entrypoint<ClientEntrypoint<Item>>(session.add).invoke({ body })
+const href = await ctx.entrypoint<ClientEntrypoint<string>>(web.about).url()
+```
+
+`call` resolves to the VALUE and throws the reply's error; `invoke` gives `{ value, outcome }` when
+the outcome decides what happens next; `url` gives the address (`{ absolute: true }` forces a fully
+qualified one). A screen entrypoint answers `url()` and refuses `call()` — a screen is navigated to.
 See [[web-panel]], [[web-client]], [[shadcn-web]], [[client-entrypoint]].
 
+The screen keeps nothing in component state: `makeContext` registers a `@owlmeans/state` resource,
+the fetch writes what came back into it with `store.replace(items)`, and `useStoreList` renders the
+live subscription. See [[state]].
+
 ## Authentication
 
 This shape is intentionally **auth-free**. To add it: `@owlmeans/server-auth` + `@owlmeans/client-auth`

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`. Move genuinely non-obvious dispatch hints there.
+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/reuse-code/SKILL.md

@@ -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,13 +47,31 @@ 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.12` 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:
+
+```json
+"dependencies": {
+  "@owlmeans/queue": "^0.1.18-rc.9"
+}
+```
+
+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.
 
 ## 3. No package? Reuse code and extract an abstraction
@@ -60,5 +86,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,7 +27,8 @@ 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.
@@ -46,11 +47,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
 

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, put it where `AGENTS.md` loads it every session.
+
 `.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
@@ -38,20 +51,35 @@ 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`.
+
 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 frontmatter parser in `@owlmeans/agent-skills` stores:
+`name`, `description`, `license`, `compatibility`, `allowed-tools` and nested `metadata`.
+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 what that parser stores 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.
 
 ## Refresh the Claude Code links
 
@@ -61,9 +89,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
 

package/template/_bare.json

@@ -0,0 +1,23 @@
+{
+  "remove": [
+    "sources/common/src/types.ts",
+    "sources/common/src/schemas.ts",
+    "sources/api/src/consts.ts",
+    "sources/api/src/app",
+    "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

@@ -9,3 +9,6 @@ bun.lockb
 # 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

@@ -10,7 +10,8 @@
   "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/src/app/session/list.ts

@@ -7,9 +7,11 @@ export const list = handleParams<SessionParams>(async (params, context) => {
   const ctx = context as Context
   const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
 
-  // The static resource lists every record; filter to this session and sort newest first.
-  const { items } = await resource.list<SessionItem>()
+  // The resource answers the whole question — this session's items, newest first.
+  const { items } = await resource.list(
+    { sessionId: params.sid },
+    { sort: [{ field: 'createdAt', order: 'desc' }] }
+  )
+
   return items
-    .filter(item => item.sessionId === params.sid)
-    .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1))
 })

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

@@ -7,7 +7,7 @@ export const remove = handleParams<ItemParams>(async (params, context) => {
   const ctx = context as Context
   const resource = ctx.getStaticResource<SessionItem>(SESSION_ITEMS)
 
-  const existing = await resource.load<SessionItem>(params.id)
+  const existing = await resource.load(params.id)
   // Only remove the item if it belongs to the requesting session.
   if (existing == null || existing.sessionId !== params.sid) {
     return { removed: false }

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,6 @@
+import { entrypoints } from '@owlmeans/server-app'
+import { sharedEntrypoints } from '__APP_SLUG__-common'
+
+// Handlers attach to the shared declarations, never to a route re-declared here:
+// `elevate(sharedEntrypoints, alias, handler)` from '@owlmeans/server-app'.
+export const appEntrypoints = [...entrypoints, ...sharedEntrypoints]

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

@@ -0,0 +1,11 @@
+import { elevate, entrypoints } from '@owlmeans/server-app'
+import { session, sessionEntrypoints } from '__APP_SLUG__-common'
+import * as handlers from './app/session/index.js'
+
+// Attach handler implementations to the shared entrypoint declarations.
+elevate(sessionEntrypoints, session.base)
+elevate(sessionEntrypoints, session.list, handlers.list)
+elevate(sessionEntrypoints, session.add, handlers.add)
+elevate(sessionEntrypoints, session.remove, handlers.remove)
+
+export const appEntrypoints = [...entrypoints, ...sessionEntrypoints]

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

@@ -1,9 +1,9 @@
 import { main } from '@owlmeans/server-app'
 import config from './config.js'
 import { makeContext } from './context.js'
-import { appModules } from './modules.js'
+import { appEntrypoints } from './entrypoints.js'
 import type { Config, Context } from './types.js'
 
 const context = makeContext<Config, Context>(config)
 
-main<{}, Config, Context>(context, appModules)
+main<{}, Config, Context>(context, appEntrypoints)

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

@@ -0,0 +1,5 @@
+import type { AppConfig, AppContext } from '@owlmeans/server-app'
+
+export interface Config extends AppConfig {}
+
+export interface Context<C extends Config = Config> extends AppContext<C> {}

package/template/sources/common/src/consts.bare.ts

@@ -0,0 +1,8 @@
+/** Service aliases shared between web and api. */
+export const APP = '__APP_SLUG__'
+export const APP_WEB = '__APP_SLUG__-web'
+export const APP_API = '__APP_SLUG__-api'
+
+/** Local development ports. */
+export const WEB_PORT = 3001
+export const API_PORT = 3000

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

@@ -0,0 +1,8 @@
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+
+/**
+ * The entrypoint declarations both sides share: the api elevates them with handlers, the web
+ * elevates them with screens or just calls them. Routes resolve under the api service `base`
+ * (`/api`), so an `entrypoint(route(alias, '/items', ...))` added here answers on `/api/items`.
+ */
+export const sharedEntrypoints: CommonEntrypoint[] = []

package/template/sources/common/src/{modules.ts → entrypoints.ts}

@@ -9,7 +9,7 @@ import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
  * elevates them with screen components and calls them. Routes resolve under the
  * api service `base` (`/api`), so e.g. `session.list` → `GET /api/session/:sid/items`.
  */
-export const sessionModules = [
+export const sessionEntrypoints = [
   entrypoint(route(session.base, '/session')),
   entrypoint(
     route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),