@owlmeans/create-app 0.1.18-rc.4 → 0.1.18-rc.41

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

@@ -1,105 +1,45 @@
 ---
 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**:
-
-```
-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)))),
-]
-```
+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
-// api/modules.ts — attach handlers
-elevate(sessionModules, session.list, handlers.list)
-export const appModules = [...modules, ...sessionModules]        // `modules` = framework defaults
+// common/src/entrypoints.ts
+export const sessionProtocols = {
+  list: protocol(
+    route(session.list, '/session', backend()),
+    contract.request({ query: typed<SessionQuery>(SessionQuerySchema) }, typed<Session[]>())
+  ),
+}
 ```
 
 ```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)))
-```
-
-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`:
-
-```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/src/entrypoints.ts
+const api = handlers<Context>()
+export const serverBindings = [
+  ...frameworkEntrypoints,
+  bind(sessionProtocols.list, api.request(sessionProtocols.list, listSessions)),
+]
 ```
 
-api: `config(APP_API, commonConfig)` (+ `cfg.port`). web: `config(APP_WEB, commonConfig)`. See [[config]].
-
-## Backend bootstrap + in-memory data
-
 ```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]].
-
-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`:
+// web/src/entrypoints.ts
+export const clientBindings = [
+  ...frameworkEntrypoints,
+  ...bindAll(sessionProtocols),
+]
 
-```tsx
-basicRender(<PanelApp context={context} provide={provide} />)
+const sessions = await context.entrypoint(sessionProtocols.list).call({ query: { sid } })
 ```
 
-`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]].
+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.

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/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.32` 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.27"
+}
+```
+
+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,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
@@ -38,20 +51,43 @@ 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 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 +97,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 +130,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) — 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,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

@@ -3,14 +3,15 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "packageManager": "bun@1.3.14",
+  "packageManager": "bun@1.4.0",
   "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,12 +11,12 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@owlmeans/server-app": "^0.1.16",
-    "@owlmeans/static-resource": "^0.1.16",
+    "@owlmeans/server-app": "^0.1.18-rc.37",
+    "@owlmeans/static-resource": "^0.1.18-rc.29",
     "__APP_SLUG__-common": "workspace:^"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.16",
+    "@owlmeans/dep-config": "^0.1.18-rc.6",
     "@types/node": "^24.10.1",
     "typescript": "^7.0.2"
   }

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

@@ -1,13 +1,14 @@
 import { randomUUID } from 'node:crypto'
-import { handleBody } from '@owlmeans/server-app'
-import type { AddItemPayload, SessionItem, SessionParams } from '__APP_SLUG__-common'
+import { handlers } from '@owlmeans/server-app'
+import { session, type SessionItem } from '__APP_SLUG__-common'
 import { SESSION_ITEMS } from '../../consts.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>()
+
+export const add = handle.body(session.add, async (payload, context, request) => {
+  const { sid } = request.params
+  const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
 
   const item: SessionItem = {
     id: randomUUID(),

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

@@ -1,15 +1,18 @@
-import { handleParams } from '@owlmeans/server-app'
-import type { SessionItem, SessionParams } from '__APP_SLUG__-common'
+import { handlers } from '@owlmeans/server-app'
+import { session, type SessionItem } from '__APP_SLUG__-common'
 import { SESSION_ITEMS } from '../../consts.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>()
+
+export const list = handle.params(session.list, async (params, context) => {
+  const resource = context.getStaticResource<SessionItem>(SESSION_ITEMS)
+
+  // 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' }] }
+  )
 
-  // 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))
 })