@pikku/skills 0.12.11 → 0.12.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -6,18 +6,24 @@
 
 ```text
 my-addon/
-├── package.json               # Exports .pikku/* and dist/
+├── package.json               # imports -> dist, exports -> dist
 ├── pikku.config.json          # addon: true + metadata
-├── tsconfig.json              # #pikku path mapping
+├── tsconfig.json              # #pikku path mapping (source side)
 ├── src/
 │   ├── services.ts            # createSingletonServices (required)
 │   └── functions/
 │       └── *.function.ts      # Function definitions
 ├── types/
 │   └── application-types.d.ts # SingletonServices interface
-└── .pikku/                    # Generated (gitignored)
+└── .pikku/addon/              # Generated (gitignored)
 ```
 
+An addon's generated tree roots one level down, at `.pikku/addon/`, so its own
+leaves are reached as `#pikku/addon/<leaf>` while an application's are
+`#pikku/<leaf>`. `paths` are global to a tsx process rather than scoped to the
+package that declared them, and the extra segment is what stops a linked addon's
+`#pikku/function` from matching the *host application's* flat leaf.
+
 ## pikku.config.json
 
 ```json
@@ -34,30 +40,74 @@ my-addon/
 }
 ```
 
+`outDir` stays `./.pikku`; `addon: true` is what appends the `addon` segment.
+
 ## package.json (key fields)
 
 ```json
 {
   "name": "@my-org/addon-todos",
   "imports": {
-    "#pikku/*.js": "./.pikku/*.ts",
-    "#pikku/*": "./.pikku/*/index.ts"
+    "#pikku/*.js": "./dist/.pikku/*.js",
+    "#pikku/*": ["./dist/.pikku/*/index.js", "./dist/.pikku/*"]
   },
   "exports": {
     ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
-    "./.pikku/*": "./.pikku/*",
-    "./.pikku/pikku-metadata.gen.json": "./.pikku/pikku-metadata.gen.json",
+    "./.pikku/*": "./dist/.pikku/addon/*",
+    "./.pikku/pikku-metadata.gen.json": "./dist/.pikku/addon/pikku-metadata.gen.json",
     "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.js": {
-      "types": "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.d.ts"
+      "types": "./dist/.pikku/addon/rpc/pikku-rpc-wirings-map.internal.gen.d.ts"
     }
   },
-  "files": ["dist", ".pikku"],
+  "files": ["dist"],
   "peerDependencies": {
-    "@pikku/core": "*"
+    "@pikku/core": "*",
+    "zod": "^4"
   },
   "scripts": {
+    "prebuild": "pikku all",
     "pikku": "pikku all",
-    "build": "tsc && cp -r .pikku dist/"
+    "build": "tsc && cp -r .pikku types dist/"
   }
 }
 ```
+
+**`imports` names `dist`, never the source tree.** `files: ["dist"]` is the whole
+published package, and `build` copies `.pikku` and `types` into it — so a
+`#pikku/*` target under `./.pikku/` resolves for the author and for nobody else.
+It is a silent break: the addon compiles, packs, installs and then throws
+`Cannot find module '.../.pikku/addon/function/index.ts'` on first import in the
+consuming app, out of a file the consumer never wrote. The addon's own build
+does not read `imports` at all — tsconfig `paths` covers it, which is why the
+two maps point at different trees.
+
+**`exports` targets carry the `addon` segment; the subpaths do not.** A consumer
+writes `@my-org/addon-todos/.pikku/rpc/...`, exactly as it would in an
+application, and the leaf stays the package's own business.
+
+## tsconfig.json (key fields)
+
+```json
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": ".",
+    "outDir": "./dist",
+    "paths": {
+      "#pikku/*.js": ["./.pikku/*.ts"],
+      "#pikku/*": ["./.pikku/*/index.ts", "./.pikku/*"]
+    }
+  },
+  "include": ["src/**/*", "types/**/*", ".pikku/**/*.ts"],
+  "exclude": ["node_modules", "dist", ".pikku/**/*.d.ts"]
+}
+```
+
+`paths` resolves the source tree because `dist` does not exist yet on the build
+that creates it. Both patterns are needed: the `.js` one reaches a generated
+file (`#pikku/addon/variables/pikku-variables.gen.js`), the bare one reaches a
+leaf's barrel (`#pikku/addon/function`). Keep the `.js` pattern first: both keys
+share the `#pikku/` prefix, and TypeScript takes the first match of the longest
+prefix rather than the most specific pattern. Node sorts by specificity and does
+not care about the order.

package/skills/pikku-agent/SKILL.md

@@ -201,8 +201,7 @@ export const todoAgent = pikkuAgent({
 ### Scaffold the HTTP surface
 
 ```bash
-pikku enable agent            # session required
-pikku enable agent --noAuth   # public
+pikku enable agent
 ```
 
 The next `pikku all` generates `agent.gen.ts` — run/stream/approve/resume

package/skills/pikku-emails/SKILL.md

@@ -82,10 +82,31 @@ Placeholders are `{{ ... }}`. Resolution order inside a template:
 - `{{> footer}}` — include a partial from `partials/`.
 - `{{content}}` / `{{subject}}` — only meaningful inside `partials/layout.html`
   (the rendered body and subject). `layout.html` wraps every template if present.
+- `{{{verifyUrl}}}` — the same value **unescaped**. See below.
 
 Locale strings may themselves contain variables and partial-free placeholders, e.g.
-`"subject": "{{inviterName}} invited you to join {{organizationName}}"`. These are
-resolved in the same pass, so a subject of `{{t.invitation.subject}}` expands fully.
+`"subject": "{{inviterName}} invited you to join {{organizationName}}"`. Locale files
+and `theme.json` ship alongside the templates, so they are expanded first and a subject
+of `{{t.invitation.subject}}` expands fully.
+
+## Escaping
+
+Values are HTML-escaped (`& < > " '`) on the way into `.html` output, so a URL, a
+display name or a font stack containing quotes lands inside its attribute instead of
+breaking out of it. `.subject.txt` and `.text.txt` are plain text and are never escaped.
+
+Rendering is **layered by trust**, and the layers do not leak into each other:
+
+- Partials are inlined first — a `data` value that happens to contain `{{> footer}}`
+  is not an include.
+- `theme.*` and `t.*` are template-author input: expanded next, escaped, and allowed
+  to contain further placeholders (up to 5 levels).
+- Everything else is caller data: substituted in **one pass**, escaped, and never
+  rescanned — a `data` value containing `{{...}}` renders as those literal characters.
+
+`{{content}}` and partials are template-authored markup and stay raw. For a value you
+genuinely want inserted as markup, use the explicit `{{{value}}}` form — it is opt-in,
+it bypasses escaping entirely, and it is only safe for HTML you control.
 
 ## Typed variables (per template)
 

package/skills/pikku-realtime/SKILL.md

@@ -66,8 +66,7 @@ see `pikku-services`.
 ## 2. Enable the server side
 
 ```bash
-yarn pikku enable events           # auth required by default
-yarn pikku enable events --noAuth  # public events
+yarn pikku enable events
 ```
 
 This sets `scaffold.events` in `pikku.config.json`. The next `pikku all` generates

package/skills/pikku-rpc/SKILL.md

@@ -75,10 +75,12 @@ The `POST /rpc/:rpcName` endpoint that dispatches every `expose: true` function
 is **generated, not hand-written**. Turn it on and let codegen own it:
 
 ```bash
-pikku enable rpc            # sets scaffold.rpc = true (auth required)
-pikku enable rpc --noAuth   # sets scaffold.rpc = { auth: false } (public)
+pikku enable rpc            # sets scaffold.rpc = true
 ```
 
+The flag says the endpoint exists, not who may call it — each exposed function
+is gated by its own `auth`, permissions and scopes.
+
 This writes `rpc-public.gen.ts` with an `rpcCaller` function and its `wireHTTP`
 call already wired. Do not write that wiring yourself — a hand-rolled copy
 collides with the generated route on the same path.

package/skills/pikku-scenario/SKILL.md

@@ -682,14 +682,13 @@ Coverage is attributed by running scenarios against a server that is collecting
 Prerequisite in `pikku.config.json`:
 
 ```bash
-pikku enable scenarios            # sets scaffold.scenarios = true (session required)
-pikku enable scenarios --noAuth   # sets scaffold.scenarios = { "auth": false }
+pikku enable scenarios            # sets scaffold.scenarios = true
 ```
 
-`scaffold.scenarios` is a boolean or `{ auth?, path? }`. The legacy string forms
-(`"auth"` / `"no-auth"`) are **rejected by the config loader**, not reinterpreted —
-under a shape where a string could be a path, silently reading one as a flag
-would be worse than failing.
+`scaffold.scenarios` is a boolean or `{ path? }` — whether the surface exists
+and where it is written. A bare string is **rejected by the config loader**, not
+reinterpreted: under a shape where a string could be a path, silently reading
+one as a flag would be worse than failing.
 
 `scaffold.scenarios` generates the coverage and stub RPCs into your project (`pikkuScenarioTakeLiveCoverage`, `pikkuScenarioResetLiveCoverage`, `pikkuScenarioResetStubs`, `pikkuScenarioGetStubCalls`), so scenario runs work against any server. The coverage RPC reads `<outDir>/function/pikku-functions-meta-verbose.gen.json` off disk at request time — codegen always writes it, but it has to be deployed alongside the app or the RPC returns `null`.