@owlmeans/create-app 0.1.18-rc.65 → 0.1.18-rc.66

package/README.md

@@ -9,7 +9,7 @@ bun create @owlmeans/app my-app
 # or
 yarn create @owlmeans/app my-app
 # or
-npx @owlmeans/create-app@^0.1.18-rc.65 my-app
+npx @owlmeans/create-app@^0.1.18-rc.66 my-app
 ```
 
 ## What it generates

package/build/consts.local.d.ts

@@ -1,5 +1,5 @@
 import type { PackageManager } from './types.js';
-export declare const HELP = "@owlmeans/create-app \u2014 scaffold a fullstack OwlMeans Common app\n\nUsage:\n  npm create @owlmeans/app@latest <dir> [options]\n  bun create @owlmeans/app <dir> [options]\n  yarn create @owlmeans/app <dir> [options]\n  npx @owlmeans/create-app@^0.1.18-rc.65 <dir> [options]\n\nGenerates three workspaces (common + api + web) with shadcn UI navigation and\nlayout, no authentication, and a session-scoped in-memory resource on the\nbackend. With --bare the demo is left out and only the working shell remains.\nAgent skills are deployed into the project by default.\n\nOptions:\n  --name <name>       human-readable app name (default: derived from <dir>)\n  --slug <slug>       package slug (default: derived from <dir>)\n  --lang <code>       language of the generated UI text (default: en)\n  --description <t>   one-line project description for the generated docs\n  --bare              scaffold the shell only \u2014 no example/demo code\n  --pm <bun|npm|yarn> package manager (default: bun)\n  --no-install        do not install dependencies\n  --no-skills         do not deploy agent skills via @owlmeans/agent-skills\n  --no-git            do not run \"git init\"\n  --yes, -y           proceed without prompts / into a non-empty directory\n  --help, -h          show this help\n";
+export declare const HELP = "@owlmeans/create-app \u2014 scaffold a fullstack OwlMeans Common app\n\nUsage:\n  npm create @owlmeans/app@latest <dir> [options]\n  bun create @owlmeans/app <dir> [options]\n  yarn create @owlmeans/app <dir> [options]\n  npx @owlmeans/create-app@^0.1.18-rc.66 <dir> [options]\n\nGenerates three workspaces (common + api + web) with shadcn UI navigation and\nlayout, no authentication, and a session-scoped in-memory resource on the\nbackend. With --bare the demo is left out and only the working shell remains.\nAgent skills are deployed into the project by default.\n\nOptions:\n  --name <name>       human-readable app name (default: derived from <dir>)\n  --slug <slug>       package slug (default: derived from <dir>)\n  --lang <code>       language of the generated UI text (default: en)\n  --description <t>   one-line project description for the generated docs\n  --bare              scaffold the shell only \u2014 no example/demo code\n  --pm <bun|npm|yarn> package manager (default: bun)\n  --no-install        do not install dependencies\n  --no-skills         do not deploy agent skills via @owlmeans/agent-skills\n  --no-git            do not run \"git init\"\n  --yes, -y           proceed without prompts / into a non-empty directory\n  --help, -h          show this help\n";
 export declare const PMS: PackageManager[];
 /** Dotfiles/dirs are shipped with an underscore prefix so npm does not strip them from the tarball. */
 export declare const DOTFILE_RENAMES: Record<string, string>;

package/build/consts.local.js

@@ -5,7 +5,7 @@ Usage:
   npm create @owlmeans/app@latest <dir> [options]
   bun create @owlmeans/app <dir> [options]
   yarn create @owlmeans/app <dir> [options]
-  npx @owlmeans/create-app@^0.1.18-rc.65 <dir> [options]
+  npx @owlmeans/create-app@^0.1.18-rc.66 <dir> [options]
 
 Generates three workspaces (common + api + web) with shadcn UI navigation and
 layout, no authentication, and a session-scoped in-memory resource on the

package/build/run.js

@@ -50,7 +50,7 @@ export const run = async (args) => {
         log(args.install
             ? '\nDeploying agent skills via @owlmeans/agent-skills…'
             : '\nDeploying harness guidance via @owlmeans/agent-skills (general skills only — re-run'
-                + '\n`npx @owlmeans/agent-skills@^0.1.18-rc.56` after installing to add the package-specific ones)…');
+                + '\n`npx @owlmeans/agent-skills@^0.1.18-rc.57` after installing to add the package-specific ones)…');
         try {
             const result = await installSkills({
                 dir: dest,
@@ -62,7 +62,7 @@ export const run = async (args) => {
                 help: false,
             });
             if (result.code !== 0) {
-                process.stderr.write(`  agent-skills exited with code ${result.code} — you can re-run \`npx @owlmeans/agent-skills@^0.1.18-rc.56\` later.\n`);
+                process.stderr.write(`  agent-skills exited with code ${result.code} — you can re-run \`npx @owlmeans/agent-skills@^0.1.18-rc.57\` later.\n`);
             }
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/create-app",
-  "version": "0.1.18-rc.65",
+  "version": "0.1.18-rc.66",
   "license": "MIT",
   "description": "Scaffold a fullstack OwlMeans Common app — common + api + web workspaces, shadcn UI navigation/layout, no auth, and a session-scoped in-memory resource, or --bare for the demo-free shell. Also usable programmatically via scaffold(). Deploys agent skills via @owlmeans/agent-skills by default.",
   "type": "module",
@@ -31,7 +31,7 @@
     "THIRD-PARTY-NOTICES.txt"
   ],
   "dependencies": {
-    "@owlmeans/agent-skills": "^0.1.18-rc.56"
+    "@owlmeans/agent-skills": "^0.1.18-rc.57"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/template/AGENTS.md

@@ -114,7 +114,7 @@ from the installed `@owlmeans/*` packages. Agents load a skill by topic, or you
 explicitly. Copilot and Codex read `.agents/skills/` directly; Claude Code reads the generated
 symlinks in `.claude/skills/` (see "Claude Code" below).
 
-- After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.56` to refresh
+- After adding or updating any `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.57` to refresh
   the deployed skills.
 - `/logging` — before adding any log line, catch block or `console` call (mechanics: `/log`).
 - Deployed files carry an `AUTO-GENERATED` banner and are refreshed in place — never hand-edit them.

package/template/README.bare.md

@@ -66,5 +66,5 @@ them; write your own guidance as separate, un-bannered files. Refresh after addi
 `@owlmeans/*` packages:
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.56
+npx @owlmeans/agent-skills@^0.1.18-rc.57
 ```

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

@@ -178,5 +178,11 @@ Then read the diff once for what no grep sees: a second exported function of one
 that takes the same first argument as its siblings, a private helper exposed on the interface, a
 bound object built in a loop, a barrel re-exporting a `.local` file.
 
-Classification details, folder decisions and the pitfalls of moving code into closures: `reference.md`
-(in the OwlMeans repositories).
+Classification details, folder decisions and the pitfalls of moving code into closures: the
+`code-structure-reference` part ([parts/code-structure-reference.md](parts/code-structure-reference.md)).
+
+## Parts
+
+| Part | Load it when |
+|---|---|
+| [code-structure-reference](parts/code-structure-reference.md) | classifying a declaration, deciding a folder, converting a module, or moving code into closures |

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

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

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

@@ -47,7 +47,7 @@ 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@^0.1.18-rc.56` to deploy its
+adding an `@owlmeans/*` dependency, run `npx @owlmeans/agent-skills@^0.1.18-rc.57` 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

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

@@ -39,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
 ```
 
@@ -80,15 +80,67 @@ or the file stops parsing and the skill silently disappears from every agent.
 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 `/`
+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
 
 After creating, renaming, or deleting a skill, run:

package/template/sources/api/package.json

@@ -11,13 +11,13 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@owlmeans/log": "^0.1.18-rc.3",
-    "@owlmeans/server-app": "^0.1.18-rc.57",
-    "@owlmeans/static-resource": "^0.1.18-rc.39",
+    "@owlmeans/log": "^0.1.18-rc.4",
+    "@owlmeans/server-app": "^0.1.18-rc.58",
+    "@owlmeans/static-resource": "^0.1.18-rc.40",
     "__APP_SLUG__-common": "workspace:^"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.18-rc.7",
+    "@owlmeans/dep-config": "^0.1.18-rc.8",
     "@types/node": "^26.6.4",
     "typescript": "^7.0.2"
   }

package/template/sources/common/package.json

@@ -19,15 +19,15 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@owlmeans/config": "^0.1.18-rc.44",
-    "@owlmeans/entrypoint": "^0.1.18-rc.41",
-    "@owlmeans/error": "^0.1.18-rc.38",
-    "@owlmeans/resource": "^0.1.18-rc.40",
-    "@owlmeans/route": "^0.1.18-rc.35",
+    "@owlmeans/config": "^0.1.18-rc.45",
+    "@owlmeans/entrypoint": "^0.1.18-rc.42",
+    "@owlmeans/error": "^0.1.18-rc.39",
+    "@owlmeans/resource": "^0.1.18-rc.41",
+    "@owlmeans/route": "^0.1.18-rc.36",
     "ajv": "^8.20.0"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.18-rc.7",
+    "@owlmeans/dep-config": "^0.1.18-rc.8",
     "@types/node": "^26.6.4",
     "typescript": "^7.0.2"
   }

package/template/sources/web/package.json

@@ -11,17 +11,17 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@owlmeans/client": "^0.1.18-rc.56",
-    "@owlmeans/client-config": "^0.1.18-rc.45",
-    "@owlmeans/client-context": "^0.1.18-rc.52",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.51",
-    "@owlmeans/client-i18n": "^0.1.18-rc.55",
-    "@owlmeans/entrypoint": "^0.1.18-rc.41",
-    "@owlmeans/log": "^0.1.18-rc.3",
-    "@owlmeans/route": "^0.1.18-rc.35",
-    "@owlmeans/state": "^0.1.18-rc.39",
-    "@owlmeans/web-client": "^0.1.18-rc.67",
-    "@owlmeans/web-panel": "^0.1.18-rc.78",
+    "@owlmeans/client": "^0.1.18-rc.57",
+    "@owlmeans/client-config": "^0.1.18-rc.46",
+    "@owlmeans/client-context": "^0.1.18-rc.53",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.52",
+    "@owlmeans/client-i18n": "^0.1.18-rc.56",
+    "@owlmeans/entrypoint": "^0.1.18-rc.42",
+    "@owlmeans/log": "^0.1.18-rc.4",
+    "@owlmeans/route": "^0.1.18-rc.36",
+    "@owlmeans/state": "^0.1.18-rc.40",
+    "@owlmeans/web-client": "^0.1.18-rc.68",
+    "@owlmeans/web-panel": "^0.1.18-rc.79",
     "@radix-ui/react-dropdown-menu": "^2.1.24",
     "@radix-ui/react-label": "^2.1.15",
     "@radix-ui/react-navigation-menu": "^1.2.22",
@@ -41,7 +41,7 @@
     "tailwindcss": "^4.3.3"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "^0.1.18-rc.7",
+    "@owlmeans/dep-config": "^0.1.18-rc.8",
     "@tailwindcss/vite": "^4.3.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",