@simpleapps-com/augur-skills 0.0.17 → 0.0.20

package/package.json

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

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

@@ -0,0 +1,163 @@
+---
+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.
+---
+
+# Augur Packages
+
+Shared npm packages for Next.js ecommerce sites and React Native apps. Published to npm under `@simpleapps-com`. Source: `simpleapps-com/augur-packages`.
+
+Before writing custom code, check whether a package export already solves the problem.
+
+## augur-utils
+
+Types, formatters, cache config. Zero framework dependencies. Works everywhere.
+
+```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
+```
+
+**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`).
+
+**Cache tiers** for React Query — every hook maps to one of these:
+
+| 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 |
+
+## augur-web
+
+shadcn/Radix UI components. Per-component entry points — no barrel export, only what you import gets bundled.
+
+```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";
+```
+
+**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`.
+
+**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).
+
+## What Stays Site-Specific
+
+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`
+- **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
+
+- **Icons:** `react-icons/lu`
+- **Tailwind:** v4, CSS-first via `augur-tailwind/base.css`
+- **Validation:** Valibot (not Zod, not Yup)
+- **Auth:** NextAuth 5 via `createAuthConfig()`
+- **Reference site:** ampro-online

package/skills/simpleapps/github/SKILL.md

@@ -1,45 +1,89 @@
 ---
 name: github
-description: GitHub conventions for SimpleApps. Covers org structure, local project layout, wiki-as-docs workflow, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, setting up repos, or working with GitHub wikis.
+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)
 ---
 
+First, use Skill("project-defaults") to load the project layout.
+
 # GitHub
 
 ## Organization
 
-All SimpleApps repos live under the **`simpleapps-com`** GitHub org.
-
-Repository pattern: `simpleapps-com/<repo-name>`
+All SimpleApps repos live under **`simpleapps-com`**. Pattern: `simpleapps-com/<repo-name>`
 
 ## Authentication
 
-Use the `gh` CLI for all GitHub operations:
-
 ```bash
-gh auth status          # Check auth status
-gh auth setup-git       # Configure gh as git credential helper
+gh auth status          # Check auth
+gh auth setup-git       # Fix git credential helper (run if push fails 401/403)
 ```
 
-If `git push` fails with 401/403, run `gh auth setup-git` to fix credentials.
+## Project Layout
 
-## Key Topics
+See `simpleapps:project-defaults` for the full directory layout, symlink setup, and permission defaults. Key point: the git repo is always at `repo/`. Use `git -C repo` for git operations from the project root.
 
-- **Wiki as context** — See `wiki-as-context.md` for why the wiki is the source of truth and how to write for both humans and AI agents.
-- **Project structure** — See `project-structure.md` for the `{project}/[repo|wiki]` layout, what goes where, and wiki conventions.
-- **Issues & pull requests** — See `issues-prs.md` for issue templates, PR commands, and cross-linking with Basecamp.
+## Wiki
 
-## Quick Reference
+See `simpleapps:wiki` for wiki conventions, token budget, and maintenance rules.
 
-```bash
-# Pushing
-gh auth setup-git && git push origin <branch>
-git push origin <tag>
+## Git Safety
+
+MUST NOT commit, push, create PRs, or merge unless the user explicitly asks. After making changes, report what was done and stop. Do not offer or suggest the next git action — wait for instructions.
+
+- **Commits**: Do not commit until the user says "commit" or equivalent
+- **Pushes**: Do not push until the user explicitly asks
+- **PRs**: Do not create or offer to create a PR — report the work, stop
+- **Merges**: Do not merge unless the user explicitly asks
+
+The pattern is always: **do the work → report results → wait**.
+
+## Issues
+
+MUST use `--repo simpleapps-com/<repo>` on every `gh` call. MUST ask the user which repo — never assume.
+
+### Title
+
+Conventional commit style: `fix: description`, `feat: description`, `chore: description`. Under 70 characters.
+
+### Body
+
+```markdown
+## Problem
+What is broken, missing, or needed?
 
-# Issues
+## Expected Behavior
+What SHOULD happen instead?
+
+## Acceptance Criteria
+- [ ] Concrete, testable criteria
+
+## Context
+Related issues, affected files, workarounds, reproduction steps.
+```
+
+Bug reports also include **Steps to Reproduce** and **Current Behavior** with error messages.
+
+### Commands
+
+```bash
 gh issue create --repo simpleapps-com/<repo> --title "type: desc" --body "..."
 gh issue list --repo simpleapps-com/<repo>
+gh issue view <number> --repo simpleapps-com/<repo>
+gh issue close <number> --repo simpleapps-com/<repo> --comment "message"
+```
+
+Include `Closes #N` in commit body to auto-close issues.
+
+## Pull Requests
 
-# PRs
+```bash
 gh pr create --repo simpleapps-com/<repo> --title "title" --body "..."
 gh pr list --repo simpleapps-com/<repo>
+gh pr view <number> --repo simpleapps-com/<repo>
+gh pr merge <number> --repo simpleapps-com/<repo>
 ```
+
+## Cross-Linking with Basecamp
+
+For client tasks originating in Basecamp, see `simpleapps:workflow` for the full cross-linking process.

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

@@ -0,0 +1,91 @@
+---
+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.
+---
+
+# Project Defaults
+
+## Directory Layout
+
+Every project MUST use this layout:
+
+```
+{project}/
+├── .claude/            # Claude Code config (symlinks to repo/.claude/)
+│   ├── rules/          # → repo/.claude/rules/
+│   └── commands/       # → repo/.claude/commands/
+├── repo/               # Git repo (simpleapps-com/<name>.git)
+├── wiki/               # Wiki repo (simpleapps-com/<name>.wiki.git)
+├── wip/                # Work-in-progress files (not in git)
+├── tmp/                # Temporary files (not in git)
+└── .simpleapps/        # Credentials (not in git)
+```
+
+The parent `{project}/` is NOT a git repo — it keeps code and wiki side-by-side. The git repo is always at `repo/`. Use `git -C repo` for git operations from the project root.
+
+| Content | Location | Examples |
+|---------|----------|---------|
+| Product code | `repo/` | Source, tests, configs, SKILL.md files |
+| Dev documentation | `wiki/` | Architecture, guides, specs, conventions |
+| Repo `.claude/rules/` | `repo/` | Minimal summaries referencing wiki |
+| Repo `.claude/CLAUDE.md` | `repo/` | Quick reference + wiki links |
+| Active task context | `wip/` | `{issue-number}-{short-desc}.md` files |
+| Temporary files | `tmp/` | Throwaway files, scratch space, build artifacts |
+| Project secrets | `{project}/.simpleapps/` | Site-specific credentials |
+| Global secrets | `~/.simpleapps/` | Shared credentials across all projects |
+
+**WIP**: Research, plans, decisions, test results. MUST NOT contain secrets, final docs, or code.
+
+**Credentials**: Project-level (`.simpleapps/`) overrides user-level (`~/.simpleapps/`). MUST NOT be committed.
+
+## Symlink Setup
+
+The repo contains `.claude/rules/` and `.claude/commands/` with project-specific rules and commands. To make these active from the project root (without starting Claude Code inside `repo/`), symlink them into the project-level `.claude/` folder:
+
+```bash
+mkdir -p {project}/.claude
+ln -sf ../repo/.claude/rules {project}/.claude/rules
+ln -sf ../repo/.claude/commands {project}/.claude/commands
+```
+
+This lets you run Claude Code from `{project}/` and still get the repo's rules and commands loaded automatically.
+
+## Permission Defaults
+
+Every project SHOULD configure `.claude/settings.local.json` with these deny rules:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(cd:*)",
+      "Bash(cat:*)",
+      "Bash(sed:*)",
+      "Bash(grep:*)",
+      "Bash(sleep:*)",
+      "Bash(kill:*)",
+      "Bash(pkill:*)"
+    ]
+  }
+}
+```
+
+Why each is denied:
+
+- **`cd`** — Use `git -C` or tool-specific flags (`--repo`, `-C`) instead. `cd` loses working directory context.
+- **`cat`** — Use the Read tool instead.
+- **`sed`** — Use the Edit tool instead.
+- **`grep`** — Use the Grep tool instead.
+- **`sleep`** — Unnecessary; use proper sequencing or background tasks.
+- **`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.
+
+## New Project Setup
+
+```bash
+mkdir {project} && cd {project}
+git clone https://github.com/simpleapps-com/<name>.git repo
+git clone https://github.com/simpleapps-com/<name>.wiki.git wiki
+mkdir -p wip tmp .simpleapps .claude
+ln -sf ../repo/.claude/rules .claude/rules
+ln -sf ../repo/.claude/commands .claude/commands
+```

package/skills/simpleapps/wiki/SKILL.md

@@ -0,0 +1,74 @@
+---
+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.
+---
+
+# Wiki
+
+The wiki is the **single source of truth** for how a project works. The wiki is the spec; the repo is the implementation.
+
+## Token Budget
+
+A wiki MUST NOT exceed **20K tokens** (~15K words, ~60KB). This is 10% of the AI agent's 200K context window — enough for the agent to load the entire wiki at session start while leaving 90% for working context.
+
+Check size: `wc -w wiki/*.md` (multiply by ~1.3 for token estimate)
+
+## Core Principle
+
+Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) MUST be minimal — orient then point to wiki. AI agents read wiki pages as local files via `Read wiki/<page>.md`. No network requests needed.
+
+```
+Wiki defines → Code implements → Learnings update wiki → Repeat
+```
+
+When code reveals the wiki is wrong or incomplete, update immediately. The wiki MUST reflect reality, not aspirations.
+
+## Three Audiences
+
+Every page serves junior devs (explanations, examples), senior devs (quick reference, decisions), and AI agents (unambiguous specs, MUST/SHOULD/MAY). Write for all three:
+
+- Lead with a summary — seniors and agents get it fast, juniors get orientation
+- Explain *why* before *how*
+- Use tables for reference, code blocks for copy-paste, RFC 2119 keywords for requirements
+- Each page SHOULD be self-contained
+- Follow `simpleapps:writing-style` — token-efficient, action verbs first, no filler
+
+## Content Rules
+
+- Wiki pages SHOULD NOT contain raw code. Describe patterns and principles instead.
+- If implementation details are needed, link to the source file in `repo/` rather than duplicating code in the wiki.
+- The wiki documents *what* and *why*. The repo is the source of truth for *how*.
+
+## Conventions
+
+- Page naming: **PascalCase** with hyphens (`Getting-Started.md`)
+- Every wiki MUST have `_Sidebar.md` for navigation
+- Links: `[[Page-Name]]` or `[[Display Text|Page-Name]]`
+- Anchor links MUST target specific sections (`[[Versioning#version-bump-procedure]]`), not just pages
+- Repo references: use relative paths (`../../../wiki/Versioning.md`)
+- Default branch: `master` (not `main`)
+
+## Keep It Lean
+
+- Document patterns and principles, not exhaustive lists
+- No hardcoded counts, no pinned versions, no full export inventories
+- Describe the pattern, give 1-2 examples, point to source for current list
+- Merge overlapping pages, archive obsolete ones
+
+## Maintenance
+
+Cross-check wiki against code before updating. Staleness-prone: versions, file counts, CI workflows, TODO markers, API surfaces. **Never echo what the wiki says — read the code, then write.**
+
+When adding/removing pages, MUST update: `Home.md`, `_Sidebar.md`, `llms.txt` (if present).
+
+**Lead-site wikis** (e.g., ampro-online) serve as platform reference. Tag sections **(platform pattern)** vs **(site-specific)** so agents on other sites know what to replicate vs customize.
+
+## Git Workflow
+
+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"
+git -C wiki push
+```

package/skills/simpleapps/github/issues-prs.md

@@ -1,89 +0,0 @@
-# Issues & Pull Requests
-
-## Issues
-
-### Creating Issues
-
-MUST always use `--repo simpleapps-com/<repo>` to target the correct org. MUST ask the user which repo to create the issue in — never assume.
-
-### Issue Title
-
-- Use conventional commit style: `fix: description`, `feat: description`, `chore: description`
-- SHOULD be a technical description, not the client's words
-- Keep under 70 characters
-
-### Issue Body
-
-Every issue MUST include these sections:
-
-```markdown
-## Problem
-What is broken, missing, or needed? Include error messages, URLs, or screenshots if relevant.
-
-## Expected Behavior
-What SHOULD happen instead? Be specific.
-
-## Acceptance Criteria
-- [ ] Concrete, testable criteria
-- [ ] Each item is independently verifiable
-
-## Context
-Any additional info: related issues, affected files, workarounds, reproduction steps.
-```
-
-For bug reports, also include:
-- **Steps to Reproduce** — numbered steps to trigger the bug
-- **Current Behavior** — what actually happens (with error messages)
-
-### Labels
-
-Use labels to categorize: `bug`, `feature`, `enhancement`
-
-### Example
-
-```bash
-gh issue create --repo simpleapps-com/<repo> \
-  --title "fix: search endpoint returns 404" \
-  --body "$(cat <<'ISSUE'
-## Problem
-The `search` MCP tool returns HTTP 404 on every query. This prevents finding content across projects.
-
-## Expected Behavior
-Search SHOULD return matching results, consistent with the Basecamp web UI.
-
-## Acceptance Criteria
-- [ ] Search returns results for known content
-- [ ] Error handling for empty results
-
-## Context
-BCX API may not expose a search endpoint. Web UI search at `/search?q=...` works.
-ISSUE
-)"
-```
-
-### Managing Issues
-
-```bash
-gh issue list --repo simpleapps-com/<repo>                    # List open issues
-gh issue list --repo simpleapps-com/<repo> --state all        # Include closed
-gh issue view <number> --repo simpleapps-com/<repo>           # View issue details
-gh issue close <number> --repo simpleapps-com/<repo>          # Close issue
-gh issue close <number> --repo simpleapps-com/<repo> --comment "message"  # Close with comment
-```
-
-### Closing via Commit
-
-Include `Closes #N` in the commit message body to auto-close issues when pushed.
-
-## Pull Requests
-
-```bash
-gh pr create --repo simpleapps-com/<repo> --title "title" --body "description"
-gh pr list --repo simpleapps-com/<repo>
-gh pr view <number> --repo simpleapps-com/<repo>
-gh pr merge <number> --repo simpleapps-com/<repo>
-```
-
-## Cross-Linking with Basecamp
-
-When working on client tasks that originate in Basecamp, see the `simpleapps:workflow` skill for the full Basecamp-to-GitHub cross-linking process.

package/skills/simpleapps/github/project-structure.md

@@ -1,146 +0,0 @@
-# Project Structure & Wiki Workflow
-
-## Local Layout
-
-Every project MUST use this layout:
-
-```
-{project}/
-├── repo/           # Main git repo (simpleapps-com/<name>.git)
-├── wiki/           # GitHub wiki repo (simpleapps-com/<name>.wiki.git)
-├── wip/            # Work-in-progress files for active tasks (not in git)
-└── .simpleapps/    # Project-level secrets and credentials (not in git)
-```
-
-The parent `{project}/` directory is NOT a git repo — it's a local wrapper that keeps the code repo and wiki side-by-side. The `wip/` and `.simpleapps/` directories sit outside both git trees so their contents can never be accidentally committed.
-
-## Why This Pattern
-
-- GitHub wikis are separate git repos. Cloning them alongside the code keeps everything local and searchable.
-- AI agents (Claude Code) can `Read` wiki files from disk instantly instead of fetching URLs.
-- The wiki becomes the **source of truth for dev docs**. The repo stays focused on product code.
-
-## Setting Up a New Project
-
-```bash
-mkdir {project}
-cd {project}
-git clone https://github.com/simpleapps-com/<name>.git repo
-git clone https://github.com/simpleapps-com/<name>.wiki.git wiki
-```
-
-If the wiki repo doesn't exist yet, create it by adding any page via the GitHub wiki UI first, then clone.
-
-## What Goes Where
-
-| Content | Location | Examples |
-|---------|----------|---------|
-| Product code | `repo/` | Source, tests, configs, SKILL.md files |
-| Dev documentation | `wiki/` | Architecture, guides, specs, conventions |
-| Repo README | `repo/README.md` | Minimal — quick start + link to wiki |
-| Repo `.claude/rules/` | `repo/` | Minimal summaries referencing wiki pages |
-| Repo `.claude/CLAUDE.md` | `repo/` | Quick reference + wiki links |
-| Active task context | `wip/` | WIP files for Basecamp todos or GitHub issues |
-| Project secrets | `{project}/.simpleapps/` | Site-specific credentials, `{siteId}.json` |
-| Global secrets | `~/.simpleapps/` | Shared credentials across all projects |
-
-Rule of thumb: if a `.md` file isn't built into the end product, it belongs in the wiki. If it contains secrets or ephemeral task state, it belongs outside both git trees.
-
-## WIP Directory
-
-The `wip/` directory holds work-in-progress files that AI agents create when picking up tasks from Basecamp or GitHub issues. Each file tracks research, plans, and progress for an active task.
-
-### Naming Convention
-
-`{issue-number}-{short-description}.md` — e.g., `14-basecamp-mcp-auto-refresh-oauth.md`
-
-### Lifecycle
-
-1. Agent picks up a Basecamp todo or GitHub issue
-2. Creates a WIP file with research findings and implementation plan
-3. Updates the file as work progresses
-4. File remains after completion as a record of decisions made
-
-### What belongs in WIP
-
-- Research findings and code analysis
-- Detailed implementation plans
-- Decision rationale
-- Test results and verification notes
-
-### What does NOT belong in WIP
-
-- Secrets, credentials, or tokens (use `.simpleapps/`)
-- Final documentation (use `wiki/`)
-- Code (use `repo/`)
-
-## Credentials (`.simpleapps/`)
-
-Secrets and credentials live in `.simpleapps/` directories at two levels:
-
-- **`~/.simpleapps/`** (user-level) — shared credentials across all projects (e.g., `augur-api.json`, `basecamp.json`)
-- **`{project}/.simpleapps/`** (project-level) — credentials specific to that project (e.g., `{siteId}.json` with test user creds)
-
-Project-level credentials override user-level ones when both exist. Both directories sit outside git trees so nothing can be accidentally committed.
-
-MUST NOT be committed to any git repository. MUST NOT be copied into `repo/` or `wiki/`.
-
-## Referencing Wiki from Repo
-
-Repo files SHOULD use **relative filesystem paths** to reference wiki content:
-
-```markdown
-Full docs: ../../../wiki/Versioning.md
-```
-
-Relative paths work for Claude Code (local file reads). GitHub URLs require network access and are slower.
-
-## Wiki Conventions
-
-### Page Naming
-
-- Use **PascalCase** with hyphens: `Getting-Started.md`, `Plugin-Structure.md`
-- Match the pattern used in GitHub wiki URLs: `wiki/Page-Name`
-
-### _Sidebar.md
-
-Every wiki MUST have a `_Sidebar.md` for navigation. Group pages by topic:
-
-```markdown
-**[[Home]]**
-
-**Getting Started**
-- [[Getting-Started]]
-
-**Architecture**
-- [[Architecture]]
-- [[Plugin-Structure]]
-
-**Development**
-- [[Development]]
-- [[Versioning]]
-```
-
-### Linking
-
-- Use `[[Page-Name]]` wiki links for internal links (renders on GitHub wiki)
-- Use `[[Display Text|Page-Name]]` for custom link text
-
-### Content Guidelines
-
-- Wiki pages are the **full, detailed** version of documentation
-- Each page SHOULD be self-contained — don't assume the reader has seen other pages
-- Include examples, code blocks, and tables where they help
-- Use RFC 2119 keywords (MUST/SHOULD/MAY) for requirements
-
-### Committing Wiki Changes
-
-The wiki is a regular git repo. Commit and push like any other:
-
-```bash
-cd {project}/wiki
-git add -A && git commit -m "docs: add architecture page"
-git push origin master
-```
-
-Note: GitHub wikis typically use `master` as the default branch, not `main`.

package/skills/simpleapps/github/wiki-as-context.md

@@ -1,162 +0,0 @@
-# Wiki as Context
-
-The GitHub wiki is the **single source of truth** for how a project works. It is not an afterthought or a place to dump notes — it is the primary context that drives development.
-
-## The Problem
-
-Documentation scattered across a codebase creates friction:
-
-- `.claude/rules/` files, README.md, inline comments, and docs/ folders all compete as sources of truth
-- AI agents waste tokens reading large files to find relevant context
-- New team members don't know where to look
-- Docs rot because they live next to code and get forgotten
-
-## The Solution
-
-The wiki is the **spec**. The repo is the **implementation**.
-
-| Wiki | Repo |
-|------|------|
-| Architecture decisions | Code that implements them |
-| API specs | API code |
-| Conventions and standards | Code that follows them |
-| Onboarding guides | Nothing — wiki is self-contained |
-| Release processes | Automation scripts |
-| Full explanations | Minimal pointers back to wiki |
-
-## How It Works
-
-### 1. Wiki First
-
-When starting new work, check the wiki first. If the wiki doesn't cover it, write the wiki page before writing code. The wiki defines *what* and *why*. The code implements *how*.
-
-### 2. Repo References Wiki
-
-Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) SHOULD be **minimal** — just enough to orient, then point to the wiki for details.
-
-```markdown
-# Versioning
-
-Full docs: ../../../wiki/Versioning.md
-
-`VERSION` file = source of truth. All version fields MUST match.
-```
-
-### 3. AI Agents Read Wiki Locally
-
-Because the wiki is cloned alongside the repo (see `project-structure.md`), AI agents read wiki pages as local files. No network requests, no URL fetching — just `Read ../../../wiki/Architecture.md`.
-
-This means wiki pages are both human documentation AND machine context.
-
-### 4. Wiki Evolves with the Project
-
-The wiki is not write-once. As the codebase changes:
-
-- Update affected wiki pages in the same work session
-- Add new pages when new patterns emerge
-- Remove pages when features are deprecated
-- Keep the `_Sidebar.md` current
-
-## Three Audiences
-
-Every wiki page serves three audiences simultaneously:
-
-| Audience | What they need | How they read |
-|----------|---------------|---------------|
-| **Junior devs** | Explanations of *why*, step-by-step instructions, examples they can copy | Top to bottom, following links for context |
-| **Senior devs** | Quick reference, architecture decisions, conventions to follow | Scan for the section they need, skip the rest |
-| **AI agents** | Unambiguous specs, exact commands, clear requirements (MUST/SHOULD/MAY) | Load the full wiki into context, act on it |
-
-### Writing for All Three
-
-- **Lead with a summary** — seniors and agents get what they need fast, juniors get orientation
-- **Explain the *why* before the *how*** — juniors learn the reasoning, seniors confirm their assumptions, agents get decision context
-- **Use tables for reference data** — scannable for seniors, parseable for agents, structured for juniors
-- **Use code blocks for anything copy-pasteable** — all three audiences benefit from exact commands
-- **Use RFC 2119 keywords (MUST/SHOULD/MAY)** — removes ambiguity for everyone, especially agents
-- **Include examples** — juniors learn by example, agents use them as patterns
-
-### Keep Pages Self-Contained
-
-Each page SHOULD make sense on its own. A junior dev landing on any page SHOULD be able to understand it without reading the rest of the wiki.
-
-### Follow the Writing Style Skill
-
-All wiki content MUST follow the `simpleapps:writing-style` skill:
-
-- **RFC 2119 keywords** — MUST/SHOULD/MAY in ALL CAPS for requirements, lowercase for casual suggestions
-- **Token efficiency** — action verbs first, no filler, specific over generic, Bottom Line Up Front
-- **Developer-facing tone** — technical and concise, include file references and acceptance criteria
-- **Expand for onboarding and architecture** — juniors and future devs need the "why"
-- **Cut everywhere else** — two sentences that answer the question beat two pages that fill the context window
-
-The wiki is developer-facing documentation. It is NOT client-facing. Write for devs and AI agents, not for non-technical readers.
-
-### Link with Anchor Precision
-
-When referencing other wiki pages, MUST link directly to the relevant section using `#` anchors — not just the page.
-
-```markdown
-# Good — links to exact section
-See [[Versioning#version-bump-procedure]] for the step-by-step process.
-Check [[Architecture#three-layers]] for how marketplace, plugins, and CLI relate.
-
-# Bad — links to top of page, reader has to hunt
-See [[Versioning]] for details.
-Check [[Architecture]] for more info.
-```
-
-This matters for two reasons:
-- **Devs** jump straight to the answer instead of scrolling through a page
-- **AI agents** use anchor links as an attention signal — a `#section` reference tells the agent exactly which part of a page is relevant to the current task, reducing noise in a 20K token wiki
-
-### The 20K Token Budget
-
-The entire wiki MUST stay under **20K tokens** (~60KB of markdown). This is a hard constraint, not a guideline.
-
-Why 20K: with a 200K token context window, the full wiki never exceeds 10% of available context. This means an AI agent can load the **entire wiki** into active context at the start of a session and keep it there throughout. No selective loading, no missed context, no stale references — the agent always has the complete picture.
-
-If the wiki approaches the budget:
-- Tighten language — cut filler, use tables over prose
-- Merge overlapping pages
-- Move implementation details back to code comments where they belong
-- Archive obsolete pages (delete, don't hoard)
-
-To check the current budget:
-```bash
-wc -c {project}/wiki/*.md
-```
-
-Rough conversion: 1 token ≈ 3 bytes of markdown. So 20K tokens ≈ 60KB.
-
-### Right-Size Each Page
-
-- Too short = missing context, agent has to search elsewhere
-- Too long = wasted tokens, buried signal
-- Target: enough to act on without reading anything else
-
-## The Feedback Loop
-
-```
-Wiki defines → Code implements → Learnings update wiki → Repeat
-```
-
-When code reveals that the wiki is wrong or incomplete, update the wiki immediately. The wiki MUST reflect reality, not aspirations.
-
-## When to Update the Wiki
-
-- **New feature** — Write the wiki page first (spec), then implement
-- **Bug fix** — If the fix reveals a gap in documentation, update the wiki
-- **Architecture change** — Update Architecture page before or during the change
-- **New convention** — Add to the relevant wiki page so the team adopts it
-- **Onboarding friction** — If someone asks "where is X?", the answer should be a wiki link. If it's not, create the page.
-
-## Anti-Patterns
-
-| Don't | Do |
-|-------|-----|
-| Write long README.md files in the repo | Minimal README + wiki link |
-| Duplicate wiki content in `.claude/rules/` | Thin rules that reference wiki |
-| Leave wiki pages stale after code changes | Update wiki in the same session |
-| Use the wiki as a dumping ground for notes | Structure pages with clear purpose |
-| Write wiki pages only humans can understand | Write for both humans and AI agents |