@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/.gitattributes

@@ -4,4 +4,5 @@
 *.config.js linguist-vendored
 eslint/rules/** linguist-vendored
 
-scripts/*.ts linguist-language=TypeScript
+scripts/*.ts linguist-language=TypeScript
+

package/.github/workflows/ci.yml

@@ -242,8 +242,14 @@ jobs:
       contents: read
       packages: read
     steps:
+      # **Two commits, not one** (joshuafolkken/kit#3644). The gate's `josh metrics` holds the totals
+      # to the ones measured on the commit this change starts from, so that commit has to be in the
+      # clone: a pull request is checked out as a merge commit whose first parent is the default
+      # branch's tip, and the default one-commit clone holds the merge commit alone.
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 2
 
       - name: Setup Node.js
         uses: ./.github/actions/setup-node
@@ -343,8 +349,16 @@ jobs:
       # buffered until it exits, so a check that *hangs* until this job's `timeout-minutes` is
       # cancelled with nothing printed — where a serial step streamed. That costs one local
       # `pnpm josh gate` to identify, and it is the price of the all-failures-in-one-pass summary.
+      #
+      # **`JOSH_METRICS_BASE` names the commit `josh metrics` measures from** (joshuafolkken/kit#3644).
+      # This clone has no default-branch ref to ask a merge-base of, so the first parent is named
+      # outright: the default branch's tip on a pull request, and the commit before the push on the
+      # default branch itself. A name that does not resolve fails the step rather than comparing
+      # with nothing.
       - name: Run verification gate
         run: pnpm josh gate --verbose --no-unit
+        env:
+          JOSH_METRICS_BASE: HEAD^1
 
   # The other half of the gate, on a runner of its own. A GitHub job is its own machine, so this job
   # sets Node up again; the pnpm preamble is the shared `.github/actions/setup-pnpm` action

package/.github/workflows/publish.yml

@@ -183,3 +183,5 @@ jobs:
           RELEASE_START_TAG: v1.887.0
           RELEASE_WORKFLOW: publish.yml
           RELEASE_JOBS: pack,publish-github,publish-npm,update-production
+          # This run creates its tag's release, so a lower tag whose run finished without one is lost.
+          RELEASE_RUN_WORKFLOW: publish.yml

package/.vscode/tasks.json

@@ -0,0 +1,14 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "josh: run board",
+			"type": "shell",
+			"command": "pnpm josh run:board",
+			"isBackground": true,
+			"problemMatcher": [],
+			"presentation": { "reveal": "always", "panel": "dedicated", "focus": false },
+			"runOptions": { "runOn": "folderOpen" }
+		}
+	]
+}

package/CLAUDE.md

@@ -1,7 +1,5 @@
 # Claude Code Instructions
 
-> 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
 
 Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS · Drizzle · better-auth · Paraglide · MCP
@@ -13,76 +11,40 @@ Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS ·
 - **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` → "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".
+- **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"; conflicting quality goals → "quality-priority".
 - **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".
-- **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`.
+- **Hook-delivered rules** (file edits, shell bodies, turn batching, Issue citation, …): `prompts/collaboration-workflow/rule-delivery.md` → "配送されている規則".
 
 ### Decision autonomy
 
 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 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. Unasked filing: unattended only (`observation-filing.md`).
 - **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.
+- **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. After a dependency-update command, load the `dependency-update` skill before reporting on the pins.
 
 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
-
-`.env`: `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` required; `JOSH_SESSION_LANG`, `PORT_SEED`, `JOSH_REPO_PATHS` optional — [environment-variables.md](https://github.com/joshuafolkken/kit/blob/main/docs/environment-variables.md). **GitHub operations are `gh api` (REST)** — `prompts/collaboration-workflow/gh-rest.md`.
-
 ## Critical Conventions (non-standard — always apply)
 
-Most are lint-enforced. Craft guidance: `prompts/coding-standards.md`.
-
-### Naming
-
-`snake_case` variables / functions / params · `PascalCase` types / classes / interfaces / enums · `UPPER_CASE` enum members · booleans prefixed `is_` / `has_` / `should_` / `can_` / `will_` / `did_` · constants `UPPER_CASE` or `snake_case`.
-
-### Functions & exports
-
-`function` syntax, not arrows (named SvelteKit route handlers may use the typed-const arrow idiom) · multiple functions → a namespace object `export { my_module }` (constants exempt) · no `export default`.
-
-### Files
-
-Svelte `PascalCase.svelte(.ts)` · TypeScript `kebab-case.ts` · tests `*.test.ts` / `*.svelte.test.ts`, colocated, never `*.spec.ts` (`prompts/testing-guide.md`) · in `scripts/`, no `../` imports — use `#scripts/*`.
+Naming, exports, file names and content rules are enforced by `eslint/rules/`; their single source is `prompts/coding-standards.md` → "Conventions". `function` syntax, not arrows (named SvelteKit route handlers may use the typed-const arrow idiom) — lint does not check it.
 
 ### Quality limits
 
 - Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4 — line counts are code lines, not physical lines (`pnpm josh lint`); test files allow 35 code lines per function.
 - No magic numbers beyond `0`, `1`, `-1` · no `any` · restricted `as` · explicit param and return types · single short early return → one-liner `if (x) return y`.
 
-### Content rules
-
-- i18n: user-visible strings use message keys in every locale.
-- Comments / test titles: English only (`eslint/rules/` may explain rationale in Japanese).
-- No duplication; `/* @refactor-ignore */` at file top excludes a file from refactoring.
-
-### Dependency overrides (`pnpm-workspace.yaml` / `package.json`)
-
-- 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 — 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
 
 Before building a feature, check for a well-maintained package — measure with `pnpm josh pkg:scout <keywords>`: `clear` → select it (Tier A), `close` → ask (Tier B).
 
 ## Code Change Rules
 
-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`.
-   - Read a target's headroom first: `pnpm josh lines <path>`.
+0. **Work summary + test declaration** — before writing any implementation code, once per Issue: Now / Change / Check, then every change with its test (`prompts/collaboration-workflow/report-format.md` → "作業前サマリはいつ・どう出すか"). **Tests are required for ALL changes** — zero tests without explicit approval is a violation; a runtime change with no test is refused at `pnpm josh git -y` on `required` (`pnpm josh test:declared`).
 1. **Refactor first** — `prompts/refactoring.md`; no high/medium refactoring left on new/modified code.
 2. **Tests** — those declared in Step 0 (`prompts/testing-guide.md`).
 3. **Verification gate** — `pnpm josh gate`; while implementing re-run one check (`pnpm josh lint:related` / `pnpm josh cspell:dot` / `pnpm josh test:related`). Add legitimate flagged terms to `cspell.config.yaml`.
@@ -94,35 +56,22 @@ In order, none skipped: tests (Step 0) → refactor → `pnpm josh gate` → Pre
 
 ## Pre-commit Self-Review (mandatory)
 
-Before every `git commit`, a subagent runs `/code-review` per `prompts/review.md` — level from `pnpm josh review:brief --level-only`, no further than the round cap (`prompts/review.md` → "Review round cap"). Each remaining non-High finding: fix it, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>`), or drop it with a PR note.
-
-## Doc Sync Rules
-
-When `josh bump` changes the version, update `docs/` for any changed behavior before committing.
+Before every `git commit`, a subagent runs `/code-review` per `prompts/review.md` — level from `pnpm josh review:brief --level-only`, no further than the round cap, then the three-way disposition (`prompts/review.md` → "Review round cap").
 
 ## 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` → "no-self-staging".
-- **Use `pnpm josh git`; open a PR with `pnpm josh pr`** — `pnpm josh rule:guard` refuses a direct `gh pr create`.
+- **Use `pnpm josh git`; open a PR with `pnpm josh pr`** — `pnpm josh rule:guard` refuses a direct `gh pr create`. GitHub operations are `gh api` (REST) — `prompts/collaboration-workflow/gh-rest.md`.
 - **Run `git status` (and `git stash list`) live** before acting on any tree assumption.
 
 ## Collaboration Workflow
 
-- 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`.
+The issue-driven flow: `prompts/collaboration-workflow.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.
-
-**`queue` and `epicrun` were removed** — point `queue` to `backlogrun #N1 #N2 …` and `epicrun` to `backlogrun #E --only`.
-
-Read the `epic-commands` skill before any `josh epic:*` command, before writing an epic that tracks a child in another repository, and when `epic:bundle` places a filed issue. Three rules bind outside it:
-
-- 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.
-- **An epic in another repository is referenced as `owner/repo#N`** — a bare `#N` resolves to this repository's issue.
+`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. Read the `epic-commands` skill before any `josh epic:*` command, before writing an epic that tracks a child in another repository, when `epic:bundle` places a filed issue, and when recording a decision on a `needs-decision` child.
 
 #### Explicit invocation required (MANDATORY)
 

package/README.md

@@ -1,14 +1,6 @@
 # @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)
 
@@ -16,81 +8,70 @@
 
 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).
+[The whole story](./docs/why.md)
 
-kit solves these in every project — and so do [app-kit] and [game-kit], which build on it:
+### Working with an AI agent
 
-- [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:
+### With the GitHub workflow
 
-| Your pain                                                                                                                  | kit | [app-kit] | [game-kit] |
-| -------------------------------------------------------------------------------------------------------------------------- | :-: | :-------: | :--------: |
-| [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)      |  —  |     —     |     ✅     |
+- [Wiring AI up to GitHub is a chore](./docs/why.md#wiring-ai-up-to-github-is-a-chore)
+- [Writing Issues is a chore](./docs/why.md#writing-issues-is-a-chore)
+- [Big requests come back sloppy](./docs/why.md#big-requests-come-back-sloppy)
 
-Each kit includes the one to its left: app-kit builds on kit, game-kit builds on app-kit.
+### Writing TypeScript
 
-[app-kit]: https://github.com/joshuafolkken/app-kit
-[game-kit]: https://github.com/joshuafolkken/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)
+- [Updating dependencies keeps breaking things](./docs/why.md#updating-dependencies-keeps-breaking-things)
 
-## The workflow
+## Quick start
 
-| You type     | The agent                                        |
-| ------------ | ------------------------------------------------ |
-| `kickoff`    | Writes the plan on the Issue, then stops         |
-| `halfrun`    | Implements and self-reviews, stops before commit |
-| `prrun`      | Opens a green pull request, stops before merge   |
-| `fullrun`    | Plans if needed, implements through to merge     |
-| `backlogrun` | Runs many Issues unattended                      |
+### With the GitHub workflow
 
-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).
+Requires [Node.js, pnpm and the gh CLI](./docs/setup/prerequisites.md).
 
-## Why you can trust "done"
+```bash
+gh auth login # once
+pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver @joshuafolkken/kit
+pnpm exec josh start
+```
 
-- **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.
+Next: [tutorial](./docs/tutorial.md)
 
-## Quick start
+### AI assistant only — no GitHub account needed
 
-Requires Node.js, pnpm (kit is installed and run with pnpm only) and the gh CLI — [how to install them](./docs/setup/prerequisites.md). Sign in once with `gh auth login` before `josh start`.
+Requires [Node.js and pnpm](./docs/setup/prerequisites.md).
 
 ```bash
-pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver @joshuafolkken/kit
-pnpm exec josh start
+pnpm --allow-build=esbuild dlx @joshuafolkken/kit init
 ```
 
-`josh start` picks the project's profile, writes kit's rules and checks, and creates the GitHub repository and workflow labels when they are missing. On a repository that already has history it opens a setup pull request instead of committing to `main` — merge it before your first run ([what it does](./docs/init.md#josh-init-or-josh-start)).
+Next: [tutorial](./docs/tutorial.md#without-github-one-change-checked-locally)
 
-Add the two Telegram credentials to `.env` so a run that needs you can reach you, or `JOSH_NOTIFY=off` to go without — [Set up notifications](./docs/how-to/set-up-notifications.md).
+## The workflow
 
-Then open your agent and follow the [tutorial](./docs/tutorial.md).
+| You type     | The agent                                        |
+| ------------ | ------------------------------------------------ |
+| `kickoff`    | Writes the plan on the Issue, then stops         |
+| `halfrun`    | Implements and self-reviews, stops before commit |
+| `prrun`      | Opens a green pull request, stops before merge   |
+| `fullrun`    | Plans if needed, implements through to merge     |
+| `backlogrun` | Runs many Issues unattended                      |
 
-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)
+[Each keyword in full](./docs/how-to/run-issues.md) · [Telegram notifications when a run needs you](./docs/how-to/set-up-notifications.md)
 
 ## Docs
 
-[Tutorial](./docs/tutorial.md) · [How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [All docs](./docs/overview.md)
+[How-to](./docs/how-to.md) · [Commands](./docs/josh-commands.md) · [Troubleshooting](./docs/troubleshooting.md) · [All docs](./docs/overview.md)
 
-[Releases](https://github.com/joshuafolkken/kit/releases) · [Security](./SECURITY.md) · [Contributing](./docs/maintainers/README.md) · [MIT](./LICENSE)
+[app-kit](https://github.com/joshuafolkken/app-kit) · [game-kit](https://github.com/joshuafolkken/game-kit) · [Releases](https://github.com/joshuafolkken/kit/releases) · [Security](./SECURITY.md) · [Contributing](./docs/maintainers/README.md) · [MIT](./LICENSE)
+
+[![Node.js](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjoshuafolkken%2Fkit%2Fmain%2Fpackage.json&search=%22node%22%3A%20%22%5C%5E%28%5B0-9%5D%2B%5C.%5B0-9%5D%2B%29%5B0-9.%5D%2A%20%5C%7C%5C%7C%20%5C%5E%28%5B0-9%5D%2B%29%5B0-9.%5D%2A%20%5C%7C%5C%7C%20%3E%3D%28%5B0-9%5D%2B%29&replace=%5E%241%20%7C%20%5E%242%20%7C%20%3E%3D%243&logo=nodedotjs&label=Node.js)](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/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Fjoshuafolkken%2Fkit%2Fmain%2Fpackage.json&search=pnpm%40%28%5B0-9.%5D%2B%29&replace=%241&logo=pnpm&label=pnpm)](https://pnpm.io/)

package/SECURITY.md

@@ -25,7 +25,7 @@ The `files` field of `package.json` decides what the published `@joshuafolkken/k
 **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.
+- `.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, branch deletions and reads of `.env`, `.env.*` (except the tracked `.env.example` and `.env.test`) and `.dev.vars`. It sets `permissions.defaultMode` to `bypassPermissions`, as the distributed `.vscode/settings.json` does for the VS Code extension — an opt-out default, which Claude Code v2.1.257 and later ignore in a project settings file, described in [`docs/init.md` → "Claude Code permission mode"](https://github.com/joshuafolkken/kit/blob/main/docs/init.md#claude-code-permission-mode). `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.

package/dist/CLAUDE.md

@@ -1,7 +1,5 @@
 # Claude Code Instructions
 
-> The entry point for every agent rule — `AGENTS.md`, `GEMINI.md` and `.cursorrules` point here; each rule has a single source (`node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/residency.md`).
-
 ## Project
 
 Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS · Drizzle · better-auth · Paraglide · MCP
@@ -13,76 +11,40 @@ Stack: TypeScript · pnpm · SvelteKit · Vitest · Playwright · TailwindCSS ·
 - **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. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/principles.md` → "elegant-design".
+- **Design for elegance and simplicity first.** Before adding a hook, guard, rule or abstraction, ask whether fixing the cause makes it unnecessary. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/principles.md` → "elegant-design"; conflicting quality goals → "quality-priority".
 - **Distinguish consultation from execution.** A question or goal statement asks for analysis only — act on an explicit imperative or a workflow keyword. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/principles.md` → "upstream-to-kit".
 - **Latest-first, fix forward — pin back only as a last resort.** `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/overview.md`.
-- **Cite an Issue with a number-link and a short title in the session language.** `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/issue-citation.md`.
 - **Durable rules belong in prompts/docs, not local MEMORY.** `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/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; `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/rule-delivery.md`.
+- **Hook-delivered rules** (file edits, shell bodies, turn batching, Issue citation, …): `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/rule-delivery.md` → "配送されている規則".
 
 ### Decision autonomy
 
 Classify each decision point and act; stop **only** where the user's judgment is genuinely needed. `node_modules/@joshuafolkken/kit/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 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. Unasked filing: unattended only (`observation-filing.md`).
 - **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.
+- **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. After a dependency-update command, load the `dependency-update` skill before reporting on the pins.
 
 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
-
-`.env`: `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` required; `JOSH_SESSION_LANG`, `PORT_SEED`, `JOSH_REPO_PATHS` optional — [environment-variables.md](https://github.com/joshuafolkken/kit/blob/main/docs/environment-variables.md). **GitHub operations are `gh api` (REST)** — `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/gh-rest.md`.
-
 ## Critical Conventions (non-standard — always apply)
 
-Most are lint-enforced. Craft guidance: `node_modules/@joshuafolkken/kit/prompts/coding-standards.md`.
-
-### Naming
-
-`snake_case` variables / functions / params · `PascalCase` types / classes / interfaces / enums · `UPPER_CASE` enum members · booleans prefixed `is_` / `has_` / `should_` / `can_` / `will_` / `did_` · constants `UPPER_CASE` or `snake_case`.
-
-### Functions & exports
-
-`function` syntax, not arrows (named SvelteKit route handlers may use the typed-const arrow idiom) · multiple functions → a namespace object `export { my_module }` (constants exempt) · no `export default`.
-
-### Files
-
-Svelte `PascalCase.svelte(.ts)` · TypeScript `kebab-case.ts` · tests `*.test.ts` / `*.svelte.test.ts`, colocated, never `*.spec.ts` (`node_modules/@joshuafolkken/kit/prompts/testing-guide.md`) · in `scripts/`, no `../` imports — use `#scripts/*`.
+Naming, exports, file names and content rules are enforced by `node_modules/@joshuafolkken/kit/eslint/rules/`; their single source is `node_modules/@joshuafolkken/kit/prompts/coding-standards.md` → "Conventions". `function` syntax, not arrows (named SvelteKit route handlers may use the typed-const arrow idiom) — lint does not check it.
 
 ### Quality limits
 
 - Function complexity ≤5 · nesting ≤2 · function ≤25 lines · file ≤300 lines · params ≤4 · statements per function ≤10 · cognitive complexity ≤4 — line counts are code lines, not physical lines (`pnpm josh lint`); test files allow 35 code lines per function.
 - No magic numbers beyond `0`, `1`, `-1` · no `any` · restricted `as` · explicit param and return types · single short early return → one-liner `if (x) return y`.
 
-### Content rules
-
-- i18n: user-visible strings use message keys in every locale.
-- Comments / test titles: English only (`node_modules/@joshuafolkken/kit/eslint/rules/` may explain rationale in Japanese).
-- No duplication; `/* @refactor-ignore */` at file top excludes a file from refactoring.
-
-### Dependency overrides (`pnpm-workspace.yaml` / `package.json`)
-
-- 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 — 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
 
 Before building a feature, check for a well-maintained package — measure with `pnpm josh pkg:scout <keywords>`: `clear` → select it (Tier A), `close` → ask (Tier B).
 
 ## Code Change Rules
 
-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. `node_modules/@joshuafolkken/kit/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): `node_modules/@joshuafolkken/kit/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`.
-   - Read a target's headroom first: `pnpm josh lines <path>`.
+0. **Work summary + test declaration** — before writing any implementation code, once per Issue: Now / Change / Check, then every change with its test (`node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/report-format.md` → "作業前サマリはいつ・どう出すか"). **Tests are required for ALL changes** — zero tests without explicit approval is a violation; a runtime change with no test is refused at `pnpm josh git -y` on `required` (`pnpm josh test:declared`).
 1. **Refactor first** — `node_modules/@joshuafolkken/kit/prompts/refactoring.md`; no high/medium refactoring left on new/modified code.
 2. **Tests** — those declared in Step 0 (`node_modules/@joshuafolkken/kit/prompts/testing-guide.md`).
 3. **Verification gate** — `pnpm josh gate`; while implementing re-run one check (`pnpm josh lint:related` / `pnpm josh cspell:dot` / `pnpm josh test:related`). Add legitimate flagged terms to `cspell.config.yaml`.
@@ -94,35 +56,22 @@ In order, none skipped: tests (Step 0) → refactor → `pnpm josh gate` → Pre
 
 ## Pre-commit Self-Review (mandatory)
 
-Before every `git commit`, a subagent runs `/code-review` per `node_modules/@joshuafolkken/kit/prompts/review.md` — level from `pnpm josh review:brief --level-only`, no further than the round cap (`node_modules/@joshuafolkken/kit/prompts/review.md` → "Review round cap"). Each remaining non-High finding: fix it, file it as a follow-up Issue only when it is a confirmed defect that reaches a runtime path (`pnpm josh disposition <path>`), or drop it with a PR note.
-
-## Doc Sync Rules
-
-When `josh bump` changes the version, update `https://github.com/joshuafolkken/kit/tree/main/docs/` for any changed behavior before committing.
+Before every `git commit`, a subagent runs `/code-review` per `node_modules/@joshuafolkken/kit/prompts/review.md` — level from `pnpm josh review:brief --level-only`, no further than the round cap, then the three-way disposition (`node_modules/@joshuafolkken/kit/prompts/review.md` → "Review round cap").
 
 ## 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`. `node_modules/@joshuafolkken/kit/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`.
+- **Use `pnpm josh git`; open a PR with `pnpm josh pr`** — `pnpm josh rule:guard` refuses a direct `gh pr create`. GitHub operations are `gh api` (REST) — `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/gh-rest.md`.
 - **Run `git status` (and `git stash list`) live** before acting on any tree assumption.
 
 ## Collaboration Workflow
 
-- The issue-driven flow: `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow.md`; where a new rule goes: `node_modules/@joshuafolkken/kit/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. `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow/wip-cap.md`.
+The issue-driven flow: `node_modules/@joshuafolkken/kit/prompts/collaboration-workflow.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.
-
-**`queue` and `epicrun` were removed** — point `queue` to `backlogrun #N1 #N2 …` and `epicrun` to `backlogrun #E --only`.
-
-Read the `epic-commands` skill before any `josh epic:*` command, before writing an epic that tracks a child in another repository, and when `epic:bundle` places a filed issue. Three rules bind outside it:
-
-- 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.
-- **An epic in another repository is referenced as `owner/repo#N`** — a bare `#N` resolves to this repository's issue.
+`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. Read the `epic-commands` skill before any `josh epic:*` command, before writing an epic that tracks a child in another repository, when `epic:bundle` places a filed issue, and when recording a decision on a `needs-decision` child.
 
 #### Explicit invocation required (MANDATORY)
 

package/dist/commands/document-section-cli.js

@@ -114,6 +114,8 @@ var file_reader = { read_optional, read_file_or_empty, read_if_readable };
 var COMMAND_PATTERN = /`(?:pnpm )?josh ([a-z][a-z0-9:-]+)/gu;
 var LABEL_PATTERN = /(?:labels\[\]=|\/labels\/|labels -f name=)([a-z][a-z0-9:_-]*)/gu;
 var SECTION_PATTERN = /(?<![\w./:`-])(?<tick>`?)(?<file>[\w./-]+\.md)\k<tick>\s*→\s*(?:§\w+,\s*)?["「](?<heading>[^"」]+)["」]/gu;
+var ADJACENT_PATTERN = /["「](?<heading>[^"「」]+)["」]\s+(?:above|below)\b/gu;
+var BARE_ARROW_PATTERN = /→\s*(?:§\w+,\s*)?["「](?<heading>[^"「」]+)["」]/gu;
 var LINK_TARGET_PATTERN = /\]\([^)\s]*\)/gu;
 var LINK_PATTERN = /\]\(([\w./-]+\.md)(?:#[\w-]+)?\)/gu;
 var PLACEHOLDER_FILES = /* @__PURE__ */ new Set(["x.md", "foo.md", "file.md", "path.md"]);
@@ -138,6 +140,16 @@ function is_placeholder_file(name) {
 function section_references(text) {
   return matches(text.replaceAll(LINK_TARGET_PATTERN, ""), SECTION_PATTERN).map(({ groups }) => ({ file: groups?.["file"] ?? "", heading: groups?.["heading"] ?? "" })).filter((reference) => !is_placeholder_file(reference.file));
 }
+function headings_matching(text, pattern) {
+  return matches(text, pattern).map(({ groups }) => groups?.["heading"] ?? "");
+}
+function adjacent_references(text) {
+  return headings_matching(text, ADJACENT_PATTERN);
+}
+function bare_arrow_references(text) {
+  const unfiled = text.replaceAll(LINK_TARGET_PATTERN, "").replaceAll(SECTION_PATTERN, "");
+  return headings_matching(unfiled, BARE_ARROW_PATTERN);
+}
 function link_targets(text) {
   return matches(text, LINK_PATTERN).map((match) => match[1] ?? "").filter((file) => !is_placeholder_file(file));
 }
@@ -149,6 +161,8 @@ function reference_forms(title) {
   return [normalized, normalized.replace(/^\d+[a-z]?\. /u, "")];
 }
 var document_scan = {
+  adjacent_references,
+  bare_arrow_references,
   command_references,
   label_references,
   link_targets,
@@ -469,10 +483,10 @@ var POINT_OF_USE_FILES = /* @__PURE__ */ new Set([
   "backlogrun-park.md",
   "backlogrun-steps.md",
   // Read only when a delegated unit goes silent or a lane's pull request conflicts with `main` — a
-  // failure path, so a run in which nothing fails never reads it (joshuafolkken/kit#3175).
+  // failure path, so a run in which nothing fails never reads it.
   "backlogrun-recovery.md",
   // Read only when `run:step` prints `pnpm josh retrospective` at a run's stop position — the very
-  // end of a run, never the entry (joshuafolkken/kit#2328). Kept out of every entry's read for the
+  // end of a run, never the entry. Kept out of every entry's read for the
   // same reason the phase documents above are: no run that never drains its backlog reaches it.
   "retrospective.md"
 ]);
@@ -507,6 +521,7 @@ var SKILL_DIRECTORY = path5.join(".claude", "skills", "workflow-commands");
 var SKILL_FILE = "SKILL.md";
 var TABLE_SECTION = "1. Which file to read";
 var NOTHING2 = 0;
+var HEADING_JOINER = '" + "';
 var SUBSECTION_PREFIX = "### ";
 var TABLE_ROW = /^\|(?<entry>[^|]+)\|(?<files>[^|]+)\|\s*$/u;
 var MARKDOWN_NAME = /`(?<name>[\w.-]+\.md)`/gu;
@@ -631,20 +646,37 @@ function file_costs(root, names) {
   return names.map((file) => ({ file, cost: cost_of2(read_document(root, file)) }));
 }
 function point_of_use_cost(root, file, references) {
-  const reference = references.find((one) => one.file === file);
-  if (reference !== void 0) return section_cost(root, reference);
-  return { file, heading: "", cost: cost_of2(read_document(root, file)), is_resolved: true };
+  const markdown = read_document(root, file);
+  const headings2 = unique(references.filter((one) => one.file === file).map((one) => one.heading));
+  if (headings2.length === NOTHING2) {
+    return { file, heading: "", cost: cost_of2(markdown), is_resolved: true };
+  }
+  return {
+    file,
+    heading: headings2.join(HEADING_JOINER),
+    cost: scoped_file_cost2(markdown, headings2),
+    is_resolved: headings2.every(
+      (heading) => document_section.section(markdown, heading) !== void 0
+    )
+  };
 }
-function cited_by(root, entry, table_text, also) {
+function path_texts(root, entry, table_text) {
   const manifests = files_for(root, entry).filter((file) => file !== SKILL_FILE);
   const rows = table_text.split("\n").filter((line) => line.startsWith("|") && line.includes(`\`${entry}\``));
-  const texts = [...manifests.map((file) => read_document(root, file)), ...rows];
-  return /* @__PURE__ */ new Set([...also, ...texts.flatMap((text) => names_in(text))]);
+  return [...manifests.map((file) => read_document(root, file)), ...rows];
+}
+function point_of_use_references(root, entry, table_text) {
+  const manifests = files_for(root, entry).filter((file) => file !== SKILL_FILE);
+  const texts = [table_text, ...manifests.map((file) => read_document(root, file))];
+  return texts.flatMap(
+    (text) => all_matches(text, SECTION_REFERENCE).map((match) => to_reference(match))
+  );
 }
 function point_of_use_costs(root, entry, also) {
   const table_text = document_section.section(read_document(root, SKILL_FILE), TABLE_SECTION)?.text ?? "";
-  const references = all_matches(table_text, SECTION_REFERENCE).map((match) => to_reference(match));
-  const cited = cited_by(root, entry, table_text, also);
+  const references = point_of_use_references(root, entry, table_text);
+  const named = path_texts(root, entry, table_text).flatMap((text) => names_in(text));
+  const cited = /* @__PURE__ */ new Set([...also, ...named]);
   return point_of_use_files2(entry, cited).map((file) => point_of_use_cost(root, file, references));
 }
 function costed(root, entry, also = /* @__PURE__ */ new Set()) {