gpustack-ui/AGENTS.md

Agent Instructions

This project keeps a single source of truth for agent/contributor conventions in CLAUDE.md. Read CLAUDE.md and follow it.

@CLAUDE.md

Downstream fork workflow

This repo is a downstream fork that customizes the product appearance on top of upstream gpustack/gpustack-ui. The mirror chain is:

upstream  https://github.com/gpustack/gpustack-ui.git
   |  (fetch)
origin    ssh://git@192.168.0.23:11022/root/gpustack-ui.git   (private registry, also https://git.digiman.live)

Goal

Track upstream releases. When upstream changes, we pull it in, then apply our own appearance/customization changes on a dedicated branch so we keep our look-and-feel on top of the latest upstream product.

Branch naming

Customization work lives on v<upstream-version>-lofyer branches (e.g. v2.2.0-lofyer). Each time upstream ships a new version we want to follow, create a new v<version>-lofyer branch from the corresponding upstream tag/branch and re-apply (or rebase) our customizations onto it.

Syncing from upstream

scripts/sync-github mirrors upstream into the private origin (full mirror, force push of all branches + tags). It auto-configures the upstream remote on first run.

# preview only, no push
DRY_RUN=1 ./scripts/sync-github

# real sync (force-pushes every upstream branch + tag to origin)
./scripts/sync-github

# also delete origin branches that no longer exist upstream (true mirror, destructive)
PRUNE_BRANCHES=1 ./scripts/sync-github

Env knobs: UPSTREAM_URL, ORIGIN_REMOTE, UPSTREAM_REMOTE, PRUNE_BRANCHES, DRY_RUN. After syncing, branch a fresh v<version>-lofyer off the updated upstream ref and apply the appearance changes there.

Re-applying brand customizations

scripts/rebrand swaps the standalone brand word GPUStack for our brand (MesaStack) across user-facing text. It is the first appearance change to re-apply on every new v<version>-lofyer branch.

# preview hits, no writes
DRY_RUN=1 ./scripts/rebrand

# apply (default GPUStack -> MesaStack)
./scripts/rebrand

# custom brand words
FROM=GPUStack TO=AcmeStack ./scripts/rebrand

It deliberately does not touch functional references — lowercase gpustack (npm pkg / URLs / paths / k8s namespace), ALL-CAPS GPUSTACK_* constants, JS identifiers like getGPUStackPlugin, and X-* HTTP headers — and carries a line-level skip list for backend-contract strings matched at runtime (see SKIP_LINE_PATTERNS in the script). Always review git diff afterwards. Logo images under src/assets/images/ are NOT changed by the script — replace those PNGs separately when new brand assets are available.