@simpleapps-com/augur-skills 0.0.21 → 0.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",

package/skills/simpleapps/augur-packages/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: augur-packages
-description: Shared npm packages under @simpleapps-com/augur-*. Covers what each package provides, correct import patterns, key usage patterns, and what custom code they replace. Use when writing code for a site that consumes augur packages, during migration, or when deciding whether to write custom code.
+description: Shared npm packages under @simpleapps-com/augur-*. Directs agents to check installed packages before writing custom code. This skill is a starting point — always read the actual package code for current API surface.
 ---
 
 # Augur Packages
@@ -9,116 +9,40 @@ Shared npm packages for Next.js ecommerce sites and React Native apps. Published
 
 Before writing custom code, check whether a package export already solves the problem.
 
-## augur-utils
+## Ground Truth: Read the Code
 
-Types, formatters, cache config. Zero framework dependencies. Works everywhere.
+This skill is a **stub, not an archive**. New packages are created, existing packages gain features, APIs evolve. This skill MUST NOT be treated as the complete picture.
 
-```typescript
-import { formatPrice, CACHE_CONFIG } from "@simpleapps-com/augur-utils";
-import type { TCartLine, TProductItem } from "@simpleapps-com/augur-utils";
-import { cn } from "@simpleapps-com/augur-utils/web"; // clsx + tailwind-merge
-```
+**Always read the installed packages in your project's `node_modules/`:**
 
-**Types** cover: cart, category, inventory, product, pricing, attributes, UOM, supplier, filter, customer, menu, order, shipping, search, tax, metadata. Each has a Valibot schema (e.g., `CartLineSchema`).
+1. Run `ls repo/node_modules/@simpleapps-com/` to discover ALL available packages — there may be packages not listed here
+2. Read `repo/node_modules/@simpleapps-com/<package>/package.json` for the `exports` field to find available sub-paths
+3. Read files in `repo/node_modules/@simpleapps-com/<package>/dist/` to understand the current API surface
+4. Do NOT look at the source repo or other folders — only read what is installed in your project's `node_modules/`
 
-**Cache tiers** for React Query — every hook maps to one of these:
+When this skill and the installed code disagree, **the installed code wins**. This skill exists to point you in the right direction, not to replace reading the code.
 
-| Tier | Use Case |
-|------|----------|
-| `CACHE_CONFIG.STATIC` | Rarely changes (categories, item master) |
-| `CACHE_CONFIG.SEMI_STATIC` | Changes occasionally (pricing, search) |
-| `CACHE_CONFIG.DYNAMIC` | Changes frequently (stock levels) |
-| `CACHE_CONFIG.CART` | User-specific, short-lived |
-| `CACHE_CONFIG.REALTIME` | Always refetch |
+## Known Packages
 
-## augur-web
+These are starting hints — not a complete list. Always check `node_modules/@simpleapps-com/` for the full set.
 
-shadcn/Radix UI components. Per-component entry points — no barrel export, only what you import gets bundled.
+| Package | Purpose |
+|---------|---------|
+| `augur-utils` | Types, formatters, cache config, Valibot schemas. Zero framework dependencies. |
+| `augur-web` | shadcn/Radix UI components. Per-component entry points. |
+| `augur-hooks` | React Query hooks and Zustand stores. Cross-platform. |
+| `augur-server` | Server-side utilities for Next.js — Redis caching, auth factory, query client. |
+| `augur-tailwind` | Tailwind v4 CSS theme. No config file needed. |
 
-```typescript
-import { Button } from "@simpleapps-com/augur-web/button";
-import { Dialog, DialogContent, DialogTitle } from "@simpleapps-com/augur-web/dialog";
-import { Card, CardHeader, CardContent } from "@simpleapps-com/augur-web/card";
-```
+## How to Check for Package Solutions
 
-**Component conventions:** CVA variants, `React.forwardRef`, `asChild` via Radix Slot, `cn()` for class merging, `"use client"` preserved in build, `displayName` set, icons use `react-icons/lu`.
+When considering custom code:
 
-**Tailwind content detection:** Tailwind v4 auto-detects sources. If augur-web classes are missing, add `@source "../node_modules/@simpleapps-com/augur-web/dist";` to your CSS.
-
-## augur-hooks
-
-React Query hooks and Zustand stores. Cross-platform (works in Next.js and React Native).
-
-```typescript
-// Cross-platform
-import { useItemPrice, useCartStore, useDebounce, AugurHooksProvider } from "@simpleapps-com/augur-hooks";
-// Web only (DOM-dependent)
-import { useIsMobile, useIsHydrated } from "@simpleapps-com/augur-hooks/web";
-```
-
-**Hook triple pattern** — every query hook exports three things:
-- `use<Name>(params, options?)` — client-side hook (reads SDK from provider context)
-- `get<Name>Options(api, params)` — server-side prefetch (accepts SDK directly)
-- `get<Name>Key(params)` — query key factory for cache invalidation
-
-```typescript
-// Client
-const { data } = useItemPrice(itemId, customerId, 1);
-
-// Server prefetch (no React context)
-await queryClient.prefetchQuery(getItemPriceOptions(api, itemId, customerId));
-
-// Cache invalidation
-queryClient.invalidateQueries({ queryKey: getItemPriceKey(itemId, customerId) });
-```
-
-**queryFn override** — web consumers can route through cached server actions:
-
-```typescript
-const { data } = useItemPrice(itemId, customerId, 1, {
-  queryFn: () => getCachedItemPrice(itemId, customerId, 1),
-});
-```
-
-**Cart hooks** use dependency injection — the package provides React Query orchestration (optimistic updates, invalidation, loading states), consumers inject site-specific mutation callbacks.
-
-**Provider required:** All query hooks need `AugurHooksProvider` wrapping the app with an SDK instance.
-
-## augur-server
-
-Server-side utilities for Next.js. Redis caching, auth factory, query client, environment detection.
-
-```typescript
-import { cachedSdkCall, getServerQueryClient, isDev, sdkCall } from "@simpleapps-com/augur-server";
-import { createAuthConfig } from "@simpleapps-com/augur-server/auth";
-```
-
-**cachedSdkCall** wraps SDK calls with Redis caching (SHA-256 key hashing, per-method stats, fire-and-forget writes, circuit breaker). Falls through without caching if ioredis is not installed.
-
-**createAuthConfig** — NextAuth 5 factory with dependency-injected callbacks:
-
-```typescript
-export const { handlers, signIn, signOut, auth } = NextAuth(
-  createAuthConfig({
-    callbacks: { getUserProfile, cartHdrLookup }, // site-specific
-    defaultCustomerId: process.env.NEXT_PUBLIC_DEFAULT_CUSTOMER_ID,
-  }),
-);
-```
-
-**Site action registry** — `createServerSite()` creates a process-global singleton. Self-heals via three-tier fallback (globalThis → module cache → auto-init from env vars).
-
-## augur-tailwind
-
-Tailwind v4 CSS theme. No `tailwind.config.ts` needed.
-
-```css
-@import "tailwindcss";
-@import "@simpleapps-com/augur-tailwind/base.css";
-@plugin "tailwindcss-animate";
-```
-
-Override brand with CSS variables: `--primary`, `--secondary`, `--radius`, etc. All HSL components (no wrapper).
+1. Run `ls repo/node_modules/@simpleapps-com/` to see what's installed
+2. Read the package's `package.json` `exports` and its `dist/` files for available functions, hooks, and components
+3. Look for the hook triple pattern in augur-hooks: `use<Name>`, `get<Name>Options`, `get<Name>Key`
+4. Check augur-web for UI components before building custom ones
+5. Only use what is in your `node_modules/` — do not reference the source repo
 
 ## What Stays Site-Specific
 
@@ -126,38 +50,26 @@ MUST NOT be replaced by packages:
 - **Server actions** (`"use server"`) — site-specific business logic
 - **Layout components** (Header, Footer, MainMenu) — brand-specific
 - **Domain components** (ProductItem, CartTable, CategoryCard) — compose UI primitives
-- **Auth callbacks** (`getUserProfile`, `cartHdrLookup`) — injected into `createAuthConfig`
+- **Auth callbacks** — injected into package auth factory
 - **Cart mutation callbacks** — depend on site-specific server actions
 - **CSS variable overrides** — brand colors, fonts, radius
 - **next.config** — image domains, redirects, security headers
 - **Site integrations** — GA4, Maps, reCAPTCHA
 
-## Anti-Pattern Catalog
-
-Custom code that duplicates package exports. When you see these in a site, replace with the package version.
-
-| Custom Code | Replace With |
-|-------------|-------------|
-| `cn()` in `@/lib/utils` | `cn` from `augur-utils/web` |
-| `formatPrice()` helpers | `formatPrice` from `augur-utils` |
-| Local types (`@/types/T*`) | Types from `augur-utils` |
-| Custom `CACHE_CONFIG` / inline TTLs | `CACHE_CONFIG` from `augur-utils` |
-| `@/components/ui/*` imports | `augur-web/<component>` |
-| Custom breadcrumb, quantity, pagination, form inputs | `augur-web/<component>` |
-| Custom `useDebounce` | `useDebounce` from `augur-hooks` |
-| Custom `useIsMobile` / `useIsHydrated` | From `augur-hooks/web` |
-| Custom price/cart hooks or stores | From `augur-hooks` |
-| Custom `cachedSdkCall` / SDK cache | `cachedSdkCall` from `augur-server` |
-| Custom `getServerQueryClient` | From `augur-server` |
-| Custom `isDev` / env detection | From `augur-server` |
-| Manual NextAuth Credentials config | `createAuthConfig` from `augur-server/auth` |
-| `lucide-react` / `@heroicons/react` | `react-icons/lu` |
-| `tailwind.config.ts` (v3) | `augur-tailwind/base.css` CSS-first |
-
-## Platform Standard
+## Suggest Package Improvements
+
+The augur packages exist to share common code across ALL Node projects. When you find yourself writing code that would benefit other sites, suggest it as a package addition:
+
+- Create a GitHub issue on `simpleapps-com/augur-packages` describing the proposed addition
+- Explain what it does, which sites would benefit, and why it belongs in the shared package
+- Examples: a new utility function, a reusable hook, a common UI component, a shared type
+
+The goal is to grow the packages over time so sites write less custom code.
+
+## Platform Standards
 
 - **Icons:** `react-icons/lu`
-- **Tailwind:** v4, CSS-first via `augur-tailwind/base.css`
+- **Tailwind:** v4, CSS-first
 - **Validation:** Valibot (not Zod, not Yup)
-- **Auth:** NextAuth 5 via `createAuthConfig()`
+- **Auth:** NextAuth 5 via package auth factory
 - **Reference site:** ampro-online

package/skills/simpleapps/github/SKILL.md

@@ -38,6 +38,26 @@ MUST NOT commit, push, create PRs, or merge unless the user explicitly asks. Aft
 
 The pattern is always: **do the work → report results → wait**.
 
+## Git Commands (no `cd`)
+
+`cd` is denied. MUST use `git -C repo` for all git operations. For multi-line commit messages, write the message to a tmp file and use `git commit -F`:
+
+```bash
+# Stage files
+git -C repo add path/to/file.md
+
+# Write commit message to tmp file (use Write tool, not echo/cat)
+# → /tmp/commit-msg.txt
+
+# Commit using -F flag
+git -C repo commit -F /tmp/commit-msg.txt
+
+# Clean up
+rm /tmp/commit-msg.txt
+```
+
+This avoids shell quoting issues with HEREDOCs and `cd` permission blocks. The Write tool creates the tmp file safely.
+
 ## Issues
 
 MUST use `--repo simpleapps-com/<repo>` on every `gh` call. MUST ask the user which repo — never assume.

package/skills/simpleapps/wiki/SKILL.md

@@ -69,6 +69,8 @@ The wiki is a separate git repo at `wiki/`. No branch protection, no PRs.
 
 ```bash
 git -C wiki add -A
-git -C wiki commit -m "docs: describe the change"
+# Write commit message using Write tool → tmp/commit-msg.txt
+git -C wiki commit -F tmp/commit-msg.txt
+rm tmp/commit-msg.txt
 git -C wiki push
 ```