foldkit/foldkit

Read `ai-docs/README.md`; it owns source structure, style, examples, generation,
and changeset policy.

1. Inspect neighboring source examples and the relevant current `LLMS.md`.
2. Edit sources under `ai-docs/src`, then run `pnpm ai-docgen`.
3. Review generated output for ordering, missing content, and unrelated changes.
4. Run applicable root validation.

The task is complete when sources and generated output agree, every generated
difference is explained, TypeScript checks pass when examples or fixtures
change, and applicable checks pass or are reported as not runnable.

Read `packages/tools/bundle/README.md`, then select one workflow:

- **Stable comparison:** `pnpm bundle-compare <base-ref>`. Use `HEAD~1` for the
  latest commit. Read `tmp/bundle-stats.txt` and report non-zero differences.
- **Selected comparison:** `pnpm bundle-compare-selected --base <ref>
  scratchpad/<fixture>.ts`. Use only user-named or investigation-local fixtures;
  keep temporary fixtures out of the stable corpus.
- **Composition:** `pnpm bundle-analyze scratchpad/<fixture>.ts`. Read raw data
  first and report the largest modules, dependency groups, and surprising
  inclusions. Its readable-name output is not an exact size measurement.
- **Current size:** Build immediately before the direct bundle report so Effect
  packages resolve from current `dist` output.
- **Cleanup:** Stable comparisons retain `tmp/bundle-base` for reuse unless
  cleanup is requested. Remove selected-comparison state retained with

Treat a changeset as the release note for the complete PR, not as a log of work
performed along the way. Finalize it after the current implementation scope and
focused validation are complete.

## Workflow

1. Inspect the complete diff from the merge base, including changeset files
   already introduced by the PR, and identify directly affected published
   packages.
2. Classify impact across source types, runtime behavior, entrypoints, required
   services, lifecycle, and persisted or wire data.
3. Perform the breaking audit below.
4. Record a reason no changeset is required, or update the PR's existing
   changeset. Create one only when the PR does not have one. When required, read

Audit the trust boundary before editing. This skill owns Actions event
semantics, workflow security, permissions, action pinning, setup reuse,
untrusted inputs, timeouts, concurrency, and artifact trust boundaries.

## Workflow

1. Decide whether this is a review or an implementation. Reviews produce
   evidence-backed findings without editing; implementations continue through
   the smallest boundary-preserving change.
2. Inspect every affected workflow, composite action, and caller. List all
   affected jobs and actions before proceeding.
3. For each job, record the trigger, actor/fork status, workflow revision,
   checked-out revision, permissions, credentials, and every external input and
   consumer. Include artifacts, caches, outputs, PR fields, refs, dispatch

Treat an upgrade as a synchronization task, not a lockfile refresh. Derive
versions, commands, and compatibility points from the current repository.

## Discover

1. Read affected manifests and scripts, `pnpm-workspace.yaml`, setup actions,
   workflows, test configuration, and compatibility documentation.
2. Search for the dependency and every current version, range, runtime input,
   image, engine constraint, patch, and compatibility claim.
3. Record each match as a development version, tested version, peer range,
   engine minimum, advertised minimum, or intentionally different constraint.
4. When adding or moving a manifest entry, read
   [manifest-roles.md](manifest-roles.md) before selecting its role.
5. Select the package-local or coordinated branch and its validation matrix.

Use the repository's AI documentation as targeted reference, not ambient
context:

1. Identify the Effect APIs and concepts involved in the change.
2. Search `LLMS.md` and `ai-docs/src` for those names and concepts, then read
   the matching sections and examples.
3. Apply the relevant guidance and inspect nearby source and tests for any
   repository-internal conventions not covered by the documentation.

The task is ready for implementation when every material Effect API or pattern
has matching local guidance, or the search has established that none exists.

## API conventions

## Workflow

1. Inspect the declaration, implementation, nearby JSDoc, tests, and call sites.
2. Select every applicable branch and load its reference before editing:
   - tags, modules, or links: [declarations.md](declarations.md);
   - categories: [categories.md](categories.md);
   - examples: [examples.md](examples.md).
3. Make a focused API fix or module refinement. Preserve verified facts and
   valuable examples rather than rewriting mechanically.
4. For module refinement or APIs with close alternatives, audit `@see` links
   and inspect implementation and tests for concrete `**Gotchas**`.
5. Run `pnpm jsdocs --check` and every applicable root validation command.

`@internal` declarations and default exports are outside public JSDoc

Update guidance when a v3 public module or API is renamed, moved, removed,
replaced, or gains a materially different v4 contract. A v4-only API without a
v3 counterpart does not automatically need an annotation.

1. Account for every affected v3 symbol.
2. Read [annotations.md](annotations.md) before adding or changing annotation
   YAML. Verify every suggested replacement against implementation and tests.
3. When checking or regenerating the reference, or when the API change exists in
   a committed ref, read [generation.md](generation.md). Otherwise report that
   generation is deferred.
4. When output was generated, inspect it for unrelated movement and stale refs.

The task is complete when every affected v3 symbol is accounted for, annotation
replacements are verified, checks and generation succeed when the change is in

Treat package work as a registration change, not a directory copy.

## Workflow

1. Inspect the closest package in the same family. Classify publication status,
   runtime, test environment, platform support, barrels, and dependency shape.
   Justify each proposed file by precedent or an explicit repository need.
   Continue when every proposed file is justified.
2. Create or move only required source, test, TypeScript, and manifest files.
   When manifest dependencies change, read [dependencies.md](dependencies.md)
   and classify every entry by role.
   Continue when pnpm discovers the intended name and manifests reference no
   absent file.
3. Read [registration.md](registration.md). Classify every registration surface

Validate correctness with focused tests before measuring. Compare the same
focused operation and environment across revisions; a single unpaired run is
not evidence of improvement.

Select every applicable branch:

- **Runtime performance:** Read [runtime.md](runtime.md).
- **Type performance:** Read [types.md](types.md).

The task is complete when every selected branch meets its measurement and
reporting criteria and applicable root checks pass or are reported as not
runnable.

A pull request is ready when its tests, implementation, comments, and changeset
are each the simplest that cover the intended behavior. Draft PRs can be used
earlier; finishing means making the PR ready for review.

## Workflow

Run each step in a fresh-context subagent when available; otherwise run it
yourself. Pass along the task context and prior results so each step can check its gate.

1. Keep tests focused. Read [test-development](../test-development/SKILL.md) for
   test placement and type. Cover each intended behavior once, in the existing
   test file for the module.
   For changes needing no tests, record why.
   Continue when removing any remaining case would leave intended behavior

Choose branches from the task's acceptance criteria before editing:

- **Runtime behavior:** The intended result is observable when code executes.
  Read [runtime.md](runtime.md).
- **Compiler behavior:** The intended result is TypeScript accepting, rejecting,
  or inferring a consumer expression in a particular way. Read
  [types.md](types.md).

An exported signature alone is validated by `pnpm check`; it enters the compiler
branch only when its inference, assignability, rejection, overload selection, or
displayed type is part of the task. Some changes require both branches because
they independently change runtime and compiler behavior.

The task is complete when each intended behavior in scope has the relevant

Treat upstream artifacts as supply-chain inputs. Change their generator or
documented import source, then regenerate; generated output is review evidence,
not an editing surface.

## Workflow

1. **Trace ownership.** Identify the artifact, generator or exact import
   procedure, upstream source/version, license, consumers, tests, and shipped
   package or bundle. Search by asset and upstream project name to find current
   packaging scripts, generated artifacts, consumers, and history.
   Continue when every input and consumer is accounted for.
2. **Pin provenance.** Resolve moving URLs, tags, branches, and omitted versions
   to an immutable release or artifact. Record project, version, path or URL,
   and digest in the generator or maintenance header. Omit a digest only when

Audit an existing Foldkit program against the same bar `generate-program` targets: this code should be **indistinguishable in quality from hand-written code in `packages/typing-game/client/src/` or `packages/website/src/`**. Not "works." Not "structurally valid." Typing-game quality.

> **Recommended setup:** the audit is dramatically higher fidelity when `repos/foldkit/` is vendored as a git subtree in the audited project. Without it, you grade against the snapshots in `generate-program/architecture.md` and `conventions.md`. With it, you grade against the live exemplars (`examples/`, `packages/typing-game/`, `packages/website/`), which is what those snapshots are summarizing in the first place. If the subtree is missing, recommend adding it before the audit begins, pinned to the release git tag matching the installed `foldkit` package so the exemplars match the APIs the project compiles against: `git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git "foldkit@$(node -p "require('./node_modules/foldkit/package.json').version")" --squash`. For a canary install, whose version (`x.y.z-canary.<commit>`) has no tag, pin to the full hash of the commit it names instead, which GitHub expands at `https://github.com/foldkit/foldkit/commit/<commit>`.

## Operating principle: report first, change nothing without consent

The audit is **read-only through Phase 6**. The output is a structured report. **Never edit a file before the user has seen the report and explicitly approved fixes**, no matter how unambiguous a finding seems, no matter how trivial the change, no matter how confident you are. Phase 7 (Offer fixes) is opt-in and gated on user consent per item or per batch.

Concretely, this means:

- Phases 1 to 6 are pure investigation: read code, run greps, spawn review subagents, synthesize findings. No `Edit`, no `Write`, no `Bash` commands that modify files.
- After delivering the report at the end of Phase 6, **stop and wait**. Ask whether to apply fixes. Don't bundle a fix into the same response as the report.
- Even after the user invites fixes, structural and semantic changes still need confirmation per item. Mechanical fixes can batch only if the user explicitly accepts the batch.
- If the user says "fix it" or "make the changes" early (before seeing findings), surface the report first anyway. The report is the value the audit provides; jumping to edits skips the consultation that lets the user prioritize and reject items.

# Foldkit

You are working on a Foldkit app. Foldkit is a complete TypeScript frontend framework, built on Effect and architected like Elm. The architecture is solved: state, events, transitions, side effects, streams, routing, UI components, validation, testing, and devtools are all part of the framework, not third-party choices to make. Your job is to model the application's behavior, not to pick libraries or invent architecture.

Foldkit is not incremental. There is no React interop, no escape hatch, no "just do it the React way for this one part." The framework gives you one shape, and there is one way to do most things.

## How to approach the work

- **Pattern-match against Foldkit's own apps.** When the local code doesn't show you the answer (or shows an early-stage version of it), reach into the vendored foldkit subtree. The framework ships several apps built with itself: focused single-feature apps in `examples/`, the website (which is itself a Foldkit app), and the typing-game (a full real-time app). These are the canonical references. Higher fidelity than prose or anything reconstructed from memory.
- **The architecture is not optional.** Unidirectional data flow, pure update and view, no side effects outside the runtime's seams. Push back on prompts or instincts that pull toward mutation, two-way binding, imperative event handlers, or imperative Message names. Propose the idiomatic Foldkit shape and explain why.
- **Foldkit UI is two categories, not one.** Stateful Submodels (Menu, Listbox, Combobox, Calendar, Disclosure, Dialog, Popover, etc.) carry their own Model / Message / update / OutMessage and are embedded via `h.submodel`. Stateless render helpers (Button, Input, Textarea, Select, Fieldset) are called directly with a ViewConfig and the caller's `h`, and return Html. Do not migrate render helpers to Submodels for "consistency": Submodel semantics imply state, and these helpers have none. See the Foldkit UI overview page in the website for the canonical split.
- **Use what the Foldkit and Effect stack provides.** Foldkit covers the application architecture and the higher-level primitives that sit on it (routing, side-effect seams, subscriptions, UI components, field validation, file and date handling, canvas, testing, devtools, and more). Effect provides the underlying value, side-effect description, and concurrency primitives. Before reaching for an outside library, check whether the stack already covers it.
- **Let `modifyFields` setters receive the field.** If a `modifyFields` setter only transforms the current value of that same field, pass the transformer directly (`entries: Array.map(f)`, `count: Number.increment`, `priceSlider: Slider.reflectRange({ min: minPrice, max: maxPrice })`). Use `() => value` for replacement values from Messages, child updates, Commands, or other Model fields.
- **The repo is more authoritative than memory.** When in doubt about a convention, an API, a name, or a pattern, read from the vendored foldkit subtree rather than guessing. Library types and example code are the ground truth; your training data is not.

Generate a complete Foldkit program based on this description:

**$ARGUMENTS**

## Phase 1: Analyze the Description

Before writing any code, analyze the description to identify:

1. **Domain entities**: nouns that become Model fields (e.g., "todos", "user", "score")
2. **User interactions**: verbs that become Messages (e.g., "add", "delete", "filter", "submit")
3. **Async operations**: external data that becomes Commands (e.g., "fetch weather", "save to localStorage")
4. **Real-time needs**: streaming data that becomes Subscriptions (e.g., "live updates", "countdown", "WebSocket")
5. **Pages/navigation**: URL structure that becomes routes (e.g., "home page", "detail page")
6. **UI component needs**: interactive widgets that map to Foldkit UI components (e.g., "dropdown" → Menu, "modal" → Dialog, "tabs" → Tabs, "autocomplete" → Combobox, "date picker" → DatePicker, "file upload" → FileDrop, "reorderable list" → DragAndDrop, "toast/notification" → Toast, "hover tooltip" → Tooltip, "range/price filter" → Slider, "long scrolling list" → VirtualList)