stackfit 0.0.0-stage → 0.1.1

package/starter/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env next to stackfit.json (it is gitignored). Never commit real values.
+
+# Optional: where this catalog lives, so stackfit works from any folder.
+# STACKFIT_CATALOG=~/code/my-skill-catalog
+
+# Optional: lets `stackfit refresh` read private GitHub repositories.
+# GITHUB_TOKEN=
+
+# Any NAME here can be used as {{env:NAME}} in commands/, rules/, and agents/, e.g.
+# REVIEWER_HANDLE=@your-handle

package/starter/README.md

@@ -0,0 +1,12 @@
+# My stackfit catalog
+
+Started from the stackfit starter. This folder is yours: keep it in a (private) Git repository.
+
+- `stackfit.json`: enabled skills and packs (which skills reach which repos).
+- `skill-sources.json`: where each vendored skill comes from, when you last reviewed it, and sync-time overrides.
+- `skills/`: the skills themselves. `stackfit refresh --all` vendors the upstream ones.
+- `rules/`, `commands/`, `agents/`: shared adapters rendered for Cursor and Claude Code.
+- `stackfit.local.json` (gitignored): where your projects live on each machine. Copy the example.
+- `.env` (gitignored): personal values for `{{env:NAME}}` placeholders. Copy `.env.example`.
+
+Add your own skills under `skills/<name>/SKILL.md`, list them in `stackfit.json` and a pack, set `kind: custom` in `skill-sources.json`, then `stackfit audit`.

package/starter/gitignore

@@ -0,0 +1,4 @@
+stackfit.local.json
+.env
+skills/.*.refresh/
+.DS_Store

package/starter/rules/defaults.mdc

@@ -0,0 +1,11 @@
+---
+description: Starter defaults for any repository (edit or replace with your own)
+alwaysApply: true
+---
+
+# Defaults
+
+- Follow the repository's own instructions (`AGENTS.md`, `CLAUDE.md`, contributing docs) over these.
+- Match existing conventions, package manager, and scripts before introducing new ones.
+- Keep changes focused on the request and say which checks you ran.
+- Ask before running anything that changes external systems.

package/starter/skill-sources.json

@@ -0,0 +1,315 @@
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/skill-sources.schema.json",
+  "schemaVersion": 2,
+  "skills": {
+    "animation-vocabulary": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/animation-vocabulary"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "apple-design": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/apple-design"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "baseline-ui": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/ibelick/ui-skills.git",
+        "path": "skills/baseline-ui"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "emil-design-eng": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/emil-design-eng"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "fixing-accessibility": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/ibelick/ui-skills.git",
+        "path": "skills/fixing-accessibility"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "fixing-motion-performance": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/ibelick/ui-skills.git",
+        "path": "skills/fixing-motion-performance"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "frontend-design": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/anthropics/skills.git",
+        "path": "skills/frontend-design"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "grilling": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/mattpocock/skills.git",
+        "path": "skills/productivity/grilling"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "improve": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/shadcn/improve.git",
+        "path": "skills/improve"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "improve-animations": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/improve-animations"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "interface-design": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/Dammyjay93/interface-design.git",
+        "path": ".claude/skills/interface-design"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "make-interfaces-feel-better": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/jakubkrehel/make-interfaces-feel-better.git",
+        "path": "skills/make-interfaces-feel-better"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "next-bundle-optimizer": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-bundle-optimizer"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "next-cache-components-adoption": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-cache-components-adoption"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-cache-components-optimizer": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-cache-components-optimizer"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-dev-loop": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-dev-loop"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "next-partial-prefetching-adoption": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-partial-prefetching-adoption"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-partial-prefetching-optimizer": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel/next.js.git",
+        "path": "skills/next-partial-prefetching-optimizer"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "next-server-security": {
+      "kind": "custom",
+      "reviewed": "2026-10-26",
+      "note": "First-party stackfit starter skill."
+    },
+    "playwright-e2e-testing": {
+      "kind": "custom",
+      "reviewed": "2026-10-26",
+      "note": "First-party stackfit starter skill."
+    },
+    "react-doctor": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/millionco/react-doctor.git",
+        "path": "skills/react-doctor"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "review-animations": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/emilkowalski/skills.git",
+        "path": "skills/review-animations"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "shadcn": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/shadcn-ui/ui.git",
+        "path": "skills/shadcn"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "evals/evals.json"
+        ]
+      }
+    },
+    "stackfit": {
+      "kind": "custom",
+      "reviewed": "2026-10-26",
+      "note": "First-party stackfit starter skill. Kept in sync with skills/stackfit in the stackfit repository."
+    },
+    "stripe-best-practices": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/stripe/ai.git",
+        "path": "skills/stripe-best-practices"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "stripe-projects": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/stripe/ai.git",
+        "path": "skills/stripe-projects"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "ui-ux-pro-max": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git",
+        "path": ".claude/skills/ui-ux-pro-max"
+      },
+      "reviewed": "2026-10-26"
+    },
+    "upgrade-stripe": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/stripe/ai.git",
+        "path": "skills/upgrade-stripe"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "vercel-composition-patterns": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/composition-patterns"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "AGENTS.md",
+          "README.md",
+          "metadata.json"
+        ]
+      }
+    },
+    "vercel-react-best-practices": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/react-best-practices"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "AGENTS.md",
+          "README.md",
+          "metadata.json"
+        ]
+      }
+    },
+    "vercel-react-view-transitions": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/react-view-transitions"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": [
+          "AGENTS.md",
+          "README.md",
+          "metadata.json"
+        ],
+        "frontmatter": {
+          "disable-model-invocation": true
+        }
+      }
+    },
+    "web-design-guidelines": {
+      "kind": "external",
+      "source": {
+        "repository": "https://github.com/vercel-labs/agent-skills.git",
+        "path": "skills/web-design-guidelines"
+      },
+      "reviewed": "2026-10-26",
+      "render": {
+        "exclude": []
+      }
+    }
+  }
+}

package/starter/skills/next-server-security/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: next-server-security
+description: Next.js App Router server-side security - Server Actions as public endpoints, data access layer and DTOs, authz in proxy.ts vs at the data, Cache Components with user data, route handler CSRF, secrets and client-boundary leaks. Use when writing or reviewing Server Actions, route.ts, proxy/middleware, auth, data fetching, or caching of user-specific data.
+---
+
+# Next.js server security
+
+Next.js-specific failure modes that generic OWASP checklists miss. For the general OWASP pass, also use `owasp-security-check`. Canonical reference: https://nextjs.org/docs/app/guides/data-security.
+
+## Entry points (audit every one)
+
+| Entry point | Why it is public |
+| --- | --- |
+| Every exported function in a `"use server"` file that the app uses | Reachable by direct `POST`, not only through your UI. Encrypted action IDs and dead-code elimination reduce exposure; they are not access control. |
+| Inline `"use server"` functions in components | Same. A page-level auth check or `redirect()` does **not** protect the actions defined on that page. |
+| `route.ts` handlers | Plain HTTP. No built-in Origin check (unlike Server Actions). |
+| `proxy.ts` (Next 16; `middleware.ts` before) | Runs on matched requests only and is easy to bypass or mis-match. |
+| `[param]` segments, `searchParams`, headers, cookies | User input. |
+
+## Rules
+
+1. **Authorize at the data, not the route.** Put auth + authorization in a server-only data access layer (DAL): `import "server-only"`, a `cache()`d `getCurrentUser()`, then ownership checks before every read or write. `proxy.ts` is for optimistic redirects only. (CVE-2025-29927 let attackers skip middleware entirely with one header; apps that also checked in the DAL were safe.)
+2. **Every Server Action re-verifies.** Inside the action (or the DAL function it calls): authenticate, authorize the specific resource (IDOR), then mutate. Identity comes from the session, never from an argument, a hidden input, or a `.bind()` value.
+3. **Validate every action argument at runtime.** TypeScript types are erased; parse `FormData` and arguments with a schema (`z.safeParse` or the repo's validator) and return a typed error state instead of throwing raw errors.
+4. **Return DTOs, not records.** Action return values and props passed to Client Components are serialized to the browser (RSC payload / HTML). Select only the fields the UI needs. Never pass a full ORM row, user object, or session to a `"use client"` component. For defense in depth enable `experimental.taint` and use `experimental_taintObjectReference` / `experimental_taintUniqueValue` on secrets and raw records.
+5. **Secrets stay in the DAL.** Only server-only modules read `process.env` secrets and DB clients. Anything prefixed `NEXT_PUBLIC_` ships in the client bundle; never put keys there. Validate env at startup with a schema.
+6. **Cache Components and user data.**
+   - `"use cache"` output is shared across users and requests. `cookies()`, `headers()`, and `searchParams` are not allowed inside it; pass values in as arguments, and they become part of the cache key.
+   - A cached function that takes `userId` returns that user's data to *any* caller who passes the id: authorize **before** calling it, outside the cache boundary.
+   - Per-user personalized results: `"use cache: private"` (never stored in a server cache across requests) or no cache.
+   - After a mutation, invalidate what you changed: `updateTag(tag)` inside the action for read-your-own-writes, `revalidateTag(tag, "max")` for stale-while-revalidate, or `revalidatePath`.
+7. **Route handlers that mutate with cookie auth need CSRF protection.** Prefer Server Actions (Next checks `Origin` against `Host`). Otherwise verify the `Origin` header, require a non-simple content type or a CSRF token, and keep session cookies `SameSite=Lax` or stricter, `HttpOnly`, `Secure`. Behind a reverse proxy or alternate domain, set `serverActions.allowedOrigins` instead of disabling checks.
+8. **No mutations during render.** Logging out, writing, or revalidating from a page because of a `searchParams` value is a GET side effect. Use an action.
+9. **Redirects.** `redirect(searchParams.callbackUrl)` is an open redirect. Allow only same-origin relative paths (starts with `/`, not `//`).
+10. **Headers.** Static security headers go in `next.config` `headers()`. A nonce-based CSP is generated in `proxy.ts` and forces dynamic rendering for those routes; choose that trade-off deliberately.
+11. **Self-hosting multiple instances:** set a stable `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` so closure encryption works across instances. Encryption of closed-over values is not a reason to close over secrets.
+12. **Rate-limit expensive actions** (email, signup, AI calls, uploads) by user and IP.
+13. **Stay on the latest patch of your Next.js and React line.** RSC protocol bugs are critical (React2Shell, CVE-2025-55182, was unauthenticated RCE in Next 15.x/16.0 App Router apps). Check the repo's audit command and https://github.com/vercel/next.js/security/advisories when touching dependencies.
+
+## Server Action shape
+
+```ts
+// app/posts/actions.ts
+"use server";
+
+import { z } from "zod";
+import { updateTag } from "next/cache";
+import { deletePost } from "@/data/posts"; // server-only DAL: auth + ownership inside
+
+const Input = z.object({ postId: z.string().uuid() });
+
+export async function deletePostAction(_prev: unknown, formData: FormData) {
+  const parsed = Input.safeParse({ postId: formData.get("postId") });
+  if (!parsed.success) return { ok: false as const, error: "Invalid input" };
+  await deletePost(parsed.data.postId); // throws/returns forbidden if not the owner
+  updateTag(`posts`);
+  return { ok: true as const }; // minimal result, no DB row
+}
+```
+
+## Review output
+
+For each finding: entry point, file:line, what an attacker sends, impact, fix. Check the repo's actual auth library and DAL location first; do not assume paths.

package/starter/skills/playwright-e2e-testing/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: playwright-e2e-testing
+description: Write, fix, or review Playwright end-to-end tests, especially for Next.js apps - locators, auth via storageState, flaky waits, server-side fetch mocking, CI against a production build. Use for *.spec.ts / e2e/ / playwright.config changes or flaky browser tests. For unit and component tests use frontend-testing.
+---
+
+# Playwright E2E
+
+## Start from repository evidence
+
+1. Read `AGENTS.md` and the testing page linked from `docs/agent/index.md`.
+2. Read `playwright.config.*` (`testDir`, `projects`, `webServer`, `use.baseURL`, `testIdAttribute`), existing fixtures, page objects, and the auth setup project.
+3. Use the repo's package manager and scripts. Match existing file names, tags, and fixture style; do not introduce page objects or new fixtures if the suite does not use them.
+
+## Rules that prevent flaky tests
+
+- **Locators:** `getByRole` with `name`, then `getByLabel`, `getByText`, then `getByTestId` (respect a configured `testIdAttribute`). No CSS chains, XPath, or `.nth()` on unstable lists.
+- **Waiting:** only web-first assertions (`await expect(locator).toBeVisible()`, `toHaveURL`, `toHaveText`). Never `waitForTimeout`. Avoid `waitForLoadState("networkidle")`: Next.js prefetching and streaming keep the network busy. After navigation use `await expect(page).toHaveURL(...)` or `page.waitForURL`.
+- **Hydration:** a click on a server-rendered button before hydration can be lost. Assert the result of the interaction (a visible state change), not just that the click ran; if the suite has a hydration-ready helper, use it.
+- **Server Actions / forms:** assert on the UI that the action produces (toast, updated row, redirect URL), not on internal network calls.
+- **Isolation:** every test creates the data it needs (API or DB fixture) and can run in parallel and in any order. No dependence on a previous test.
+- **Auth:** log in once in a setup project and save `storageState` per role; tests reuse it. Do not log in through the UI in every test.
+
+## Next.js specifics
+
+- **CI runs against a production build** (`next build` then `next start`) through `webServer`; `next dev` compiles routes on first hit and causes timeouts. Use `reuseExistingServer: !process.env.CI` locally.
+- **`page.route` only intercepts browser requests.** Fetches made by Server Components, Route Handlers, or Server Actions run on the server and are not intercepted. Point the server at a test backend/database via env, or use the repo's existing server-side mocking (MSW in the server, or `next/experimental/testmode/playwright` if already set up).
+- **Instant navigation / static shell guards** under Cache Components: use the `next-cache-components-optimizer` skill (`@next/playwright` `instant()`).
+- **Visual snapshots:** fixed viewport, `animations: "disabled"`, mask dynamic regions (dates, avatars). Snapshots are per OS/browser; only update them on the platform CI uses.
+
+## Run and debug
+
+- Narrow first: `<pm> playwright test <file> -g "<title>" --project=chromium`.
+- Flaky: `--repeat-each=10 --workers=1`, then `--trace on` and `playwright show-trace`.
+- Report the exact command, pass/fail, and any test you could not run (for example missing env or seed data).

package/starter/skills/stackfit/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: stackfit
+description: Set up and run stackfit, the CLI that gives each repository only the agent skills, rules, commands, and subagents that fit its stack, from one catalog, for Claude Code, Cursor, and Codex. Use when skills load in repos that don't need them, when syncing skills or rules across several repos or machines, when asked which skills a repo should have or what they cost in context, or when stackfit is mentioned.
+license: MIT
+---
+
+# stackfit
+
+Every installed skill puts its name and description into every agent session. Install 30 skills globally and a Go service carries your React animation guides on every turn. stackfit keeps one **catalog** of skills and gives each repository only the **packs** its manifests call for, rendered natively for Claude Code, Cursor, and Codex.
+
+Docs: https://github.com/amin0075/stackfit · Package: `npx stackfit` (Node 22+, no dependencies).
+
+## Ground rules for the agent
+
+1. **Measure, then dry-run, then write.** Run `report` and `status` before `sync`, and show the user what will change.
+2. **Every project command needs a selector:** `--project <path>`, `--root <dir>`, or `--all` (needs a machine profile). Bare `stackfit status` fails.
+3. **Never pass `--force` on your own.** A collision means a file stackfit did not create. Show it and follow `references/troubleshooting.md`.
+4. **Never commit, push, or publish** unless asked. Know what is tracked: stackfit excludes exactly the files it generates (via `.git/info/exclude`); files you create in `docs/agent/` (config, repo-owned skills) and the `init` scaffolding are meant to be committed. Check with `git check-ignore -v <file>` (ignored?) and `git ls-files <path>` (tracked?), and tell the user which files to commit.
+5. **No personal values in the catalog.** Emails, org names, and tokens go in the catalog's gitignored `.env`, used as `{{env:NAME}}`.
+6. **Report numbers honestly.** `report` estimates what loads in every session: skill names + descriptions and always-on rules, per repo, plus the global skill folders that load everywhere regardless. Compare per-repo numbers with today's global cost; if a repo goes up, say so. Never present "every catalog skill in every repo" as the user's previous state.
+7. Reuse the user's existing catalog (`stackfit audit` finds it); never create a second one silently.
+
+## Set up stackfit for someone's repos
+
+1. **Baseline.** Note what loads today, per tool: `~/.claude/skills` (Claude Code), `~/.cursor/skills` (Cursor), `~/.codex/skills` (Codex), `~/.agents/skills` (shared): `ls ~/.claude/skills ~/.agents/skills ~/.cursor/skills ~/.codex/skills 2>/dev/null`. Per repo, check `.claude/skills`, `.cursor/skills`, `.cursor/rules`, `.agents/skills`. stackfit writes for all three tools, so a user who only had Claude globals will see Cursor and Codex gain skills they did not have; say so.
+2. **Catalog.** `npx stackfit audit` first: if a catalog exists, use it. `No catalog found` (exit 1) is expected on a first run. Choose with the user:
+   - **Their own skills only** (they already have skills, or few globals): `npx stackfit catalog init`, then import their skills (recipe 3), skipping any the model doesn't need (recipe 11). Lowest context; nothing new is added.
+   - **Curated starter** (they want good skills per stack): `npx stackfit catalog init --starter`, then `npx stackfit refresh --all` (needs git + GitHub). Adds packs they never had: some repos may load more than today.
+   - Both: start empty, then copy chosen skills from a starter made in another folder (`catalog init /tmp/sf-starter --starter`).
+   Then `npx stackfit audit` (expect no errors).
+3. **Preview.**
+   ```bash
+   npx stackfit report --root ~/code
+   npx stackfit status --root ~/code
+   ```
+   **Record the `Global skills add ...` line now**: it is the baseline, and it disappears once the globals are cleaned up. Compare each repo's `per session` with it. Too high for a repo? Trim with `excludePacks` (recipe 4) or mark long one-off skills manual-only (recipe 7). If `status` stops at `unmanaged collision`, the repo already has its own skills or rules: move them (recipe 3), then preview again.
+4. **Write.** `npx stackfit sync --root ~/code`, then `status` again: every repo should say `up to date`. Besides what `status` listed, sync writes `.stackfit.lock.json` and a managed block in `.git/info/exclude` in each repo. Do step 6 right after: until the global copies move, those skills load twice.
+5. **Make `--all` work** (optional; for daily `sync --all` / `update --all`). Create `<catalog>/stackfit.local.json`:
+   ```json
+   { "schemaVersion": 1, "machines": [ { "id": "laptop", "match": { "platform": "darwin" }, "roots": ["~/code"] } ] }
+   ```
+   `platform` is `darwin`, `linux`, or `win32`. Without `projects`, every Git repo directly under the roots is included.
+6. **Clean up globals, carefully.** Global copies of skills that are now in the catalog still load everywhere; removing them is where most savings come from. For each one, with the user's OK:
+   - `diff -r ~/.claude/skills/<name> <catalog>/skills/<name>`: keep the user's edits if they differ;
+   - make sure it is in a pack that reaches every repo that needs it: an `always` pack (like `core`) for every synced repo, otherwise only repos whose manifests match;
+   - `always` means every repo stackfit syncs, not every session: folders outside the roots and non-repo sessions lose the skill. If the user wants it truly everywhere, keep that one global (and out of the catalog's packs, so it doesn't load twice) or add more roots;
+   - move rather than delete: `mkdir -p ~/.claude/skills-backup && mv ~/.claude/skills/<name> ~/.claude/skills-backup/`.
+7. **Report.** Run `report` again. Per repo: packs and `per session` against the baseline you recorded, per tool. If the absolute numbers are small, say so: the gain may be organisation, not context. Name the files to commit (`docs/agent/...`). Suggest keeping the catalog in a private Git repo; run `git init` / push only if the user agrees.
+
+What `report` looks like (starter catalog, four repos, 31 skills installed globally):
+
+```text
+project         skills  skill listings     rules  per session  packs
+ingest-worker        2        ~168 tok   ~83 tok     ~251 tok  core
+marketing-site      25       ~1.5k tok   ~83 tok    ~1.6k tok  core, react, nextjs, ui, motion
+payments-api         5        ~397 tok   ~83 tok     ~480 tok  core, stripe
+storefront          24       ~1.5k tok   ~83 tok    ~1.6k tok  core, react, nextjs, e2e, ui, shadcn, stripe
+
+With stackfit: ~4.0k tokens across 4 project(s). Every catalog skill in every repo would be ~8.7k.
+Global skills add ~3.0k tokens to every session in every repo, with or without stackfit: ~/.claude/skills (31).
+```
+
+Here the Go worker goes from ~3.0k (all globals) to ~251 once the globals are moved into the catalog; the Next.js apps need most packs and save little.
+
+## How it works
+
+```text
+~/.stackfit/ (the catalog; keep it in a private Git repo)
+  stackfit.json         enabled skills + packs (which skills go where)
+  skill-sources.json    upstream source, review date, render overrides per skill
+  skills/<name>/        the skills
+  rules/ commands/ agents/   shared adapters
+  stackfit.local.json   (gitignored) project folders per machine
+  .env                  (gitignored) values for {{env:NAME}}
+
+<project>/
+  .agents/skills/                   selected skills, one physical copy (Codex reads this)
+  .claude/skills, .cursor/skills    links to it
+  .claude/rules, .cursor/rules, .claude/commands, .cursor/commands, .claude/agents, .cursor/agents
+  .stackfit.lock.json               what stackfit owns here (git-excluded with the rest)
+  docs/agent/config.json            optional, tracked: this repo's pack choices
+  docs/agent/skills/<name>/         optional, tracked: skills only this repo uses
+```
+
+**Packs** decide everything. A pack is `always` (every repo), `detect`ed (dependencies in `package.json`, `requirements*.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`, or marker files, at the root and in subfolders like `web/`, `apps/*`, `packages/*`), or opt-in. Projects are named by folder. Field reference: `references/configuration.md`.
+
+## Commands
+
+| Command | Use it to |
+| --- | --- |
+| `catalog init [dir] [--starter]` | Create a catalog (default `~/.stackfit`) |
+| `report [--json]` | Per repo: packs, skills, listing + rule tokens per session; global skill folders as baseline |
+| `status [--check]` | Dry run; `--check` exits 1 if anything would change |
+| `sync` | Write skills, rules, commands, agents into projects |
+| `update` | `git pull --ff-only` the catalog, then sync (`--skip-pull` to skip) |
+| `init` | Add tracked `AGENTS.md`, `CLAUDE.md`, `docs/agent/` (never overwrites; ask first) |
+| `refresh --skill <name>` / `--all` | Re-vendor upstream skills into the catalog |
+| `audit [--json]` | Provenance, staleness (180 days), packs, description sizes, cost |
+
+The catalog is found from `--catalog`, `STACKFIT_CATALOG`, the nearest `stackfit.json` above the current folder, or `~/.stackfit`.
+
+## Common requests
+
+| The user says | Do this | Recipe |
+| --- | --- | --- |
+| "Too many skills" / "what does this repo load?" | `report --project .`, explain the packs column and the global line | 1 |
+| "Skill X should apply to every repo" | Put it in an `always` pack (e.g. `core`), sync, then remove the global copy | 3 |
+| "Set this up for all my repos" | The setup steps above | 2, 3, 5 |
+| "I already have skills in ~/.claude/skills or .cursor/rules" | Move shared ones to the catalog, repo-specific ones to `docs/agent/` | 3 |
+| "This repo needs X but not Y" | `packs` / `excludePacks` / `skills` in `docs/agent/config.json` | 4 |
+| "Same setup on my work laptop" | Clone the catalog there, add a machine entry, `sync --all` | 5 |
+| "Add skill Z from GitHub" | `source` in `skill-sources.json`, then `refresh --skill` | 6 |
+| "This upstream skill is too long" / "only when I ask" | `render.frontmatter` override | 7 |
+| "Check this in CI" | Validate the repo config and the catalog in CI | 8 |
+| "Share with my team" | Catalog in a team repo; everyone runs `update --all` | 9 |
+
+Step-by-step versions: `references/recipes.md`. Every error message and its fix: `references/troubleshooting.md`.
+
+## After any change
+
+Run `npx stackfit status` with the same selector (expect `up to date` for every repo) and `npx stackfit report`. Tell the user what changed per repo, the before/after figures, and which tracked files (`docs/agent/...`) to commit.