From ba8f925eed614eb87f63d460c0599204582f39ff Mon Sep 17 00:00:00 2001 From: EFLKumo <96906415+EFLKumo@users.noreply.github.com> Date: Sun, 4 Oct 2026 11:51:59 +0800 Subject: [PATCH] init --- .agents/skills/jj-vcs/SKILL.md | 155 + .../skills/jj-vcs/references/collaboration.md | 125 + .agents/skills/jj-vcs/references/commands.md | 51 + .../skills/jj-vcs/references/core-concepts.md | 95 + .../skills/jj-vcs/references/daily-work.md | 117 + .../jj-vcs/references/history-rewriting.md | 130 + .agents/skills/jj-vcs/references/recovery.md | 119 + .agents/skills/shadcn/SKILL.md | 277 + .agents/skills/shadcn/agents/openai.yml | 5 + .agents/skills/shadcn/assets/shadcn-small.png | Bin 0 -> 1049 bytes .agents/skills/shadcn/assets/shadcn.png | Bin 0 -> 3852 bytes .agents/skills/shadcn/cli.md | 290 + .agents/skills/shadcn/customization.md | 209 + .agents/skills/shadcn/evals/evals.json | 77 + .agents/skills/shadcn/mcp.md | 105 + .agents/skills/shadcn/registry.md | 277 + .agents/skills/shadcn/rules/base-vs-radix.md | 306 + .agents/skills/shadcn/rules/chat.md | 250 + .agents/skills/shadcn/rules/composition.md | 213 + .agents/skills/shadcn/rules/forms.md | 192 + .agents/skills/shadcn/rules/icons.md | 101 + .agents/skills/shadcn/rules/styling.md | 185 + .gitignore | 19 + .npmrc | 1 + .prettierignore | 10 + .prettierrc | 11 + LICENSE | 21 + README.md | 21 + apps/web/components.json | 23 + apps/web/eslint.config.js | 21 + apps/web/package.json | 40 + apps/web/public/favicon.ico | Bin 0 -> 3870 bytes apps/web/public/manifest.json | 25 + apps/web/public/robots.txt | 3 + apps/web/src/hooks/use-mobile.ts | 19 + apps/web/src/routeTree.gen.ts | 68 + apps/web/src/router.tsx | 20 + apps/web/src/routes/__root.tsx | 47 + apps/web/src/routes/index.tsx | 19 + apps/web/tsconfig.json | 34 + apps/web/tsr.config.json | 3 + apps/web/vite.config.ts | 12 + package.json | 22 + packages/ui/components.json | 23 + packages/ui/eslint.config.js | 21 + packages/ui/eslint.config.ts | 3 + packages/ui/package.json | 50 + packages/ui/src/components/.gitkeep | 0 packages/ui/src/components/accordion.tsx | 72 + packages/ui/src/components/alert-dialog.tsx | 185 + packages/ui/src/components/alert.tsx | 75 + packages/ui/src/components/aspect-ratio.tsx | 22 + packages/ui/src/components/attachment.tsx | 207 + packages/ui/src/components/avatar.tsx | 106 + packages/ui/src/components/badge.tsx | 51 + packages/ui/src/components/breadcrumb.tsx | 124 + packages/ui/src/components/bubble.tsx | 127 + packages/ui/src/components/button-group.tsx | 87 + packages/ui/src/components/button.tsx | 57 + packages/ui/src/components/calendar.tsx | 222 + packages/ui/src/components/card.tsx | 102 + packages/ui/src/components/carousel.tsx | 241 + packages/ui/src/components/chart.tsx | 370 + packages/ui/src/components/checkbox.tsx | 28 + packages/ui/src/components/collapsible.tsx | 19 + packages/ui/src/components/combobox.tsx | 296 + packages/ui/src/components/command.tsx | 197 + packages/ui/src/components/context-menu.tsx | 269 + packages/ui/src/components/dialog.tsx | 160 + packages/ui/src/components/direction.tsx | 4 + packages/ui/src/components/drawer.tsx | 227 + packages/ui/src/components/dropdown-menu.tsx | 264 + packages/ui/src/components/empty.tsx | 103 + packages/ui/src/components/field.tsx | 236 + packages/ui/src/components/hover-card.tsx | 50 + packages/ui/src/components/input-group.tsx | 158 + packages/ui/src/components/input-otp.tsx | 84 + packages/ui/src/components/input.tsx | 19 + packages/ui/src/components/item.tsx | 201 + packages/ui/src/components/kbd.tsx | 26 + packages/ui/src/components/label.tsx | 19 + packages/ui/src/components/marker.tsx | 70 + packages/ui/src/components/menubar.tsx | 279 + .../ui/src/components/message-scroller.tsx | 129 + packages/ui/src/components/message.tsx | 91 + packages/ui/src/components/native-select.tsx | 61 + .../ui/src/components/navigation-menu.tsx | 168 + packages/ui/src/components/pagination.tsx | 130 + packages/ui/src/components/popover.tsx | 87 + packages/ui/src/components/progress.tsx | 82 + packages/ui/src/components/questionnaire.tsx | 325 + packages/ui/src/components/radio-group.tsx | 35 + packages/ui/src/components/resizable.tsx | 49 + packages/ui/src/components/scroll-area.tsx | 52 + packages/ui/src/components/select.tsx | 199 + packages/ui/src/components/separator.tsx | 22 + packages/ui/src/components/sheet.tsx | 136 + packages/ui/src/components/sidebar.tsx | 724 ++ packages/ui/src/components/skeleton.tsx | 13 + packages/ui/src/components/slider.tsx | 51 + packages/ui/src/components/spinner.tsx | 11 + packages/ui/src/components/switch.tsx | 31 + packages/ui/src/components/table.tsx | 113 + packages/ui/src/components/tabs.tsx | 81 + packages/ui/src/components/textarea.tsx | 17 + packages/ui/src/components/toast.tsx | 235 + packages/ui/src/components/toggle-group.tsx | 87 + packages/ui/src/components/toggle.tsx | 42 + packages/ui/src/components/tooltip.tsx | 65 + packages/ui/src/hooks/.gitkeep | 0 packages/ui/src/lib/.gitkeep | 0 packages/ui/src/lib/utils.ts | 1 + packages/ui/src/styles/globals.css | 131 + packages/ui/tsconfig.json | 17 + packages/ui/tsconfig.lint.json | 14 + pnpm-lock.yaml | 7952 +++++++++++++++++ pnpm-workspace.yaml | 9 + skills-lock.json | 17 + test-results/.last-run.json | 4 + tsconfig.json | 9 + turbo.json | 24 + 121 files changed, 19786 insertions(+) create mode 100644 .agents/skills/jj-vcs/SKILL.md create mode 100644 .agents/skills/jj-vcs/references/collaboration.md create mode 100644 .agents/skills/jj-vcs/references/commands.md create mode 100644 .agents/skills/jj-vcs/references/core-concepts.md create mode 100644 .agents/skills/jj-vcs/references/daily-work.md create mode 100644 .agents/skills/jj-vcs/references/history-rewriting.md create mode 100644 .agents/skills/jj-vcs/references/recovery.md create mode 100644 .agents/skills/shadcn/SKILL.md create mode 100644 .agents/skills/shadcn/agents/openai.yml create mode 100644 .agents/skills/shadcn/assets/shadcn-small.png create mode 100644 .agents/skills/shadcn/assets/shadcn.png create mode 100644 .agents/skills/shadcn/cli.md create mode 100644 .agents/skills/shadcn/customization.md create mode 100644 .agents/skills/shadcn/evals/evals.json create mode 100644 .agents/skills/shadcn/mcp.md create mode 100644 .agents/skills/shadcn/registry.md create mode 100644 .agents/skills/shadcn/rules/base-vs-radix.md create mode 100644 .agents/skills/shadcn/rules/chat.md create mode 100644 .agents/skills/shadcn/rules/composition.md create mode 100644 .agents/skills/shadcn/rules/forms.md create mode 100644 .agents/skills/shadcn/rules/icons.md create mode 100644 .agents/skills/shadcn/rules/styling.md create mode 100644 .gitignore create mode 100644 .npmrc create mode 100644 .prettierignore create mode 100644 .prettierrc create mode 100644 LICENSE create mode 100644 README.md create mode 100644 apps/web/components.json create mode 100644 apps/web/eslint.config.js create mode 100644 apps/web/package.json create mode 100644 apps/web/public/favicon.ico create mode 100644 apps/web/public/manifest.json create mode 100644 apps/web/public/robots.txt create mode 100644 apps/web/src/hooks/use-mobile.ts create mode 100644 apps/web/src/routeTree.gen.ts create mode 100644 apps/web/src/router.tsx create mode 100644 apps/web/src/routes/__root.tsx create mode 100644 apps/web/src/routes/index.tsx create mode 100644 apps/web/tsconfig.json create mode 100644 apps/web/tsr.config.json create mode 100644 apps/web/vite.config.ts create mode 100644 package.json create mode 100644 packages/ui/components.json create mode 100644 packages/ui/eslint.config.js create mode 100644 packages/ui/eslint.config.ts create mode 100644 packages/ui/package.json create mode 100644 packages/ui/src/components/.gitkeep create mode 100644 packages/ui/src/components/accordion.tsx create mode 100644 packages/ui/src/components/alert-dialog.tsx create mode 100644 packages/ui/src/components/alert.tsx create mode 100644 packages/ui/src/components/aspect-ratio.tsx create mode 100644 packages/ui/src/components/attachment.tsx create mode 100644 packages/ui/src/components/avatar.tsx create mode 100644 packages/ui/src/components/badge.tsx create mode 100644 packages/ui/src/components/breadcrumb.tsx create mode 100644 packages/ui/src/components/bubble.tsx create mode 100644 packages/ui/src/components/button-group.tsx create mode 100644 packages/ui/src/components/button.tsx create mode 100644 packages/ui/src/components/calendar.tsx create mode 100644 packages/ui/src/components/card.tsx create mode 100644 packages/ui/src/components/carousel.tsx create mode 100644 packages/ui/src/components/chart.tsx create mode 100644 packages/ui/src/components/checkbox.tsx create mode 100644 packages/ui/src/components/collapsible.tsx create mode 100644 packages/ui/src/components/combobox.tsx create mode 100644 packages/ui/src/components/command.tsx create mode 100644 packages/ui/src/components/context-menu.tsx create mode 100644 packages/ui/src/components/dialog.tsx create mode 100644 packages/ui/src/components/direction.tsx create mode 100644 packages/ui/src/components/drawer.tsx create mode 100644 packages/ui/src/components/dropdown-menu.tsx create mode 100644 packages/ui/src/components/empty.tsx create mode 100644 packages/ui/src/components/field.tsx create mode 100644 packages/ui/src/components/hover-card.tsx create mode 100644 packages/ui/src/components/input-group.tsx create mode 100644 packages/ui/src/components/input-otp.tsx create mode 100644 packages/ui/src/components/input.tsx create mode 100644 packages/ui/src/components/item.tsx create mode 100644 packages/ui/src/components/kbd.tsx create mode 100644 packages/ui/src/components/label.tsx create mode 100644 packages/ui/src/components/marker.tsx create mode 100644 packages/ui/src/components/menubar.tsx create mode 100644 packages/ui/src/components/message-scroller.tsx create mode 100644 packages/ui/src/components/message.tsx create mode 100644 packages/ui/src/components/native-select.tsx create mode 100644 packages/ui/src/components/navigation-menu.tsx create mode 100644 packages/ui/src/components/pagination.tsx create mode 100644 packages/ui/src/components/popover.tsx create mode 100644 packages/ui/src/components/progress.tsx create mode 100644 packages/ui/src/components/questionnaire.tsx create mode 100644 packages/ui/src/components/radio-group.tsx create mode 100644 packages/ui/src/components/resizable.tsx create mode 100644 packages/ui/src/components/scroll-area.tsx create mode 100644 packages/ui/src/components/select.tsx create mode 100644 packages/ui/src/components/separator.tsx create mode 100644 packages/ui/src/components/sheet.tsx create mode 100644 packages/ui/src/components/sidebar.tsx create mode 100644 packages/ui/src/components/skeleton.tsx create mode 100644 packages/ui/src/components/slider.tsx create mode 100644 packages/ui/src/components/spinner.tsx create mode 100644 packages/ui/src/components/switch.tsx create mode 100644 packages/ui/src/components/table.tsx create mode 100644 packages/ui/src/components/tabs.tsx create mode 100644 packages/ui/src/components/textarea.tsx create mode 100644 packages/ui/src/components/toast.tsx create mode 100644 packages/ui/src/components/toggle-group.tsx create mode 100644 packages/ui/src/components/toggle.tsx create mode 100644 packages/ui/src/components/tooltip.tsx create mode 100644 packages/ui/src/hooks/.gitkeep create mode 100644 packages/ui/src/lib/.gitkeep create mode 100644 packages/ui/src/lib/utils.ts create mode 100644 packages/ui/src/styles/globals.css create mode 100644 packages/ui/tsconfig.json create mode 100644 packages/ui/tsconfig.lint.json create mode 100644 pnpm-lock.yaml create mode 100644 pnpm-workspace.yaml create mode 100644 skills-lock.json create mode 100644 test-results/.last-run.json create mode 100644 tsconfig.json create mode 100644 turbo.json diff --git a/.agents/skills/jj-vcs/SKILL.md b/.agents/skills/jj-vcs/SKILL.md new file mode 100644 index 0000000..98e0b31 --- /dev/null +++ b/.agents/skills/jj-vcs/SKILL.md @@ -0,0 +1,155 @@ +--- +name: jj-vcs +description: Using jj (Jujutsu) for version control. Make sure to use this skill whenever the user mentions jj, jujutsu, version control, commits, branches/bookmarks, rebasing, history rewriting, cloning/pushing/pulling, or any VCS workflow — even when they don't explicitly say "jj." This skill covers daily editing, history restructuring, collaboration with remotes, and recovery from mistakes. When the user's repository uses jj (look for a .jj/ directory), ALWAYS use jj commands instead of git commands. +allowed-tools: Bash(jj:*) +license: MIT +metadata: + author: OpticLM + version: "0.41.0.2" +--- + +## Core mental model + +jj is a Git-compatible version control system built around *changes* (revisions) that evolve over time. Each change has a **change ID** (stable — follows the change across rebases) and a **commit hash** (changes whenever the commit content changes). Refer to changes by their change ID (short prefix form) when you want to track a logical change, or by commit hash when pinning exact content. + +Key differences from Git: +- **No staging area.** The working copy (`@`) is itself a commit. `jj status` compares `@` to its parent. Changes to tracked files are automatically part of `@`. +- **Change IDs**, not branch names, are the primary way history is organized. A commit's change ID survives rebase, squash, and split. +- **Operation log.** Every jj command creates an operation. `jj undo` simply undoes the last operation. `jj op log` shows the full history of commands run. Nothing is lost unless you explicitly garbage-collect. +- **Bookmarks, not branches.** Bookmarks are labels on revisions. To move a bookmark to point at a different revision, use `jj bookmark move`. Git branches are just bookmarks that jj syncs to the remote. +- **Revsets.** jj's revision selection language. Used everywhere commands accept revisions. Learn the common patterns (see core-concepts.md). + +--- + +## Finding the right command + +### Daily work loop + +The core cycle is: **start a change → make edits → describe → (optionally) start the next change.** + +| Intent | Command | +|---|---| +| See what's changed in `@` | `jj status` (aliases: `st`) | +| See file-level diff | `jj diff` (use `--git` for git-style output, `-s` for summary) | +| Start a new change on top of `@` | `jj new [REVISION]` (defaults to `@`) | +| Describe/set the commit message | `jj describe -m "msg"` or `jj describe` (opens editor) | +| Describe + start next change | `jj commit -m "msg"` (equivalent to `describe -m && new`) | +| View revision graph | `jj log` (use `-r` with a revset to filter, `-p` for patch) | +| Browse file in older revision | `jj file show -r REV PATH` | + +`jj new` is the primary way to create changes. It creates an empty child of the given revision and makes it the new `@`. Unlike `git checkout -b`, it does not need a branch name. + +When the user says "commit my changes" they almost always mean `jj describe -m "message"` to record a message on the current change, or `jj commit -m "message"` to record and start a new empty change on top. + +### History restructuring + +jj makes rewriting history safe because nothing is truly lost (the operation log preserves everything). + +| Intent | Command | +|---|---| +| Move a change to a different parent | `jj rebase -r REV -o NEW_PARENT` | +| Move a whole branch of changes | `jj rebase -b REV -o NEW_PARENT` | +| Absorb changes from `@` into parent | `jj squash` (moves `@`'s diff into its parent) | +| Squash specific changes into sibling | `jj squash -f FROM_REV -t INTO_REV` | +| Split a revision in two | `jj split [-r REV]` (interactive by default) | +| Drop a change entirely | `jj abandon [-r REV]` (defaults to `@` if empty) | +| Rename/edit a change's description | `jj describe -r REV -m "new message"` | +| Edit a change's metadata (author, etc.) | `jj metaedit -r REV` | +| Pull edits from child into parent | `jj absorb` (auto-detects where changes belong) | +| Reorder siblings into a chain | `jj parallelize -r REVS...` | +| Interactive graph rearrangement | `jj arrange` | +| Touch up a change's content diff | `jj diffedit -r REV` | + +**Common squash patterns:** +- `jj squash` — squash `@` into its parent (the most common: you made a small fix that belongs in the previous commit) +- `jj squash -f FEATURE_REV -t MAIN` — move changes from a feature revision into main + +**Common rebase patterns:** +- `jj rebase -r REV -o DEST` — rebase a single revision onto DEST +- `jj rebase -b REV -o DEST` — rebase REV and all its descendants onto DEST +- `jj rebase -r REV --insert-after ANCHOR` — reorder REV to come after ANCHOR (useful for reordering commits in a stack) +- `jj rebase -r REV --insert-before ANCHOR` + +When rebasing after a squash/split/abandon, jj automatically rebases descendants. You rarely need to manually restack. + +### Collaboration + +jj interoperates with Git remotes. The workflow is: fetch → rebase → push. + +| Intent | Command | +|---|---| +| Clone a remote repo | `jj git clone ` | +| Fetch from remote | `jj git fetch [--remote NAME]` | +| Push to remote | `jj git push [--remote NAME]` | +| List bookmarks and their targets | `jj bookmark list` (aliases: `b l`) | +| Track a remote bookmark as local | `jj bookmark track NAME --remote origin` | +| Move a bookmark to point at a revision | `jj bookmark move --to REV BOOKMARK` (aliases: `b m -t REV BOOKMARK`) | +| Create a new bookmark | `jj bookmark create NAME` | +| List remotes | `jj git remote list` | +| Add a remote | `jj git remote add NAME URL` | + +**Push workflow:** +1. Ensure the bookmark you want to push points at your revision: `jj bookmark move --to=@ BOOKMARK` +2. Push: `jj git push` +3. If the remote has new commits: `jj git fetch` then `jj rebase -b BOOKMARK -o BOOKMARK@origin` + +**Important:** Before pushing, always check the change has a description. `jj git push` will fail or warn you if a change lacks a description. Use `jj describe -m "msg"` first. + +### Recovery + +| Intent | Command | +|---|---| +| Undo the last operation | `jj undo` | +| Redo an undo | `jj redo` | +| See operation history | `jj op log` | +| Restore repo to a past state | `jj op restore OPERATION_ID` | +| Restore files in `@` (undo edits in wd) | `jj restore` (restores all files from parent) | +| Restore specific paths from another revision | `jj restore --from SOURCE_REV PATH...` | +| Undo the changes introduced by a commit | `jj restore --changes-in REV` (creates a reverse of REV on top of @, effectively undoing its changes) | +| Resolve conflicts | `jj resolve PATH...` (opens external merge tool) | +| Inspect old repo state without restoring | `jj --at-op OPERATION_ID status` | + +`jj undo` is the first thing to reach for when something goes wrong. If you need to undo farther back, `jj op log` + `jj op restore` can take you to any previous state. + +--- + +## Git-to-jj translation + +When a user asks for a git command, translate to the equivalent jj command: + +| Git | jj | +|---|---| +| `git add FILE` | Edit FILE (no staging needed — tracked files auto-included) | +| `git commit -m "msg"` | `jj describe -m "msg"` (or `jj commit -m "msg"` to also start a new change) | +| `git commit --amend` | `jj squash` (move `@`'s changes into its parent) | +| `git checkout BRANCH` | `jj new BOOKMARK` | +| `git checkout -b BRANCH` | `jj new` then `jj bookmark create NAME` | +| `git branch -d BRANCH` | `jj bookmark delete NAME` | +| `git rebase main` | `jj rebase -b @ -o MAIN` | +| `git reset HEAD~1` | `jj restore` then `jj abandon @` | +| `git revert COMMIT` | `jj restore --changes-in COMMIT` | +| `git log --oneline` | `jj log --no-graph` | +| `git stash` | Not needed — just `jj new` to start fresh on top, or `jj bookmark create` to save the current state | + +--- + +## Choosing the right ancestor (`-o`) vs insert-after (`-A`) vs insert-before (`-B`) + +- `-o` / `--onto`: makes the source revision(s) children of the target. Most common. +- `-A` / `--insert-after`: inserts the source revision(s) *after* the target, making them siblings of the target's current children. Use when reordering within a stack. +- `-B` / `--insert-before`: inserts the source revision(s) *before* the target, making them parents of the target. Use when you want to add a step before an existing commit. + +These options appear on `rebase`, `new`, `split`, `squash`, and `restore`. + +--- + +## Reference files + +Read these for deeper guidance on specific workflows: + +- **references/core-concepts.md** — Revsets, change IDs, working copy mechanics, configuration +- **references/daily-work.md** — Commands and patterns for the daily edit/describe/log loop +- **references/history-rewriting.md** — Detailed squash, rebase, split, abandon, and absorb patterns +- **references/collaboration.md** — Pushing, pulling, bookmark management, Gerrit +- **references/recovery.md** — Undo, operation log, conflict resolution, and restore +- **references/commands.md** — Quick reference for every jj command with key flags diff --git a/.agents/skills/jj-vcs/references/collaboration.md b/.agents/skills/jj-vcs/references/collaboration.md new file mode 100644 index 0000000..dc71077 --- /dev/null +++ b/.agents/skills/jj-vcs/references/collaboration.md @@ -0,0 +1,125 @@ +# Collaboration + +Commands for working with Git remotes, bookmarks, and pushing/pulling changes. + +## jj git clone + +Clone a remote Git repository into a jj-backed repo. + +``` +jj git clone # clone and checkout default branch +jj git clone --colocate # clone as a colocated repo (works with git commands too) +``` + +## jj git fetch + +Fetch changes from a remote. Unlike `git fetch`, this fetches all bookmarks by default and can automatically track new bookmarks based on config. + +``` +jj git fetch # fetch all remotes +jj git fetch --remote origin # fetch only origin +jj git fetch --remote origin main # fetch specific bookmark(s) +``` + +After fetch, new remote bookmarks appear as `BOOKMARK@remote`. They aren't automatically tracked — you must explicitly `jj bookmark track` them. + +## jj git push + +Push changes to a remote. By default, pushes all bookmarks that have a remote counterpart. + +``` +jj git push # push all tracked bookmarks +jj git push --remote origin # push to specific remote +jj git push --bookmark main # push only specific bookmark(s) +jj git push --deleted BOOKMARK # propagate a bookmark deletion +jj git push --change CHANGE_ID # push a specific change by change ID +``` + +- `--bookmark` / `-b`: specify which bookmarks to push +- `--change`: push a single change to the remote as a draft PR (creates a bookmark on the remote) +- `--remote`: specify the remote +- `--deleted`: confirm you want to push a bookmark deletion to the remote + +**Push checklist:** +1. The revision has a description: `jj describe -m "msg"` +2. The bookmark points at the right revision: `jj bookmark move --to=REV BOOKMARK` or use `jj bookmark set BOOKMARK` (creates or moves) +3. The revision does not have conflicts: `jj status` will show them +4. You're not upstream of others' work (if collaborating) +5. Push: `jj git push` + +## jj bookmark + +Bookmark management. Short alias: `jj b`. + +``` +jj bookmark list # list all bookmarks and their targets (aliases: l) +jj bookmark create NAME # create a new bookmark at @ (aliases: c) +jj bookmark move --to REV NAME # move bookmark NAME to point at REV (aliases: m) +jj bookmark set NAME # create or update bookmark NAME at @ (aliases: s) +jj bookmark track NAME --remote R # track a remote bookmark locally (aliases: t) +jj bookmark untrack NAME # stop tracking a remote bookmark +jj bookmark delete NAME # delete a local bookmark (aliases: d) +jj bookmark forget NAME # forget a bookmark without pushing deletion +jj bookmark advance NAME # advance bookmark to nearest descendant of current target +jj bookmark rename OLD NEW # rename a bookmark +``` + +**Bookmark workflow for pushing changes:** +1. Work in `@` (on top of main) +2. When ready: `jj bookmark move --to=@ main` (move the main bookmark to `@`) +3. `jj git push` (pushes main to origin/main) + +Or use a feature-branch workflow: +1. `jj bookmark create my-feature` (creates bookmark at `@`) +2. Work, describe, etc. +3. `jj git push -b my-feature` (pushes just `my-feature`) + +**Tracking:** When you clone a repo, remote bookmarks like `main@origin` exist but aren't automatically tracked. `jj bookmark track main --remote origin` creates a local `main` bookmark that follows `main@origin`. Without this, `jj git push` may not know which local bookmark corresponds to which remote bookmark. + +## jj git remote + +Manage Git remotes. + +``` +jj git remote list # list remotes +jj git remote add NAME URL # add a remote +jj git remote remove NAME # remove a remote +jj git remote set-url NAME URL # change a remote's URL +``` + +## jj git colocation + +Manage colocation with an underlying Git repo. Colocation means the `.jj` repo works on the same working copy as a `.git` repo, allowing both `jj` and `git` commands. + +``` +jj git colocation init # initialize colocation +jj git colocation deinit # remove colocation +jj git export # manually sync jj changes to git +jj git import # manually sync git changes to jj +``` + +With colocation, export/import happens automatically on most commands. Use manual `jj git export` or `jj git import` if you've made changes in git that jj doesn't see yet. + +## jj gerrit + +Interact with Gerrit Code Review. + +``` +jj gerrit submit CHANGE_ID # submit a change to Gerrit +jj gerrit abandon CHANGE_ID # abandon a change in Gerrit +``` + +## Working with stacks + +jj excels at stacking changes. Common pattern: + +1. `jj new main` — start from main +2. `jj describe -m "part 1"` — describe first change +3. `jj new` — start second change +4. `jj describe -m "part 2"` — describe second change +5. `jj bookmark create stack-1` — save both (bookmark on latest) +6. `jj bookmark create stack-2` — or just push with `jj git push -b stack-1` + +To restack after reviews: +1. `jj rebase -b stack-1 -o main` — move whole stack +2. `jj git push` — update remote diff --git a/.agents/skills/jj-vcs/references/commands.md b/.agents/skills/jj-vcs/references/commands.md new file mode 100644 index 0000000..0ea2444 --- /dev/null +++ b/.agents/skills/jj-vcs/references/commands.md @@ -0,0 +1,51 @@ +# Command quick reference + +Every jj command with a one-line description and key flags. Read this when you need a quick overview of what commands are available. + +| Command | Description | Key flags | +|---|---|---| +| `jj abandon [-r REV]` | Drop a revision from history | `-r` revision to drop (default: `@`) | +| `jj absorb` | Auto-merge changes into their logical parent revisions | — | +| `jj arrange` | Interactively rearrange the commit graph | — | +| `jj bisect -r GOOD..BAD` | Binary search for a bad revision | Standard bisect: start, good, bad, skip | +| `jj bookmark ` | Manage bookmarks | Subcommands: list, create, delete, move, set, track, untrack, forget, advance, rename | +| `jj commit -m "msg"` | Describe `@` and create a new empty change on top | `-m`, `-i` interactive | +| `jj config ` | Manage configuration | Subcommands: get, set, edit, list, default | +| `jj describe -r REV -m "msg"` | Set or edit a revision's description | `-r` revision, `-m` message, `--stdin`, `--editor` | +| `jj diff [-r REV]` | Show diff of a revision | `-r`, `--git`, `-s` summary, `--stat`, `--name-only`, `--color-words` | +| `jj diffedit -r REV` | Edit a revision's content diff interactively | `-r`, `-i` | +| `jj duplicate -r REV` | Copy a revision's content to a new change ID | `-r` | +| `jj edit REV` | Switch working copy to an existing revision | — | +| `jj evolog -r REV` | Show how a change's content evolved over time | `-r`, `-p` patch | +| `jj file ` | File operations | Subcommands: list, show, chmod, track, untrack | +| `jj fix [-r REV]` | Apply formatting/linting tools to files in a revision | `-r`, `-s` source revsets, `--tool`, `-i` | +| `jj git ` | Git remote operations | Subcommands: clone, fetch, push, remote, init, export, import, colocation | +| `jj gerrit ` | Interact with Gerrit Code Review | Subcommands: submit, abandon | +| `jj help [CMD]` | Show help for jj or a specific command | — | +| `jj interdiff --from A --to B` | Show differences between two revisions' diffs | `--from`, `--to` | +| `jj log [-r REVSET]` | Show revision history graph | `-r`, `-n`, `--no-graph`, `-p`, `--reversed`, `--count`, `-T` template | +| `jj metaedit -r REV` | Edit revision metadata (author, date, description) | `-r`, `--reset-author` | +| `jj new [REV]...` | Create a new empty change (child of given revision) | `-m`, `--no-edit`, `--insert-after`, `--insert-before` | +| `jj next` | Move working copy to the child revision | `-e` edit the destination | +| `jj op ` | Operation log commands | Subcommands: log, restore, undo, discard, integrate | +| `jj parallelize -r REVS` | Make sibling revisions into parallel branches | `-r` | +| `jj prev` | Move working copy to the parent revision | `-e` edit the destination | +| `jj rebase -r REV -o DEST` | Move revisions to different parent(s) | `-r`, `-s`, `-b`, `-o/\!--onto`, `--insert-after`, `--insert-before`, `--skip-emptied` | +| `jj redo` | Redo the last undone operation | — | +| `jj resolve PATH...` | Resolve merge conflicts | `--list` | +| `jj restore [PATH]...` | Restore file contents (undo changes to a path or revision) | `--from`, `--into`, `--changes-in`, `-i` | +| `jj revert [-r REV]` | Apply reverse of the given revision(s) | `-r` (same as `jj restore --changes-in REV`) | +| `jj root` | Show workspace root directory | — | +| `jj show [-r REV]` | Show revision description and its diff | `-r` | +| `jj sign -r REV` | Cryptographically sign a revision | `-r` | +| `jj simplify-parents -r REV` | Remove redundant parent edges | `-r` | +| `jj sparse ` | Manage sparse checkout patterns | Subcommands: set, edit, list, clear, reset | +| `jj split [-r REV]` | Split a revision into two | `-r`, `-i`, `-m`, `--parallel`, `--insert-after`, `--insert-before` | +| `jj squash [-f FROM -t INTO]` | Move changes between revisions | `-f` from, `-t` into, `-i`, `-k` keep-emptied, `-m`, `--insert-after` | +| `jj status` | Show working copy status (aliases: `st`) | — | +| `jj tag ` | Manage tags | Subcommands: list, set, delete | +| `jj undo` | Undo the last operation | `--undo` (un-undo) | +| `jj unsign -r REV` | Drop cryptographic signature from a revision | `-r` | +| `jj util ` | Infrequently used utilities | Subcommands: gc, completion, config-schema, etc. | +| `jj version` | Show version information | — | +| `jj workspace ` | Manage workspaces | Subcommands: root, list, add, forget, upgrade | diff --git a/.agents/skills/jj-vcs/references/core-concepts.md b/.agents/skills/jj-vcs/references/core-concepts.md new file mode 100644 index 0000000..07a02b4 --- /dev/null +++ b/.agents/skills/jj-vcs/references/core-concepts.md @@ -0,0 +1,95 @@ +# Core concepts + +Understanding these concepts is essential for using jj correctly. Read this when the user seems new to jj, or when you need to reason about jj behavior beyond simple commands. + +## Change IDs vs commit hashes + +Every revision in jj has two identifiers: + +- **Change ID** — A stable identifier (e.g., `abc12345`) that follows the revision across rebases, squashes, and splits. Use this when referring to a logical change over time. +- **Commit hash** — A hash of the commit content (like Git). Changes every time the diff changes. Use this when you need to reference exact content. + +Commands that take revisions (almost all of them) accept change IDs, commit hashes, or revset expressions. Prefer change IDs for user-facing references since they're stable. + +## The working copy (`@`) + +The `@` symbol represents the working copy revision. Unlike Git's detached HEAD or branch-based model: + +- `@` is always a regular commit. It can have a description, parent(s), and children. +- When you edit files, those changes belong to `@`. +- `jj new` creates a new *empty* commit on top of `@` and makes that the new `@`. The old `@` becomes `@-` (parent of working copy). +- `jj edit REV` sets the working copy to revision REV. Edits go directly into that revision's diff. Use `jj new` instead unless you specifically need to amend an existing change. +- `jj status` shows the diff between `@` and its parent (`@-`). + +## Operation log + +Every jj command creates an **operation** in the operation log. This is jj's safety net: + +- `jj op log` shows the history of commands (like shell history but richer) +- `jj undo` creates a new operation that reverses the last one +- `jj op restore OP_ID` restores the repo to the state after a given operation +- `jj --at-op OP_ID ` runs a command as if the repo were at that operation (read-only inspection) + +Nothing is permanently lost unless you run `jj util gc` (garbage collection). The operation log is append-only. + +## Revsets + +Revsets are jj's query language for selecting revisions. They appear everywhere a command accepts revisions. Key patterns: + +| Expression | Meaning | +|---|---| +| `@` | The working copy revision | +| `main` | The revision pointed to by bookmark `main` | +| `main@origin` | The revision pointed to by `main` on the `origin` remote | +| `root()` | The root revision (virtual, all repos share it) | +| `all()` | Every revision in the repo | +| `mine()` | Revisions authored by the current user | +| `none()` | Empty set | +| `parents(REVSET)` | Parents of revisions in the set | +| `children(REVSET)` | Children of revisions in the set | +| `ancestors(REVSET)` | All ancestors (recursive parents) | +| `descendants(REVSET)` | All descendants (recursive children) | +| `::` | DAG range — `A::B` means "A and B and everything between them" | +| `..` | Reachable from B but not from A — `A..B` means "B and ancestors of B not also ancestors of jj" | +| `X \ Y` | Set difference | +| `X + Y` | Set union | +| `X & Y` | Set intersection | +| `empty()` | Revisions with no diff from their parent | +| `description(REGEX)` | Revisions whose description matches REGEX | +| `author("NAME")` | Revisions authored by NAME (partial match) | +| `bookmarks()` | Revisions that have bookmarks | +| `immutable_heads()` | The configured immutable set | +| `latest(N, REVSET)` | The latest N revisions in the set | +| `merged()` | Merge commits | + +**Practical examples:** +- `main..@` — revisions in `@`'s ancestors that aren't in main (what you changed since main) +- `ancestors(@) & ~immutable_heads()` — everything you can safely rewrite +- `@-` — the parent of the working copy (one commit back) +- `@--` — grandparent of the working copy +- `description("fix.*")` — revisions with descriptions starting with "fix" +- `empty() & ~@` — revisions that are empty but not the working copy (candidates for abandonment) + +## Bookmarks + +Bookmarks are labels attached to revisions. They serve the same conceptual role as Git branches but behave differently: + +- Bookmarks can coexist at the same revision (no conflict) +- Moving a bookmark doesn't affect the revision it points to — the revision keeps its change ID +- Tracking a remote bookmark (`jj bookmark track NAME --remote origin`) creates a local bookmark that follows the remote's updates +- Git branches are represented as bookmarks with `@remote` suffixes (e.g., `main@origin`) +- `jj bookmark list` shows all bookmarks; the output format is `BOOKMARK: CHANGE_ID commit_hash` + +## The immutable set + +By default, jj prevents rewriting commits that are ancestors of any remote-tracking bookmark. This is configured by `revsets.immutable_heads` in the config (typically `immutable_heads() & ~@` plus `bookmarks()@remote`). Use `--ignore-immutable` to bypass this check (e.g., `jj rebase --ignore-immutable -r OLD_REV`). + +## Global flags + +These work with any jj command: + +- `--at-op OP` — run as if repo were at a past operation (read-only) +- `--ignore-immutable` — allow rewriting protected commits +- `--ignore-working-copy` — skip snapshotting the working copy (faster, but may show stale state) +- `-R PATH` — operate on a different repository +- `--config NAME=VAL` — set config options inline (TOML syntax) diff --git a/.agents/skills/jj-vcs/references/daily-work.md b/.agents/skills/jj-vcs/references/daily-work.md new file mode 100644 index 0000000..fa6bb10 --- /dev/null +++ b/.agents/skills/jj-vcs/references/daily-work.md @@ -0,0 +1,117 @@ +# Daily work + +Commands and patterns for the core edit/describe/log cycle. + +## jj status + +Shows the diff between the working copy (`@`) and its parent. This is the first thing to run when a user asks "what's going on?" or "what have I changed?". + +Key alias: `jj st` (the most common form used in practice). + +Output shows: +- Which revision you're on (change ID, commit hash, bookmark) +- Whether `@` is empty or has changes +- The diff (added/modified/deleted files) +- Any conflicts + +## jj new + +Creates a new empty revision as a child of the given revision (default: `@`) and makes it the working copy. This is the closest jj equivalent to starting a new branch of work. + +``` +jj new # new child of @, empty, becomes new @ +jj new REV # new child of REV +jj new A B # new merge revision with parents A and B +``` + +- `--insert-after REV` — insert the new revision after REV (between REV and its children) +- `--insert-before REV` — insert before REV (between REV and its parents) +- `-m "msg"` — set description immediately +- `--no-edit` — create the revision but don't switch working copy to it + +## jj describe + +Sets or edits the description (commit message) of a revision. + +``` +jj describe # opens editor to edit @'s description +jj describe -m "msg" # set description of @ inline +jj describe -r REV # describe a specific revision +``` + +- `-m "msg"` — set description from command line (no editor) +- `--stdin` — read description from stdin +- `-r REV` — describe a different revision (default: `@`) + +**Important:** A revision needs a description before it can be pushed. Always use `jj describe` (not `jj commit`) when the user says "write a commit message." + +## jj commit + +Combines `jj describe -m "msg"` followed by `jj new`. Records the current change's description and immediately starts a fresh empty revision on top. + +``` +jj commit -m "feat: add user auth" +``` + +This is the jj equivalent of git's `commit` but note: there's no staging step. Any changes to tracked files are included. + +## jj log + +Shows the revision graph. This is your primary tool for understanding history. + +``` +jj log # default view (configurable via revsets.log) +jj log -r "main..@" # changes you've made since main +jj log -r "author(me)" # your changes +jj log -r "all()" # everything +jj log -r REV # log starting from REV +``` + +Key flags: +- `-r REVSET` — which revisions to show (revset) +- `-n N` / `--limit N` — limit to N results +- `--no-graph` — flat list (good for scripting) +- `--reversed` — oldest first +- `-p` / `--patch` — show the diff for each revision +- `-T TEMPLATE` — custom template +- `--count` — just print the count + +## jj diff + +Shows the diff of a revision. Unlike `jj log -p`, this focuses purely on the content diff. + +``` +jj diff # diff of @ vs its parent +jj diff -r REV # diff of REV vs its parent +jj diff --from A --to B # diff between two specific revisions +``` + +Key flags: +- `--git` — git-format diff (good for piping or review) +- `-s` / `--summary` — just show which files changed +- `--stat` — histogram of changes +- `--name-only` — just file paths +- `--color-words` — word-level diff +- `--context N` — lines of context + +## jj edit + +Sets the working copy to an existing revision. Edits go directly into that revision's diff — this rewrites history. + +``` +jj edit REV # switch working copy to REV +``` + +Prefer `jj new REV` over `jj edit REV` in most cases: `jj new` creates a child so you can't accidentally rewrite the parent. Use `jj edit` when you intentionally want to amend an existing change (e.g., you forgot to include a file). + +## jj file + +File-level operations. + +``` +jj file list [-r REV] # list tracked files in REV +jj file show -r REV PATH # show file contents from REV +jj file chmod MODE PATH # change file mode (e.g., +x, -x) +jj file untrack PATH # stop tracking a file (adds to .gitignore automatically) +jj file track PATH # start tracking a file (reverses untrack) +``` diff --git a/.agents/skills/jj-vcs/references/history-rewriting.md b/.agents/skills/jj-vcs/references/history-rewriting.md new file mode 100644 index 0000000..681a420 --- /dev/null +++ b/.agents/skills/jj-vcs/references/history-rewriting.md @@ -0,0 +1,130 @@ +# History rewriting + +Commands for restructuring the commit graph. jj's operation log makes history rewriting safe — nothing is permanently lost. + +## jj rebase + +Move revisions to different parent(s). The most fundamental history-rewriting command. + +``` +jj rebase -r REV -o DEST # rebase single revision REV onto DEST +jj rebase -b REV -o DEST # rebase REV and all its descendants onto DEST +jj rebase -r REV --insert-after ANCHOR # reorder: put REV after ANCHOR +jj rebase -r REV --insert-before ANCHOR # reorder: put REV before ANCHOR +``` + +Moving `-r` vs `-b`: +- `-r REV` — rebase only REV; its descendants follow because jj automatically rebases them on top +- `-b REV` — rebase the entire branch (REV and all its descendants) to a new location. Equivalent to `-s roots(dest..REV)` + +Note: jj automatically rebases descendants so you don't need to manually restack after a rebase. However, this can create duplicate commits if the destination already has commits with the same change IDs. `--keep-divergent` controls this behavior. + +## jj squash + +Move changes from one revision into another. The most common pattern is moving `@`'s changes into its parent (the jj equivalent of amending). + +``` +jj squash # squash @ into its parent +jj squash -f SOURCE -t DEST # move SOURCE's changes into DEST +``` + +- Without flags: squash `@` into `@-` (the parent). After this, `@` becomes empty and `@-` now includes the changes. +- `-f` / `--from`: which revision to take changes from (default: `@`) +- `-t` / `--into`: which revision to put changes into (default: `@`) +- `-i` / `--interactive`: choose which parts of the diff to squash +- `-k` / `--keep-emptied`: don't abandon the source revision after squashing +- `-m "msg"`: set description on the result + +The `-o` (experimental), `--insert-after`, and `--insert-before` flags control where the resulting revision goes in the graph, similar to `jj rebase`. + +## jj split + +Split one revision into two. Changes in the original revision are partitioned into two new revisions. + +``` +jj split -r REV # interactively choose which files go into the first split +jj split FILE... # put specified files into the new first revision +``` + +- `-r REV`: the revision to split (default: `@`) +- `-i`: force interactive mode (choose which hunks go where) +- `-m "msg"`: description for the new (first) revision +- `--parallel`: split into two parallel revisions (same parent) instead of parent-child +- `--insert-after` / `--insert-before` / `-o`: control where the new revision goes + +## jj abandon + +Drop a revision. The revision is removed from the graph and its descendants are rebased onto its parent(s). + +``` +jj abandon -r REV # abandon a specific revision +jj abandon # abandon @ (only works if @ is empty) +``` + +Common use: clean up empty revisions after squash/restructuring. `jj abandon -r empty()` is a batch cleanup pattern. + +## jj absorb + +Automatically moves changes from child revisions into the parent revisions they logically belong to. It detects which changes should have been made in which parent by analyzing the diff. + +``` +jj absorb +``` + +Runs on `@` by default. Useful when you make a fix that should belong to a lower commit in your stack — instead of manually squashing, `jj absorb` figures out where each hunk belongs. + +## jj parallelize + +Make sibling revisions into a linear chain or vice versa. + +``` +jj parallelize -r REVS... +``` + +Takes a set of revisions and makes them siblings (all children of the same parent), rebasing their descendants as needed. + +## jj arrange + +Interactive graph rearrangement. Opens a diff editor where you can drag and drop revisions to reorder them. More visual than command-line rebase operations. + +``` +jj arrange +``` + +## jj diffedit + +Touch up the content changes in a revision. Opens an editor showing the revision's diff and lets you modify it directly. + +``` +jj diffedit -r REV +``` + +Use this when you need to change what a specific revision does, rather than adding a fix on top. + +## jj metaedit + +Modify a revision's metadata (author, author date, committer, description) without changing its content. + +``` +jj metaedit -r REV +``` + +## jj restack + +This is not a real command — jj restacks automatically. You should never need to manually restack after rebase, squash, etc. If a rebase leaves empty commits, `jj abandon` them. + +## jj squash/absorb vs jj squash + +- Use `jj squash` when you want to explicitly move changes between revisions +- Use `jj absorb` when you want jj to figure out where changes belong automatically + +## jj squash vs git commit --amend + +- `jj squash` without arguments is jj's equivalent of `git commit --amend`: it takes `@`'s changes and merges them into `@-`, leaving `@` empty +- Unlike git, the old `@`'s change ID still exists (as an empty revision) — you can `jj abandon` it afterwards + +## jj split + jj rebase + +A common pattern: split a large revision into two, then rebase one of them to a different parent: +1. `jj split -r BIG_COMMIT` — split into two +2. `jj rebase -r NEW_REV -o DIFFERENT_PARENT` — move the new revision elsewhere diff --git a/.agents/skills/jj-vcs/references/recovery.md b/.agents/skills/jj-vcs/references/recovery.md new file mode 100644 index 0000000..072cbbc --- /dev/null +++ b/.agents/skills/jj-vcs/references/recovery.md @@ -0,0 +1,119 @@ +# Recovery + +Commands for undoing mistakes, resolving conflicts, and restoring lost work. + +## jj undo + +Undoes the most recent operation. This is the first recovery command to reach for. + +``` +jj undo # undo last operation +jj undo --undo # undo the undo (same as jj redo) +``` + +Any operation can be undone — commit, rebase, push, etc. The undo itself creates a new operation, so it can also be undone. + +## jj redo + +Redo the most recently undone operation. + +``` +jj redo # redo last undo +``` + +## jj op log / jj operation + +View the operation log — the history of all jj commands run in this repo. This is jj's equivalent of shell history but tied to repo state. + +``` +jj op log # show all operations +jj op log -n 20 # show last 20 operations +``` + +Each operation has an ID (hash). The most recent operation is shown at the top with `@`. The snapshot of the working copy is also an operation. + +## jj op restore + +Restore the repo to a previous state by operation. Unlike `jj undo` (which only undoes the last operation), this can jump to any point in the operation log. + +``` +jj op restore OP_ID # restore repo to state after OP_ID +jj op restore --what undo # restore just the undo history (not working copy) +``` + +This is *not* a revert — it moves the entire repo state backward (or forward). Changes made after that operation will appear as divergent changes. Use `jj --at-op` for read-only inspection first. + +## jj restore (content restore) + +Restore file contents within a revision. This is NOT the same as `jj op restore`. + +``` +jj restore # restore all files in @ from its parent +jj restore PATH # restore specific files in @ from its parent +jj restore --from SOURCE # restore from a specific source revision +jj restore --changes-in REV # undo the changes introduced by REV (creates reverse diff on @) +``` + +- Without `--from`: restores from the parent of the target revision +- Without `--into`: restores into `@` +- `--changes-in REV` is the closest equivalent to `git revert REV` — it applies the reverse of REV's diff to `@` +- `--restore-descendants`: when rebasing descendants, preserve their content (not their diff) + +To "unstage" files (there's no real staging area in jj, but for git users who ask): use `jj restore PATH` to undo changes to specific files in `@`. + +## jj resolve + +Resolve merge conflicts. jj tracks conflicts natively (unlike git, which leaves conflict markers in files and lets you handle them). + +``` +jj resolve PATH... # resolve conflicts in specific files +jj resolve --list # list all unresolved conflicts +``` + +When you run `jj resolve`, jj opens the external merge tool (configured in `merge-tools`). If no tool is configured, it falls back to leaving conflict markers in the file, which you can edit manually. + +After resolving conflicts manually (by editing the file), mark them as resolved with `jj resolve PATH`. + +## jj --at-op (read-only inspection) + +Run any jj command as if the repo were at a past operation. Read-only — useful for inspecting old state before deciding whether to restore. + +``` +jj --at-op OP_ID log # log from past state +jj --at-op OP_ID status # status from past state +jj --at-op OP_ID diff -r REV # diff from past state +``` + +## Divergent changes + +When the operation log has diverged (e.g., two concurrent operations), `jj status` will warn about divergent operations. This happens when you run jj commands from different terminals or after `jj op restore`. + +To resolve divergence: +1. `jj --at-op OP_ID status` for each divergent operation to understand the state +2. `jj op restore` to pick one side +3. Or use `jj new` to create a merge of the divergent states + +## Common recovery scenarios + +**"I rebased and lost changes"** +- `jj undo` — undoes the rebase +- If `jj undo` isn't enough: `jj op log` to find the pre-rebase operation, then `jj op restore OP_ID` + +**"I pushed the wrong thing"** +- You can't unpush (remote doesn't support it), but you can: + 1. Fix the local revision + 2. `jj bookmark move --to=FIXED BOOKMARK` + 3. `jj git push --force` or `jj git push` with a new commit + +**"I accidentally squashed the wrong files"** +- `jj undo` immediately +- If too late: use the operation log to find the pre-squash state + +**"I want to get old version of a file back"** +- `jj restore --from OLD_REV PATH` — restore PATH from OLD_REV into `@` +- Or: `jj file show -r OLD_REV PATH > PATH` to extract it as a file + +**"jj status shows conflicts"** +- `jj resolve --list` to see which files have conflicts +- Resolve them individually: `jj resolve PATH` +- After resolving all, `jj status` will clear diff --git a/.agents/skills/shadcn/SKILL.md b/.agents/skills/shadcn/SKILL.md new file mode 100644 index 0000000..1b4c414 --- /dev/null +++ b/.agents/skills/shadcn/SKILL.md @@ -0,0 +1,277 @@ +--- +name: shadcn +description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset". +user-invocable: false +allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *) +--- + +# shadcn/ui + +A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI. + +> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project. + +## Current Project Context + +```json +!`npx shadcn@latest info --json` +``` + +The JSON above contains the project config and installed components. Use `npx shadcn@latest docs ` to get documentation and example URLs for any component. + +## Principles + +1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too. +2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table. +3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc. +4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`. + +## Critical Rules + +These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs. + +### Styling & Tailwind → [styling.md](./rules/styling.md) + +- **`className` for layout, not styling.** Never override component colors or typography. +- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`. +- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`. +- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`. +- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`). +- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries. +- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking. + +### Forms & Inputs → [forms.md](./rules/forms.md) + +- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout. +- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`. +- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.** +- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state. +- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading. +- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control. + +### Component Structure → [composition.md](./rules/composition.md) + +- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`. +- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md) +- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden. +- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`. +- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`. +- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`. +- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load. + +### Use Components, Not Custom Markup → [composition.md](./rules/composition.md) + +- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`. +- **Callouts use `Alert`.** Don't build custom styled divs. +- **Empty states use `Empty`.** Don't build custom empty state markup. +- **Toast follows the project base.** Use `toast` from the `toast` component for + Base UI projects. Use `toast()` from `sonner` for Radix and React Aria + projects. +- **Use `Separator`** instead of `
` or `
`. +- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs. +- **Use `Badge`** instead of custom styled spans. + +### Icons → [icons.md](./rules/icons.md) + +- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon. +- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`. +- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup. + +### Chat & Messaging → [chat.md](./rules/chat.md) + +- **Chat UI composes the chat primitives.** Conversations use `MessageScroller`, rows use `Message`, surfaces use `Bubble`. Never hand-rolled bubble `div`s or a raw scroll container. +- **`MessageScroller` owns scroll behavior.** Streaming follow, anchoring, and jump-to-latest (`MessageScrollerButton`) are built in. Don't write a `useStickToBottom`/`ResizeObserver` hook. +- **Attachments use `Attachment`; system notes and dividers use `Marker`.** Not `Item` cards or `Separator` + a label. + +### CLI + +- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode `, `preset url `, or `preset open `. For project-aware preset detection, use `npx shadcn@latest preset resolve`. +- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply ` for existing projects, or `npx shadcn@latest init --preset ` when initializing. + +## Key Patterns + +These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above. + +```tsx +// Form layout: FieldGroup + Field, not div + Label. + + + Email + + + + +// Validation: data-invalid on Field, aria-invalid on the control. + + Email + + Invalid email. + + +// Icons in buttons: data-icon, no sizing classes. + + +// Spacing: gap-*, not space-y-*. +
// correct +
// wrong + +// Equal dimensions: size-*, not w-* h-*. + // correct + // wrong + +// Status colors: Badge variants or semantic tokens, not raw colors. ++20.1% // correct ++20.1% // wrong +``` + +## Component Selection + +| Need | Use | +| -------------------------- | --------------------------------------------------------------------------------------------------- | +| Button/action | `Button` with appropriate variant | +| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` | +| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem` | +| Data display | `Table`, `Card`, `Badge`, `Avatar` | +| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` | +| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) | +| Feedback | `toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner` | +| Command palette | `Command` inside `Dialog` | +| Charts | `Chart` (wraps Recharts) | +| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` | +| Empty states | `Empty` | +| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` | +| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` | +| Chat / conversation UI | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker` | + +## Key Fields + +The injected project context contains these key fields: + +- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode. +- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive. +- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`. +- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one. +- **`style`** → component visual treatment (e.g. `nova`, `vega`). +- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props. +- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`. +- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc. +- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA). +- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`). +- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information. + +See [cli.md — `info` command](./cli.md) for the full field reference. + +## Component Docs, Examples, and Usage + +Run `npx shadcn@latest docs ` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content. + +```bash +npx shadcn@latest docs button dialog select +``` + +**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing. + +## Workflow + +1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh. +2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed. +3. **Find components** — `npx shadcn@latest search`. +4. **Get docs and examples** — run `npx shadcn@latest docs ` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`. +5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below). +6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project. +7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on. +8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user. +9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**? + - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values. + - **Inspect incoming preset**: `npx shadcn@latest preset decode `. Use `preset url ` or `preset open ` to share or open the preset builder. + - **Overwrite**: `npx shadcn@latest apply `. Overwrites detected components, fonts, and CSS variables. + - **Partial**: `npx shadcn@latest apply --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms. + - **Merge**: `npx shadcn@latest init --preset --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually. + - **Skip**: `npx shadcn@latest init --preset --force --no-reinstall`. Only updates config and CSS, leaves components as-is. + - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base ` explicitly — preset codes do not encode the base. + +## Updating Components + +When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.** + +1. Run `npx shadcn@latest add --dry-run` to see all files that would be affected. +2. For each file, run `npx shadcn@latest add --diff ` to see what changed upstream vs local. +3. Decide per file based on the diff: + - No local changes → safe to overwrite. + - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications. + - User says "just update everything" → use `--overwrite`, but confirm first. +4. **Never use `--overwrite` without the user's explicit approval.** + +## Quick Reference + +```bash +# Create a new project. +npx shadcn@latest init --name my-app --preset base-nova +npx shadcn@latest init --name my-app --preset a2r6bw --template vite + +# Create a monorepo project. +npx shadcn@latest init --name my-app --preset base-nova --monorepo +npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo + +# Initialize existing project. +npx shadcn@latest init --preset base-nova +npx shadcn@latest init --defaults # shortcut: --template=next --preset=nova (base style implied) + +# Apply a preset to an existing project. +npx shadcn@latest apply a2r6bw +npx shadcn@latest apply a2r6bw --only theme +npx shadcn@latest apply a2r6bw --only font +npx shadcn@latest apply a2r6bw --only theme,font + +# Inspect preset codes and project preset state. +npx shadcn@latest preset decode a2r6bw +npx shadcn@latest preset url a2r6bw +npx shadcn@latest preset open a2r6bw +npx shadcn@latest preset resolve +npx shadcn@latest preset resolve --json + +# Add components. +npx shadcn@latest add button card dialog +npx shadcn@latest add @magicui/shimmer-button +npx shadcn@latest add owner/repo/item +npx shadcn@latest add --all + +# Preview changes before adding/updating. +npx shadcn@latest add button --dry-run +npx shadcn@latest add button --diff button.tsx +npx shadcn@latest add @acme/form --view button.tsx +npx shadcn@latest add owner/repo/item --dry-run + +# Search registries. +npx shadcn@latest search @shadcn -q "sidebar" +npx shadcn@latest search @tailark -q "stats" +npx shadcn@latest search owner/repo -q "login" +npx shadcn@latest search # all configured registries +npx shadcn@latest search @shadcn -q "menu" -t ui # filter by item type + +# Get component docs and example URLs. +npx shadcn@latest docs button dialog select + +# View registry item details (for items not yet installed). +npx shadcn@latest view @shadcn/button +npx shadcn@latest view owner/repo/item +``` + +**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma` +**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo) +**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw` or `b0`), from [ui.shadcn.com](https://ui.shadcn.com). + +## Detailed References + +- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states +- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading +- [rules/chat.md](./rules/chat.md) — MessageScroller, Message, Bubble, Attachment, Marker; streaming, anchoring, jump-to-latest +- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects +- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index +- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion +- [cli.md](./cli.md) — Commands, flags, presets, templates +- [registry.md](./registry.md) — Authoring source registries, `include`, item definitions, dependencies, GitHub registry rules +- [customization.md](./customization.md) — Theming, CSS variables, extending components diff --git a/.agents/skills/shadcn/agents/openai.yml b/.agents/skills/shadcn/agents/openai.yml new file mode 100644 index 0000000..ab636da --- /dev/null +++ b/.agents/skills/shadcn/agents/openai.yml @@ -0,0 +1,5 @@ +interface: + display_name: "shadcn/ui" + short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI." + icon_small: "./assets/shadcn-small.png" + icon_large: "./assets/shadcn.png" diff --git a/.agents/skills/shadcn/assets/shadcn-small.png b/.agents/skills/shadcn/assets/shadcn-small.png new file mode 100644 index 0000000000000000000000000000000000000000..547154b97f2298335159c23eec1dac0d147a1246 GIT binary patch literal 1049 zcmeAS@N?(olHy`uVBq!ia0y~yU=RRd4mJh`2Kmqb6B!s7SkfJR9T^xl_H+M9WMyDr zP)PO&@?~JCQe$9fXklRZ#lXPO@PdJ%)PRBERRRNp)eHs(@q#(K0&N%=7+O*zJkxxA z8MGJ}7&sVM8HE^_85kHC85kKD7^N6MrZF-wFnBRa!`VTM8c;P%3=Hj=3@l*v3=B~W z5a0pjLulp&j8N5#3=9jH;Hm`{FeBI?jmPt4J~A*ca29w(7Bet#3xhBt!>lsd^Q;1t47vHWgMCxdpkYC5Z|ZxjA{oRu#5NU=>z*#a19; zeI*63l9Fs&r3l{u1?T*tR0T6V13d#JJ1zwU1)HLjG^-#NH>mcalr&qVjFOT9D}DX) z@^Za$W4-*MbbUihOG|wNBYh(y-J+B<-Qvo;lEez#ykcdDAuw}XQj3#|G7CyF^Yauy z<|ZcPmzLNnDS<3ffB}d*OES|CHsuvVy_KAws}GXVH`FuGhno#D9wchzUzC}eSCR-a z-_FnmtP({GYLAUR$Z{mdKzs@o4RUd_ zb;v=WN6NOMljVy-Q&Xo?({c`}{Vspb-(9?@u4B1E(@!SFy}@%=-fX$+uv~rax>xh+ zD&{@!?X8hsDW&x6&ZL_;YTZW{y(+Q#AiQ{g58JiFjOXN6M?2h@c6#aNuT{2&PVp>d z38`wH+i!fX53 zx?M^y_Omn}bdbGd5?X5^vqXdIVDbL@SKAaOpFARHp{%U#xyWqE-x@p78oT*(@7LH} z-@G?1Huv7liQj+kWsYAT&hA!nqQGLwTC)Qutj(2;-(Jj6=|AqQH=Vmts7>*lDdXy1 zYvbIehs*|YajG0m@l4+=PaB1ANV~;io_qP_mUAq^Z5+Gr`bA&uIkY8l_uV|bQsaqL z*LEe^I2KsVU7~Y3Z1ulxnd2LqYVWtNvpL-KGfdfv3L6 zn$Nh%AeYSM`7LUV@BhQc cIhgwE8BD4xt6i`E`V30(p00i_>zopr0BcoQSpWb4 literal 0 HcmV?d00001 diff --git a/.agents/skills/shadcn/assets/shadcn.png b/.agents/skills/shadcn/assets/shadcn.png new file mode 100644 index 0000000000000000000000000000000000000000..b7b6814acc25073e5f48099b1fd3f70c47bfb1c3 GIT binary patch literal 3852 zcmeAS@N?(olHy`uVBq!ia0y~yU`PRB4mJh`hJr^^Ll_tsSkfJR9T^xl_H+M9WMyDr zP)PO&@?~JCQe$9fXklRZ#lXPO@PdJ%)PRBERRRNp)eHs(@q#(K0&N%=7+O*zJkxxA z8MGJ}7&sVM8HE^_85kHC85kKD7^N6MrZF-wFnBRa!`VTM8c;P%3=Hj=3@l*v3=B~W z5a0pjLulp&j8N5#3=9jH;Hpy=FeBI?jdvP1J25aYa29w(7Bet#3xhBt!>lsd^Q;1t47vHWgMCxdpkYC5Z|ZxjA{oRu#5NU=>z*#a19; zeI*63l9Fs&r3l{u1?T*tR0T6V13d#JJ1zwU1)HLjG^-#NH>mcalr&qVjFOT9D}DX) z@^Za$W4-*MbbUihOG|wNBYh(y-J+B<-Qvo;lEez#ykcdDAuw}XQj3#|G7CyF^Yauy z<|ZcPmzLNnDS<3ffB}d*OES|CHsuvVy_KAws}GXVH`FuGhno#D9wchzUzC}eSCR-a z-_FnmtP({GYLAUR$Z{mdKzs@o4RUd_{b{~P!z*7}#^K-norUULO$wjtmETE;D|PKE zdf^|wlH(G0biu=rS55^_rh83w{$?9k`swbeQ#Dh6#<@K^9bTyz=i-)j>}{3|N!d}=p`*2Z%>iOTkr$l=9u5A8UFym08#Y%-mEOL%MO773q3}5^Z z=-t0^0du?N#GXU;HxyZZWMwyIH%wq&&yaptE`TRcRj0%A(#~TN2ZfI)vr2a`ESU0a z$`@9Vw_nv~Mkr5ut8AUZ-JmF>(YET}ft#;<4$PX?v~!*~`+r$!r5m2l^R&A7S936A zOE5l>|KY$o&H0};=SKsH*Wyi{v5MaW6rL$O(`Wdv?y10hT8UMX$>|i+nZ~~bo@;;n z2nu6h5Bw?p@yVv$M_5-QJ#mxuNk!^2>X(d2VsN&Ds{Lcqk^? z*|~Xl!NWrbUeB>EUuT_r%Vcx^@!Lmu#28bX{W3%!AMY=p5Vxn|p-$YM8#nh>Z{J+? zHS77;*VoVWN}JCqetu3e=h>N=kN4F4yu_2Zt=2o?{DjpjZdZN#(kZOIYjgT}v-_W~ ztPFm)yZk-N>q#dzJiWK8^mOe0y1kZe9-hpTf3e!F2%gx(DXg}G<;SC=-E!Rb_t%&2 zul@Z@X?e%j9cRy;ZR^ntUUow*^@D(uk(%$UCld=_UQ&IO*YUw@2}97nnx9Fl^6u@) z?3iI+zwhMDFoBn$*LeAyI38SC8GM(OTTCLrRPvV6pCt*uFE97c%g$bH$$u?W^~J*H z#{Z^%dmY}wBYdsve8I6E$;UR;-_8gc%~>10eU`p%Mf*AP0=<+kFD{;2<~!S`^3#)( zYR~O9PrTrMSJ=sDNw{_L@xD?kD=VeR506VccW&c9&eSfu@%pB@uY0d*ofL4-(Ruvy z^K;S3ihcJgKQQ!1o%H$Te`cvFkLc-5iVGi0mOL}%lzeteQ1s|W$q(XD`|AE?naSH$ zrQC8}ks~?zPm>%Q&&h_*M}4G^yB0o}#W6+jpOeF>h0g6h)}No9HMT5miFFqJ`qh=A z(aHar&0;AdhZ7eUyYq5-PuJV(%XVwMypso;Q}j9URf^0DKYVTcZb^ISr?{VoT9dP z<;s(?RwWs;Tmr)FI29!&mPvHol32Dvoi%-4yc0)I(89IbdO}x+NhYjNc2)Z1$!?+E8GxoH?KIbi(g5#!9O4b}b4g|Gsxgdr&pw(qy|=Cp&l|Jl_gC zO?YD0vh~6=t1O28TWT#1NB3TCH`UN}T&Vj@QnGd17jehRw?a-vuMD>EDm9gE_3Thn z?hK87YplhY+s-TPb|B~ZR(Fn*2MnfuS)%Wi;r;i6dbgNvQTUpOheYtxdzn__D{BB+B?mdd#{ySAoyAmI*w!%YUsn&dl0{dk(*YMvAWhx!r;pJME2tod3;^ugD3Lx zb-%yAzdSlBibu1D?QqG_73bRoni{QZ{}_4RJ^x_xtEUbN>Rx@D{7~I7|8kPUnSHgt zc@#N%PrvNms9)>E;kK2380^8cm?6!Qyl z+`{9__FSHG5@XUEK_{b4RUN&*ByAq-&N}^}S#F!G%duNqvwhe5&ETnS5$K8H$aU|L zNIY;k<;Yjb4LyHJmEx!I}OkCe<&HO#OV;j$; ziH9C9Jt^cgA*W@V%;uGc{aLo{)X&J}65i>h)4aKG9m9kV3V%7TsJe3;+#q^u)87sH zz6%nj+L*0O?6PZq+ZOB0^!22`A?~xU6wM|z{+9GSW4z`3f>afTGLieiwu&l;%QC!e z>k=a3&lYj~Y5yiEv+RYj$By{zt#4m(C`y>supL~`w?O}Vt(jA_Td?LNM($O80(12B z|9rZ)YI2B)=u<^ACf50ZCs*k%*2 zMYF;d-RIs~$}P^U_m7l)dg96deZ|650m){SExz*vW+p%YLmyd{WJoVs7jL>g*gaUYZQDs9r`He8_w&o!&cVFFm&K z;&T7_eJP5LDK0xNyC=By$-Fc(Gn1NIA+FStJFAz`uIWUA$ojfUmas#v zHh1FN9>})VP2gx#Q$A&|RDaq{A#|TwdX9d76UeSk+Pr6}tkzss6ag7+__*RRcg(kH;+6%-)mo`3Ij zpHatw+p8zOPTrueKgrwa6H}h*_0H)ZXWK8DBopYVcvHdQjkTkP`+L(T*&EKXSwu&5 z{^b_9^!e2PdHZ9xF5Qr^-G)i!Nxi}o`=|Z7-w5`hzofzrD5b=2aF2(u?Bel{sl^JD~ **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Check `packageManager` from project context to choose the right one. Examples below use `npx shadcn@latest` but substitute the correct runner for the project. + +> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager from the project's lockfile; there is no `--package-manager` flag. + +## Contents + +- Commands: init, apply, add (dry-run, smart merge), search, view, docs, info, build +- Templates: next, vite, start, react-router, astro +- Presets: named, code, URL formats and fields +- Switching presets + +--- + +## Commands + +### `init` — Initialize or create a project + +```bash +npx shadcn@latest init [components...] [options] +``` + +Initializes shadcn/ui in an existing project or creates a new project (when `--name` is provided). Optionally installs components in the same step. + +| Flag | Short | Description | Default | +| ----------------------- | ----- | --------------------------------------------------------- | ------- | +| `--template