@simpleapps-com/augur-skills 0.0.22 → 2026.3.1

package/package.json

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

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

@@ -1,6 +1,10 @@
 ---
 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.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
 ---
 
 # Augur Packages
@@ -9,116 +13,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 +54,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/basecamp/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: basecamp
 description: Basecamp 2 integration via MCP. Covers MCP tool reference, URL parsing, authentication, Chrome fallback, attachments, and site-info documents. Use when reading or writing Basecamp data.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - mcp__plugin_simpleapps_basecamp__*
+  - mcp__claude-in-chrome__*
 ---
 
 # Basecamp 2

package/skills/simpleapps/claude-code-docs/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: claude-code-docs
 description: Claude Code documentation reference and discovery. Use when looking up Claude Code features, configuration, plugins, skills, hooks, or troubleshooting.
+allowed-tools:
+  - Read
+  - WebFetch
 ---
 
 # Claude Code Documentation

package/skills/simpleapps/fyxer/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: fyxer
 description: Fyxer AI meeting recording integration. Covers extraction, local caching, posting to Basecamp, and Fyxer Index management. Use when processing Fyxer recordings or meeting transcripts.
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Bash
+  - mcp__plugin_simpleapps_basecamp__*
+  - mcp__claude-in-chrome__*
 ---
 
 # Fyxer

package/skills/simpleapps/github/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: github
 description: GitHub conventions for SimpleApps. Covers org structure, git safety, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, or working with GitHub repos.
-allowed-tools: Skill(project-defaults)
+allowed-tools:
+  - Skill(project-defaults)
+  - Read
+  - Glob
+  - Grep
+  - Bash
 ---
 
 First, use Skill("project-defaults") to load the project layout.

package/skills/simpleapps/project-defaults/SKILL.md

@@ -1,11 +1,32 @@
 ---
 name: project-defaults
 description: SimpleApps project conventions. Covers directory layout, symlink setup for .claude integration, permission defaults (deny cd, kill), and per-project baseline settings. Use when setting up projects, checking structure, or configuring Claude Code defaults.
+allowed-tools:
+  - Read
+  - Bash
 ---
 
 # Project Defaults
 
-## Directory Layout
+## Base Directory Standard
+
+All projects live under `~/projects/` in two groups:
+
+```
+~/projects/
+├── simpleapps/          # Internal repos (augur-*, shared infra)
+│   ├── augur-skills/
+│   ├── augur-packages/
+│   └── augur/
+└── clients/             # Client site repos
+    ├── ampro-online/
+    └── directsupplyinc/
+```
+
+- Internal repos go in `~/projects/simpleapps/`
+- Client site repos go in `~/projects/clients/`
+
+## Project Directory Layout
 
 Every project MUST use this layout:
 
@@ -57,6 +78,9 @@ Every project SHOULD configure `.claude/settings.local.json` with these deny rul
 ```json
 {
   "permissions": {
+    "allow": [
+      "Bash(pnpm:*)"
+    ],
     "deny": [
       "Bash(cd:*)",
       "Bash(cat:*)",
@@ -64,7 +88,12 @@ Every project SHOULD configure `.claude/settings.local.json` with these deny rul
       "Bash(grep:*)",
       "Bash(sleep:*)",
       "Bash(kill:*)",
-      "Bash(pkill:*)"
+      "Bash(pkill:*)",
+      "Bash(find:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(awk:*)",
+      "Bash(rg:*)"
     ]
   }
 }
@@ -77,8 +106,29 @@ Why each is denied:
 - **`sed`** — Use the Edit tool instead.
 - **`grep`** — Use the Grep tool instead.
 - **`sleep`** — Unnecessary; use proper sequencing or background tasks.
+- **`find`** — Use the Glob tool instead.
+- **`head`/`tail`** — Use the Read tool with `offset` and `limit` parameters instead.
+- **`awk`** — Use the Edit tool instead.
+- **`rg`** — Use the Grep tool instead (it uses ripgrep internally).
 - **`kill`/`pkill`** — Use `TaskStop` to manage background processes. For internal tasks running in the background (dev servers, watchers, etc.), always use `TaskStop` instead of shell kill commands. `TaskStop` cleanly shuts down the task and updates Claude Code's internal tracking.
 
+## Bin Scripts (PATH)
+
+The augur-skills plugin includes shell scripts (`cld`, `cldo`, `tmcld`, etc.) in `plugins/simpleapps/bin/`. When installed via the Claude Code marketplace, these live at:
+
+```
+~/.claude/plugins/marketplaces/augur-skills/plugins/simpleapps/bin/
+```
+
+To make them available on PATH, add to `~/.zshrc`:
+
+```bash
+# SimpleApps augur-skills bin scripts
+export PATH="$PATH:$HOME/.claude/plugins/marketplaces/augur-skills/plugins/simpleapps/bin"
+```
+
+This path is stable across plugin updates (marketplace updates are git pulls). The `project-init` command checks for this and adds it if missing.
+
 ## New Project Setup
 
 ```bash

package/skills/simpleapps/wiki/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: wiki
 description: Wiki conventions for SimpleApps projects. Covers token budget, writing for three audiences, page conventions, maintenance rules, and git workflow. Use when reading, writing, or auditing wiki content.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - Bash
 ---
 
 # Wiki

package/skills/simpleapps/workflow/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: workflow
 description: How we track and deliver work. Covers the Basecamp-to-GitHub flow for client requests, task tracking, cross-linking, and issue templates. Use when working on client tasks, creating issues, or checking assignments.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
 ---
 
 # Workflow