@joshuafolkken/kit 1.1178.0 → 1.1229.0

package/.cursorrules

@@ -1,45 +1,10 @@
-You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:
+# Agent Instructions
 
-## Available MCP Tools:
+> **All rules for this repository live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
+> any work here, and follow every rule in it.** This file exists only to point at it.
 
-### 1. list-sections
+**No hooks are configured for Cursor** — apply every hook-delivered rule yourself, per `prompts/collaboration-workflow/principles.md` → "Claude Code 以外のエージェントでの読み替え". Do not copy rules back into this file.
 
-Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths.
-When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.
+## Svelte MCP
 
-### 2. get-documentation
-
-Retrieves full documentation content for specific sections. Accepts single or multiple sections.
-After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.
-
-### 3. svelte-autofixer
-
-Analyzes Svelte code and returns issues and suggestions.
-You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.
-
-### 4. playground-link
-
-Generates a Svelte Playground link with the provided code.
-After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.
-
-## Code Change Rules
-
-Whenever modifying, adding, or deleting any code:
-
-1. **Verify the gate**: Run `pnpm josh gate` — lint, type check, spell check and unit tests, run concurrently, with every failing check reported in one pass. Re-run one on its own by copying the command from its output header while fixing — `pnpm josh lint`, `pnpm josh check`, `pnpm josh cspell:dot`, `pnpm josh test:unit` for a project with no application toolkit.
-2. **Verify IDE Feedback**: ALWAYS run the **ReadLints** tool on every modified file (and any file that might be affected) before finishing. Fix all reported errors and warnings. IDE/ReadLints can report issues that terminal `pnpm josh lint` does not (e.g. type resolution for generated or gitignored paths).
-3. **Fix Issues**: If any check fails (terminal or IDE feedback, or ReadLints), fix all reported issues immediately.
-4. **Repeat**: Repeat the checks until **all** pass and **ReadLints shows no errors** for the modified files.
-5. **Completion**: Only finish the task or response after ALL checks pass and ReadLints reports **zero errors** on modified files (warnings only are acceptable only when documented as a known exception, e.g. unused eslint-disable for Paraglide).
-6. **Full test gate (code or E2E-impacting work):** `pnpm josh gate` already covers the spell check and the unit tests; E2E is closed on top of it, and **never by asking the user to run it**. With a pull request open, the CI E2E job is the authority and `pnpm josh followup` refuses to merge while any check is non-passing. With no pull request, run **`pnpm josh test:e2e`** yourself and read what it prints — it exits 0 without running when Playwright or the `*.e2e.{ts,js}` files are absent, and that printed skip is the answer for a project with no E2E suite. **Do not** claim completion using only `pnpm josh test:unit --run` when E2E applies, and **do not** fall back to **`pnpm build`** or **`CI=true`** to get past a Playwright run that will not finish — report that it did not run instead. Run it with `CI` unset so Playwright uses **DEV** (`pnpm run dev`, on the port `playwright.config.ts` resolves from `PORT_SEED`), matching the VS Code Test extension. Details: **Completion gate** in `CLAUDE.md` and `prompts/testing-guide.md` → "Closing the E2E gate without a human run".
-
-**Constraint**: Never state "it should pass" without actually having run the commands and confirmed the output. Do not end a task while **errors** exist. Before completing, you MUST run **ReadLints** on every modified file and fix every **error** (not just rely on terminal check/lint). If verification commands fail (e.g., system error), you MUST rely on ReadLints to ensure correctness. If **`pnpm josh test:e2e`** cannot complete in your environment, say so in the completion report and name the E2E result as missing — with a pull request open the CI E2E job is that result, and with no pull request there is none, so the gate is **not** closed. Never switch to build/CI flags to make it finish, and never hand the run to the user instead.
-
-## Refactoring Rules
-
-- **Prompt Reference**: When performing any refactoring, ALWAYS read and follow the instructions in `prompts/refactoring.md` before starting.
-
-## Git Rules
-
-- **No Commits**: DO NOT commit changes unless explicitly requested by the user.
-- **Workflow Awareness**: Use `pnpm josh git` when the user asks for git operations.
+For Svelte 5 / SvelteKit work, use the Svelte MCP server: call `list-sections` first, then `get-documentation` for every section whose use_cases match the task, and run `svelte-autofixer` on any Svelte code you write until it reports nothing. Offer `playground-link` only when asked, and never for code written to project files.

package/.github/actions/setup-node/action.yml

@@ -5,7 +5,7 @@ description: >
 
 # The one place the Node.js version of kit's workflows is written (joshuafolkken/kit#3084). Every
 # job used to call actions/setup-node with its own `node-version` literal, so a version move had to
-# find all of them. A job that needs a different runtime says so explicitly — `node-26-pnpm` in
+# find all of them. A job that needs a different runtime says so explicitly — `node-compat` in
 # `ci.yml` passes its own runtime to `.github/actions/setup-pnpm` instead of calling this.
 #
 # Distributed: `josh sync` writes this file into a consumer beside the workflows that call it, the

package/.github/workflows/auto-tag.yml

@@ -19,9 +19,8 @@ jobs:
           ref: ${{ github.event.client_payload.sha }}
           fetch-depth: 2
 
-      - name: Setup Node.js
-        uses: ./.github/actions/setup-node
-
+      # No Node.js setup: this job installs nothing and reads package.json with jq, which the runner
+      # image ships, so a Node.js version step would only add time (joshuafolkken/kit#3326).
       - name: Check if package.json changed
         id: pkg_changed
         run: |
@@ -37,7 +36,7 @@ jobs:
         id: current_version
         if: steps.pkg_changed.outputs.changed == 'true'
         run: |
-          VERSION=$(node -p "require('./package.json').version")
+          VERSION=$(jq -r '.version' package.json)
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           echo "Current version: $VERSION"
 

package/.github/workflows/ci.yml

@@ -32,19 +32,41 @@ env:
 # pnpm version resolution, the store cache, the safe-chain installer pin and the install
 # (joshuafolkken/kit#2982).
 jobs:
-  node-26-pnpm:
-    name: Node 26 pnpm
+  # Every other job runs on the Node.js version `.github/actions/setup-node` names, while `engines`
+  # and the esbuild target accept Node 22 and a consumer may already be on 26. This job builds the
+  # package and starts the bundled CLI on both ends of that range, so a syntax or API the oldest
+  # supported Node lacks fails here instead of in a consumer (joshuafolkken/kit#3326). The runtime
+  # comes from pnpm's `runtime` input, not setup-node, so the one Node.js version stays written once.
+  # The oldest entry is the exact `engines` floor, not a bare major that resolves to the newest 22.x;
+  # `scripts/ci/ci-yml-pnpm-setup.test.ts` holds it equal to the floor `package.json` declares.
+  node-compat:
+    name: Node ${{ matrix.node }} build
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ['22.19.0', 26]
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     permissions:
       contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: ./.github/actions/setup-pnpm
+
+      - name: Setup pnpm and install dependencies
+        uses: ./.github/actions/setup-pnpm
         with:
-          runtime: node@26
-          install: 'false'
-      - run: node --version && pnpm --version
+          runtime: node@${{ matrix.node }}
+
+      - name: Verify Node.js version
+        env:
+          NODE_VERSION: ${{ matrix.node }}
+        run: node --version | tee /dev/stderr | grep -qE "^v${NODE_VERSION}(\.|$)" && pnpm --version
+
+      - name: Build package
+        run: pnpm build
+
+      - name: Run CLI smoke
+        run: node dist/josh.js help
 
   playwright-image:
     name: Resolve Playwright image
@@ -519,19 +541,9 @@ jobs:
       packages: read
     container: ${{ fromJSON(needs.playwright-image.outputs.container) }}
     timeout-minutes: 10
-    # Better Auth rejects any origin its BETTER_AUTH_URL does not name, so this job pins the value
-    # to the preview server the suite talks to rather than letting a production value reach it.
-    # It has to be the port that server listens on. 4173 is correct because `PORT_SEED` — the
-    # personal offset `playwright.config.ts` resolves the preview port from — is not committed (it
-    # lives in a gitignored `.env`) and is not set anywhere in this workflow, so the port resolves
-    # to its base on every CI run. That is the invariant, not a constant in `playwright.config.ts`:
-    # the port there is seed-derived. The one setting that would move the port and leave this URL
-    # behind is an `env` entry for the seed in this file, at workflow or job level. A repository or
-    # organization variable would not: it reaches a step only through an explicit `vars.PORT_SEED`
-    # expression, and nothing here writes one. For a seeded CI job, derive this URL from
-    # `josh port preview` in the same job instead.
-    env:
-      BETTER_AUTH_URL: http://localhost:4173
+    # kit is not a SvelteKit app, so this job carries neither the `.svelte-kit` build cache nor the
+    # Better Auth `BETTER_AUTH_URL` pin; both belong to the consumer's copy in
+    # `templates/workflows/ci.yml`, which keeps them (joshuafolkken/kit#3326).
     steps:
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -541,17 +553,6 @@ jobs:
         with:
           registry-url: 'https://npm.pkg.github.com'
 
-      - name: Setup build cache
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        id: build-cache
-        with:
-          path: |
-            .svelte-kit
-          key: ${{ runner.os }}-build-cache-e2e-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('svelte.config.js', 'vite.config.ts', 'tsconfig.json', 'src/lib/server/auth.ts') }}
-          restore-keys: |
-            ${{ runner.os }}-build-cache-e2e-${{ hashFiles('pnpm-lock.yaml') }}-
-            ${{ runner.os }}-build-cache-e2e-
-
       - name: Setup pnpm and install dependencies
         uses: ./.github/actions/setup-pnpm
         with:

package/.github/workflows/dependabot-auto-merge.yml

@@ -11,18 +11,24 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-permissions:
-  contents: write
-  pull-requests: write
-
 jobs:
+  # Gated on who opened the pull request rather than on who triggered the run, the same job gate as
+  # the distributed copy; arming stays restricted to Dependabot's own events, on the step below. The
+  # write rights are granted to this job alone (joshuafolkken/kit#3268).
   auto-merge:
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    if: github.actor == 'dependabot[bot]'
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    permissions:
+      contents: write
+      pull-requests: write
     steps:
+      # The author gate also runs the job on a maintainer's push to a Dependabot branch, where this
+      # action fails because the first commit is no longer Dependabot's. Contained as in the
+      # distributed copy: the outputs stay empty, so the arming step below is simply not reached.
       - name: Fetch Dependabot metadata
         id: metadata
+        continue-on-error: true
         uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
         with:
           github-token: '${{ secrets.GITHUB_TOKEN }}'
@@ -47,7 +53,8 @@ jobs:
       # CI only proves that kit still builds. Major bumps never auto-merge in either ecosystem.
       - name: Enable auto-merge for github-actions patch and minor updates
         if: >-
-          steps.metadata.outputs.package-ecosystem == 'github_actions'
+          github.actor == 'dependabot[bot]'
+          && steps.metadata.outputs.package-ecosystem == 'github_actions'
           && (steps.metadata.outputs.update-type == 'version-update:semver-patch'
           || steps.metadata.outputs.update-type == 'version-update:semver-minor')
         env:

package/.github/workflows/publish.yml

@@ -12,7 +12,37 @@ on:
 # cache is off here: a cache entry another run saved never reaches a job with publish credentials.
 
 jobs:
+  # The package is built once, here, and both registries receive this one tarball: a job that built
+  # its own copy could publish different bytes under the same version (joshuafolkken/kit#3268). The
+  # job holds no publish credentials, so the build runs without any.
+  pack:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: ./.github/actions/setup-node
+
+      - uses: ./.github/actions/setup-pnpm
+        with:
+          cache: 'false'
+
+      - run: pnpm pack --out "$RUNNER_TEMP/kit.tgz"
+
+      # Kept as long as GitHub lets a run be re-run, so re-running a failed publish job still finds
+      # the tarball instead of forcing a full re-run that republishes an existing version.
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: kit-package
+          path: ${{ runner.temp }}/kit.tgz
+          if-no-files-found: error
+          retention-days: 30
+
   publish-github:
+    needs: pack
     if: startsWith(github.ref, 'refs/tags/v')
     concurrency:
       group: package-publish
@@ -53,14 +83,22 @@ jobs:
         env:
           LATEST: ${{ steps.registry-latest.outputs.latest }}
 
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: kit-package
+          path: ${{ runner.temp }}
+
       # The tag reaches the command through the environment rather than expanded into it, so a step
-      # output is never parsed as shell (joshuafolkken/kit#3084).
-      - run: pnpm publish --no-git-checks --tag "$PUBLISH_TAG" --registry https://npm.pkg.github.com
+      # output is never parsed as shell (joshuafolkken/kit#3084). setup-node's user config carries
+      # the GitHub Packages token, so it is kept here.
+      - name: Publish to GitHub Packages
+        run: cd "$RUNNER_TEMP" && npm publish kit.tgz --tag "$PUBLISH_TAG" --registry https://npm.pkg.github.com
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PUBLISH_TAG: ${{ steps.publish-tag.outputs.tag }}
 
   publish-npm:
+    needs: pack
     if: startsWith(github.ref, 'refs/tags/v')
     concurrency:
       group: package-publish
@@ -88,7 +126,10 @@ jobs:
         with:
           cache: 'false'
 
-      - run: pnpm pack --out "$RUNNER_TEMP/kit.tgz"
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: kit-package
+          path: ${{ runner.temp }}
 
       - name: Select npm tag
         id: publish-tag
@@ -115,6 +156,9 @@ jobs:
   create-release:
     needs: [publish-github, publish-npm, update-production]
     runs-on: ubuntu-latest
+    # `josh release:github` waits up to 60 minutes (120 polls, 30 seconds apart) for lower tags'
+    # releases, which can sit queued behind `package-publish`; the extra 5 minutes cover the setup
+    # before it. Lower this only together with that wait budget.
     timeout-minutes: 65
     permissions:
       actions: read
@@ -138,4 +182,4 @@ jobs:
           RELEASE_TAG: ${{ github.ref_name }}
           RELEASE_START_TAG: v1.887.0
           RELEASE_WORKFLOW: publish.yml
-          RELEASE_JOBS: publish-github,publish-npm,update-production
+          RELEASE_JOBS: pack,publish-github,publish-npm,update-production

package/.github/workflows/sonar-qube.yml

@@ -3,7 +3,10 @@ on:
   push:
     branches:
       - main
+  # Limited to main like ci.yml: a pull request into another branch is never merged to main as is,
+  # so its scan would spend a run and SonarCloud analysis on code that does not ship.
   pull_request:
+    branches: [main]
     types: [opened, synchronize, reopened]
 # A push run is grouped by the commit it carries, so a later push to main never cancels an earlier
 # one; without the sha every push to main shares one group and the run for the commit that changed

package/.pnpmfile.mjs

@@ -2,9 +2,10 @@
 // `josh init` / `josh sync` copy this file into every project that publishes (joshuafolkken/kit#3110)
 // and overwrite it while this first line stays; edit it in kit, not here.
 // Strips the Safe Chain `preinstall` from the packed manifest only (joshuafolkken/kit#2693).
-// kit writes it to run Safe Chain for the repository's own development installs; shipped, it becomes
-// a build script every consumer's pnpm refuses to run unapproved, and it could not protect them
-// anyway — their install has already started by the time a dependency's `preinstall` runs. The
+// kit writes it to warn the repository's own development installs when Safe Chain is not active
+// (joshuafolkken/kit#3269); shipped, it becomes a build script every consumer's pnpm refuses to run
+// unapproved, and it could not protect them anyway — their install has already started by the time
+// a dependency's `preinstall` runs. The
 // repository's package.json keeps it; `pnpm pack` and `pnpm publish` call this hook on the copy they
 // write. Any other lifecycle script — a native build, a binary download — is the package's own and
 // ships untouched.

package/.prettierignore

@@ -1,5 +1,11 @@
-# Claude Code
-.claude/
+# Claude Code — local runtime state stays out; the distributed parts are formatted like any source
+.claude/*
+!.claude/settings.json
+!.claude/skills/
+!.claude/agents/
+!.claude/.claude-plugin/
+# Prettier pads every Markdown table column, which grows the skills past their byte budgets (joshuafolkken/kit#3325)
+.claude/**/*.md
 
 # Package Managers
 package-lock.json

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Claude Code Instructions
 
-> **This file is the entry point for every agent rule.** `AGENTS.md` and `GEMINI.md` are pointers to it. A rule's trigger is written **once**, here; its procedure and numbers **once**, at its pointer (the single source). History and rationale: `docs/maintainers/claude-md-history.md`.
+> The entry point for every agent rule — `AGENTS.md`, `GEMINI.md` and `.cursorrules` point here; each rule has a single source (`prompts/collaboration-workflow/residency.md`).
 
 ## Project
 
@@ -10,29 +10,29 @@ Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS ·
 
 - **Answer opinion-seeking questions from a neutral standpoint.** A leading question is not a cue to agree — recommend the option you genuinely judge best.
 - **Fix root causes, not symptoms.** Where the proper fix is out of scope, surface the root cause instead of papering over it.
-- **Cross-package problems → file the upstream Issue, then stop.** A defect in another package (a dependency, or `josh` / kit tooling) is never worked around locally — **weakening a verification gate is a workaround too**. File it (first-party Tier A, third-party Tier C) and stop. `prompts/collaboration-workflow/upstream-interrupt.md`.
+- **Cross-package problems → file the upstream Issue, then stop.** A defect in another package (a dependency, or `josh` / kit tooling) is never worked around locally — **weakening a verification gate is a workaround too**. File it (first-party Tier A, third-party Tier C) and stop. `prompts/collaboration-workflow/upstream-interrupt.md`. Your own repository's run tooling is not another package: `upstream-interrupt.md` → "実行中のリポジトリ自身のラン機構の不具合".
 - **Third-party repositories are Tier C.** Decide the party with `pnpm josh repo:party`; every write to a tracker we do not own needs explicit current-turn instruction. `prompts/collaboration-workflow/upstream-interrupt.md`.
-- **No clones — single-source, even across package boundaries.** Duplicate non-trivial logic only after presenting the alternative and getting explicit approval. `prompts/collaboration-workflow/principles.md` → "クローン禁止".
-- **Design for elegance and simplicity first.** Before adding a hook, guard, rule or abstraction, ask whether fixing the cause makes it unnecessary. `prompts/collaboration-workflow/principles.md` → "設計はエレガント".
-- **Distinguish consultation from execution.** A question or goal statement asks for analysis only — act on an explicit imperative or a workflow keyword. `prompts/collaboration-workflow/principles.md` → "相談と実行".
-- **Route distributed-doc / config changes upstream to kit.** In a consumer repo never edit kit-distributed docs/config (`josh sync` overwrites them); in kit you are the source. `prompts/collaboration-workflow/principles.md` → "配布ドキュメント".
-- **Latest-first, fix forward — pin back only as a last resort.** `prompts/collaboration-workflow/principles.md` → "最新優先".
+- **No clones — single-source, even across package boundaries.** Duplicate non-trivial logic only after presenting the alternative and getting explicit approval. `prompts/collaboration-workflow/principles.md` → "no-clones".
+- **Design for elegance and simplicity first.** Before adding a hook, guard, rule or abstraction, ask whether fixing the cause makes it unnecessary. `prompts/collaboration-workflow/principles.md` → "elegant-design".
+- **Distinguish consultation from execution.** A question or goal statement asks for analysis only — act on an explicit imperative or a workflow keyword. `prompts/collaboration-workflow/principles.md` → "consult-vs-execute".
+- **Route distributed-doc / config changes upstream to kit.** In a consumer repo never edit kit-distributed docs/config (`josh sync` overwrites them); in kit you are the source. `prompts/collaboration-workflow/principles.md` → "upstream-to-kit".
+- **Latest-first, fix forward — pin back only as a last resort.** `prompts/collaboration-workflow/principles.md` → "latest-first".
 - **Output language follows `JOSH_SESSION_LANG`** (default `ja`) for session output and artifact prose; English for Issue/PR titles, code comments, test titles, commit messages and script strings. `prompts/collaboration-workflow/overview.md`.
 - **Cite an Issue with a number-link and a short title in the session language.** `prompts/collaboration-workflow/issue-citation.md`.
-- **Durable rules belong in prompts/docs, not local MEMORY.** `prompts/collaboration-workflow/principles.md` → "恒久ルール".
+- **Durable rules belong in prompts/docs, not local MEMORY.** `prompts/collaboration-workflow/principles.md` → "durable-rules".
 - **Never carry a file's new text inside a shell command.** Use the Edit tool, not a heredoc. `prompts/collaboration-workflow/file-edits.md`.
 - **Never put a body in shell double quotes** — a backtick or `$` there is _executed_; pass the body by path. `prompts/collaboration-workflow/shell-body.md`.
 - **Put every call that does not depend on another's result in the same turn.** **The criterion is whether this call's input needs another call's result, not what kind of call it is** — edits are covered exactly as reads are. `pnpm josh batch:guard` enforces it; `prompts/collaboration-workflow/rule-delivery.md`.
 
-### Decision autonomy (minimize confirmation stops)
+### Decision autonomy
 
-Classify each decision point and act; stop **only** when it genuinely needs the user's judgment. `prompts/collaboration-workflow/operating-rules.md` → 「意思決定の自律ポリシー（確認停止を減らす）」.
+Classify each decision point and act; stop **only** where the user's judgment is genuinely needed. `prompts/collaboration-workflow/operating-rules.md` → "decision-autonomy".
 
 - **Tier A — reversible implementation / design choices** (library, naming, layout, tests, refactor shape; placing a filed Issue into an epic; self-correction). Pick the clearly-better option, proceed, log it.
 - **Tier B — genuine toss-up.** The only tier that stops — ask with the candidates and trade-offs.
 - **Tier C — irreversible / shared-state / out-of-scope actions** (merge, branch delete, force push, destructive ops, repo settings, out-of-scope work, `devEngines` / overrides edits): explicit user instruction only, never auto-decided. Deleting a git-tracked file is reversible, so it is not a destructive op — inspect the target first and surface any contradiction.
 
-Log auto-decisions: an Issue comment inside an Issue workflow, otherwise a one-line "Auto-decided: `<choice>` over `<alt>` because `<reason>`" in the reply.
+Log auto-decisions: an Issue comment in an Issue workflow, else a one-line "Auto-decided: `<choice>` over `<alt>` because `<reason>`" in the reply.
 
 ## Environment Variables
 
@@ -40,7 +40,7 @@ Log auto-decisions: an Issue comment inside an Issue workflow, otherwise a one-l
 
 ## Critical Conventions (non-standard — always apply)
 
-Most are lint-enforced; `function` syntax and the early-return one-liner are not. Craft guidance: `prompts/coding-standards.md`.
+Most are lint-enforced. Craft guidance: `prompts/coding-standards.md`.
 
 ### Naming
 
@@ -69,7 +69,7 @@ Svelte `PascalCase.svelte(.ts)` · TypeScript `kebab-case.ts` · tests `*.test.t
 
 - Effective overrides live in `pnpm-workspace.yaml`; check both files.
 - **NEVER** remove or modify entries in **either** location without explicit user approval.
-- **NEVER** modify the `devEngines` field in `package.json` without explicit user confirmation.
+- **NEVER** modify the `devEngines` field in `package.json` without explicit user confirmation — except the `josh latest` lockstep pnpm bump, kept per the `dependency-update` skill.
 - After any dependency-update command, load the `dependency-update` skill before reporting anything about the pins.
 
 ## Package-First Development
@@ -78,7 +78,7 @@ Before building a feature, check for a well-maintained package — measure with
 
 ## Code Change Rules
 
-0. **Work summary + test declaration** — before writing any implementation code, once per Issue (required in fullrun/halfrun/backlogrun; `kickoff` exempt), never wrapped in a code fence, never a confirmation stop. `prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint`.
+0. **Work summary + test declaration** — before writing any implementation code, once per Issue (required in fullrun/halfrun/prrun/backlogrun; `kickoff` exempt), never wrapped in a code fence, never a confirmation stop. `prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint`.
    - **Overview** — **Now / Change / Check**, one sentence each in the session language that a non-programmer can follow; name the concrete subject in each line — subject-less prose is not acceptable. Use no file paths, function or type names, or CLI option flags — only internal identifiers are banned.
    - **Details** — every change with its test: `<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`. Completion reports lead with **Cause / Fix / Result**.
    - **Tests are required for ALL changes** — zero tests without explicit approval is a violation. Exceptions (non-runtime and basic-profile manual checks): `prompts/testing-guide.md`. `pnpm josh test:declared` answers from the changed paths; a runtime change with no test is refused at `pnpm josh git -y` on `required`.
@@ -103,18 +103,18 @@ When `josh bump` changes the version, update `docs/` for any changed behavior be
 ## Git Rules
 
 - **No commits** unless explicitly requested. **No merges, branch deletions, force pushes or other shared-state mutations** unless requested in the current turn — except invoking `fullrun` or `backlogrun` authorizes the merge via `pnpm josh followup`; `prrun` does not. `.claude/settings.json` denies these, but the deny is narrower than the rule — never read "the tool let me" as permission.
-- **Never stage or mutate the git index on your own** — only on explicit instruction or via `pnpm josh git`. `prompts/collaboration-workflow/operating-rules.md` → "git index を勝手に変更しない".
+- **Never stage or mutate the git index on your own** — only on explicit instruction or via `pnpm josh git`. `prompts/collaboration-workflow/operating-rules.md` → "no-self-staging".
 - **Use `pnpm josh git`; open a PR with `pnpm josh pr`** — `pnpm josh rule:guard` refuses a direct `gh pr create`.
 - **Run `git status` (and `git stash list`) live** before acting on any tree assumption.
 
 ## Collaboration Workflow
 
-- The issue-driven flow: `prompts/collaboration-workflow.md`. **Before writing a rule as prose, place it by `prompts/collaboration-workflow/residency.md`** — computable answers go to `pnpm josh oracle:list`, ordering to `pnpm josh run:step`.
-- **File through `pnpm josh issue:file` — it counts the target repository's open Issues, never a hand count; above the WIP cap, close one first.** Nothing honestly closable means do not file. A filing the run is blocked by is exempt, and so is an **interrupt** — three tests decide that, never judgement: a verification answers wrongly, a documented workflow cannot complete, or data is lost or written outside the repository; both exemptions proceed, stating the overage. Meeting none of the three, a finding stays discretionary. `pnpm josh rule:guard` states it again at the call that files. `prompts/collaboration-workflow/wip-cap.md`.
+- The issue-driven flow: `prompts/collaboration-workflow.md`; where a new rule goes: `prompts/collaboration-workflow/residency.md` (computable answers → `pnpm josh oracle:list`, ordering → `pnpm josh run:step`).
+- **File through `pnpm josh issue:file`, never a hand count; above the WIP cap, close one first.** Exempt: a filing the run is blocked by, and an **interrupt** — a verification answers wrongly, a documented workflow cannot complete, or data is lost or written outside the repository; both proceed, stating the overage, and anything else stays discretionary. `pnpm josh rule:guard` states the rest at the call that files. `prompts/collaboration-workflow/wip-cap.md`.
 
 ### Shorthand Commands
 
-`kickoff`, `fullrun`, `prrun`, `halfrun`, `backlogrun` (with `#N` / `new`) are procedures in the `workflow-commands` skill — read it before any part of a command, including the first `gh` call. **What stays here is decided by one question: must the rule fire on a turn where no skill was loaded?** Explicit invocation, the mid-workflow stop notification, the `overrides` / `devEngines` prohibitions, the UI-verification gate and the three `epic:*` rules below all do.
+`kickoff`, `fullrun`, `prrun`, `halfrun`, `backlogrun` (with `#N` / `new`) are procedures in the `workflow-commands` skill — read it before any part of a command, including the first `gh` call.
 
 **`queue` and `epicrun` were removed** — point `queue` to `backlogrun #N1 #N2 …` and `epicrun` to `backlogrun #E --only`.
 
@@ -135,5 +135,3 @@ Before pausing **any** run for the user — a command's stop, an upstream-Issue
 ```bash
 pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'<one-line reason>\n<what is needed from the user>'
 ```
-
-Keep `--body=...` one token when the body starts with `-`, otherwise `parseArgs` rejects it.

package/README.md

@@ -12,32 +12,39 @@
 [![CI](https://github.com/joshuafolkken/kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/joshuafolkken/kit/actions/workflows/ci.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=joshuafolkken_kit&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=joshuafolkken_kit)
 
-**Tell your AI agent the change. It files the GitHub Issue and takes it to a merged PR — the same way in every project.**
+**AI assistant setup, plus an optional GitHub workflow.**
 
-kit gives Claude Code or Codex (or Gemini, Cursor) your project's rules, checks and an Issue-driven workflow.
+kit gives Claude Code or Codex your project's rules and checks. With the workflow, the agent takes each change from Issue to merged PR.
+
+**Only want the AI assistant, without the GitHub workflow?** Set it up here: [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) · [Other projects](./docs/setup/basic.md)
 
 ## Sound familiar?
 
 Each pain links to how it is solved — or read [the whole story](./docs/why.md).
 
+kit solves these in every project — and so do [app-kit] and [game-kit], which build on it:
+
+- [Done doesn't mean done](./docs/why.md#done-doesnt-mean-done)
+- [Quality slips with every change](./docs/why.md#quality-slips-with-every-change)
+- [I keep repeating the same instructions](./docs/why.md#i-keep-repeating-the-same-instructions)
+- [The agent does things I never asked for](./docs/why.md#the-agent-does-things-i-never-asked-for)
+- [Reviewing every change is a chore](./docs/why.md#reviewing-every-change-is-a-chore)
+- [Some changes need a human eye](./docs/why.md#some-changes-need-a-human-eye)
+- [I spend all day talking to the agent](./docs/why.md#i-spend-all-day-talking-to-the-agent)
+- [Big requests come back sloppy](./docs/why.md#big-requests-come-back-sloppy)
+- [I want many Issues solved at once](./docs/why.md#i-want-many-issues-solved-at-once)
+- [AI costs keep climbing](./docs/why.md#ai-costs-keep-climbing)
+- [Writing Issues is a chore](./docs/why.md#writing-issues-is-a-chore)
+- [Wiring AI up to GitHub is a chore](./docs/why.md#wiring-ai-up-to-github-is-a-chore)
+- [I can't tell if the agent is stuck or done](./docs/why.md#i-cant-tell-if-the-agent-is-stuck-or-done)
+- [One task overwrote another's work](./docs/why.md#one-task-overwrote-anothers-work)
+- [A session cut off and I lost track](./docs/why.md#a-session-cut-off-and-i-lost-track)
+- [The backlog fills with duplicate Issues](./docs/why.md#the-backlog-fills-with-duplicate-issues)
+
+The app and game kits add:
+
 | Your pain                                                                                                                  | kit | [app-kit] | [game-kit] |
 | -------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :--------: |
-| [Done doesn't mean done](./docs/why.md#done-doesnt-mean-done)                                                              | ✅  |    ✅     |     ✅     |
-| [Quality slips with every change](./docs/why.md#quality-slips-with-every-change)                                           | ✅  |    ✅     |     ✅     |
-| [I keep repeating the same instructions](./docs/why.md#i-keep-repeating-the-same-instructions)                             | ✅  |    ✅     |     ✅     |
-| [The agent does things I never asked for](./docs/why.md#the-agent-does-things-i-never-asked-for)                           | ✅  |    ✅     |     ✅     |
-| [Reviewing every change is a chore](./docs/why.md#reviewing-every-change-is-a-chore)                                       | ✅  |    ✅     |     ✅     |
-| [Some changes need a human eye](./docs/why.md#some-changes-need-a-human-eye)                                               | ✅  |    ✅     |     ✅     |
-| [I spend all day talking to the agent](./docs/why.md#i-spend-all-day-talking-to-the-agent)                                 | ✅  |    ✅     |     ✅     |
-| [Big requests come back sloppy](./docs/why.md#big-requests-come-back-sloppy)                                               | ✅  |    ✅     |     ✅     |
-| [I want many Issues solved at once](./docs/why.md#i-want-many-issues-solved-at-once)                                       | ✅  |    ✅     |     ✅     |
-| [AI costs keep climbing](./docs/why.md#ai-costs-keep-climbing)                                                             | ✅  |    ✅     |     ✅     |
-| [Writing Issues is a chore](./docs/why.md#writing-issues-is-a-chore)                                                       | ✅  |    ✅     |     ✅     |
-| [Wiring AI up to GitHub is a chore](./docs/why.md#wiring-ai-up-to-github-is-a-chore)                                       | ✅  |    ✅     |     ✅     |
-| [I can't tell if the agent is stuck or done](./docs/why.md#i-cant-tell-if-the-agent-is-stuck-or-done)                      | ✅  |    ✅     |     ✅     |
-| [One task overwrote another's work](./docs/why.md#one-task-overwrote-anothers-work)                                        | ✅  |    ✅     |     ✅     |
-| [A session cut off and I lost track](./docs/why.md#a-session-cut-off-and-i-lost-track)                                     | ✅  |    ✅     |     ✅     |
-| [The backlog fills with duplicate Issues](./docs/why.md#the-backlog-fills-with-duplicate-issues)                           | ✅  |    ✅     |     ✅     |
 | [Setting up SvelteKit on Cloudflare takes a day](https://github.com/joshuafolkken/app-kit/blob/main/docs/setup/install.md) |  —  |    ✅     |     ✅     |
 | [I'm not sure the app is secure](https://github.com/joshuafolkken/app-kit/blob/main/docs/security-headers.md)              |  —  |    ✅     |     ✅     |
 | [Nobody looked at the screen](https://github.com/joshuafolkken/app-kit/blob/main/docs/shot.md)                             |  —  |    ✅     |     ✅     |
@@ -80,7 +87,7 @@ Add the two Telegram credentials to `.env` so a run that needs you can reach you
 
 Then open your agent and follow the [tutorial](./docs/tutorial.md).
 
-No Issue workflow? [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) · [Other projects](./docs/setup/basic.md)
+AI assistant only, no GitHub workflow? [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) · [Other projects](./docs/setup/basic.md)
 
 ## Docs
 

package/SECURITY.md

@@ -29,7 +29,7 @@ The `files` field of `package.json` decides what the published `@joshuafolkken/k
 - `.codex/` — the same hooks for Codex (`hooks.json`) and its project settings (`config.toml`).
 - `.github/` — GitHub Actions workflows (CI, tagging, pull request classification, Dependabot auto-merge, SonarQube and production), composite actions, `dependabot.yml`, the pull request template and the release-notes config. `josh sync` overwrites the distributed workflows; their action references are pinned to commit SHAs. kit's own `publish.yml` ships in the package but is never copied into a project.
 - `lefthook/` — Git hook presets: lint before commit, checks before push.
-- The `preinstall` script `josh init` adds to `package.json` runs `pnpm dlx @aikidosec/safe-chain setup-ci` on every install, then a `node -e` check that only prints a warning, and only outside CI. The `prepare` script it adds runs `lefthook install` when Lefthook is present, then, when tsx is present, kit's `fix-gh-packages` script: only when the project `.npmrc` routes a scope to GitHub Packages, it reads a GitHub token (`NODE_AUTH_TOKEN`, a token in the project `.npmrc`, or `gh auth token`), queries GitHub Packages and rewrites tarball URLs in `pnpm-lock.yaml`.
+- The `preinstall` script `josh init` adds to `package.json` is a `node -e` check that fetches nothing and only prints a warning — outside CI, when safe-chain is not scanning the install (see [Installing safe-chain](#installing-safe-chain)). The `prepare` script it adds runs `lefthook install` when Lefthook is present, then, when tsx is present, kit's `fix-gh-packages` script: only when the project `.npmrc` routes a scope to GitHub Packages, it reads a GitHub token (`NODE_AUTH_TOKEN`, a token in the project `.npmrc`, or `gh auth token`), queries GitHub Packages and rewrites tarball URLs in `pnpm-lock.yaml`.
 - `.pnpmfile.mjs` — a pnpm `beforePacking` hook that removes that safe-chain `preinstall` from the manifest `pnpm pack` and `pnpm publish` write, and changes nothing else. `josh init` and `josh sync` copy it only into a project whose `package.json` is not `private: true`, and never over a pnpmfile of the project's own.
 
 **Agent instructions and skills**
@@ -47,6 +47,20 @@ The `files` field of `package.json` decides what the published `@joshuafolkken/k
 - `.vscode/`, `.gitattributes`, `.ncurc.json`, `.prettierignore`, `pnpm-workspace.yaml` — editor, Git and package-manager settings.
 - `CODE_OF_CONDUCT.md`, `SECURITY.md` — community files.
 
+## Installing safe-chain
+
+[safe-chain](https://github.com/AikidoSec/safe-chain) scans a local `pnpm install` for malware once its shell integration is active. The `preinstall` script only warns when it is not; it never installs safe-chain itself. Install it from a release whose installer hash you have checked — the same release and SHA-256 kit's CI uses, pinned as `SAFE_CHAIN_INSTALLER_VERSION` and `SAFE_CHAIN_INSTALLER_SHA256` in [`.github/actions/setup-pnpm/action.yml`](https://github.com/joshuafolkken/kit/blob/main/.github/actions/setup-pnpm/action.yml):
+
+```sh
+version=<SAFE_CHAIN_INSTALLER_VERSION>
+sha256=<SAFE_CHAIN_INSTALLER_SHA256>
+curl --proto '=https' -fsSL "https://github.com/AikidoSec/safe-chain/releases/download/$version/install-safe-chain.sh" -o install-safe-chain.sh
+echo "$sha256  install-safe-chain.sh" | shasum -a 256 -c -
+sh install-safe-chain.sh
+```
+
+Stop if `shasum` does not print `install-safe-chain.sh: OK`. Then restart your terminal; if the warning still appears, run `safe-chain setup` and restart it again.
+
 ## Secrets
 
 kit never stores a secret in a file it ships or commits. The ones it uses: