@joshuafolkken/kit 1.1050.0 → 1.1094.0

package/.github/workflows/pr-classification.yml

@@ -15,13 +15,6 @@ on:
 # nothing here needs it: every run reads the pull request's labels as they stand when it runs, not as
 # its event carried them, so whichever suite GitHub counts as newest holds a current verdict.
 
-# The same safe-chain installer pin as ci.yml — the release and its install-safe-chain.sh SHA-256.
-# `pnpm dlx … setup-ci` left only shims, so the install below ran without a scan (joshuafolkken/kit#2765).
-# `josh latest` moves both together, in this file and in ci.yml.
-env:
-  SAFE_CHAIN_INSTALLER_VERSION: 1.5.20
-  SAFE_CHAIN_INSTALLER_SHA256: 0ad25efe15d1fa56105157a454d647223e78eb0c53d1f85e3d10afcd722e7bfd
-
 jobs:
   classification:
     name: Release classification
@@ -45,41 +38,12 @@ jobs:
       - name: Configure GitHub Packages authentication for existing projects
         run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
 
-      - name: Resolve pnpm version
-        id: pnpm-version
-        run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-
-      - name: Setup pnpm
-        uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
-        with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - name: Resolve pnpm store path
-        run: echo "PNPM_STORE_PATH=$(pnpm store path)" >> "$GITHUB_ENV"
-
-      - name: Setup pnpm store cache
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      # The shared pnpm preamble — version, store cache, the safe-chain installer pin and the install
+      # (joshuafolkken/kit#2765, joshuafolkken/kit#2982).
+      - name: Setup pnpm and install dependencies
+        uses: ./.github/actions/setup-pnpm
         with:
-          path: ${{ env.PNPM_STORE_PATH }}
-          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-store-
-
-      - name: Setup safe-chain
-        run: |
-          installer="$RUNNER_TEMP/install-safe-chain.sh"
-          curl --proto '=https' -fsSL "https://github.com/AikidoSec/safe-chain/releases/download/$SAFE_CHAIN_INSTALLER_VERSION/install-safe-chain.sh" -o "$installer"
-          echo "$SAFE_CHAIN_INSTALLER_SHA256  $installer" | sha256sum -c -
-          sh "$installer" --ci
-
-      - name: Install dependencies
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: pnpm install --frozen-lockfile --ignore-scripts
+          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Check release classification
         env:

package/.github/workflows/publish.yml

@@ -7,6 +7,10 @@ run-name: Publish ${{ github.ref_name }}
 on:
   workflow_dispatch:
 
+# Every job installs through `.github/actions/setup-pnpm`, so the jobs holding the publish rights
+# install behind the same hash-verified safe-chain scan as CI (joshuafolkken/kit#2982). The store
+# cache is off here: a cache entry another run saved never reaches a job with publish credentials.
+
 jobs:
   publish-github:
     if: startsWith(github.ref, 'refs/tags/v')
@@ -27,29 +31,28 @@ jobs:
           registry-url: 'https://npm.pkg.github.com'
           scope: '@joshuafolkken'
 
-      - name: Resolve pnpm version
-        id: pnpm-version
+      # Read before setup-pnpm puts the safe-chain shims on PATH: safe-chain hides recent versions from
+      # registry metadata and prints a notice to stdout, which corrupts the value (joshuafolkken/kit#3060).
+      - name: Read registry latest
+        id: registry-latest
         run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://npm.pkg.github.com)
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+      - uses: ./.github/actions/setup-pnpm
         with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - run: pnpm install --frozen-lockfile --ignore-scripts
+          cache: 'false'
 
       - name: Select GitHub Packages tag
         id: publish-tag
         run: |
           version=$(node -p "require('./package.json').version")
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://npm.pkg.github.com)
-          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$latest")
+          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$LATEST")
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          LATEST: ${{ steps.registry-latest.outputs.latest }}
 
       - run: pnpm publish --no-git-checks --tag ${{ steps.publish-tag.outputs.tag }} --registry https://npm.pkg.github.com
         env:
@@ -73,19 +76,16 @@ jobs:
           node-version: 24
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Resolve pnpm version
-        id: pnpm-version
+      # Before setup-pnpm, for the same reason as publish-github's lookup (joshuafolkken/kit#3060).
+      - name: Read registry latest
+        id: registry-latest
         run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
+          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org)
+          echo "latest=$latest" >> "$GITHUB_OUTPUT"
 
-      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+      - uses: ./.github/actions/setup-pnpm
         with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - run: pnpm install --frozen-lockfile --ignore-scripts
+          cache: 'false'
 
       - run: pnpm pack --out "$RUNNER_TEMP/kit.tgz"
 
@@ -93,9 +93,10 @@ jobs:
         id: publish-tag
         run: |
           version=$(node -p "require('./package.json').version")
-          latest=$(cd "$RUNNER_TEMP" && npm view @joshuafolkken/kit dist-tags.latest --registry https://registry.npmjs.org)
-          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$latest")
+          tag=$(pnpm exec tsx scripts/release/publish-tag-cli.ts "$version" "$LATEST")
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
+        env:
+          LATEST: ${{ steps.registry-latest.outputs.latest }}
 
       - name: Publish to npm
         run: cd "$RUNNER_TEMP" && npm publish kit.tgz --access public --tag ${{ steps.publish-tag.outputs.tag }} --registry https://registry.npmjs.org --userconfig /dev/null
@@ -124,22 +125,16 @@ jobs:
         with:
           node-version: 24
 
-      - name: Resolve pnpm version
-        id: pnpm-version
-        run: |
-          version=$(node -p "const m = require('./package.json'); m.packageManager?.match(/^pnpm@([^+]+)/)?.[1] ?? (m.devEngines?.packageManager?.name === 'pnpm' ? m.devEngines.packageManager.version?.split('+')[0] : 'latest') ?? 'latest'")
-          test -n "$version"
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-
-      - uses: pnpm/setup@fbda4c85fc2e1e08721cd8763afea8f48d60f024 # v3.0.0
+      - uses: ./.github/actions/setup-pnpm
         with:
-          version: ${{ steps.pnpm-version.outputs.version }}
-          install: false
-
-      - run: pnpm install --frozen-lockfile --ignore-scripts
+          cache: 'false'
 
+      # Tags through v1.887.0 predate automatic GitHub Releases and must not block the first new one.
       - name: Publish GitHub Release
-        run: pnpm exec tsx scripts/release/github-release-cli.ts
+        run: pnpm josh release:github
         env:
           GH_TOKEN: ${{ github.token }}
           RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_START_TAG: v1.887.0
+          RELEASE_WORKFLOW: publish.yml
+          RELEASE_JOBS: publish-github,publish-npm,update-production

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

@@ -18,6 +18,7 @@ jobs:
     name: SonarQube
     permissions:
       contents: read
+      packages: read
     runs-on: ubuntu-latest
     # A consumer that does not use SonarCloud has no SONAR_TOKEN, and the scan would fail on
     # authentication and turn a required check red (joshuafolkken/kit#2815). `secrets` cannot be read
@@ -34,11 +35,43 @@ jobs:
         if: env.SONAR_TOKEN != ''
         with:
           fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
+      # SonarCloud's New Code starts at the previous version, so an analysis without
+      # `sonar.projectVersion` never moves that start and New Code grows without end, diluting every
+      # ratio the Quality Gate judges (joshuafolkken/kit#3045). The version is `package.json`'s, so
+      # each `josh bump` that reaches main starts a new New Code period.
+      - name: Resolve project version
+        id: project-version
+        if: env.SONAR_TOKEN != ''
+        run: |
+          version=$(jq -r '.version // empty' package.json)
+          echo "args=${version:+-Dsonar.projectVersion=$version}" >> "$GITHUB_OUTPUT"
       - name: SonarQube Scan
         if: env.SONAR_TOKEN != ''
         uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
         with:
-          # Wait for the SonarCloud Quality Gate and fail this job (a required PR check) when the
-          # gate is red, so a PR that introduces a Maintainability / code-smell finding cannot be
-          # merged green. Without this flag the scan only uploads results and never blocks.
-          args: -Dsonar.qualitygate.wait=true
+          # Wait for the SonarCloud Quality Gate and fail this job when the gate is red. The gate
+          # judges ratings and ratios, not counts, so it alone lets a few new code smells or a small
+          # copied block through; the new-code check below is what fails on a single finding.
+          args: -Dsonar.qualitygate.wait=true ${{ steps.project-version.outputs.args }}
+      # The new-code check reads the pull request's analysis from the SonarCloud API and fails this
+      # job (a required PR check) when the pull request adds any new issue, of any type or severity,
+      # or any new duplicated block (joshuafolkken/kit#3045). An issue resolved in SonarCloud as
+      # accepted or a false positive is not counted. A push to main has no pull request to read.
+      - name: Setup Node.js
+        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '24'
+      - name: Configure GitHub Packages authentication for existing projects
+        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
+        run: printf '//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}\n' >> "$HOME/.npmrc"
+      - name: Setup pnpm and install dependencies
+        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
+        uses: ./.github/actions/setup-pnpm
+        with:
+          node-auth-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Fail on new Sonar issues or duplicated blocks
+        if: env.SONAR_TOKEN != '' && github.event_name == 'pull_request'
+        env:
+          PULL_REQUEST: ${{ github.event.pull_request.number }}
+        run: pnpm josh sonar:new-code "$PULL_REQUEST"

package/AGENTS.md

@@ -1,8 +1,18 @@
 # Agent Instructions
 
 > **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. Nothing in
-> `CLAUDE.md` is Claude-specific — it applies to whatever agent is doing the work.
+> any work here, and follow every rule in it.** This file exists only to point at it. The rules apply
+> to whatever agent is doing the work, but `CLAUDE.md` is written for Claude Code and names its
+> features — read them as follows.
+
+- **Hooks.** Codex runs the same hooks from `.codex/hooks.json`, which is generated from
+  `.claude/settings.json`. Where Codex does not show a hook's output, apply the rule yourself — resolve
+  `JOSH_SESSION_LANG` from `.env` rather than waiting for it to be injected.
+- **Skills, `/verify-ui` and `/code-review`.** Where `CLAUDE.md` says to load a skill or run one in a
+  subagent, read that skill's `SKILL.md` and follow it in your own session.
+- **The `.claude/settings.json` deny list** is not enforced here. The rules it backs — no commits,
+  merges, staging or other shared-state changes without instruction — still bind you.
+- **`AskUserQuestion`** means asking the user in plain text.
 
 **Do not copy rules back into this file.** Every change to how agents work in this repository belongs
 in `CLAUDE.md`.

package/CLAUDE.md

@@ -1,8 +1,6 @@
 # Claude Code Instructions
 
-> **This file is the single source for every agent rule.** `AGENTS.md` and `GEMINI.md` are pointers to it and carry no rules of their own — a rule addition, spec change or wording fix is written **once**, here. History: `docs/maintainers/claude-md-history.md`.
->
-> Each rule is written as a **trigger plus a pointer** — enough to act safely with nothing else loaded, with the steps and rationale at the pointer.
+> **This file is the entry point for every agent rule.** `AGENTS.md` and `GEMINI.md` are pointers to it and carry no rules of their own — a rule's trigger is written **once**, here, and its procedure and any number it uses **once**, at its pointer. History, and the explanations kept out of this file: `docs/maintainers/claude-md-history.md`.
 
 ## Project
 
@@ -19,8 +17,8 @@ Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS ·
 - **Distinguish consultation from execution.** A question about approach or a goal statement ("どうすべき？", "〜したい") is a request for analysis only — act only 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 locally (`josh sync` overwrites them); propose the change for kit. In kit itself you are the source. `prompts/collaboration-workflow/principles.md` → "配布ドキュメント".
 - **Latest-first, fix forward — pin back only as a last resort.** Adopt newest versions by default and resolve a breaking bump forward, recording why on the rare pin-back. `prompts/collaboration-workflow/principles.md` → "最新優先".
-- **Output language follows `JOSH_SESSION_LANG`** (default `ja`; a hook injects it). It governs session-facing output and artifact prose (Issue bodies, comments, Telegram). English stays for Issue/PR titles, code comments/test titles/commit messages, and script-emitted strings. `prompts/collaboration-workflow/overview.md`.
-- **Cite an Issue with a number-link and a short Japanese title in session-facing output** — `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <短い要約>`. `prompts/collaboration-workflow/issue-citation.md`.
+- **Output language follows `JOSH_SESSION_LANG`** (default `ja`; a hook injects it). It governs session-facing output and artifact prose (Issue bodies, comments, Telegram). English stays for Issue/PR titles, code comments/test titles/commit messages, and script-emitted strings. One language per doc layer (English here; mostly Japanese in the prompt files). `prompts/collaboration-workflow/overview.md`.
+- **Cite an Issue with a number-link and a short title in the session language in session-facing output** — `[#<N>](https://github.com/<owner>/<repo>/issues/<N>) — <short summary>`. `prompts/collaboration-workflow/issue-citation.md`.
 - **Durable rules belong in prompts/docs, not local MEMORY.** Encode a lasting rule as a change to kit's distributed prompts/docs, not auto-memory; propose the edit when the turn does not authorize one. `prompts/collaboration-workflow/principles.md` → "恒久ルール".
 - **Never carry a file's new text inside a shell command.** Edit a region with the Edit tool, never a heredoc — unless the change is so scattered the partial edit would carry more text than the file. The criterion is whether the command carries the replacement wholesale, not the tool's name. `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`.
@@ -38,7 +36,7 @@ Classify each decision point into one tier and act; stop **only** when the choic
 
 ## Environment Variables
 
-Read from a `.env` file at the project root by the AI scripts, `josh port` and `playwright.config.ts`. `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are required for notifications; `JOSH_SESSION_LANG`, `PORT_SEED` and `JOSH_REPO_PATHS` are optional and personal. Setup and full semantics: [docs/scripts-ai.md](https://github.com/joshuafolkken/kit/blob/main/docs/scripts-ai.md) and [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md).
+A `.env` at the project root: `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are required for notifications; `JOSH_SESSION_LANG`, `PORT_SEED` and `JOSH_REPO_PATHS` are optional and personal. Setup and semantics: [docs/scripts-ai.md](https://github.com/joshuafolkken/kit/blob/main/docs/scripts-ai.md) and [docs/josh-commands.md](https://github.com/joshuafolkken/kit/blob/main/docs/josh-commands.md).
 
 **GitHub operations are `gh api` (REST) — instructing prose included — and need `gh` installed; some environments lack it.** Auth: `gh auth login`; `GH_TOKEN` in CI/cloud. `prompts/collaboration-workflow/gh-rest.md`.
 
@@ -66,7 +64,7 @@ Read from a `.env` file at the project root by the AI scripts, `josh port` and `
 ### Quality limits
 
 - Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4
-- **Those line counts are code lines, not physical lines** (`max-lines` / `max-lines-per-function` run with `skipBlankLines` + `skipComments`) — judge by what `pnpm josh lint` reports, never `wc -l`. Test files (`*.test.ts` / `*.e2e.ts`) allow 35 code lines per function.
+- **Those line counts are code lines, not physical lines** — judge by what `pnpm josh lint` reports, never `wc -l`. Test files (`*.test.ts` / `*.e2e.ts`) allow 35 code lines per function.
 - Magic numbers: extract all literals except `0`, `1`, `-1` to named `UPPER_CASE` constants
 - No `any` · no unused vars · no floating promises · type assertions (`as`) are restricted
 - All function params and return types must be explicitly typed
@@ -96,17 +94,17 @@ Read from a `.env` file at the project root by the AI scripts, `josh port` and `
 
 - Before building a feature, check whether a well-maintained package already solves the problem rather than writing original code first, and propose replacing hand-rolled implementations with a suitable package when it improves maintainability.
 - Prefer modern, actively-maintained packages (maintenance, popularity, bundle size, TypeScript support, license, fit). **If one is clearly the best fit, select it** (Tier A — log it); **only when two or more are genuinely close**, present about three ranked options and let the user choose.
-- **Measure the choice before you judge it — `pnpm josh pkg:scout <keywords>`.** It ranks the candidate packages by downloads, last publish, bundled types, license and install size, and prints `clear` when the leader is ahead by at least the near-tie threshold (select it, Tier A) or `close` when the top two are within it (ask, Tier B) — so "clearly best" and "genuine toss-up" are read off the output rather than decided by impression.
+- **Measure the choice before you judge it — `pnpm josh pkg:scout <keywords>`:** `clear` → select it (Tier A), `close` → ask (Tier B). Metrics and threshold: `docs/josh-commands-automation.md`.
 
 ## Code Change Rules
 
 For every code modification, in order:
 
-0. **Work summary + test declaration** _(before writing any implementation code)_: a two-layer summary — a plain-language overview a non-programmer can follow (three lines, **Now / Change / Check**, one sentence each, in the session language; name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen), **Details**, then **every change with its test** (`<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`). Ordinary markdown, **never wrapped in a code fence**, once per Issue before implementation — required in fullrun/halfrun/backlogrun even when the Issue body was filled (`kickoff` is exempt); completion reports lead with **Cause / Fix / Result**. `prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint` checks the form, and the `UserPromptSubmit` hook points here. Presentation only, never a confirmation stop.
+0. **Work summary + test declaration** _(before writing any implementation code)_: a two-layer summary — a plain-language overview a non-programmer can follow (three lines, **Now / Change / Check**, one sentence each, in the session language; name the concrete subject in each line — subject-less prose is not acceptable; no file paths, function or type names, or CLI option flags — only internal identifiers are banned, not names the reader sees on screen), **Details**, then **every change with its test** (`<what changes> — Test: <Unit|E2E> — <file path> — <what it verifies>`). Ordinary markdown, **never wrapped in a code fence**, once per Issue before implementation — required in fullrun/halfrun/backlogrun even when the Issue body was filled (`kickoff` is exempt); completion reports lead with **Cause / Fix / Result**. `prompts/collaboration-workflow/report-format.md`; `pnpm josh report:lint` checks the form, and a session's first runtime `Edit` / `Write` points here. Presentation only, never a confirmation stop.
 
    - **Tests are required for ALL changes** — zero tests without explicit approval is a violation (bug fixes, timing/animation fixes and refactors included): bug fix → regression test; UI/animation/timing → E2E for the observable change; logic/utility → unit; refactor → tests pinning existing behavior BEFORE the change (`prompts/refactoring.md`).
    - **Non-runtime updates (pre-approved manual-only exception)**: a change touching no executable runtime code path may proceed with manual verification — declare it in Step 0 and state why. It covers docs, non-executable config, editor/IDE files, and cosmetic asset swaps with no selector/path change; the mechanically exempt (`*.md`, `.editorconfig`, `.idea/**`, `.vscode/**`, `prompts/**`) are recognized by the command below, and the rest stay the exemption a person declares. A test infeasible for a runtime change needs its reason stated and user approval.
-   - **basic の手動確認例外:** `package.json` に `josh.profile: basic`（改名前の `static` も同じ）が記録され、変更が kit がテストできない言語のファイル（HTML/CSS や Lua などのソース）だけなら、自動テストの代わりに手で確認する。HTML/CSS はブラウザーで対象ページを開き、想定する画面幅でレイアウト・リンク・HTML 内の操作を確認する。そのほかのソースは変更した処理を実際に動かす。どちらも観察結果を報告する。JavaScript と TypeScript のファイルには同時に変更した場合も自動テストが必要。`pnpm josh test:declared` はこの場合だけ理由を添えて `exempt` と表示する。
+   - **Basic-profile manual-check exception:** when `package.json` records `josh.profile: basic` (or its former name `static`) and the change touches only files in languages kit cannot test (HTML/CSS, or sources such as Lua), verify by hand instead of with an automated test. For HTML/CSS, open the page in a browser and check layout, links and interactions in the HTML at the intended screen widths; for any other source, actually run the changed code. Report what you observed either way. JavaScript and TypeScript files still need automated tests, even when changed alongside. `pnpm josh test:declared` prints `exempt` with the reason in this case only.
    - **The commit stage answers this mechanically**: `pnpm josh test:declared` prints `required` / `exempt` / `satisfied` from the changed paths, and a runtime change with no test is refused at `pnpm josh git -y` on `required` — add the declared test or declare the non-runtime exception, then reissue (`prompts/collaboration-workflow/rule-delivery.md`).
    - **Read a target's line headroom before editing: `pnpm josh lines <path>`** — near the limit, `Target` carries the splitting plan.
 
@@ -131,7 +129,7 @@ Run the full verification set **in order**; do not skip, reorder, or report comp
 
 ## Pre-commit Self-Review (mandatory)
 
-Before every `git commit` (follow-up commits included), self-review against `prompts/review.md` — a subagent runs `/code-review`, never a main-line `Skill` load: the staged diff, and `git diff main...HEAD` before opening or updating a PR. Level from `pnpm josh review:brief --level-only`; resolve all high/medium findings; iterate — **at most two reviews in total**, the second a verification pass over the fix delta. Then route each remaining non-High finding through the three-way disposition: fix in place, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path — `pnpm josh disposition <path>` answers `runtime` / `non-runtime`, so the only judgement left is whether the defect is confirmed — or drop it with a one-line PR note (the default). **A filed finding is run through `pnpm josh epic:bundle <new>` before the current Issue closes.** A confirmed High blocks rather than buying a third round; CI runs no Claude review, so this pass is authoritative. `prompts/review.md` → "Review round cap".
+Before every `git commit` (follow-up commits included), self-review against `prompts/review.md` — a subagent runs `/code-review`, never a main-line `Skill` load: the staged diff, and `git diff main...HEAD` before opening or updating a PR. Level from `pnpm josh review:brief --level-only`; resolve all high/medium findings; iterate — **no further than the round cap**, the last round a verification pass over the fix delta. Then route each remaining non-High finding through the three-way disposition: fix in place, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>` answers `runtime` / `non-runtime`) — or drop it with a one-line PR note (the default). **A filed finding is run through `pnpm josh epic:bundle <new>` before the current Issue closes.** A confirmed High blocks rather than buying a round past the cap. `prompts/review.md` → "Review round cap".
 
 ## Doc Sync Rules
 
@@ -148,11 +146,11 @@ Before every `git commit` (follow-up commits included), self-review against `pro
 
 - For the issue-driven proposal/plan/execution/notification flow, follow `prompts/collaboration-workflow/` (indexed by `prompts/collaboration-workflow.md`; each topic is its own file).
 - **Before writing a rule as prose, place it by `prompts/collaboration-workflow/residency.md`** — its single source. A computable answer goes to `pnpm josh oracle:list` and an ordering rule to `pnpm josh run:step`, never into `CLAUDE.md` or a prompt file.
-- **Count the target repository's open Issues before filing; with more than 30 open, 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. The count command and both procedures: `prompts/collaboration-workflow/wip-cap.md`.
+- **Count the target repository's open Issues before filing; 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. The count command and both procedures: `prompts/collaboration-workflow/wip-cap.md`.
 
 ### Shorthand Commands
 
-`kickoff`, `fullrun`, `halfrun` and `backlogrun` are the Issue-driven shorthand commands. **Their procedures are not resident** — they live in the `workflow-commands` skill. **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; everything a run reaches only after reading the skill is routed to, never restated (`prompts/collaboration-workflow/residency.md` → "第 2 問").
+`kickoff`, `fullrun`, `prrun`, `halfrun` and `backlogrun` are the Issue-driven shorthand commands. **Their procedures are not resident** — they live in the `workflow-commands` skill. **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; everything a run reaches only after reading the skill is routed to, never restated (`prompts/collaboration-workflow/residency.md` → "第 2 問").
 
 **Read the skill before running any part of a command — including the first `gh` call.**
 
@@ -160,18 +158,19 @@ Before every `git commit` (follow-up commits included), self-review against `pro
 | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | `kickoff [#N \| new]`    | Plan only — normalize title, post the plan, notify, **stop**                                                                                                          | `workflow-commands` skill + `kickoff.md` + `split-assessment.md` |
 | `fullrun [#N \| new]`    | Plan → implement → gate → PR → **merge** → notify                                                                                                                     | + `fullrun.md` + `split-assessment.md` + `chain-rule.md`         |
+| `prrun [#N \| new]`      | `fullrun` up to a green, mergeable PR, then **stop** for a person to merge by hand                                                                                    | + `prrun.md` + the `fullrun` set                                 |
 | `halfrun [#N \| new]`    | Implement + gate, then **stop before commit** for manual verification                                                                                                 | + `halfrun.md` + `split-assessment.md`                           |
 | `backlogrun [#N1 #N2 …]` | Run named Issues and epics in order (an epic runs its children first), then drain the opted-in backlog — dependency order, lanes. `--only` stops after the named list | + `backlogrun.md` + `split-assessment.md` + the `fullrun` set    |
 
 **`queue` and `epicrun` were removed** — tell a user who types `queue` to run `backlogrun #N1 #N2 …`, and one who types `epicrun` to run `backlogrun #E --only` (drop `--only` to also drain the backlog).
 
-**Three rules decide what a run does when the work turns out not to be one Issue** — the split assessment every entry point applies identically (**its default is not to split**: separability **and** a scope clearly exceeding one verification gate — about 10 changed files, about 400 changed lines (test files excluded) — must both hold), a prerequisite discovered mid-run (a dependency, not parked), and a named `backlogrun` item that is not an epic. All bind only after a command has started, so all are read from the `workflow-commands` skill: `split-assessment.md`, `SKILL.md` → §2d, `backlogrun-child.md` → "When `#N` is not an epic", and `fullrun.md` / `halfrun.md` / `backlogrun.md` for the branch each entry takes.
+**Three rules decide what a run does when the work turns out not to be one Issue** — the split assessment every entry point applies identically (**its default is not to split**: separability **and** a scope clearly exceeding one verification gate — the size guide in `split-assessment.md`, measured by `pnpm josh split:assess` — must both hold), a prerequisite discovered mid-run (a dependency, not parked), and a named `backlogrun` item that is not an epic. All bind only after a command has started, so all are read from the `workflow-commands` skill: `split-assessment.md`, `SKILL.md` → §2d, `backlogrun-child.md` → "When `#N` is not an epic", and `fullrun.md` / `halfrun.md` / `backlogrun.md` for the branch each entry takes.
 
 **The `josh epic:*` commands have their own skill** — `epic:audit`, `epic:next`, `epic:bundle`, and how an epic spans repositories. **Read the `epic-commands` skill before running any of them, before writing an epic that tracks a child in another repository, and right after filing an issue.** Three rules stay here because they bind outside those commands: **recording a decision removes that child's `needs-decision` label** (Tier A); **fixing what the audit finds is Tier A**, park only when the contradiction is a design choice nobody has made; and **an epic in another repository is referenced as `owner/repo#N`** (a bare `#N` resolves to this repository's issue). Canonical reference: `.claude/skills/epic-commands/SKILL.md`.
 
 #### Explicit invocation required (MANDATORY)
 
-Never start a `kickoff` / `halfrun` / `fullrun` / `backlogrun` workflow (including their `#N` and `new` variants) unless the user has typed the keyword in the **current turn's prompt**.
+Never start a `kickoff` / `halfrun` / `prrun` / `fullrun` / `backlogrun` workflow (including their `#N` and `new` variants) unless the user has typed the keyword in the **current turn's prompt**.
 
 - Conversational requests like "implement X", "fix Y", "open a PR for Z" are **NOT** implicit invocations — do not infer authorization from the request shape.
 - Do **NOT** ask confirmation questions like "Shall I run `fullrun`?". A confirmation prompt is not a substitute for explicit invocation.
@@ -184,7 +183,7 @@ Never start a `kickoff` / `halfrun` / `fullrun` / `backlogrun` workflow (includi
 
 #### Mid-workflow stop notification (`confirmation`)
 
-Whenever you pause **any** run mid-execution to wait for the user — a `kickoff` / `halfrun` / `fullrun` stop, an upstream-Issue interrupt, a Tier C confirmation — you MUST send a Telegram notification **before** stopping, so the user is alerted off-screen. `halfrun`'s built-in stop before commit is a confirmation pause and follows this same rule.
+Whenever you pause **any** run mid-execution to wait for the user — a `kickoff` / `halfrun` / `prrun` / `fullrun` stop, an upstream-Issue interrupt, a Tier C confirmation — you MUST send a Telegram notification **before** stopping, so the user is alerted off-screen. `halfrun`'s built-in stop before commit is a confirmation pause and follows this same rule.
 
 ```bash
 pnpm josh notify --task-type confirmation --issue-url "<issue-url>" --body=$'<one-line reason>\n<what is needed from the user>'

package/GEMINI.md

@@ -1,10 +1,22 @@
 # Agent Instructions
 
 > **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. Nothing in
-> `CLAUDE.md` is Claude-specific — it applies to whatever agent is doing the work.
+> any work here, and follow every rule in it.** This file exists only to point at it. The rules apply
+> to whatever agent is doing the work, but `CLAUDE.md` is written for Claude Code and names its
+> features — read them as follows.
 
 @CLAUDE.md
 
+- **No hooks run under Gemini.** Every rule `CLAUDE.md` says a hook enforces or delivers is silently
+  unenforced here, so apply each one yourself: present the work summary before implementing, resolve
+  `JOSH_SESSION_LANG` from `.env`, run `pnpm josh lint:related` and `pnpm josh cspell:dot` after
+  editing instead of relying on the format-on-edit hook, and cite every Issue with a link and a short
+  title instead of relying on the stop-time check.
+- **Skills, `/verify-ui` and `/code-review`.** Where `CLAUDE.md` says to load a skill or run one in a
+  subagent, read that skill's `SKILL.md` and follow it in your own session.
+- **The `.claude/settings.json` deny list** is not enforced here. The rules it backs — no commits,
+  merges, staging or other shared-state changes without instruction — still bind you.
+- **`AskUserQuestion`** means asking the user in plain text.
+
 **Do not copy rules back into this file.** Every change to how agents work in this repository belongs
 in `CLAUDE.md`.

package/README.md

@@ -1,29 +1,72 @@
 # @joshuafolkken/kit
 
+[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-D97757?logo=claude&logoColor=white)](https://claude.com/claude-code)
+[![Codex](https://img.shields.io/badge/Codex-supported-412991)](https://openai.com/codex/)
+[![npm version](https://img.shields.io/npm/v/@joshuafolkken/kit)](https://www.npmjs.com/package/@joshuafolkken/kit)
+[![License](https://img.shields.io/github/license/joshuafolkken/kit)](./LICENSE)
+
+[![Node.js](https://img.shields.io/node/v/@joshuafolkken/kit?logo=nodedotjs)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/npm/dependency-version/@joshuafolkken/kit/peer/typescript?logo=typescript)](https://www.typescriptlang.org/)
+[![pnpm](https://img.shields.io/github/package-json/packageManager/joshuafolkken/kit?logo=pnpm&label=pnpm)](https://pnpm.io/)
+
+[![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)
+
 **Write a GitHub Issue. Your AI agent takes it to a merged PR — the same way in every project.**
 
-kit gives Claude Code (or Codex, Gemini, Cursor) your project's rules, checks and an Issue-driven workflow. You type one keyword. The agent plans, implements, verifies, opens the PR and merges it.
+kit gives Claude Code or Codex (or Gemini, Cursor) your project's rules, checks and an Issue-driven workflow.
+
+## Sound familiar?
+
+Each pain links to how it is solved — or read [the whole story](./docs/why.md).
+
+| 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)                             |  —  |    ✅     |     ✅     |
+| [Starting a 3D game means building it all first](https://github.com/joshuafolkken/game-kit/blob/main/docs/install.md)      |  —  |     —     |     ✅     |
+
+Each kit includes the one to its left: app-kit builds on kit, game-kit builds on app-kit.
+
+[app-kit]: https://github.com/joshuafolkken/app-kit
+[game-kit]: https://github.com/joshuafolkken/game-kit
 
 ## The workflow
 
-| You type         | The agent                                                              |
-| ---------------- | ---------------------------------------------------------------------- |
-| `kickoff new`    | Files the Issue from your conversation, posts the plan and stops       |
-| `halfrun #N`     | Implements and verifies, then stops before commit so you can look      |
-| `fullrun #N`     | Implements, verifies, self-reviews, opens the PR, waits for CI, merges |
-| `backlogrun #N…` | Works through several Issues (or an epic) unattended                   |
+| You type     | The agent                                        |
+| ------------ | ------------------------------------------------ |
+| `kickoff`    | Writes the plan on the Issue, then stops         |
+| `halfrun`    | Implements and self-reviews, stops before commit |
+| `fullrun`    | Plans if needed, implements through to merge     |
+| `backlogrun` | Runs many Issues unattended                      |
 
-## Why you can trust "done"
+Each keyword in full: [Run Issues with the workflow keywords](./docs/how-to/run-issues.md). When a run needs you, it [notifies you on Telegram](./docs/how-to/set-up-notifications.md).
 
-- **Checks are commands, not requests.** Lint, type check, spell check and tests run as one gate. "It should pass" doesn't count.
-- **Missing tests stop the commit.** kit decides from the changed files whether a test is required, and stops the commit until the agent adds one or declares the change exempt.
-- **It tells you when it stops.** A run that needs you sends a [Telegram notification](./docs/how-to/set-up-notifications.md).
+## Why you can trust "done"
 
-More: [why kit exists](./docs/why.md) (Japanese)
+- **Checks are commands.** Lint, types, spelling and tests run as one gate — "it should pass" doesn't count.
+- **No test, no commit.** kit decides from the changed files whether a test is required.
 
 ## Quick start
 
-Requires Node.js 22.19+, pnpm 12+ and the gh CLI — [how to install them](./docs/setup/prerequisites.md).
+Requires Node.js, pnpm and the gh CLI — [how to install them](./docs/setup/prerequisites.md).
 
 ```bash
 pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver @joshuafolkken/kit
@@ -32,12 +75,10 @@ pnpm exec josh start
 
 Then open your agent and follow the [tutorial](./docs/tutorial.md).
 
-No Issue workflow? Run `pnpm --allow-build=esbuild dlx @joshuafolkken/kit init` instead — see setup for [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) or [other projects](./docs/setup/basic.md).
+No Issue workflow? [Node projects](./docs/setup/full.md#2-install-and-initialize-with-josh-init) · [Other projects](./docs/setup/basic.md)
 
 ## Docs
 
-[Tutorial](./docs/tutorial.md) · [How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [Overview & all docs](./docs/overview.md)
-
-## Contributing · License
+[Tutorial](./docs/tutorial.md) · [How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [All docs](./docs/overview.md)
 
-[CLAUDE.md](./CLAUDE.md) · [publishing.md](./docs/publishing.md) · [MIT](./LICENSE)
+[Releases](https://github.com/joshuafolkken/kit/releases) · [Security](./SECURITY.md) · [Contributing](./CLAUDE.md) · [Maintaining kit](./docs/maintainers/README.md) · [MIT](./LICENSE)

package/SECURITY.md

@@ -4,7 +4,10 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.x     | :white_check_mark: |
+| Latest  | :white_check_mark: |
+| Older   | :x:                |
+
+Fixes ship in a new release rather than as patches to older versions; upgrade to the latest release to receive them. Each release's changes are listed on the [Releases](https://github.com/joshuafolkken/kit/releases) page.
 
 ## Reporting a Vulnerability
 
@@ -17,13 +20,40 @@ We aim to acknowledge reports within **48 hours** and provide a resolution or mi
 
 ## Published Package Contents
 
-The following files are intentionally included in the published npm package and distributed to consuming projects via `josh sync`:
+The `files` field of `package.json` decides what the published `@joshuafolkken/kit` package contains. None of it carries credentials or private URLs. `josh init` and `josh sync` copy or merge part of it into a project; [sync.md](https://github.com/joshuafolkken/kit/blob/main/docs/sync.md) lists which files are overwritten and which are merged.
+
+**Code that runs on your machine and in CI**
+
+- `dist/`, `scripts/` — the `josh` command and the scripts behind it. They read and write files in your repository, run `git`, `gh` and `pnpm`, and call the GitHub API and, when configured, the Telegram API.
+- `.claude/settings.json` — Claude Code hooks that run `pnpm josh …` commands on session start, on each prompt, before and after tool calls and on stop, plus a deny list for staging, committing, merging, force pushes and branch deletions. `josh sync` overwrites it.
+- `.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`.
+
+**Agent instructions and skills**
+
+- `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `prompts/` — the rules and procedures AI agents follow.
+- `.claude/skills/`, `.claude/.claude-plugin/`, `.claude-plugin/` — the Claude Code skills, shipped as the `kit` plugin and its marketplace entry.
+- `.mcp.json` — the MCP server configuration for the Svelte documentation server. It contains only the public endpoint `https://mcp.svelte.dev/mcp`.
+- `.coderabbit.yaml` — CodeRabbit review settings.
+
+**Configuration presets and templates**
+
+- `eslint/`, `prettier/`, `tsconfig/`, `cspell/`, `env/`, `ports/`, `playwright.config.ts`, `tsconfig.sonar.json` — shared configuration your project imports or receives.
+- `templates/` — the templates `josh init` and `josh sync` write from.
+- `.vscode/`, `.gitattributes`, `.ncurc.json`, `.prettierignore`, `pnpm-workspace.yaml` — editor, Git and package-manager settings.
+- `CODE_OF_CONDUCT.md`, `SECURITY.md` — community files.
+
+## Secrets
 
-- `.mcp.json` — MCP server configuration for the Svelte documentation server. Contains only the public endpoint `https://mcp.svelte.dev/mcp`. No credentials or private URLs.
-- `.coderabbit.yaml`, `.cursorrules` — AI tool configurations with no sensitive data.
-- `templates/`, `prompts/` — Markdown and config templates. No credentials.
+kit never stores a secret in a file it ships or commits. The ones it uses:
 
-Sensitive runtime secrets (`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`) are stored only in a local `.env` file which is gitignored and never committed to the repository.
+- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` — Telegram notifications. Keep them in a local `.env` file, which is gitignored, or in the environment. Set `JOSH_NOTIFY=off` to need neither.
+- `SONAR_TOKEN` — a repository secret the distributed SonarQube workflow reads. Without it the workflow skips the scan.
+- `GITHUB_TOKEN` — supplied by GitHub Actions to the distributed workflows; nothing to configure.
+- `GH_TOKEN` — authenticates `gh` in CI and cloud sessions, where `gh auth login` is not available.
+- `NODE_AUTH_TOKEN` — the GitHub Packages credential, only for projects that still install kit from there ([authentication.md](https://github.com/joshuafolkken/kit/blob/main/docs/authentication.md)). The `prepare` script above reads it.
 
 ## MCP External Endpoints