@owlmeans/agent-skills 0.1.9 → 0.1.10

package/agent-meta/instructions/getting-started.instructions.md

@@ -0,0 +1,62 @@
+---
+description: "How to build a fullstack OwlMeans Common app — the common/api/web three-workspace pattern, server and web context bootstrap, shared entrypoints + elevate(), and a session-scoped in-memory resource via @owlmeans/static-resource. Apply when starting a new OwlMeans project or wiring web↔api."
+applyTo: "**/modules.ts, **/context.ts, **/config.ts, **/render.tsx, **/index.tsx, **/sources/**"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Building a fullstack OwlMeans Common app
+
+A minimal app is a **bun-workspace monorepo with three packages**:
+
+- `sources/common` — shared **entrypoints** (routes), AJV schemas, types and config. The single
+  source of truth.
+- `sources/api` — `@owlmeans/server-app` backend; handlers attached to the shared entrypoints.
+- `sources/web` — `@owlmeans/web-panel` + shadcn UI; screens attached to the same entrypoints.
+
+Full walkthrough: `docs/getting-started.md`. To generate it: `npm create @owlmeans/app`.
+
+## One contract, two sides
+
+Declare each route once in `common`, then `elevate()` it on both sides:
+
+```ts
+// common/modules.ts
+export const sessionModules = [
+  entrypoint(route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
+    filter(params(SessionParamsSchema))),
+]
+// api/modules.ts   → elevate(sessionModules, session.list, handlers.list)
+// web/modules.ts   → elevate(modules, session.list)  // call-only; screens via handler(Component)
+```
+
+## Config
+
+`common/config.ts` registers both services; `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)
+```
+
+## Backend + in-memory data
+
+```ts
+const context = makeContext(cfg, true)
+appendStaticResource(context, SESSION_ITEMS)   // @owlmeans/static-resource — no DB
+```
+
+Handlers (`handleRequest`/`handleBody`/`handleParams`) use `ctx.getStaticResource<T>(alias)`.
+`static-resource.list()` accepts no criteria — list all and filter in JS. `main(context, appModules)`
+starts the server. Swap for `@owlmeans/mongo-resource` / `redis-resource` when you need persistence.
+
+## Web (shadcn)
+
+`web-panel`'s `PanelApp` is shadcn/Tailwind v4. The app **provides** `@/lib/utils` and
+`@/components/ui/{alert,button,card,input,label,progress}` at the `@` alias (→ `src`). Render with
+`provide` from `@owlmeans/web-client`: `basicRender(<PanelApp context={context} provide={provide} />)`.
+A parent `BASE` route renders the layout via `handler(Layout)`; `HOME` is its default child. Screens
+call the API with `context.entrypoint(alias).call({ params, body })`.
+
+This shape is auth-free by design; add `@owlmeans/server-auth` + `@owlmeans/client-auth` and
+`guard(...)` when needed.

package/agent-meta/instructions/scaffolding.instructions.md

@@ -0,0 +1,47 @@
+---
+description: "How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags and output, plus the manual alternative. Apply when creating or bootstrapping a fresh OwlMeans app."
+applyTo: "**/package.json, **/README.md"
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Scaffolding a new OwlMeans Common project
+
+Two paths produce the same minimal fullstack project (`common` + `api` + `web`, shadcn UI
+navigation/layout, **no auth**, a **session-scoped in-memory resource**). Reference:
+`docs/getting-started.md`.
+
+## Path 1 — `@owlmeans/create-app`
+
+```sh
+npm create @owlmeans/app@latest my-app   # or: bun create @owlmeans/app my-app
+npx @owlmeans/create-app my-app
+```
+
+By default it copies the template, runs `git init`, installs dependencies, and deploys agent
+guidance via `@owlmeans/agent-skills` (`.claude/skills/` + `.github/instructions/`).
+
+Flags: `--name`, `--pm <bun|npm|yarn>` (default `bun`), `--no-install`, `--no-skills`, `--no-git`,
+`--yes`. Run with `cd my-app && bun run dev` (API :3000, web :3001).
+
+Prefer this over hand-writing boilerplate when the user wants to start a new OwlMeans app.
+
+## Path 2 — manual
+
+Follow Option B in `docs/getting-started.md`: bun workspace → `common` (entrypoints/schemas/config)
+→ `api` (`@owlmeans/server-app` + `appendStaticResource` handlers + `main`) → `web`
+(`@owlmeans/web-panel` + shadcn `@`-provided primitives + layout/nav/screens). Finish with
+`npx @owlmeans/agent-skills`.
+
+## Generated layout
+
+```
+my-app/
+├── package.json            # bun workspaces: sources/*
+├── sources/common/         # consts, types, schemas, config, modules
+├── sources/api/            # context (appendStaticResource), app/session/*, modules, index
+└── sources/web/            # vite + tailwind v4, components/ui/*, layout, nav, screens, render
+```
+
+Session items live in `@owlmeans/static-resource`, namespaced by a client-generated `sid` in
+`localStorage` — no database, no authentication.

package/agent-meta/instructions/shadcn-versions.instructions.md

@@ -1,6 +1,7 @@
 ---
 description: How to update Tailwind CSS, shadcn UI primitives, and related UI lib versions across shadcn-based OwlMeans packages. Distinct from the @owlmeans/* version sync (see versions.instructions.md).
 applyTo: "**/components.json"
+scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

package/agent-meta/instructions/shadcn-web.instructions.md

@@ -1,6 +1,7 @@
 ---
 description: How to build and maintain shadcn UI + Tailwind v4 web packages in OwlMeans Common. Load when editing components.json, tailwind.config.*, globals.css, or files under components/ui/.
 applyTo: "**/components.json, **/tailwind.config.{ts,js,mjs}, **/globals.css, **/components/ui/**, **/@/lib/utils.ts"
+scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

package/agent-meta/manifest.json

@@ -1,35 +1,63 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/agent-skills",
-  "version": "0.1.9",
-  "generatedAt": "2026-06-14T13:34:06.135Z",
+  "version": "0.1.10",
+  "generatedAt": "2026-06-17T09:37:28.174Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
+    {
+      "kind": "skill",
+      "name": "getting-started",
+      "category": "general",
+      "file": "skills/getting-started/SKILL.md",
+      "canonicalPath": ".claude/skills/getting-started/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "shadcn-web",
-      "category": "multi-package",
+      "category": "general",
       "file": "skills/shadcn-web/SKILL.md",
       "canonicalPath": ".claude/skills/shadcn-web/SKILL.md"
     },
+    {
+      "kind": "skill",
+      "name": "scaffolding",
+      "category": "general",
+      "file": "skills/scaffolding/SKILL.md",
+      "canonicalPath": ".claude/skills/scaffolding/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "shadcn-versions",
-      "category": "multi-package",
+      "category": "general",
       "file": "skills/shadcn-versions/SKILL.md",
       "canonicalPath": ".claude/skills/shadcn-versions/SKILL.md"
     },
+    {
+      "kind": "instruction",
+      "name": "getting-started",
+      "category": "general",
+      "file": "instructions/getting-started.instructions.md",
+      "canonicalPath": ".github/instructions/getting-started.instructions.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "scaffolding",
+      "category": "general",
+      "file": "instructions/scaffolding.instructions.md",
+      "canonicalPath": ".github/instructions/scaffolding.instructions.md"
+    },
     {
       "kind": "instruction",
       "name": "shadcn-versions",
-      "category": "multi-package",
+      "category": "general",
       "file": "instructions/shadcn-versions.instructions.md",
       "canonicalPath": ".github/instructions/shadcn-versions.instructions.md"
     },
     {
       "kind": "instruction",
       "name": "shadcn-web",
-      "category": "multi-package",
+      "category": "general",
       "file": "instructions/shadcn-web.instructions.md",
       "canonicalPath": ".github/instructions/shadcn-web.instructions.md"
     }

package/agent-meta/skills/getting-started/SKILL.md

@@ -0,0 +1,104 @@
+---
+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
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Getting started with OwlMeans Common — fullstack app 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)))),
+]
+```
+
+```ts
+// api/modules.ts — attach handlers
+elevate(sessionModules, session.list, handlers.list)
+export const appModules = [...modules, ...sessionModules]        // `modules` = 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)))
+```
+
+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: `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`:
+
+```tsx
+basicRender(<PanelApp context={context} provide={provide} />)
+```
+
+`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]].

package/agent-meta/skills/scaffolding/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: scaffolding
+description: How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags, what it generates, and the manual alternative. Use when asked to create/bootstrap/start a new OwlMeans app or set up a fresh project.
+user-invocable: true
+scope: general
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Scaffolding a new OwlMeans Common project
+
+Two paths produce the same minimal fullstack project (`common` + `api` + `web`, shadcn UI
+navigation/layout, **no auth**, a **session-scoped in-memory resource**). The full reference is
+[`docs/getting-started.md`](../../../docs/getting-started.md); the framework shape is [[getting-started]].
+
+## Path 1 — `@owlmeans/create-app` (one command)
+
+```sh
+npm create @owlmeans/app@latest my-app
+bun create @owlmeans/app my-app
+yarn create @owlmeans/app my-app
+npx @owlmeans/create-app my-app
+```
+
+By default it copies the template, runs `git init`, installs dependencies, and **deploys agent
+guidance** into the project via [[bun]]-installed `@owlmeans/agent-skills` (`.claude/skills/` +
+`.github/instructions/`).
+
+Flags: `--name <name>`, `--pm <bun|npm|yarn>` (default `bun`), `--no-install`, `--no-skills`,
+`--no-git`, `--yes`/`-y`, `--help`.
+
+Then run:
+
+```sh
+cd my-app && bun run dev      # API :3000, web :3001
+```
+
+**When an agent should use this:** the user asks to start/bootstrap/create a new OwlMeans app from
+nothing. Prefer it over hand-writing boilerplate. After it runs, point the user at the **Session**
+screen and `docs/getting-started.md`.
+
+## Path 2 — manual
+
+Follow **Option B** in [`docs/getting-started.md`](../../../docs/getting-started.md): create the bun
+workspace, then `common` (shared entrypoints/schemas/config), `api` (`@owlmeans/server-app` +
+`appendStaticResource` handlers + `main`), and `web` (`@owlmeans/web-panel` + shadcn `@`-provided
+primitives + layout/nav/screens). Finish with `npx @owlmeans/agent-skills` to add agent guidance.
+
+## What gets generated
+
+```
+my-app/
+├── package.json            # bun workspaces: sources/*
+├── sources/common/         # consts, types, schemas, config, modules (entrypoints)
+├── sources/api/            # context.ts (appendStaticResource), app/session/*, modules.ts, index.ts
+└── sources/web/            # vite + tailwind v4, components/ui/*, layout, nav, screens, render.tsx
+```
+
+The session demo stores items in `@owlmeans/static-resource`, namespaced by a client-generated
+`sid` kept in `localStorage` — no database, no authentication. See [[static-resource]],
+[[server-app]], [[web-panel]].

package/agent-meta/skills/shadcn-versions/SKILL.md

@@ -2,6 +2,7 @@
 name: shadcn-versions
 description: How to update versions of shadcn UI primitives, Tailwind CSS v4, and related UI libs across all shadcn-based OwlMeans web packages. Distinct from the @owlmeans/* package version sync (see [[versions]] skill). Use when bumping tailwind, shadcn components, or utility libs.
 allowed-tools: Bash(grep *), Bash(sed *), Bash(bun install)
+scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

package/agent-meta/skills/shadcn-web/SKILL.md

@@ -2,6 +2,7 @@
 name: shadcn-web
 description: How to build and maintain shadcn UI + Tailwind v4 web packages in the OwlMeans framework. Auto-invoked when editing components.json, tailwind.config.*, globals.css, or files under components/ui/. Use when creating a new shadcn-based web package or adding shadcn components.
 user-invocable: false
+scope: general
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
 

package/build/discover.d.ts

@@ -1,7 +1,7 @@
 export interface ManifestEntry {
     kind: 'skill' | 'instruction';
     name: string;
-    category: 'package-specific' | 'multi-package';
+    category: 'package-specific' | 'multi-package' | 'general';
     file: string;
     canonicalPath: string;
 }
@@ -16,7 +16,7 @@ export interface Manifest {
 export interface DiscoveredEntry {
     kind: 'skill' | 'instruction';
     name: string;
-    category: 'package-specific' | 'multi-package';
+    category: 'package-specific' | 'multi-package' | 'general';
     /** Absolute path to the embedded source file. */
     sourcePath: string;
     canonicalPath: string;

package/build/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,GAAG,aAAa,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,kBAAkB,GAAG,eAAe,CAAA;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,aAAa,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,aAAa,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,kBAAkB,GAAG,eAAe,CAAA;IAC9C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAA;CACjB;AA4FD,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,2BAA2B;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,mEAAmE;AACnE,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,OAAM,eAAoB,KAAG,eAAe,EA4CvF,CAAA"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,GAAG,aAAa,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,kBAAkB,GAAG,eAAe,GAAG,SAAS,CAAA;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,aAAa,EAAE,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,GAAG,aAAa,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,kBAAkB,GAAG,eAAe,GAAG,SAAS,CAAA;IAC1D,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;IACrB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAA;CACjB;AA4FD,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,2BAA2B;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,mEAAmE;AACnE,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,EAAE,OAAM,eAAoB,KAAG,eAAe,EA4CvF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/agent-skills",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "license": "MIT",
   "type": "module",
   "scripts": {

package/src/discover.ts

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 export interface ManifestEntry {
   kind: 'skill' | 'instruction'
   name: string
-  category: 'package-specific' | 'multi-package'
+  category: 'package-specific' | 'multi-package' | 'general'
   file: string
   canonicalPath: string
 }
@@ -22,7 +22,7 @@ export interface Manifest {
 export interface DiscoveredEntry {
   kind: 'skill' | 'instruction'
   name: string
-  category: 'package-specific' | 'multi-package'
+  category: 'package-specific' | 'multi-package' | 'general'
   /** Absolute path to the embedded source file. */
   sourcePath: string
   canonicalPath: string