@pikku/skills 0.12.25 → 0.12.27

package/skills/pikku-blueprint-to-fabric/scripts/inventory.mjs

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+// Emit the Pikku implementation inventory for a .knowledge/ blueprint.
+//
+//   node inventory.mjs <path-to-.knowledge> [--json] [--domain <Name>]
+//
+// Answers "what will actually be built?" BEFORE any code exists: every pikkuFunc,
+// permission, scheduler, queue worker, workflow, HTTP wiring, event channel,
+// table and scenario — plus, crucially, what is BLOCKED by an unresolved decision
+// and what is deliberately NOT built.
+//
+// This is a projection of the blueprint, not a plan you write by hand. It is
+// derived, so it stays honest: if it says 187 functions, the blueprint says 187.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const dir = process.argv[2]
+const asJson = process.argv.includes('--json')
+const domainArg = process.argv.includes('--domain')
+  ? process.argv[process.argv.indexOf('--domain') + 1]
+  : null
+
+if (!dir) {
+  console.error('usage: inventory.mjs <path-to-.knowledge> [--json] [--domain <Name>]')
+  process.exit(2)
+}
+
+// The four files pikku-software-archaeology's schema marks `x-optional` — an
+// API-only app really has no frontend. Every other file is REQUIRED, and a
+// missing or unparseable one is fatal rather than an empty list: this script's
+// whole claim is that its counts come from the blueprint, so silently reporting
+// "0 commands" for a directory that isn't a blueprint tells the exact lie the
+// inventory exists to prevent.
+const OPTIONAL = new Set([
+  'interfaces.json',
+  'frontend.json',
+  'frontend-routes.json',
+  'frontend-components.json',
+])
+
+const fatal = (msg) => {
+  console.error(`inventory: ${msg}`)
+  process.exit(1)
+}
+
+if (!existsSync(dir)) fatal(`no such directory: ${dir}`)
+
+const read = (f) => {
+  const p = join(dir, f)
+  if (!existsSync(p)) {
+    if (OPTIONAL.has(f)) return null
+    fatal(
+      `${dir} is missing ${f}. Run the archaeology validator first — ` +
+        `an incomplete blueprint gives a count that reads as complete.`
+    )
+  }
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'))
+  } catch (e) {
+    fatal(`${f} is not valid JSON: ${e.message}`)
+  }
+}
+
+/** A required file that parsed but carries the wrong shape is the same lie. */
+const list = (f, key) => {
+  const doc = read(f)
+  if (doc === null) return []
+  const rows = doc[key]
+  if (rows === undefined) fatal(`${f} has no "${key}" array — blueprint shape changed?`)
+  if (!Array.isArray(rows)) fatal(`${f}: "${key}" is ${typeof rows}, expected an array`)
+  return rows
+}
+
+const domains = list('domains.json', 'domains')
+const entities = list('entities.json', 'entities')
+const commands = list('commands.json', 'commands')
+const queries = list('queries.json', 'queries')
+const events = list('events.json', 'events')
+const policies = list('policies.json', 'policies')
+const workflows = list('workflows.json', 'workflows')
+const apiDoc = read('api.json')
+const api = apiDoc.surfaces ?? apiDoc.api ?? fatal('api.json has neither "surfaces" nor "api"')
+const integrations = list('integrations.json', 'integrations')
+const migration = read('migration.json')
+const interfaces = read('interfaces.json')?.interfaces ?? []
+const feComponents = read('frontend-components.json')?.components ?? []
+const feRoutes = read('frontend-routes.json')?.routes ?? []
+
+// ---- the decisions gate -----------------------------------------------------
+// A concept named in an unresolved decision's blockedConcepts cannot be built.
+//
+// Answers are recorded OUTSIDE the blueprint — in the rebuild's own knowledge
+// base — because the blueprint is a record of the LEGACY app and must not be
+// rewritten as the rebuild proceeds. So pass the ones already answered:
+//
+//   --resolved 1,2,3        (1-based index into migration.json.decisionsNeeded)
+//
+// Anything not listed is still blocking.
+const allDecisions = migration.decisionsNeeded ?? []
+const resolvedArg = process.argv.includes('--resolved')
+  ? process.argv[process.argv.indexOf('--resolved') + 1]
+  : ''
+const resolvedIdx = new Set(
+  resolvedArg.split(',').map((s) => parseInt(s.trim(), 10)).filter(Boolean)
+)
+const decisions = allDecisions.filter((_, i) => !resolvedIdx.has(i + 1))
+const resolved = allDecisions.filter((_, i) => resolvedIdx.has(i + 1))
+const blocked = new Map() // concept -> question
+for (const d of decisions) {
+  for (const c of d.blockedConcepts ?? []) {
+    if (!blocked.has(c)) blocked.set(c, d.question)
+  }
+}
+const dropped = migration.dropped ?? []
+const droppedNames = new Set(
+  dropped.map((d) => (d.path ?? d.file ?? '').split('/').pop())
+)
+
+const isBlocked = (name, domain) => blocked.has(name) || blocked.has(domain)
+
+// ---- classification ---------------------------------------------------------
+// Cron-ish triggers. The blueprint records schedules in prose ("daily at 05:00",
+// "every minute"), because that is how the legacy code expressed them.
+const CRON = /(cron|daily|nightly|hourly|every minute|every \d|schedule|at \d{2}:\d{2})/i
+const QUEUE = /(queue|consumer|perform_later|sidekiq|worker|async)/i
+const WEBHOOK = /(webhook|POST \/webhooks)/i
+// A trigger that fires off a row write is the legacy shape of an EVENT, not of a
+// workflow — a handler doing five unrelated things because there was no bus.
+// These become an event + its consumers, which is the structural upgrade.
+const EVENT = /(after_commit|after_save|on create\/update\/destroy|observer|callback|mirror)/i
+
+const classifyWorkflow = (w) => {
+  const t = `${w.name} ${w.trigger ?? ''}`
+  if (w.kind === 'system') {
+    if (WEBHOOK.test(t)) return 'wireHTTP + command (webhook ingress)'
+    if (CRON.test(t)) return 'wireScheduler'
+    if (EVENT.test(t)) return 'event consumer (realtime/queue)'
+    if (QUEUE.test(t)) return 'wireQueueWorker'
+    return 'pikkuWorkflowFunc'
+  }
+  // User and admin journeys are NOT pikku workflows — they are sequences of
+  // commands a person drives through the UI. They become scenarios.
+  return 'scenario (user journey)'
+}
+
+// HTTP is warranted ONLY where the caller is a system we do not control and
+// cannot ask to speak RPC — i.e. it POSTs to a URL we publish, on its schedule.
+// In practice that means inbound webhooks.
+//
+// Everything else is RPC, including surfaces that look like they need HTTP:
+//   - `auth: none` means anonymous, not external. Our own sign-up page calls it.
+//   - a tokened/capability URL (a check-in link, a public share link) is a
+//     first-party page reading a token; the page can call RPC like any other.
+// The caller being ours is what decides this, not the URL's shape or its auth.
+const needsHttp = (s) => /webhook/i.test(s.path ?? '')
+
+const byDomain = (arr) => {
+  const m = new Map()
+  for (const x of arr) {
+    const d = x.domain ?? 'unassigned'
+    if (!m.has(d)) m.set(d, [])
+    m.get(d).push(x)
+  }
+  return m
+}
+
+const cmdByDomain = byDomain(commands)
+const qryByDomain = byDomain(queries)
+const polByDomain = byDomain(policies)
+const evtByDomain = byDomain(events)
+const entByDomain = byDomain(entities)
+
+const schedulers = workflows.filter((w) => classifyWorkflow(w) === 'wireScheduler')
+const queueWorkers = workflows.filter((w) => classifyWorkflow(w) === 'wireQueueWorker')
+const ingress = workflows.filter((w) => classifyWorkflow(w).startsWith('wireHTTP'))
+const eventConsumers = workflows.filter((w) => classifyWorkflow(w) === 'event consumer (realtime/queue)')
+const pikkuWorkflows = workflows.filter((w) => classifyWorkflow(w) === 'pikkuWorkflowFunc')
+const journeys = workflows.filter((w) => classifyWorkflow(w) === 'scenario (user journey)')
+const httpSurfaces = api.filter(needsHttp)
+const scenarioCount = workflows.reduce((n, w) => n + (w.scenarios ?? []).length, 0)
+
+const blockedCommands = commands.filter((c) => isBlocked(c.name, c.domain))
+const blockedQueries = queries.filter((q) => isBlocked(q.name, q.domain))
+const customLogic = feComponents.filter((c) => c.rebuild === 'custom-logic')
+const cheapComponents = feComponents.filter((c) => c.rebuild !== 'custom-logic')
+
+// ---- addons -----------------------------------------------------------------
+// An addon is warranted where a capability is self-contained, reused across
+// domains, and has a clear service seam — which is what a `hard`/`critical`
+// integration is. Advisory: the call is the operator's.
+const addonCandidates = integrations.filter(
+  (i) => i.importance === 'critical' || i.replacementDifficulty === 'hard'
+)
+
+if (asJson) {
+  console.log(
+    JSON.stringify(
+      {
+        totals: {
+          pikkuFunc: commands.length,
+          pikkuSessionlessFuncReadonly: queries.length,
+          pikkuPermission: policies.length,
+          wireScheduler: schedulers.length,
+          wireQueueWorker: queueWorkers.length,
+          webhookIngress: ingress.length,
+          pikkuWorkflowFunc: pikkuWorkflows.length,
+          wireHTTP: httpSurfaces.length,
+          eventChannels: events.length,
+          tables: entities.length,
+          scenarios: scenarioCount,
+          blockedCommands: blockedCommands.length,
+          blockedQueries: blockedQueries.length,
+          droppedArtifacts: dropped.length,
+          customLogicComponents: customLogic.length,
+        },
+        blocked: [...blocked.entries()].map(([concept, question]) => ({ concept, question })),
+      },
+      null,
+      2
+    )
+  )
+  process.exit(0)
+}
+
+// ---- report -----------------------------------------------------------------
+const out = []
+const p = (s = '') => out.push(s)
+
+p('# Pikku implementation inventory')
+p('')
+p(`Derived from \`${dir}\`. Every number below is a projection of the blueprint —`)
+p('nothing here is estimated or invented.')
+p('')
+
+p('## Totals')
+p('')
+p('| Pikku artifact | Count | From |')
+p('|---|---:|---|')
+p(`| \`pikkuFunc\` (state-changing) | ${commands.length} | \`commands.json\` |`)
+p(`| \`pikkuSessionlessFunc\` + \`readonly: true\` | ${queries.length} | \`queries.json\` |`)
+p(`| \`pikkuPermission\` | ${policies.length} | \`policies.json\` |`)
+p(`| \`wireScheduler\` | ${schedulers.length} | \`workflows.json\` (system + cron) |`)
+p(`| \`wireQueueWorker\` | ${queueWorkers.length} | \`workflows.json\` (system + queue) |`)
+p(`| webhook ingress (\`wireHTTP\` + command) | ${ingress.length} | \`workflows.json\` (system + webhook) |`)
+p(`| \`pikkuWorkflowFunc\` | ${pikkuWorkflows.length} | \`workflows.json\` (system, multi-step) |`)
+p(`| \`wireHTTP\` (fixed external URLs only) | ${httpSurfaces.length} of ${api.length} surfaces | \`api.json\` |`)
+p(`| event channels (realtime/queue) | ${events.length} | \`events.json\` |`)
+p(`| tables | ${entities.length} | \`entities.json\` |`)
+p(`| scenarios | ${scenarioCount} | \`workflows.json[].scenarios\` |`)
+p('')
+p(`**Not built:** ${dropped.length} dropped artifacts · **Blocked:** ${blockedCommands.length + blockedQueries.length} concepts behind ${decisions.length} open decisions.`)
+p('')
+
+if (resolved.length) {
+  p('## Decisions already taken')
+  p('')
+  p('Answered at the gate and recorded in the rebuild\'s knowledge base. Each is a')
+  p('**deliberate behaviour change** and belongs in the parity report.')
+  p('')
+  for (const d of resolved) p(`- ${(d.blockedConcepts ?? []).join(', ')} — _${d.question.split('.')[0]}._`)
+  p('')
+}
+
+p('## Blocked by an open decision')
+p('')
+if (decisions.length === 0) {
+  p('_None — the gate is clear._')
+} else {
+  p('These cannot be built until the question is answered. They block **their own')
+  p('domains only** — every other slice proceeds.')
+  p('')
+  for (const d of decisions) {
+    p(`- **${(d.blockedConcepts ?? []).join(', ') || '(unscoped)'}**`)
+    p(`  <br>${d.question}`)
+    if (d.options) p(`  <br>_Options:_ ${d.options.join(' · ')}`)
+  }
+}
+p('')
+
+p('## Scheduled tasks (`wireScheduler`)')
+p('')
+p('| Workflow | Trigger |')
+p('|---|---|')
+for (const w of schedulers) p(`| ${w.name} | ${(w.trigger ?? '').replace(/\|/g, '\\|')} |`)
+p('')
+
+if (queueWorkers.length || ingress.length || pikkuWorkflows.length || eventConsumers.length) {
+  p('## Other system wiring')
+  p('')
+  p('| Workflow | Becomes |')
+  p('|---|---|')
+  for (const w of [...ingress, ...queueWorkers, ...eventConsumers, ...pikkuWorkflows])
+    p(`| ${w.name} | \`${classifyWorkflow(w)}\` |`)
+  p('')
+}
+
+p('## Journeys → scenarios')
+p('')
+p(`${journeys.length} user/admin journeys carrying ${scenarioCount} scenarios excavated from the`)
+p('legacy test suite. These are **not** `pikkuWorkflowFunc`s — they are sequences a')
+p('person drives through the UI, and they become scenario tests.')
+p('')
+p('| Journey | Kind | Scenarios |')
+p('|---|---|---:|')
+for (const w of journeys) p(`| ${w.name} | ${w.kind} | ${(w.scenarios ?? []).length} |`)
+p('')
+
+p('## Per domain')
+p('')
+p('| Domain | Tables | `pikkuFunc` | readonly | permissions | events | blocked |')
+p('|---|---:|---:|---:|---:|---:|---:|')
+for (const d of domains) {
+  const n = d.name
+  const b = (cmdByDomain.get(n) ?? []).filter((c) => isBlocked(c.name, n)).length +
+            (qryByDomain.get(n) ?? []).filter((q) => isBlocked(q.name, n)).length
+  p(
+    `| ${n} | ${(entByDomain.get(n) ?? []).length} | ${(cmdByDomain.get(n) ?? []).length} | ${(qryByDomain.get(n) ?? []).length} | ${(polByDomain.get(n) ?? []).length} | ${(evtByDomain.get(n) ?? []).length} | ${b || ''} |`
+  )
+}
+p('')
+
+p('## Addon candidates')
+p('')
+p('Advisory. A capability earns an addon when it is self-contained, reused across')
+p('domains, and has a clear service seam — which is what a critical/hard-to-replace')
+p('integration usually is. The call is yours.')
+p('')
+p('| Integration | Importance | Replace |')
+p('|---|---|---|')
+for (const i of addonCandidates)
+  p(`| ${i.name} | ${i.importance ?? ''} | ${i.replacementDifficulty ?? ''} |`)
+p('')
+
+if (feComponents.length) {
+  p('## Frontend')
+  p('')
+  p(`- **${cheapComponents.length}** components are a cheap re-expression in Mantine (standard / composition / restyle).`)
+  p(`- **${customLogic.length}** carry \`custom-logic\` and must be **ported**. This is the real frontend project.`)
+  p(`- **${feRoutes.length}** routes → TanStack routes; their \`dataFrom\` names are already the function names above.`)
+  p('')
+  if (customLogic.length) {
+    p('| custom-logic component | What must survive |')
+    p('|---|---|')
+    for (const c of customLogic)
+      p(`| ${c.name} | ${(c.customLogic ?? '').replace(/\|/g, '\\|').slice(0, 110)} |`)
+    p('')
+  }
+}
+
+if (interfaces.length) {
+  p('## Interfaces')
+  p('')
+  p('| Channel | Audience | Status |')
+  p('|---|---|---|')
+  for (const i of interfaces) p(`| ${i.kind} | ${i.audience ?? ''} | ${i.status ?? ''} |`)
+  p('')
+}
+
+p('## Deliberately not built')
+p('')
+p('| Artifact | Why |')
+p('|---|---|')
+for (const d of dropped)
+  p(`| \`${d.path ?? d.file}\` | ${(d.reason ?? '').replace(/\|/g, '\\|').slice(0, 120)} |`)
+p('')
+
+console.log(out.join('\n'))

package/skills/pikku-build/SKILL.md

@@ -12,6 +12,7 @@ description: >-
   or wants one specific surface explained rather than built (use that surface's skill).
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
 argument-hint: '[feature description]'
+installGroups: [core]
 ---
 
 # Build on Pikku

package/skills/pikku-build/references/app.md

@@ -265,7 +265,7 @@ the database still holds that code no longer declares — both need §0's bootst
 to have run, and both are worth a look once it has.
 
 **One warning about the scaffold's own notes:** `knowledge/index.md` may claim
-the people live in `pikku.config.json`, put there by a `fabric persona` command.
+the people live in `pikku.config.json`, put there by a persona command.
 That is stale. In this template they live in `personas.ts` as above, and
 `pikku.config.json` carries no personas key at all — only `scenarios.emailDomain`.
 Trust the file you can read over the note describing it.

package/skills/pikku-build/references/multi-app.md

@@ -8,6 +8,61 @@ leaves `pikkufabric.config.json` pointing at an app nobody has designed yet.
 If the split is "one app with paths", you never need this file — add route
 segments under `/app` and give each audience its own entries in `useNavItems()`.
 
+## Deciding it is two apps, not one
+
+The split you are acting on should already be recorded, but this is the reasoning
+behind it — and the place people get it wrong is the third case at the bottom.
+
+**A group that comes in through its own front door gets its own app.** A role
+*inside* an app is not that: it changes which nav items and which buttons a person
+sees, and lives in `useNavItems()` and the `permissions` on the function, not in a
+route subtree.
+
+**The test is which side of the counter they are on.** Colleagues share one app and
+differ by nav — the mechanic, the person on the counter, the bookkeeper. Someone
+across the counter with an account of their own gets their own — the customer, the
+tenant, the patient. One app is a real answer and often the right one.
+
+**The asymmetry that forces a split is sign-up.** Where staff accounts are created
+*for* people and customers create their own, the two need different sign-up, different
+onboarding and different session shape, and bending one app around both costs more
+than the second app does. Do not collapse two audiences into one app to save a build.
+
+Never invent a person the notes do not name in order to reach two.
+
+### The group that never signs in
+
+Some people use the product with no account at all — ordering from a menu, booking a
+table, opening an invitation. They are not a third case, and **they do not get their
+own frontend**: an app is built around the personas who sign into it. What they get is
+the public route space every app already has.
+
+- **`/app/*` is the signed-in application.** One `beforeLoad` on `/app` bounces a
+  signed-out visitor to the login. There is no per-route exception.
+- **Every other route is public** — `/`, `/menu`, `/book`, `/r/$code`. No gate, no
+  session.
+- **`/` is a landing page and you must write it.** A starter that forwards `/` to
+  `/app` does so only because it ships no homepage. Leave the forward in and the
+  product's front door is a sign-in form: the anonymous visitor arrives at a login it
+  has no account for and never reaches the thing it came for — **while every check
+  still passes**, because everything that looks at the app signs in first. This is the
+  failure this section exists for.
+
+So a screen whose users have no account goes at `/menu`, never `/app/menu`.
+
+### The frontend guard is UX and proves nothing
+
+The bundle is on the origin and the nav is a client-side decision; anyone can read
+both. The security boundary is the `permissions` field on the function — see
+pikku-permissions. Hiding a nav item keeps people out of screens that would confuse
+them; it never protects data. Never let a hidden UI be the only thing between a user
+and someone else's record: if the invoices nav item is hidden but `listAllInvoices`
+has no `permissions`, the app is wide open and the nav is decoration.
+
+Worth a scenario each, because they are two different claims: that a mechanic cannot
+*see* the invoices nav item, and that their call to an invoices RPC is *refused*. The
+second is the one that catches a `permissions` field nobody wired.
+
 ## The clone
 
 ```bash

package/skills/pikku-build/references/ship.md

@@ -74,8 +74,8 @@ Everything above is open source. This is the contract that keeps
 - **`pikkufabric.config.json` describes reality.** Every app has an entry with
   the right `cwd`, `port`, `kind` and `dev.command`; exactly one is `primary`;
   `serves` and `personas` name real personas from the personas section. Leave `projectId` as
-  `__PROJECT_ID__` — that placeholder means "unlinked", and `fabric init` writes
-  the real one. Do not invent a value to make it look configured.
+  `__PROJECT_ID__` — that placeholder means "unlinked", and linking the project
+  writes the real one. Do not invent a value to make it look configured.
 - **One `definePersonas` call**, every persona reachable through exactly one
   frontend. Fabric materialises these as its virtual users; a persona nobody
   serves imports as a person with no way in.

package/skills/pikku-fabric/SKILL.md

@@ -291,24 +291,40 @@ reload).
 pikku fabric login              # opens a browser; needs a human, wait for it
 pikku fabric init https://github.com/<owner>/<repo>
 pikku fabric validate           # must pass clean
-pikku fabric deploy apply --production --sync --auto-approve
+pikku fabric deploy apply --production -y
 ```
 
+The branch is positional and defaults to the checked-out one, and `-y` is the
+short form of `--auto-approve`, so a one-shot deploy is:
+
+```bash
+pikku fabric deploy apply -y            # the branch you are standing on
+pikku fabric deploy apply my-branch -y  # a named one
+```
+
+`-y` answers the prompts and nothing more. It does **not** approve migrations
+that drop or rewrite data — that stays `--allow-destructive`, typed out on
+purpose.
+
+Inferring the branch is safe because the git safety check refuses any branch
+without an upstream or out of sync with it, so it cannot ship an unpushed
+commit; the branch it picked is printed before the build starts. A detached
+HEAD is refused by name rather than travelling on as a branch called `HEAD`.
+
 There is no `deploy plan` subcommand — `apply` runs the same auth, git-safety
 and ref resolution itself, and fabric produces the real plan server-side.
 
 `apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
-it refuses rather than hangs. `--auto-approve` supplies that confirmation; drop
-it only when a human is at a real terminal.
+it refuses rather than hangs. `--auto-approve` (`-y`) supplies that confirmation;
+drop it only when a human is at a real terminal.
 
-By default `apply` queues the deploy, prints the deployment id and returns. That
-tells you nothing about whether it worked. `--sync` waits for a terminal state
-and exits non-zero unless the deployment went live, which is the only form worth
-running in CI:
+`apply` waits for a terminal state and exits non-zero unless the deployment went
+live. `--detach` opts out — it queues the deploy, prints the deployment id and
+returns 0, which tells you nothing about whether it worked:
 
 | exit | meaning                                                                 |
 | ---- | ----------------------------------------------------------------------- |
-| 0    | live (or queued, without `--sync`)                                      |
+| 0    | live (or queued, under `--detach`)                                      |
 | 1    | the command could not run — not logged in, unsafe git state, bad flags  |
 | 2    | the deployment failed, errored, timed out server-side, or was cancelled |
 | 3    | the deployment is blocked and nothing the CLI can do will unblock it    |
@@ -318,14 +334,14 @@ Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
 Why it parked is the whole story, and it is `statusReason`, not `status`:
 
 - `awaiting_approval` — the plan is fine, a human has to publish it.
-  `--auto-approve` does that; without it you get exit 3 and the command to run.
+  `-y` does that; without it you get exit 3 and the command to run.
   One exception: if fabric marked any pending migration **destructive** — a
-  drop, a truncate, a rewrite — `--auto-approve` alone declines and exits 3,
+  drop, a truncate, a rewrite — `-y` alone declines and exits 3,
   because a standing yes was given before anyone knew the plan dropped a table.
   The CLI lists the migrations and fabric's reasons; `--allow-destructive`
-  accepts them for that deploy.
+  accepts them for that deploy, and `-y` implies it.
 - `needs_config` — a declared secret or variable has no value covering the
-  stage. The CLI names them. `--auto-approve` will **not** force this through;
+  stage. The CLI names them. `-y` will **not** force this through;
   set the values and re-attach — `pikku fabric secrets set <name>` for a
   declared secret, `pikku fabric variables set <name> --value <v>` for a declared
   variable. They are separate stores: a secret is sealed to the stage and cannot
@@ -334,24 +350,25 @@ Why it parked is the whole story, and it is `statusReason`, not `status`:
   stage exactly as it is from `.env`, and `--value '"true"'` is the string.
 - `needs_attention` — the plan is red. Nothing to approve.
 
-`--sync` defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
+The wait defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
 it prints the deployment id and the re-attach command rather than lying about
 the outcome.
 
 Splitting kick-off from waiting across two CI jobs is the reason
-`--deployment-id` exists:
+`--deployment-id` exists, and what `--detach` is for — the first job here has to
+return the id and exit rather than wait:
 
 ```bash
-id=$(pikku fabric deploy apply --production --auto-approve --json | jq -r 'select(.event=="result").deploymentId')
+id=$(pikku fabric deploy apply --production -y --detach --json | jq -r 'select(.event=="result").deploymentId')
 # …later, in another job…
-pikku fabric deploy apply --deployment-id "$id" --sync --auto-approve
+pikku fabric deploy apply --deployment-id "$id" -y
 ```
 
 `--deployment-id` skips the git safety check entirely (the deployment already
 pins a sha, and the checkout is allowed to have moved on) and refuses to be
-combined with `--branch`/`--production`, which would let the two disagree.
+combined with a branch or `--production`, which would let the two disagree.
 
-Under `--json`, `--sync` emits one NDJSON event per line — `created`/`attached`,
+Under `--json`, the wait emits one NDJSON event per line — `created`/`attached`,
 `status` on each transition, `blocked`, `approved` — and the last line is the
 terminal result object, tagged `"event": "result"`.
 

package/skills/pikku-i18n/SKILL.md

@@ -63,9 +63,11 @@ is what makes an RTL language just another locale file.
 - **Do not `asI18n()` a hardcoded English string.** `asI18n` exists to pass
   opaque server data (a name, a slug, an id) through the i18n gate. An enum value
   goes through its generated label map.
-- **Do not wrap `m`.** No re-export module, no branding layer. `m.some__key()`
-  already satisfies the `I18nNode` gate; a wrapper adds nothing and costs
-  per-message tree-shaking.
+- **Do not wrap `m` without a reason you can name.** `m.some__key()` already
+  satisfies the `I18nNode` gate, so a plain re-export module adds nothing and
+  costs per-message tree-shaking. Wrapping the namespace is only worth it when it
+  buys a feature the gate cannot — debug masking of translated copy, say — and
+  then the catalogue has to be small enough to ship whole.
 - **Do not translate message keys.** `auth__login__title` stays English in
   `de.json`; only the value changes.
 - **Do not edit or commit `src/paraglide/`, `i18n-enum.gen.ts` or `enums.gen.ts`.**

package/skills/pikku-knowledge/SKILL.md

@@ -13,6 +13,7 @@ description: >-
   brief to record. DO NOT TRIGGER when: user asks what
   functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
   note), or to write a scenario test (use pikku-scenario).
+installGroups: [core]
 ---
 
 # Pikku Knowledge